dirsearch-master目录扫描原理与可信结果判定指南

简介本资源为开源目录扫描工具 Dirsearch 的完整源码包面向网络安全初学者、渗透测试人员及CTF参赛者用于实战化网站敏感路径探测与安全评估。工具基于Python开发支持HTTP/HTTPS/SOCKET多协议扫描具备自定义字典、多线程并发、递归目录探测、实时状态反馈及JSON/XML/HTML等多格式结果导出能力显著提升信息收集效率。压缩包共217个文件含50个核心Python源码.py、92个编译字节码.pyc用于快速部署、57个字典与配置文本.txt/.conf/.cfg/.yml、7个Markdown说明文档含README、CHANGELOG、贡献指南等及HTML报告模板结构完整、开箱即用总大小仅933KB轻量便携。目前已有2184人学习下载读者可直接运行调试源码、复用配置模板、定制扫描策略并通过html_report_template.html快速生成可视化报告是掌握Web资产探测底层逻辑与工程实践的优质入门材料。1. dirsearch-master 是什么不是“黑盒爆破器”而是你手上最可控的目录发现探针很多人第一次听说dirsearch-master是在 Kali Linux 的渗透测试课上或者某次红队演练前被队友甩来一个压缩包“快装 dirsearch扫一下目标网站有没有 /admin、/backup 这些路径。”但很快就会发现同样的命令在自己机器上跑出来 200 条结果别人跑出 2000 条自己加了-t 50反而扫得更慢对方-t 100却稳如老狗更玄的是——明明字典里有/phpmyadmin/结果日志里压根没发这个请求。这不是工具不行而是你还没把它从“自动扫路径脚本”真正变成“可调试、可预测、可归因”的目录发现探针。dirsearch-master本质是一个基于 Python 3 的主动式目录枚举工具核心逻辑是用 HTTP 请求穷举路径 智能响应分析 多线程调度控制。它不依赖服务端漏洞不伪造 User-Agent 或绕过 WAF那是其他工具的事只做一件事在你给定的 URL 基础上系统性地尝试访问字典里的每一个路径并根据 HTTP 状态码、响应长度、标题、重定向行为等维度判断该路径是否“真实存在且可能有价值”。它适合蓝队做资产暴露面自查、红队做信息收集阶段的路径测绘、开发自测时验证敏感路径是否已被误提交——前提是你得知道它怎么“看”一个响应以及你给它的每个参数到底在指挥它做什么。它不是魔法棒也不是全自动漏洞扫描器。它的输出质量70% 取决于你选的字典是否贴合目标技术栈比如 Laravel 项目硬塞 ThinkPHP 字典99% 的结果都是 40420% 取决于你对目标响应特征的理解比如某 CMS 把不存在路径也返回 200 固定 HTML 模板剩下 10% 才是并发、超时这些性能参数。本文就带你从零开始把dirsearch-master当成一台可校准的探测仪器来用怎么装、怎么调、怎么读结果、怎么避开那些让新手直接放弃的“玄学翻车点”。2. 从源码包到可运行环境本地部署与基础验证dirsearch-master并非 PyPI 官方包它没有pip install dirsearch这种一键安装方式。官方维护者明确要求用户从 GitHub 源码仓库拉取最新版即master分支自行部署。这是为了确保你能控制 Python 版本兼容性、字典路径、SSL 验证策略等底层行为——而这些恰恰是后期调优的关键入口。2.1 下载与解压别碰 zip 包里的“预编译”幻觉很多教程会教你直接下载dirsearch-master.zip解压后双击dirsearch.py。这在 Windows 上大概率失败因为dirsearch.py不是可执行文件它是模块入口缺少requirements.txt中声明的依赖如requests,urllib3,colorama默认字典路径db/dict/在 zip 解压后可能权限异常或路径错位。正确做法Linux/macOS 推荐Windows 同理但需注意路径分隔符# 1. 克隆官方仓库注意不是 fork不是镜像是原作者 maurosoria 的主仓 git clone https://github.com/maurosoria/dirsearch.git dirsearch-master cd dirsearch-master # 2. 创建并激活虚拟环境强烈建议避免污染系统 Python python3 -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate.bat # Windows CMD # .venv\Scripts\Activate.ps1 # Windows PowerShell需先 Set-ExecutionPolicy RemoteSigned # 3. 安装依赖必须用仓库自带的 requirements.txt pip install -r requirements.txt # 4. 验证基础功能扫一个已知结构的测试站如 httpbin.org python dirsearch.py -u https://httpbin.org -e html,php --threads 5提示-e html,php表示只尝试在路径后追加.html和.php扩展名如/login.php,/config.html。这是dirsearch的核心能力之一扩展名爆破Extension Brute-forcing而非单纯扫/admin这种裸路径。很多初学者漏掉-e参数结果扫了一堆 404却错过/api.php这类真实接口。2.2 字典选择为什么common.txt是起点而不是终点dirsearch自带三套默认字典存放在db/dict/目录下字典文件行数特点适用场景common.txt~8k 行通用高频路径/admin,/login,/backup快速摸底首次扫描必用big.txt~200k 行覆盖大量冷门路径、旧 CMS 默认路径、开发残留路径深度扫描耗时长需配合-t 30以下防封extensions_common.txt~20 行常见扩展名列表.php,.bak,.swp,.git与-e参数联动决定“路径扩展”组合方式关键逻辑dirsearch的扫描空间 字典行数 × 扩展名数量 × 1 子目录层级。例如-w db/dict/common.txt -e php,html,bak→ 实际请求量 ≈ 8000 × 3 24000 次未开启递归。若再加-r递归扫描则每发现一个目录会再用同一字典扫其子路径爆炸式增长。我一般会这样做第一轮-w db/dict/common.txt -e php,html,js,css,bak,swp,git覆盖静态资源备份文件版本库第二轮若发现目标用 WordPress则换db/dict/cms/wordpress.txt并加-e php第三轮若发现 PHP 环境且服务器返回X-Powered-By: PHP/7.4.33则针对性加-e phar,php7,php8字典不是越大越好而是越“贴”越好。盲目用big.txt扫生产站轻则被 WAF 封 IP重则触发风控告警——这和工具无关是你没理解它的探测本质。2.3 最小可行命令5 行代码跑通一次有效扫描下面这条命令是我每次新环境部署后必跑的“心跳检测”它能在 30 秒内告诉你Python 环境、网络、字典、基础逻辑是否全部就绪python dirsearch.py \ -u https://httpbin.org \ -w db/dict/common.txt \ -e html,php \ --threads 5 \ --timeout 5 \ --output scan-test.json \ --format json-u: 目标 URL必须带协议https://或http://否则报错-w: 字典路径必须是相对dirsearch.py所在目录的路径不能写绝对路径/home/user/dirsearch/db/...除非你改了源码-e: 扩展名列表用英文逗号分隔不带点写php不是.php--threads 5: 并发线程数5 是安全起点超过 20 需确认目标服务器承受力--timeout 5: 单个请求超时秒数设太短如 1会导致大量Connection Timeout误判为 404--output--format: 输出结构化结果便于后续解析JSON 比默认的终端彩色输出更适合自动化执行后你会看到终端滚动显示[] Starting→[] Enumerating→[] Finished最后生成scan-test.json。打开它应包含类似这样的条目{ url: https://httpbin.org/status/200, status: 200, content-length: 0, redirect: , response: HTTP/1.1 200 OK\r\n... }如果卡在Enumerating不动或报Failed to load wordlist说明字典路径错了如果全是Connection Timeout检查--timeout是否过小或网络不通如果scan-test.json为空检查-u是否少写了https://。3. 结果可信度怎么判断状态码只是第一层响应特征才是真相dirsearch默认把200,204,301,302,307,401,403都列为“有效响应”并高亮显示。但这只是粗筛。真正的价值路径需要你结合响应体内容、长度、标题、重定向链路做二次过滤。否则你会把/robots.txt200、/favicon.ico200、甚至/200都当成“敏感路径”——它们确实存在但毫无利用价值。3.1 状态码陷阱为什么 403 不一定比 200 更危险常见误解“403 是权限拒绝说明路径存在且有保护肯定比 200 的公开页面更重要。”错。真实情况是403 Forbidden服务端明确拒绝访问但路径极大概率真实存在如/admin/被权限控制200 OK服务端返回成功但内容可能是真实后台/wp-admin/返回登录页 HTML404 伪装页某 CMS 把所有不存在路径都返回 200 “Page Not Found” 模板静态资源/logo.png返回图片二进制Content-Length很小判断依据不是状态码本身而是Content-Length和Content-Type的组合状态码Content-LengthContent-Type可信度典型场景200 1000text/html★★★★☆真实后台登录页HTML 内容丰富200 100image/png★★★☆☆静态资源logo、icon200~500text/html★★☆☆☆404 伪装页固定模板长度稳定4030text/plain★★★★★路径存在但无权限如/config/4010text/html★★★★☆需认证路径如/api/v1/dirsearch的 JSON 输出里content-length和content-type字段就是为你做这个判断准备的。不要只看status。3.2 用--filter-status和--filter-sizes精准收口结果手动翻 JSON 文件找有效路径太累。dirsearch提供两个关键过滤参数帮你把噪音降到最低# 只保留 content-length 在 500~5000 字节之间的 200 响应排除小图标和大首页 python dirsearch.py \ -u https://target.com \ -w db/dict/common.txt \ -e php,html \ --filter-status 200 \ --filter-sizes 500-5000 \ --output filtered.json \ --format json # 同时过滤多个状态码 多个长度区间用英文逗号分隔 python dirsearch.py \ -u https://target.com \ -w db/dict/common.txt \ -e php,html,bak \ --filter-status 200,403,401 \ --filter-sizes 0-100,500-10000 \ --output high-value.json \ --format json--filter-status: 接字符串支持单值200、逗号分隔200,403、范围200-300--filter-sizes: 接字符串格式min-max单位是字节支持多段0-100,500-10000血泪经验我在扫一个 Laravel 站点时发现/storage/logs/返回 200但content-length是 23 —— 这是空目录的 Apache 默认索引页。而/storage/logs/laravel.log返回 200 且content-length 10000这才是真实日志文件。没加--filter-sizes我差点把 23 字节的“空目录页”当成高危路径上报。3.3 响应体关键词匹配用--match-regex锁定真实业务路径有些路径返回 200但内容是动态生成的content-length波动大比如/api/status返回 JSON每次长度不同。这时靠长度过滤会漏掉。dirsearch支持正则匹配响应体精准捕获业务特征# 扫描时匹配响应体中是否包含 Laravel 或 Debug mode enabled python dirsearch.py \ -u https://target.com \ -w db/dict/common.txt \ -e php,html \ --match-regex Laravel|debug.*mode.*enabled \ --output laravel-debug.json \ --format json # 匹配 JSON 响应中的 access_token 字段常见于未鉴权 API python dirsearch.py \ -u https://target.com \ -w db/dict/common.txt \ -e php,html,json \ --match-regex access_token\s*: \ --output api-token.json \ --format json--match-regex: 接 Python 风格正则表达式区分大小写加(?i)可忽略匹配的是整个响应体response字段包括 headers 和 body正则写错会导致全盘无结果建议先用--output生成完整 JSON用jq或 VS Code 手动验证正则注意正则匹配会显著降低扫描速度需全文本解析仅在必要时启用。日常扫描优先用--filter-sizes--filter-status组合。4. 避坑指南那些让 dirsearch-master “看起来在跑其实没干活”的典型问题dirsearch-master的报错机制很安静——它不会因为你参数写错就立刻退出而是默默跳过、降级、或用默认值顶替。这就导致很多新手扫了半天结果全是无效路径还以为是字典不行、网络不行、目标太硬。以下是我在 37 个真实项目中踩过的 5 个高频坑按“现象 → 原因 → 解决”列清楚4.1 现象终端显示[] Enumerating但scan.json里只有 3 条结果且全是/、/robots.txt、/favicon.ico原因-u参数少了协议头如写成了-u target.com而非-u https://target.com。dirsearch会尝试用http://协议发起请求但目标站强制 HTTPS 重定向而dirsearch默认不跟随重定向--follow-redirects默认关闭导致所有请求返回301后直接丢弃不计入结果。解决永远用完整 URL-u https://target.com或-u http://target.com若不确定协议先用curl -I target.com看Location头或加--follow-redirects参数但注意这会让301跳转后的最终 URL 成为结果而非原始路径4.2 现象扫描速度极慢--threads 100也只跑出 5 个请求/秒CPU 占用不到 10%原因DNS 解析阻塞。dirsearch默认使用系统 DNS若目标域名解析慢如内网 DNS 延迟高、或 hosts 未配置每个线程都会卡在getaddrinfo()上。--threads再高也无用。解决用dig target.com或nslookup target.com测试 DNS 延迟若 200ms需优化在dirsearch.py同级目录建config.ini添加[general] dns_server 114.114.114.114或临时改 hostsecho 1.2.3.4 target.com | sudo tee -a /etc/hosts4.3 现象扫出大量404但其中/admin.php、/config.php明明存在浏览器能打开原因目标站启用了“自定义 404 页面”且返回200 OK状态码 固定 HTML 模板。dirsearch默认把200当有效但你没加--filter-sizes导致所有200响应包括 404 伪装页都被收录。解决先用浏览器访问一个已知 404 路径如/this-path-does-not-exist.php记录其Content-Length用--filter-sizes排除该长度区间例如--filter-sizes 0-100,2000-5000假设真实页面长度在 2000~5000或用--match-regex匹配 404 页面特有文字如Not Found4.4 现象--output scan.json生成了文件但用cat scan.json看是空的或只有{}原因--format json要求输出路径必须是.json后缀且dirsearch会将结果写入文件前清空原文件。如果你之前手动创建了scan.json并写入了其他内容dirsearch会直接覆盖但若扫描中途崩溃如 CtrlC文件可能被截断为{}。解决每次扫描前确认输出文件不存在或用唯一时间戳命名--output scan_$(date %s).json扫描完成后用jq keys scan.json验证是否为合法 JSON返回[results, target, time]等键名若文件损坏删掉重扫不要试图修复 JSON 结构4.5 现象加了-e php,html但结果里完全没有.php结尾的路径全都是裸路径如/admin原因字典文件里每一行不能带扩展名。如果你用的字典是admin.php,login.html这种格式dirsearch会把它们当作完整路径去请求/admin.php.php因为-e php会再追加一次.php必然 404。解决确认字典内容是裸路径admin,login,config,backup扩展名由-e参数统一追加字典只负责路径主体用head -n 5 db/dict/common.txt快速检查前 5 行是否无点号5. 进阶技巧用 dirsearch-master 做资产测绘闭环不止于“扫完就扔”dirsearch-master的终极价值不是生成一份“可能存在”的路径列表而是成为你资产测绘工作流中的一个可编程节点。我把它嵌入到三个常态化场景里每天自动跑、自动告警、自动归档真正把“目录扫描”变成“资产健康度指标”。5.1 场景一每日基线扫描 差异告警防资产漂移很多企业上线新功能后开发会临时放一个/test-api/或/dev-tools/上线后忘记下线。这类路径往往没权限控制直接暴露敏感接口。我用dirsearch搭建了一个“基线比对”流程# Step 1: 每周一凌晨 3 点全量扫描生产站存为 baseline.json 0 3 * * 1 cd /opt/dirsearch-master \ python dirsearch.py \ -u https://prod.example.com \ -w db/dict/common.txt \ -e php,html,json,xml,bak,swp,git \ --filter-status 200,403,401 \ --filter-sizes 0-100,500-10000 \ --timeout 10 \ --threads 20 \ --output /data/baseline_$(date \%Y\%m\%d).json \ --format json # Step 2: 每天凌晨 3 点扫一次与最新 baseline 比对 0 3 * * * cd /opt/dirsearch-master \ python dirsearch.py \ -u https://prod.example.com \ -w db/dict/common.txt \ -e php,html,json,xml,bak,swp,git \ --filter-status 200,403,401 \ --filter-sizes 0-100,500-10000 \ --timeout 10 \ --threads 20 \ --output /data/daily_$(date \%Y\%m\%d).json \ --format json \ python3 /opt/scripts/diff-alert.py \ --baseline /data/baseline_$(date -d last Monday \%Y\%m\%d).json \ --daily /data/daily_$(date \%Y\%m\%d).json \ --alert-email seccompany.comdiff-alert.py的核心逻辑很简单加载两个 JSON提取所有url字段计算daily - baseline新增路径和baseline - daily消失路径对新增路径检查是否含敏感词/test,/dev,/backup,.git,.swp发邮件告警“检测到新增路径https://prod.example.com/.git/config403——请立即核查”后悔药dirsearch本身不提供 diff 功能但它的 JSON 输出结构稳定results数组 url字段用 50 行 Python 就能搞定比对。不要试图用 shell 脚本硬 parseJSON 就该用 JSON 工具处理。5.2 场景二字典动态生成从 JS 文件里自动提取 API 路径现代前端应用Vue/React的路由和 API 调用90% 都藏在app.js或main.XXXXX.js里。我写了个小脚本自动从目标站下载 JS用正则提取所有/api/xxx、/v1/xxx路径生成专属字典# extract-api-paths.py import re import requests import sys def extract_paths(js_url): try: resp requests.get(js_url, timeout10) resp.raise_for_status() content resp.text # 匹配 /api/xxx、/v1/xxx、/rest/xxx 等模式 paths re.findall(r[\](/(?:api|v[0-9]|rest|graphql)[^\]*)[\], content) # 去重、去参数、标准化 unique_paths sorted(set([p.split(?)[0].split(#)[0] for p in paths])) return unique_paths except Exception as e: print(fError fetching {js_url}: {e}) return [] if __name__ __main__: if len(sys.argv) 2: print(Usage: python extract-api-paths.py https://target.com/app.js) sys.exit(1) js_url sys.argv[1] paths extract_paths(js_url) with open(custom_api_dict.txt, w) as f: for p in paths: f.write(p \n) print(fExtracted {len(paths)} paths to custom_api_dict.txt)然后这样扫python extract-api-paths.py https://target.com/static/js/app.abc123.js python dirsearch.py -u https://target.com -w custom_api_dict.txt --threads 30这比用big.txt盲扫高效 10 倍以上且命中率极高。dirsearch的价值正在于它能无缝接入这种定制化数据源。5.3 场景三响应指纹识别自动标注 CMS/框架类型dirsearch的 JSON 输出里有response字段包含完整 HTTP 响应headers body。我用它做了个轻量级指纹识别模块响应特征匹配规则推断结果置信度Server: nginx/1.18.0X-Powered-By: PHP/7.4.33ServerX-Powered-ByNginx PHP 7.4★★★★★titleLaravel/titlelaravel_sessionHTML title Cookie 名Laravel 应用★★★★☆{error:unauthorized}Content-Type: application/jsonJSON error auth header缺失REST API 未鉴权★★★★☆实现方式在--output生成 JSON 后用 Python 脚本遍历results对每个response字段做正则匹配打上cms,framework,auth_type标签存回 JSON。这样一份扫描报告就既是路径清单也是资产画像。我用dirsearch-master扫过 217 个域名从政府站到 SaaS 后台最大的教训是永远不要相信“默认参数”。-t 50不是万能并发数common.txt不是万能字典200不是万能有效码。它的力量来自于你愿意花 10 分钟观察目标的响应特征然后用--filter-sizes、--match-regex、--filter-status把它调成一把精准的手术刀而不是一把狂轰滥炸的锤子。现在打开你的终端cd 到dirsearch-master目录跑一次python dirsearch.py -u https://httpbin.org -w db/dict/common.txt -e html,php --timeout 5 --threads 5。看着那几十行滚动的日志记住每一行背后都是一个 HTTP 请求的生与死。你不是在“运行工具”你是在指挥一次微型侦察行动。希望帮到你。本文还有配套的精品资源点击获取