简介Dirsearch目录扫描工具是一款基于Python语言开发的网站路径探测软件常被渗透测试人员、安全运维人员和网络安全学习者用来快速发现站点中可能存在的敏感目录与隐藏文件从而提早定位漏洞风险。工具支持多协议如HTTP、HTTPS及底层Socket套接字等扫描支持多线程与自定义字典能够设置线程数量同时还具备目录递归扫描、扫描状态实时显示以及结果导出等功能实战中可高效梳理目标网站结构减少人工检查成本。压缩包采用RAR格式总计217个文件包括50个Python源码文件、92个编译后的字节码文件、57个文本说明或字典文件以及若干Markdown文档、YAML配置、Dockerfile和HTML报告模板整体大小仅933KB结构清晰、便于直接部署使用。目前已有2188人学习下载。资源内附完整工程代码、配置样例和容器化部署文件既可以作为二次开发的基础也可以用来研读目录扫描的实现思路与策略适合初中级安全人员深入参考。1. 目录扫描工具 dirsearch为什么还在用爆破找隐藏接口有一次我在复盘模拟项目X时遇到了典型场景目标站只开了 80 端口前端页面翻完只有三个导航登录入口却迟迟找不到。后来我把 dirsearch 的 common 字典拉了一遍三分钟翻出 /backup/ 底下的压缩包才意识到这套系统真正的入口藏在没人宣传的路径里。这就是目录扫描工具 dirsearch 的核心用途用预先准备好的路径字典批量探测服务器上真实存在但未被披露的目录和文件。它本质是一个运行在 Python socket 连接池上的 HTTP 探测工具把并发请求打到目标 URL 上靠状态码和响应体区分「存在」与「不存在」。它不是黑科技原理就是字典加响应比对但配合好的字典资源和参数调优往往能挖出比常规信息收集多一倍的路径。适合做授权测试的工程师、核对线上路由的开发以及刚上手 Web 安全的新手。2. 先看懂工作方式字典、递归与并发2.1 字典是核心资产默认字典的结构与命中逻辑dirsearch 拿到目标后要做的第一件事就是读字典。资源包里附带了一个 db 目录里面按技术栈拆成了多份字典common.txt 是通用路径适合快速摸底php.txt、asp.txt、jsp.txt 这类针对特定语言还有专门收集备份文件、敏感目录、上传目录的专项字典。默认情况下它会按配置把 common 与目标语言字典合并成一份待测列表。看到这里你应该反应过来字典质量直接决定了扫描结果的上限——工具本身只是把请求发出去有没有价值全看字典里有没有「对的词」。命中逻辑上有一点容易忽略服务器对 /admin 和 /admin/ 的响应常常不一样。前者可能返回 301 跳到 /admin/后者才返回 200 或 302。dirsearch 的默认行为会带上扩展名和路径逐项测试但不会自动帮你递归展开重定向后的目录。所以拿到 301 结果时要手动确认 Location 头指向哪里那往往是真正的资源位置。以 common.txt 为例它收录的大多是单级路径适用广但深度浅。像 /api、/v1、/internal 这类命名大型 Web 应用里非常容易命中。我一般不会改这份默认字典的内容而是优先追加「站点特征词」从目标页面源码里扒接口名、脚本路径、品牌缩写生成一份几十行的补充字典命中率比官方字典高很多。2.2 递归与并发线程数、延时与请求量的三角关系很多人把 dirsearch 当成「字典爆破器」来用忽略了它内置的递归扫描能力。开启 -r / --recursive 之后发现一个新目录会自动往它的下一级继续扫描。这里要控制两个参数--max-recursion-depth 限制递归层级默认值在不同版本里不太一样通常是无限递归配合 --recursion-status 指定只有 200、301、403 这类状态码才继续下钻。如果目标存在 /admin/user/edit 这种三层深的路由手动字典很难全覆盖递归就有用武之地了。并发控制上有三组参数在打架-t 线程数、-d 延时、--timeout 超时。dirsearch 内部用 socket 连接池复用连接线程数不必设太高默认 30 已经能打满小水管。调高到 100 时如果目标没做限流扫描速度确实会翻倍但误报率也会上升——部分中间件在高并发下会返回 503 或空响应干扰判定。我常用的经验值组合是公网目标线程 20、延时 0.1 秒配置较差的目标线程 5、延时 1 秒内网目标线程 40、延时 0。超时默认 10 秒一般不用动除非你过代理链。参数之间的关系要这样理解线程数决定同时存活多少个 socket 连接延时决定每个连接发送请求的间隔超时决定响应等待上限。三者互相制约。举个例子如果你用 -t 100 -d 0 去打一个限流网关前 5 秒看起来很快第 6 秒开始全网段超时这是目标把连接断开后的典型表现。这时候不是继续加线程而是降线程、加延时。2.3 为什么不用 gobuster 或 ffuf工具的选型边界市面上同类工具不少。gobuster 用 Go 写单二进制分发速度极快ffuf 擅长把某个参数位置当 fuzz 位配合自定义响应过滤条件搞参数爆破和 vhost 枚举很强。那为什么还要留下 dirsearch我的判断是场景互补而不是互相替代。dirsearch 的差异化优势有三点。第一字典资产内置得最友好开箱即有 common、php、jsp、asp 等多套字典不用额外下载 wordlist。第二递归扫描是内建的另外两个工具要配合脚本循环才能真正做到递归。第三输出格式与代理联动做得很完整支持 plain、json、csv 多种报告--proxy 参数直接对接 HTTP 代理方便做流量留存。对一次授权测试来说时间一般比较紧先用 dirsearch 把路径清单摸出来再针对敏感路径用 ffuf 做参数级 fuzz是最顺手的组合拳。选型边界也清晰如果目标是几千个域名的大批量存活探测gobuster 扫完一批再换下一批的吞吐量比 dirsearch 高如果目标是测一个具体接口的 GET/POST 参数ffuf 的 -w 和 -u 组合更灵活。dirsearch 的定位就是「先帮你找到哪里值得继续挖」而不是从头挖到尾。3. 落地部署从 clone 到跑通第一个授权目标3.1 环境准备与依赖安装在真实环境里我不会直接跑系统自带的 Python而是先建虚拟环境避免把全局环境搞乱。dirsearch 的代码在 master 分支上主要依赖集中在 requirements.txt 里声明了 requests、beautifulsoup4 等基础库。操作步骤git clone dirsearch-master仓库地址 dirsearch-master cd dirsearch-master python3 -m venv venv source venv/bin/activate pip install -r requirements.txt python dirsearch.py --version逻辑说明先 clone master 分支代码然后创建虚拟环境激活后再装依赖最后用一次 --version 验证安装链路完整。很多初学者在这一步能发现自己把包装错了环境。Windows 上激活命令是 venv\Scripts\activate其余一致。关于 Python 版本dirsearch 需要较新的 Python 3 环境。如果系统默认 python3 版本太老推荐用 pyenv 安装新版本再指向它。依赖安装失败时别急着换版本先看报错缺编译工具的一般是 lxml 依赖问题Linux 上装 build-essentialWindows 上装 Microsoft C Build Tools 就能解决。3.2 最小可用命令第一次实战怎么跑进入目录、激活虚拟环境之后第一次扫描我建议用最保守的参数组合先把路走通再谈调优。最小命令如下python dirsearch.py -u http://127.0.0.1:8080 -e php,txt,bak -t 10这个命令的意思是对本地 8080 端口的目标发起扫描扩展名只测 php、txt、bak 三类线程数压到 10。第一次跑不建议加 -r 递归也不要把线程怼到 100先把输出格式和状态码分布看清楚。如果目标是 HTTPS 且用了自签名证书加上 --unusual-certificate 参数跳过证书校验具体参数名以 --help 输出为准。跑完后终端每行会输出一个 URL前面是状态码后面跟响应大小。常见状态码含义200 表示资源存在301/302 表示重定向需要结合 Location 头看目标地址403 表示目录存在但禁止访问这往往比 200 更有价值404 就是不存在。碰到 3xx 和 401 时这条路径基本可以加入后续要测的列表。3.3 结果读取状态码、响应大小与重定向三要素dirsearch 的终端输出虽然直观但信息密度不够因为状态码只告诉你有响应没告诉你是谁返回的。我一般会打开默认存放在 reports 目录下的报告文件一条结果对应一个 URL。关键要看三样东西状态码、响应大小、Location 头。字段含义判断建议200资源存在直接进验证列表301/302存在但跳转记录 Location继续验证403目录在但拒绝高价值优先手工探测401有鉴权拦着值得测弱口令或越权404不存在排除500服务器报错可能是参数触发留档响应大小也容易误导。有些站点的 404 页面和 200 页面一样大这种情况下状态码不可信必须对比响应体。最简单的办法手工访问一个不存在的路径把 URL 和大小记录成基线再和扫描结果里的 200 作对比大小完全一样的多半是前端路由兜底。这个问题在后面的排查章节还会展开。还有个容易被忽略的字段是 Content-Type。如果 200 响应返回的是 application/json而路径又没有 .json 后缀说明这里很可能是个接口路由值得记录到接口清单里。我习惯在扫描结束后把这类结果单独过一遍它们往往是被遗漏的 API 入口。4. 把扫描结果变成接口清单输出格式与联动玩法4.1 输出格式选择JSON 与 CSV 的实际差异dirsearch 的 --format 参数支持 plain、json、csv 三种主流格式。plain 适合人眼快速扫但后续没法接脚本json 和 csv 适合程序化处理。命令行加 --format json 即可把报告写为 JSON 文件时间戳自动带上。python dirsearch.py -u https://模拟目标 -e php,bak --format json -o report.json python -c import json; datajson.load(open(report.json)); print([i[status] for i in data[results]][:10])第二句是快速抽查 JSON 结构results 列表里每条包含 path、status、content-length 等字段。想要全量过滤出特定状态码用一段小脚本更顺手而不是打开 JSON 慢慢翻。CSV 格式适合 Excel 表格二次加工所以我一般导出 json 用于脚本需要人工核对时再另存 CSV。4.2 与代理联动过 Burp 记录完整请求流dirsearch 默认发直连请求这在大部分测试场景下没问题但如果你需要留存请求和响应做进一步分析最好把它挂到本地代理后面。命令行加 --proxy 参数即可最常见的配合对象是 Burp。python dirsearch.py -u https://模拟目标 -e php,txt --proxy http://127.0.0.1:8080启动后 Burp 的 HTTP history 里会流出所有探测请求包括 URL、请求头、响应头。这对判断某个路径的真实网关行为特别有用状态码一样时看响应头的 Server、X-Powered-By、Set-Cookie 就能区分到底是应用返回还是 WAF 拦截。挂代理后性能会下降一截这是正常的因为每个请求多了一层转发。注意如果目标用了自签名证书代理里要先信任目标证书否则请求会中断在 TLS 握手阶段。另外配合 socket 转发类的插件或本地转发规则还能把 dirsearch 的流量导给多台出口做分布式扫描。但这类玩法对协议一致性要求高不推荐新手在没读源码的情况下直接用容易把请求带偏。4.3 自定义字典反向利用命中结果提高覆盖率内置字典覆盖面广但针对性不够。比如目标系统叫某后台系统真正有用的可能是 /system/order/export 这样的业务路径通用字典绝不可能收录。合理做法是先用内置字典扫一遍拿到一组命中路径再观察这些路径的命名规律生成站点专属字典。构造字典的常见做法是写一个列表文件每行一个路径/v1/orders /v1/orders/admin /v1/orders/export /api/admin/user /api/admin/system/config /swagger /swagger-ui.html把这个文件保存为 custom.txt然后执行python dirsearch.py -u https://模拟目标 -w custom.txt -e php逻辑说明-w 参数指定自定义字典后dirsearch 会用这份字典替代内置字典不再读默认词表。这意味着你不用关心扩展名组合直接按实际业务路径去撞。生成这类字典时我习惯从目标首页的 JS 文件里抓接口字符串再套一层通用后缀/list、/detail、/export、/save命中率比拍脑袋高不少。5. 常见问题排查五个高频翻车点与对策5.1 扫不到任何目录先怀疑字典和目标基线现象字典跑了一大半输出全是 404一个 200 都没有。原因分两类目标做了统一 404 响应所有路径返回同一个页面或者字典维度不对比如你扫 Java 站却只带了 php,txt 扩展名。解决先手工创建一个不存在的路径curl 一下看状态码。如果手建的假路径也返回 200说明站点把所有请求都导向了首页此时状态码毫无意义得对比响应体 hash。再换字典把扩展名补上 jsp,do,action并考虑目标是不是前后端分离。用 --exclude-status 404 过滤没用因为问题不在过滤规则而在判定依据。5.2 被封 IP延时、随机 UA 与代理的正确用法现象扫描到一半所有请求开始超时报 connection reset 或 timeout。原因目标限流或 WAF 发现同一 IP 请求频率异常直接断连。解决第一时间降速而不是降线程。把线程降到 5延时加到 1 秒同时开启 --random-agent 让每次请求头里的 User-Agent 随机化。命令参考python dirsearch.py -u http://模拟目标 -e php -t 5 -d 1 --random-agent公网目标建议线程 10、延时 0.2 就是安全区间内网目标不受限流约束才用高线程。如果代理池质量一般宁可不用因为公共代理的响应时延和丢包会把扫描判定搅浑误报率飙升。5.3 404 误报满天飞统一响应体才是真坑现象结果里全是 200手动访问不存在的路径也是 200看起来每个目录都存在。原因单页应用SPA或全局兜底路由把所有未知路径都指向 index.html状态码统一为 200。解决先访问一个绝对不存在的路径拿到兜底页的响应体长度和 hashcurl -s -o /dev/null -w %{http_code} %{size_download}\n https://模拟目标/not-exist-path再写几行脚本遍历扫描结果把所有 content-length 与兜底页一致的结果剔除。这类过滤 dirsearch 默认不做得靠 -o 输出报告后脚本处理避免人工肉眼筛查。5.4 Python 环境问题版本选择与依赖冲突现象跑 dirsearch.py 提示 module requests not found或者 OpenSSL 报错。原因系统默认 Python 环境依赖混乱多个项目共用一套包版本被顶掉。解决强制使用虚拟环境把依赖装进独立环境里不要直接 pip install -r requirements.txt 到全局。Windows 上如果报编码问题先把终端切到 UTF-8chcp 65001再运行。Python 版本优先选较新的 3.x遇到 lxml 编译失败再降级或装预编译 wheel而不是反复重装整个环境。5.5 递归结果爆炸怎么把范围收窄现象加了 -r 之后递归扫描跑了几十分钟结果上万条有用的没几条。原因递归进入了静态资源目录或上传目录比如 /static/css/ 下面的子路径也被当成目录继续扫。解决递归只针对目录但 static 这类目录没有业务价值。收窄方式是用 --recursion-status 限定只有 200 才下钻再用 --max-recursion-depth 限制深度为 2配合 --exclude-status 404 排除无效层级。想要更严的人可以观察第一轮结果手工把 /static、/images、/uploads 加入排除词dirsearch 支持排除某些路径前缀跑起来会快很多。6. 把扫描结果验证一遍用两次响应对比过滤无效路径扫出来的路径不等于能访问的路径至少在大规模目标上是这样。dirsearch 报告里状态码分得清但遇到 SPA 兜底、统一 403 拦截、以及内容完全相同的错误页时状态码会骗人。我习惯在扫描结束后跑一段后处理脚本把报告中的候选路径逐个拿真实请求打一遍再和目标的兜底页基线做响应体 hash 对比留下的才进验证清单。import hashlib, csv, sys, requests base sys.argv[1] with open(sys.argv[2]) as f: rows list(csv.DictReader(f)) def page_hash(url): try: s requests.Session() r s.get(url, timeout10, allow_redirectsFalse) return hashlib.sha256(r.content).hexdigest()[:16], r.status_code except Exception: return error, 0 _, base_code page_hash(base /__nonexist__) for row in rows: url row[url] h, c page_hash(url) if c ! 404 and h ! base_code: print(c, url, h)这段脚本的核心逻辑是先请求一个绝对不存在的路径拿到目标在「未命中」时的响应体 hash 和状态码然后逐个请求报告里的候选 URL凡是状态码为非 404 且响应体 hash 与未命中页不同的才认为这条路径真实存在。参数说明base 是目标根地址第二个参数是 dirsearch 导出的 CSV 报告结果打到标准输出方便重定向到文件。实际跑一轮你会发现之前报告里 200 的路径被过滤掉一大半剩下的是真正返回独立资源的接口和页面。对于 301/302 结果我还会把 Location 头一并取出来记录转发目标往往藏着一个真实存在的目录。这一步做完才敢把结果说成「资产路径」不然就是拿谣传当事实。有一次我直接把第一次扫描的报告发给了同事结果大半路径是前端路由兜底生成的白跑一晚上。从那以后每次扫描完我都会强制走一遍这套响应体对比流程再决定哪些路径值得写进报告。希望帮到你。本文还有配套的精品资源点击获取