1. 为什么要做目录扫描以及为什么选 dirsearch做渗透测试、Web 安全检查或者纯粹想搞清楚一个站点到底暴露了多少东西的时候目录扫描几乎是必做的一步。不管目标是一个老旧的 CMS、某个内部管理系统还是一个刚上线的业务系统总能通过扫描发现一些没打算公开的路径后台登录页、备份文件、日志目录、旧版本残留、svn/git 泄露文件等等。这些路径在正常浏览时根本不会出现在页面上但一旦被探测出来往往就是安全问题的突破口。扫描目录的工具其实不少Burp Suite 自带的 Intruder、Nmap 脚本、御剑这类图形界面工具还有各种在线平台但我个人最常用的还是 dirsearch。原因有三个一是开源免费代码在公开仓库里躺着想研究原理可以直接看源码二是扫描速度快默认配置下线程跑满一个中等规模的字典也就是几分钟的事情三是参数设计贴合实际场景既支持递归扫描、指定扩展名又支持 HTTP 请求头定制、代理转发基本覆盖了日常测试的所有需求。这篇文章面向的读者主要是在 Windows 环境里搭工具的人。网上讲 dirsearch 安装的文章大多写得比较简略一上来就让你 git clone、pip install然后就没然后了。真拿到一台 Windows 机器问题马上就来没装 Git、Python 版本不对、pip 源连不上、被 Defender 拦了……这篇文章就把这些坑一个个说清楚从零开始把环境、安装、命令参数、字典定制、常见报错全部过一遍。装完之后你不仅能跑出结果还能根据不同的目标调整扫描策略。我个人在实际项目里的习惯是拿到一个授权范围内的目标之后先用 dirsearch 跑一遍快速字典看响应码分布再针对发现的目录结构做递归扫描最后对重点路径手工验证。整个过程快则十分钟慢则半小时足以对目标暴露面有个基本认知。下面进入正题。2. 安装前的环境准备Python 版本的坑与依赖处理2.1 为什么先要装 Python以及装哪个版本dirsearch 本身是 Python 写的所以 Windows 上跑它的前提是先有一个可用的 Python 解释器。这里有个误区很多人以为随便装个 Python 就行其实版本选择会影响后续依赖安装和运行稳定性。dirsearch 对 Python 版本的要求不算高但也要注意区分。早期的 3.x 版本在 Python 2.7 下也能跑后来项目维护者明确转向 Python 3如果你还在用 Python 2.7跑起来会直接报语法错误。现在最新的 master 分支我实际测试下来 Python 3.6 到 3.12 都能正常运行但建议装 3.8 以上因为某些第三方依赖库对新版本 Python 的兼容性处理得更好。装 Python 的时候有个细节容易被忽略安装界面最底部的 Add Python to PATH 复选框默认是不勾选的。如果你直接点 Install 走完流程后面在命令行里敲 python 只会得到不是内部或外部命令的提示。所以记得勾上这个选项或者装完之后手动把 Python 的安装目录和 Scripts 子目录加到系统环境变量里。提示如果已经在系统里装过其他版本的 Python注意看版本号避免用错。cmd 里输入python --version能看到当前默认解释器的版本。2.2 pip 源与依赖安装的常见卡点Python 装好了不代表万事大吉接下来要安装 dirsearch 的依赖库。项目根目录下有一个 requirements.txt 文件里面列了 requests、certifi 之类的库。这些库本身不大但在国内网络环境下直接 pip install 经常会出现下载速度极慢、超时、连接被重置这类问题。原因说白了就是默认走的 PyPI 官方源在国外访问链路长同一时刻还有大量客户端在并发请求自然不稳定。解决办法很简单换用国内镜像源比如清华、阿里云、中科大的 PyPI 镜像。我习惯在全局配置里指定源地址这样以后装任何 Python 包都走镜像不用每次手动加-i参数。具体操作是在用户目录下创建 pip.ini 文件Windows 路径是C:\Users\你的用户名\pip\pip.ini写入以下内容[global] index-url https://mirrors.aliyun.com/pypi/simple/ [install] trusted-host mirrors.aliyun.com保存之后再执行pip install -r requirements.txt实测下来同样的包在这套配置下几秒钟就能装完基本不会中断。2.3 Git 不一定要装压缩包也能解很多安装教程会让你先装 Git然后用 git clone 把仓库拉下来。这在 Linux 服务器上是标准操作但在 Windows 上反而多了一道门槛——有些机器上根本没装 Git或者装了版本很旧拉代码时报证书错误。其实 dirsearch 提供了 zip 压缩包下载通道直接去开源仓库的 Releases 页面下载 Source code (zip) 即可下载后解压就能用完全不需要 Git。我前几次在 Windows 上装的时候就是这么干的省去一个环节少踩一个坑。下载后把压缩包解压到一个路径干净的地方比如D:\tools\dirsearch避免放在中文路径或带空格的目录下虽然代码对路径的容忍度还行但命令行操作时中文路径偶尔会有编码问题没必要冒这个险。3. 完整安装流程一步步实操3.1 第一步确认 Python 环境和 pip 可用打开 cmd 或 PowerShell依次执行python --version pip --version看到 Python 版本号和 pip 版本号正常输出说明环境没问题。如果 python 命令没反应检查环境变量如果 pip 报错提示找不到通常是环境变量里缺了 Scripts 目录补上之后重新打开命令行窗口即可。这一步看似简单但值得认真确认。我遇到过几次情况是系统装了多个 Pythonpip 指向的版本和 python 指向的版本不一致导致后面依赖装到了别的环境里运行 dirsearch 时又提示缺模块。处理这类问题的方法也很直接用python -m pip来执行安装命令而不是直接敲 pip这样可以保证安装对象始终是当前 python 解释器对应的 pip。3.2 第二步获取 dirsearch 源码并安装依赖获取源码有两种方式任选其一方式一直接用浏览器下载 zip 包并解压。方式二如果机器上已经装了 Git可以执行git clone https://github.com/XXXX/dirsearch.git注意以上仓库地址仅为示意。实际下载时请到开源社区搜索 dirsearch 官方仓库获取最新地址。进入解压后的目录cd D:\tools\dirsearch然后安装依赖python -m pip install -r requirements.txt安装完成后可以先跑一下版本确认命令。新版 dirsearch 支持-v参数查看版本python dirsearch.py -v正常会输出类似dirsearch v0.4.3这样的信息。到这里安装步骤就全部完成了。3.3 第三步首次运行与简单的目标测试为了确认一切正常先跑一个小目标测试。注意测试目标必须是你自己搭建的环境或者获得明确授权的目标不要随便扫别人的站点这是最基本的职业底线。python dirsearch.py -u http://127.0.0.1:8080 -e php这里说明一下参数含义-u指定目标 URL-e指定要探测的扩展名。如果本地已经有一个测试站点比如 PHP 环境自带的默认服务这条命令会开始扫描 php 扩展名的路径并实时输出响应状态码、页面大小等信息。如果输出能看到 [200]、[301]、[403] 这些状态码对应的路径列表说明工具已经能正常工作。4. 核心参数解析把工具用到极致安装只是第一步真正拉开差距的是对参数的理解和使用习惯。dirsearch 的参数非常多但我认为关键的就那么十几个把它们吃透就能应对大多数扫描场景。4.1 目标指定与请求控制最基本的-u/--url和-l/--list是一对搭档。-u用于单个目标-l用于批量目标——如果你有一个目标列表每行一个 URL就可以用-l target.txt全部跑一遍扫描结果会按目标分别输出非常省事。关于请求速度很多人第一次用的时候直接上默认线程然后发现要么被目标 WAF 封 IP要么结果丢失严重、报错一大堆。这里的关键参数是参数作用建议值-t/--threads线程数默认 25本地测试可以 10-30公网建议 5-10--timeout请求超时时间默认 7.5 秒网络不稳定时调大到 15-20--delay请求间隔单位秒默认无间隔目标敏感时设置 1-3-x/--exclude-status排除指定状态码常用排除 403, 404减少噪音线程数并不是越大越好。线程开太高目标服务器响应不过来大量连接被重置反而导致漏报。我做公网扫描时一般控制在 5 到 10 个线程配合超时和延迟设置整体速度虽然慢一些但结果质量明显更高。4.2 字典的选择与定制dirsearch 自带了多个字典位于 db 目录下。默认使用的字典是 db/dict.txt里面包含的路径数量不小覆盖面也比较广。但不同的目标场景适合的字典完全不同。举例来说目标是一个常见的开源 CMS比如 WordPress、Discuz那么直接使用默认字典基本可以覆盖大多数已知路径目标是 Java 系的应用Spring Boot、Tomcat需要关注 actuator、swagger-ui、api-docs、manager 这类路径目标是前端纯静态站点路径往往比较规整但泄漏点常常是源码压缩包、.git 目录、.env 文件、备份文件等。dirsearch 支持自定义字典python dirsearch.py -u http://target.com -w custom_dict.txt-w参数指定自己的字典文件格式是每行一个路径。我自己维护了几个场景化的字典文件wordpress.txt收集了插件、主题、上传目录等常见路径spring.txt针对 Java 框架的常见端点bak.txt专门测备份文件比如.bak、.zip、.tar.gz、www.zip、backup.sql这类高价值目标。如果你刚开始用我的建议是先别急着到处找大字典从 default 开始跑几个目标后自己总结哪些路径命中率高、哪些方向容易遗漏慢慢沉淀出自己的字典集合。这个过程比单纯找一个超全字典有用得多。4.3 递归扫描与扩展名规则递归扫描是 dirsearch 最实用的功能之一。默认情况下扫描器只针对目标根路径跑字典不会深入子目录。但如果目标结构类似http://target.com/admin/根路径扫描就无法覆盖admin目录下的更多内容。使用-r/--recursive参数可以开启递归扫描还可以用--recursive-depth指定递归深度比如值为 3 表示最多深入三层。另外-R/--max-recursion-depth可以设更大值。递归扫描要注意时间和流量消耗。如果目录嵌套很深、子目录又多扫描时间会呈倍数增长。建议先跑一遍根路径根据返回的 200/301 结果人工挑选有探索价值的目录再对指定子目录执行递归扫描而不是一上来就开全站递归。扩展名处理方面-e php,asp,jsp,html,js是常见写法但很多人不知道-f参数的作用。加上-f表示强制在所有字典条目后追加扩展名再测试不加的话只处理在字典大小写里已经包含扩展名的条目。如果你想测 backup.zip、config.php.bak 这类后缀在路径中间的文件-f配合多扩展名的组合才会比较完整。5. 实用进阶技巧与坑位实录5.1 用代理观察请求验证扫描质量在实战中我习惯把 dirsearch 的请求通过代理转发到 Burp Suite 或 Fiddler一边扫描一边观察实际发送的请求包。这样做的目的不是单纯为了中断操作而是确认扫描器发出的请求是否符合预期比如 User-Agent 是否过于特征明显、是否携带了站点的 Cookie、是否在请求头里塞了必要字段。你可能要问为什么刻意用没有明显特征的请求头因为有些 WAF 看到一连串路径探测请求且 UA 为默认的 python-requests会直接拉黑。设置伪装 UA 是有必要的python dirsearch.py -u http://target.com --user-agent Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36如果你需要带身份认证的扫描比如目标是从后台某个入口进去才能访问的模块可以用-H参数手动加 Cookie 或其他请求头python dirsearch.py -u http://target.com -H Cookie: sessionidxxxx; login15.2 结果输出与报告整理扫描结果默认输出到 reports 目录下按目标域名和时间戳组织文件名。dirsearch 支持多种输出格式plain text、JSON、CSV、Markdown 等。我一般用--formatjson输出结构化结果方便后续用脚本分析状态码分布、提取响应长度异常项。举个例子python dirsearch.py -u http://target.com -o result.json --formatjson生成的 JSON 文件里记录了每个路径的 URL、状态码、响应长度、Content-Type 等信息。拿到这些数据之后我会先按状态码分组200 的逐一人工浏览301/302 的关注 Location 跳转方向403 的偶尔也要看有些 403 只是目录列表被禁但里面的文件可能能访问500 的要重点验证是否存在代码层面的问题。5.3 Windows 环境特有的几个坑第一杀毒软件拦截。Windows Defender 或第三方安全软件对 Python 脚本的下载、解压、运行有时会报毒或直接隔离文件。遇到这种情况先把工具目录加入白名单或者暂时关闭实时防护再运行。前提是你清楚地知道自己在干什么工具是从正规渠道下载的。第二编码问题。cmd 默认的代码页是 GBK而某些字典文件是 UTF-8 编码扫描过程中如果字典里有中文字符命令行输出可能会乱码严重的直接报 UnicodeDecodeError。解决办法是在运行前执行chcp 65001把代码页切换到 UTF-8或者直接使用 Windows Terminal 运行兼容性好很多。第三路径空格问题。目录解压到了C:\Program Files这类带空格的路径下命令行里需要给路径加引号。为了减少麻烦建议把 dirsearch 放在纯英文无空格的路径下。第四批量扫描时的日志分割。用-l跑多个目标时如果一个目标报错导致脚本卡住会影响后续目标的扫描。实际操作中我倾向于写一个简单的批处理脚本每个目标单独起一次扫描命令超时则跳过保证单个目标的问题会影响整体排期。写一个简单的 for 循环批处理或者用 Python 脚本调用 subprocess 都可以。6. 常见问题速查表与实战心得6.1 常见报错与对应处理报错信息原因分析处理方式python 不是内部或外部命令Python 没装好或未加入 PATH重装并勾选 Add Python to PATH或手动添加环境变量ModuleNotFoundError: No module named requests依赖库未安装或没装在当前 Python 环境里使用python -m pip install -r requirements.txt重新安装ConnectionError: HTTPSConnectionPool ...网络问题或目标拒绝连接换 PYPI 镜像源或检查目标地址是否正确、网络是否可达[SSL: CERTIFICATE_VERIFY_FAILED]目标证书不被信任加上-k/--insecure参数跳过证书验证SyntaxError: invalid syntax用了过旧的 Python 版本升级到 Python 3.8扫描速度极慢线程数太少、超时太长或网络本身波动适当增加线程数、调低超时时间但也要综合考虑目标情况6.2 多个实战方向的体会第一扫描之前先了解目标而不是上来就跑字典。我会先手工访问首页看一下技术栈响应头里的 Server 字段、页面渲染框架特征、URL 风格确认大致类型再决定用什么字典、带什么扩展名。盲目拿大字典去扫所有目标效率和命中率都很差。第二结果里的低置信度条目往往才是真正有价值的。很多人扫描完成后只盯着 200 状态码看忽略了 301/302 跳转目录。实际上很多后台的入口是一个 302 跳到登录页响应长度异常小的 200 页面也可能隐藏着空目录或纯文本暴露。这些细节只有手工验证过才不会漏。第三字典质量比扫描速度重要。你可以用最快的速度扫完一个巨大字典但里面 80% 的路径跟你的目标毫无关系。慢慢积累适合自己业务方向的字典比任何全网最全字典都更实用。第四合规底线要守牢。目录扫描本质上是主动探测行为必须确保目标是你自己有权限测试的系统或者在明确授权范围内开展。未经授权的扫描不仅是道德问题还可能触犯相关法律法规这一点怎么强调都不为过。6.3 后续扩展方向如果你的工作涉及 Web 安全测试掌握了 dirsearch 之后可以考虑把能力链延伸一下结合域名枚举工具做子域名层面的信息收集把扫描范围从单点到面配合漏洞扫描工具对发现的高价值路径做进一步验证或者写一点自动化脚本把常见资产的目录扫描结果定期存档建立自己的信息台账。这些动作单看都不复杂但组合起来就是完整的资产发现流程。回到 Windows 安装这件事本身第一步跨过去后面剩下的大多是熟练度问题。按本文的流程把环境配好把参数理解透再结合实际目标做几次完整扫描dirsearch 这个工具基本就吃透了。工具只是起点真正有价值的还是你拿到扫描结果之后能否做出正确的判断和行动。