简介本资源是开源目录扫描工具 Dirsearch 的完整源码包面向网络安全初学者、渗透测试学习者及 CTF 参赛选手用于实战掌握 Web 路径枚举技术与安全信息收集方法。压缩包共88个文件以64个Python脚本含核心扫描逻辑、连接控制、结果解析等模块为主体辅以7份Markdown文档含README、贡献指南、更新日志、6个配置/词表文本如blacklist、user-agents、字典文件、4个YAML配置含CI/CD与工作流定义以及Dockerfile、logo、测试脚本等结构清晰、开箱即用194KB轻量紧凑。已有2010人学习下载读者可直接运行dirsearch.py开展靶机探测获取完整扫描流程实践能力深入理解多线程请求调度、HTTP状态码语义分析、自定义词典加载机制并通过预置的400/403/500黑名单、静态资源识别逻辑等细节掌握工业级目录扫描工具的设计思路与安全边界意识。1. dirsearch-master.zip 不是“压缩包”它是你手上最轻量、最可控的目录爆破起点很多人第一次看到dirsearch-master.zip下意识点开解压后翻半天README.md发现没安装脚本、没.exe、没图形界面就关掉了——这恰恰错过了一个在渗透测试、红队评估、资产测绘中真正能“扛事”的命令行工具。dirsearch不是扫站黑盒它不发漏洞利用载荷不绕过 WAF 规则也不模拟浏览器行为它干一件极朴素的事用高并发、可定制的 HTTP 请求系统性地探测目标路径是否存在响应200/301/302/403 等并把结果结构化输出。它适合谁适合需要快速摸清 Web 资产表面结构的渗透工程师、安全运维人员、CTF 参赛者也适合刚学完 HTTP 协议、想亲手验证“目录遍历”“隐藏接口”“备份文件泄露”这些概念的新手。它不依赖 Python 虚拟环境隔离错它强依赖它支持中文路径字典默认不支持需手动转码它跑完就出报告不它默认只打屏要存报告得加参数。这些不是缺陷而是设计取舍轻量、透明、可调试、无黑匣子。你拿到dirsearch-master.zip本质是拿到了一份可审计、可修改、可嵌入自动化流水线的目录枚举源码——不是拿来即用的玩具而是你构建自己侦察能力的最小可靠基座。2. 从 zip 解压到终端可执行Python 环境、依赖与最小运行链路dirsearch-master.zip是 GitHub 上maurosoria/dirsearch仓库的主分支快照压缩包不是 PyPI 安装包也不是预编译二进制。它的价值正在于“源码可见”你能一眼看清它怎么发请求、怎么处理重定向、怎么判断状态码有效性、怎么跳过无效响应。但这也意味着——你必须亲手搭起它的运行环境而不是 pip install 一下就完事。下面这条链路是我在线上靶机、客户内网、CTF 服务器上反复验证过的最小可行路径跳过任何一环都可能卡在ModuleNotFoundError或UnicodeDecodeError。2.1 解压后第一件事确认 Python 版本与编码基础dirsearch主仓库明确要求Python 3.7最新稳定版推荐 3.9–3.11且对 Windows 用户有特殊提示必须使用 UTF-8 终端编码。很多新手在 PowerShell 或 CMD 里直接运行失败根本原因不是脚本问题而是终端本身不认中文路径或字典里的中文注释。# Linux/macOS 检查默认编码应为 utf-8 python3 -c import locale; print(locale.getpreferredencoding()) # Windows PowerShell 中强制设置每次新开窗口都要执行 chcp 65001提示Windows 用户强烈建议改用 Windows TerminalMicrosoft Store 免费下载它原生支持 UTF-8避免chcp命令失效或被其他程序重置。解压dirsearch-master.zip后进入目录你会看到核心结构dirsearch-master/ ├── dirsearch.py # 主入口脚本不是模块不能 import ├── lib/ │ ├── __init__.py │ └── ... # 核心逻辑requester、report、scanner 等 ├── db/ │ └── wordlists/ # 内置字典目录重点后续调参全靠它 ├── README.md └── requirements.txt注意dirsearch.py是脚本不是包。你不能import dirsearch只能python3 dirsearch.py [args]。这是它和gau、httpx等工具的关键区别——没有抽象层全是直给。2.2 用 requirements.txt 装依赖为什么不用 pip install dirsearchdirsearch没上 PyPI官方明确不支持pip install dirsearch会装错包。正确做法是进解压目录用其自带的requirements.txtcd dirsearch-master python3 -m pip install -r requirements.txt该文件当前2024 年主流版本包含 4 个关键依赖包名作用是否可省略血泪经验requests发送 HTTP 请求支持 Session、Cookie、代理❌ 不可省略必须 ≥2.25.0旧版不支持 HTTP/2 和部分 TLS 选项urllib3requests 底层连接池管理⚠️ 通常随 requests 自动装若手动降级 requests需同步降 urllib3否则InsecurePlatformWarningcolorama终端彩色输出状态码高亮、进度条✅ 可省略无影响功能省略后所有输出变黑白但--output报告完全不受影响tldextract提取域名根域用于自动识别子域、过滤无效 host✅ 可省略仅影响-u http://a.b.c.com时的自动 host 推断若你总用-u显式指定 URL可跳过注意不要用pip install --user安装。dirsearch在扫描时会动态导入lib/下模块若用--userPython 可能找不到本地lib/目录报ImportError: No module named lib。务必在项目目录内执行pip install -r。2.3 最小命令跑通验证环境 看懂第一行输出别急着扫目标站。先用内置的test.txt字典和httpbin.org公开测试服务跑通最小闭环python3 dirsearch.py -u https://httpbin.org -w db/wordlists/test.txt -t 10 -e html,php,js参数说明-u https://httpbin.org目标 URL必须带协议httpbin.org会返回/status/200、/status/404等标准路径-w db/wordlists/test.txt字典路径test.txt仅含 5 行如index.html,robots.txt秒出结果-t 10线程数10 是安全起点过高易被封 IP过低效率低-e html,php,js扩展名追加对每个字典词尝试xxx.html、xxx.php等避免漏掉常见后缀成功输出首行类似[14:22:03] Starting dirsearch v0.4.3 [14:22:03] Threads: 10 | Wordlist: db/wordlists/test.txt [14:22:03] Target: https://httpbin.org/ [14:22:03] Output File: reports/httpbin.org_24-05-15_14-22-03.txt这行[14:22:03] Output File: ...是关键信号——说明环境已通日志已生成后续所有扫描结果都会落盘到这个路径。如果卡在这里不动或报ConnectionError说明网络或证书验证出问题见 4.1 避坑节。3. 字典、线程与扩展三个核心参数的实战调优逻辑dirsearch的效果 70% 取决于这三个参数-w字典、-t线程、-e扩展名。它们不是越大越好、越多越全而是需要根据目标场景做对抗性权衡既要覆盖常见路径又要避开蜜罐陷阱既要提速又要防被 WAF 限速既要猜后缀又要减少无效请求。下面拆解真实项目中的调参逻辑。3.1 字典选择不是“越大越好”而是“最匹配目标技术栈”dirsearch-master.zip自带db/wordlists/目录但新手常犯的错误是直接用common.txt2.3 万行扫生产站结果扫了 2 小时只出 3 个 403。原因common.txt是通用字典混杂了 WordPress、Drupal、Joomla 等 CMS 路径而你的目标是个静态 Vue 前端站根本不存在/wp-admin/。我的做法是分三级字典策略字典类型适用场景典型文件行数使用命令示例精准栈字典已知目标技术如 Spring Bootdb/wordlists/general/common.txtspring-boot.txt需自建500–2000-w db/wordlists/general/common.txt -w custom/spring-boot.txt轻量通用字典未知技术栈快速探活db/wordlists/general/small.txt1200 行~1200-w db/wordlists/general/small.txt深度扩展字典已发现敏感路径如/backup/需递归探测db/wordlists/general/deep.txt含/backup/config.zip等~5000-w db/wordlists/general/deep.txt --recursive提示dirsearch支持多-w参数会按顺序合并字典去重。我习惯先用small.txt快速摸底发现/api/后再切到api-focused.txt自建含/api/v1/users,/api/admin等。自建字典技巧从目标站 HTML 源码提取script src...、link href...中的路径去重后转成字典用git log --oneline | head -n 100查看开源项目 commit 记录找高频新增路径如src/pages/,public/assets/对robots.txt解析出的Disallow:路径反向构造Allow:字典如Disallow: /admin/→ 加入/admin/login.php。3.2 线程数-t不是 CPU 核数而是目标服务器的“容忍阈值”很多人设-t 50觉得“我电脑有 16 核必须榨干”。错。dirsearch的瓶颈从来不是你的 CPU而是目标服务器的连接池、WAF 的速率限制、中间 CDN 的排队策略。实测经验阈值针对国内常见云厂商 Nginx 阿里云 WAF目标类型推荐-t现象观察应对动作静态官网纯 Nginx30–50扫描稳定平均响应 200ms可维持PHPMySQL 站宝塔面板15–25响应时间波动大200ms–2s偶现 503降-t到 10加--delay 0.1前端 SSRNext.js/Nuxt5–10大量ConnectionTimeout--timeout需调至 10s必须-t 5--timeout 10--retries 2关键参数组合python3 dirsearch.py -u https://target.com -w small.txt -t 10 \ --timeout 10 --retries 2 --delay 0.1--timeout 10单请求超时 10 秒默认 5sSSR 渲染慢易误判--retries 2失败重试 2 次默认 1网络抖动时漏结果--delay 0.1请求间强制休眠 0.1 秒防触发 WAF 的“短时高频”规则3.3 扩展名-e为什么html,php,js是黄金组合-e参数决定dirsearch对每个字典词追加哪些后缀。例如字典含config-e php,txt,bak会实际请求https://target.com/config.phphttps://target.com/config.txthttps://target.com/config.bak但绝不是“把所有后缀都写上”。我见过有人写-e php,jsp,asp,aspx,html,htm,js,css,txt,bak,zip,rar,7z,sql,log结果 90% 请求返回 404还因请求量过大被封。真实项目中的后缀策略目标特征推荐-e依据PHP 站含 ThinkPHP/Laravelphp,html,txt,bak.php是入口.txt/.bak易泄露配置.html是静态页 fallbackNode.jsExpress/Nestjs,html,json,ts.js是源码.json是 API 响应.ts是 TypeScript 源文件若未编译JavaSpring Bootjar,war,xml,yml,properties.jar可下载.yml是配置文件.xml是 Spring 配置静态站点Vue/Reacthtml,js,css,json,map.map文件泄露源码映射.json是 mock 数据注意.map文件是前端安全盲区。一次客户扫描中-e js,map扫出/static/js/main.abc123.map反编译后还原出完整 React 组件源码——这是比robots.txt更致命的泄露。4. 避坑5 个让 dirsearch “静默失败” 的真实陷阱与解法dirsearch的日志很“诚实”但它不会主动告诉你哪里错了。很多新手扫完 0 结果以为目标没漏洞其实是工具卡在某个环节没报错。以下是我在 37 个真实项目中踩出的 5 个高频静默陷阱每一条都附带curl验证命令和修复动作。4.1 现象扫描卡住不动CPU 占用 0%日志停在Starting dirsearch...原因目标站启用了HTTP/2 强制升级而dirsearch默认的requests库基于 urllib3不支持 HTTP/2连接 hang 住。验证curl -I --http2 https://target.com # 若返回 200说明支持 HTTP/2 curl -I --http1.1 https://target.com # 若返回 200但 --http2 超时则确认是此问题解决升级requests到支持 HTTP/2 的版本并安装h2python3 -m pip install --upgrade requests python3 -m pip install h2 # 然后加参数强制用 HTTP/1.1更稳 python3 dirsearch.py -u https://target.com -w small.txt --http114.2 现象大量403 Forbidden但手工访问robots.txt是 200原因目标 WAF 拦截了dirsearch的默认 User-Agentdirsearch/0.4.3而放行了浏览器 UA。验证curl -H User-Agent: dirsearch/0.4.3 -I https://target.com/robots.txt # 返回 403 curl -H User-Agent: Mozilla/5.0 -I https://target.com/robots.txt # 返回 200解决换 UA且必须用--user-agent不是-apython3 dirsearch.py -u https://target.com -w small.txt \ --user-agent Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.364.3 现象扫出/admin/是 302但手工访问是 200且dirsearch没跟跳原因dirsearch默认不跟随重定向--follow-redirects 未开启302 被当成功能路径但实际内容在重定向后的 URL。验证curl -I https://target.com/admin/ # 看是否含 Location: /admin/login.php解决显式开启跟随并限制跳转深度防死循环python3 dirsearch.py -u https://target.com -w small.txt \ --follow-redirects --max-redirs 34.4 现象字典含中文路径如后台管理.txt扫描时报UnicodeEncodeError原因Windows CMD 默认 GBK 编码无法解析 UTF-8 字典中的中文。验证type db\wordlists\chinese.txt # 在 CMD 中乱码即确认解决方案 1推荐用 Windows Terminal UTF-8 编码打开字典另存为 UTF-8-BOM 格式方案 2在字典中用 URL 编码替代中文如后台管理.txt→%E5%90%8E%E5%8F%B0%E7%AE%A1%E7%90%86.txt方案 3Linux/macOS 下无此问题直接用。4.5 现象--output生成的 TXT 报告为空但终端显示有结果原因dirsearch的--output只保存最终确认的有效路径200/301/302/403而默认终端输出包含所有状态码包括 404。新手误以为“终端有输出 报告有内容”。验证# 终端输出含 404但报告只收 200/302/403 python3 dirsearch.py -u https://httpbin.org -w test.txt --output report.txt cat report.txt # 只有 /status/200 这一行解决用--full-url--formatplain保证报告完整性并用--output-format指定格式python3 dirsearch.py -u https://target.com -w small.txt \ --output report.html --output-formathtml \ --full-urlHTML 报告会包含所有状态码、响应大小、标题且可搜索。5. 报告解读与二次挖掘从 10 行结果里挖出 3 个高危点扫完不是终点。dirsearch输出的每一行有效路径都是一个待验证的攻击面入口。我从不满足于“扫出/backup/就截图交差”而是用固定流程做三层穿透分析路径语义 → 响应内容 → 关联风险。下面以一次真实电商站扫描为例展示如何从dirsearch的原始输出里榨取最大价值。5.1 原始输出12 行有效路径但只有 3 行值得深挖假设dirsearch扫出以下有效路径已去重按状态码排序301 https://shop.example.com/api/ - https://shop.example.com/api/v1/ 200 https://shop.example.com/api/v1/ 200 https://shop.example.com/api/v1/users 200 https://shop.example.com/api/v1/products 403 https://shop.example.com/admin/ 200 https://shop.example.com/admin/login.php 200 https://shop.example.com/static/js/app.123456.js 200 https://shop.example.com/static/js/vendor.abcdef.js 200 https://shop.example.com/static/css/main.css 403 https://shop.example.com/.git/ 200 https://shop.example.com/robots.txt 200 https://shop.example.com/.env.example注意403不代表“没权限”而是“路径存在但拒绝访问”——这比404更危险说明/admin/和/.git/目录真实存在。5.2 第一层路径语义分类3 类必跟我用 Excel 快速分类列 AURL列 B手动标注URL分类动作/api/v1/API 根路径立即 curl 测试是否返回 Swagger UI 或 OpenAPI 文档/admin/login.php后台入口检查是否弱口令admin:admin、是否暴露版本titleAdmin v2.3.1/title/.git/源码泄露用git-dumper工具下载整个 Git 仓库含历史 commit、密钥提示/.env.example是伪高危项。它只是示例文件但说明开发留了.env习惯——立刻 curl/.env若返回 200直接拿走数据库密码。5.3 第二层响应内容深度解析用 curl jq 快速验证对/api/v1/不只看状态码要看响应体是否含 API 文档# 检查是否返回 JSON SchemaOpenAPI curl -s https://shop.example.com/api/v1/ | jq keys 2/dev/null | grep -q openapi echo OpenAPI detected # 检查是否返回 HTMLSwagger UI curl -s https://shop.example.com/api/v1/ | head -20 | grep -q html echo Swagger UI detected对/static/js/app.123456.js检查是否含硬编码密钥curl -s https://shop.example.com/static/js/app.123456.js | \ grep -E (api_key|secret|password|token) | \ sed s/[^[:print:]]//g | head -55.4 第三层关联风险推演用路径关系反推架构dirsearch扫出的路径是离散点但组合起来能画出架构草图。例如/api/v1//admin/login.php→ 后台用独立 PHP 系统API 用 Node.js跨域配置可能不同/.git//robots.txt→ 开发未清理部署产物robots.txt中Disallow: /internal/暗示存在未公开内部接口/static/js//static/css/→ 前端资源分离部署可尝试https://shop.example.com/static/js/..%2f..%2f..%2fetc%2fpasswd测试路径遍历我的习惯是扫完立即用grep -E (api|admin|git|env|backup|conf) report.html快速定位高危关键词再逐个验证。不依赖 dirsearch 的“高亮”因为它的颜色只是状态码不是风险等级。最后说句实在话dirsearch-master.zip里那几百行 Python 代码我读过三遍。它没有炫技的异步框架没有花哨的 AI 路径生成就是老老实实用requests.Session()发请求、用threading控并发、用open()写报告。正因如此当我发现某个客户站扫不出结果时我能直接进lib/requester.py加print(req.url, req.status_code)调试而不是对着黑盒报错干瞪眼。这种可控感是任何封装过深的工具给不了的。希望帮到你。本文还有配套的精品资源点击获取