dirsearch 是一款强大的开源命令行工具，用于对 Web 服务器进行目录和文件暴力破解。它通过扫描目标网站，尝试发现隐藏的目录、文件或潜在的敏感资源，广泛应用于渗透测试和安全审计。dirsearch 提供丰富的选项和灵活的配置文件支持，允许用户自定义扫描行为。本教程将详细介绍 dirsearch 的安装、使用方法、命令行选项、配置文件设置，以及实际案例和注意事项，旨在帮助初学者和专业人士高效使用此工具。
在这里插入图片描述

1. dirsearch 简介

dirsearch 的主要功能是通过字典暴力破解，扫描目标 Web 服务器的目录和文件。它支持多线程、递归扫描、自定义扩展名、代理设置等功能，适用于多种场景：

  • 渗透测试：快速定位后台（/admin）、备份文件（.bak/.zip）、配置文件（.env/config.php）；
  • 漏洞挖掘：发现未授权 API（/api/v1）、测试页面（/test）、源码泄露路径；
  • 资产测绘：梳理企业 Web 资产暴露面，识别遗留系统与敏感入口；
  • CTF 竞赛：快速枚举隐藏路径，定位 flag 所在文件 / 目录。

关键特性

  • 多线程异步扫描：支持自定义线程数，并发高效发包，缩短扫描时间；
  • 超多目标导入方式：支持单个URL、URL列表文件、标准输入、CIDR网段、Nmap报告、原始HTTP请求导入；
  • 完善字典体系：内置多分类字典，支持自定义字典、扩展名替换、前缀后缀追加、大小写变换；
  • 全维度结果过滤：支持状态码、响应大小、页面文本、正则、重定向、404相似度多重过滤，降低误报；
  • 多层递归扫描：普通递归、深度递归、强制递归，可自定义递归深度与允许递归状态码；
  • 完整请求自定义：支持自定义HTTP请求方法、POST数据、请求头、Cookie、随机UA、各类身份认证；
  • 网络环境适配：支持超时设置、请求延迟、多代理、代理池、Tor匿名网络、请求失败重试、指定网卡；
  • 丰富输出格式：支持普通文本、JSON、XML、Markdown、CSV、HTML、SQLite、MySQL、PostgreSQL多格式导出；
  • 全局配置文件：支持config.ini全局默认配置，一次配置永久生效，无需每次命令行重复输参数；
  • 会话断点续扫：支持扫描会话保存、列出会话、断点继续扫描，避免长时间扫描中断重跑。

2. 同类工具对比优势

对比维度 dirsearch dirb gobuster
开发语言 Python3（跨平台易扩展） C（编译型，扩展性弱） Go（高性能，配置灵活度低）
多线程 支持（默认 25 线程，可自定义） 单线程 支持
递归扫描 深度递归/强制递归，可限制深度 基础递归 基础递归
过滤规则 状态码/大小/文本/正则/响应相似度 仅状态码 状态码/大小
输出格式 10+ 种（含数据库写入） 文本/XML 文本/JSON/CSV
字典管理 内置多分类字典，支持自定义前缀/后缀/大小写 基础字典 需手动指定字典

版本迭代与最新特性

dirsearch 持续迭代更新，v0.4.4（2025 年 2 月） 为最新稳定版，核心更新如下：

  • 新增 MySQL/PostgreSQL 数据库直接写入功能，支持结果持久化到数据库；
  • 优化 HTML 报告，新增结果排序功能，提升可读性；
  • 修复请求头默认值错误、递归扫描深度限制失效等关键 bug；
  • 扩展内置字典，新增 Swagger v1/v2/v3、Oracle eBusiness 相关路径；
  • 支持配置项列表类型值，增强 config.ini 灵活性。

3. 安装 dirsearch

方法 1：Git 源码安装(推荐)

  1. 克隆官方仓库： 
    git clone https://github.com/maurosoria/dirsearch.git --depth 1
cd dirsearch
  2. 安装到全局路径（使用uv）： 
    uv tool install .

方法 2：通过 PyPI

pip3 install dirsearch

但是可能会出现依赖问题，不建议。

方法 3：Docker 安装

  1. 拉取 Docker 镜像： 
    docker pull maurosoria/dirsearch
  2. 运行容器： 
    docker run -it --rm maurosoria/dirsearch -u https://target.com

方法 4：APT 安装(废弃)

Kali Linux 等发行版可以通过 apt install dirsearch 直接安装 dirsearch，但是版本老旧。

Kali 默认配置文件路径：/etc/dirsearch/config.ini
Kali 默认字典路径：/usr/share/dirsearch/db/

验证安装

安装完成后，运行以下命令检查版本和帮助：

python3 dirsearch.py --version
python3 dirsearch.py --help

4. dirsearch 命令行选项设置

dirsearch 提供丰富的命令行选项，用于覆盖配置文件或临时调整扫描行为。以下是主要选项的分类和说明。

如需查看更详细的配置说明，可跳转我的这篇文章：dirsearch 命令行选项详解

4.1 基本选项

  • -u, --url <URL>：指定目标 URL（必填）。 
    python3 dirsearch.py -u https://example.com
  • -l, --url-list <FILE>：从文件中读取多个目标 URL。 
    python3 dirsearch.py -l urls.txt
  • -e, --extensions <EXT>：指定文件扩展名，覆盖默认值。 
    python3 dirsearch.py -u https://example.com -e php,html,txt
  • -x, --exclude-extensions <EXT>：排除特定扩展名。 
    python3 dirsearch.py -u https://example.com -x log,old

4.2 字典选项

  • -w, --wordlist <FILE>：指定字典文件路径。 
    python3 dirsearch.py -u https://example.com -w /path/to/wordlist.txt
  • -f, --force-extensions：强制为每个路径添加扩展名。 
    python3 dirsearch.py -u https://example.com -e php -f
  • --prefixes <PREFIX>：为字典项添加前缀。 
    python3 dirsearch.py -u https://example.com --prefixes admin,.
  • --suffixes <SUFFIX>：为字典项添加后缀。 
    python3 dirsearch.py -u https://example.com --suffixes ~,.bak

4.3 请求选项

  • -m, --http-method <METHOD>：指定 HTTP 方法（GET、POST、HEAD 等）。 
    python3 dirsearch.py -u https://example.com -m HEAD
  • -H, --header <HEADER>：添加自定义请求头。 
    python3 dirsearch.py -u https://example.com -H "Authorization: Bearer token"
  • --user-agent <UA>：自定义 User-Agent。 
    python3 dirsearch.py -u https://example.com --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  • --cookie <COOKIE> nationalities：设置 Cookie。 
    python3 dirsearch.py -u https://example.com --cookie "SESSIONID=123"

4.4 连接选项

  • -t, --threads <NUM>：设置线程数。 
    python3 dirsearch.py -u https://example.com -t 50
  • --timeout <SEC>：设置请求超时时间。 
    python3 dirsearch.py -u https://example.com --timeout 10
  • --proxy <PROXY>：指定代理服务器。 
    python3 dirsearch.py -u https://example.com --proxy http://localhost:8080
  • --max-rate <RATE>：限制每秒请求数。 
    python3 dirsearch.py -u https://example.com --max-rate 100

4.5 过滤选项

  • --include-status <CODES>：仅显示指定状态码的结果。 
    python3 dirsearch.py -u https://example.com --include-status 200,301
  • --exclude-status <CODES>：排除指定状态码的结果。 
    python3 dirsearch.py -u https://example.com --exclude-status 404,500
  • --exclude-sizes <SIZES>：排除特定大小的响应。 
    python3 dirsearch.py -u https://example.com --exclude-sizes 0b,1kb
  • --exclude-text <TEXT>：排除包含特定文本的响应。 
    python3 dirsearch.py -u https://example.com --exclude-text "Not Found"

4.6 输出选项

  • -o, --output <FILE>：指定输出文件。 
    python3 dirsearch.py -u https://example.com -o results.txt
  • --format <FORMAT>：指定输出格式（plain、json、xml 等）。 
    python3 dirsearch.py -u https://example.com --format json -o results.json
  • --quiet：启用安静模式，仅输出结果。 
    python3 dirsearch.py -u https://example.com --quiet

4.7 高级选项

  • -r, --recursive：启用递归扫描。 
    python3 dirsearch.py -u https://example.com -r
  • --deep-recursive：启用深度递归。 
    python3 dirsearch.py -u https://example.com --deep-recursive
  • --crawl：启用爬虫模式，解析页面链接。 
    python3 dirsearch.py -u https://example.com --crawl
  • --random-agent：随机选择 User-Agent。 
    python3 dirsearch.py -u https://example.com --random-agent

5. 实际使用案例

案例 1：基本目录扫描

扫描目标网站的常见目录和文件，使用内置所有拓展名：

python3 dirsearch.py -u https://example.com -e*
  • 扫描扩展名为 .php, .jsp, .asp, .aspx, .do, .action, .cgi, .html, .htm, .js, .tar.gz 的文件。
  • 使用默认字典（db/dict.txt）和 25 个线程。

案例 2：自定义字典与代理

扫描特定子目录，使用自定义字典并通过代理：

python3 dirsearch.py -u https://example.com/admin从/admin/ -w /path/to/custom_dict.txt -e php --proxy http://localhost:8080
  • 扫描 /admin/ 子目录。
  • 使用自定义字典和代理服务器。

案例 3：递归扫描与结果过滤

启用递归扫描，仅显示特定状态码并输出 JSON 报告：

python3 dirsearch.py -u http://example.com -r -i 200,300-399 -o results.json --format json
  • 显示 200 和 300-399 状态码。
  • 输出 JSON 格式报告。

案例 4：高并发与速率限制

高线程扫描，同时限制请求速率以避免触发防御：

python3 dirsearch.py -u https://example.com -t 100 --max-rate 50 --timeout 10
  • 使用 100 个线程，每秒最多 50 个请求。
  • 设置 10 秒超时。

案例 5：结合 Burp Suite 进行深入测试

通过 Burp Suite 代理进行扫描并启用爬虫模式：

python3 dirsearch.py -u https://example.com --proxy http://127.0.0.1:8080 -e php,asp --crawl
  • 启用爬虫模式，解析页面链接。
  • 流量通过 Burp Suite 代理，便于手动分析。

案例 6：深度优化与自定义配置

递归扫描，限制深度并排除特定子目录，添加自定义请求头：

python3 dirsearch.py -u http://example.com -r -R 3 --exclude-subdirs logs,static -e* -H "X-API-Key: abc123" -f
  • 递归扫描，最大深度 3。
  • 排除 logs 和 static 子目录。
  • 添加自定义请求头 X-API-Key: abc123。

6. dirsearch配置文件设置

dirsearch 默认配置文件（Kali 路径：/etc/dirsearch/config.ini）定义全局扫描行为，优先级低于命令行参数，可通过 --config 指定自定义配置文件。

作用：预先定义所有扫描默认参数，不用每次命令行重复敲参数

整个配置文件分为7大分区，下面逐块逐配置项精讲含义与实战用途。

6.1 [general] 全局通用配置区

控制线程、递归、状态码、扫描时长、会话行为等核心全局规则

  • threads = 25：默认扫描线程25，可改为30/50适配自己习惯；
  • recursive = False：默认关闭递归，需要递归再命令行加-r或改配置；
  • deep-recursive = False：默认关闭深度递归，避免默认扫描流量过大；
  • force-recursive = False：默认关闭强制递归，防止无效请求泛滥；
  • recursion-status = 200-399,401,403：定义哪些状态码允许往下递归；
  • max-recursion-depth = 0：0代表不限制递归深度，可改为2/3固定层级；
  • exclude-subdirs：预设递归时自动排除的垃圾目录（编码目录、上级目录符号等），无需手动过滤；
  • max-time = 0：默认无全局扫描超时；
  • exit-on-error = False：遇到单个目标错误不终止整体批量扫描。

6.2 [dictionary] 字典默认配置区

预设字典、扩展名、大小写、前后缀全局默认规则

  • default-extensions = php,aspx,jsp,html,js：未用-e指定后缀时，默认使用这组后缀；
  • force-extensions = False：默认不强制全量追加后缀；
  • overwrite-extensions = False：默认不覆盖字典原有后缀；
  • lowercase/uppercase/capitalization：默认不做大小写转换，保持字典原样；
  • 可手动开启 prefixes/suffixes 全局默认前后缀，永久生效不用每次命令行加。

6.3 [request] 请求默认配置区

预设HTTP请求方式、重定向、请求头、Cookie全局默认值

  • http-method = get：默认请求方法GET；
  • follow-redirects = False：默认不自动跟随重定向；
  • 可在配置内写入默认headers、user-agent、cookie，全局所有扫描自动携带，不用重复指定。

6.4 [connection] 网络连接默认配置区

预设超时、延迟、代理、重试、Tor全局网络行为

  • timeout = 7.5：默认请求超时；
  • delay = 0：默认无请求延迟；
  • max-retries = 1：默认失败重试1次；
  • 可写入默认proxy、proxy-auth，全局默认走代理扫描。

6.5 [advanced] 高级配置区

  • crawl = False：默认关闭页面爬虫，需要自动爬链接再手动开启。

6.6 [view] 视图显示配置区

预设终端输出样式、颜色、静默模式
可默认开启 full-url、关闭颜色、默认安静模式，适配个人使用习惯。

6.7 [output] 输出报告配置区

预设默认导出格式、日志路径、报告保存位置
可设置默认输出html/md格式，每次扫描自动生成报告，无需命令行手动指定。

默认配置文件解析

# dirsearch Default Configuration (/etc/dirsearch/config.ini)
# Comments after `#` are ignored

[general]
threads = 25                    # 线程数，控制并发请求数量
recursive = False               # 是否启用递归扫描（扫描发现的目录）
deep-recursive = False          # 是否深度递归（递归所有子目录）
force-recursive = False         # 是否强制递归（忽略状态码限制）
recursion-status = 200-399,401,403  # 递归扫描的状态码范围
max-recursion-depth = 0         # 最大递归深度（0 表示无限制）
exclude-subdirs = %ff/,.;/,..;/,;/,./,../,%2e/,%2e%2e/  # 排除的子目录（如 .git、.. 等）
random-user-agents = False      # 是否随机选择 User-Agent
max-time = 0                    # 最大扫描时间（秒，0 表示无限制）
exit-on-error = False           # 遇到错误时是否退出
# subdirs = /,api/              # 附加扫描的子目录
# include-status = 200-299,401  # 仅显示指定状态码的结果
# exclude-status = 400,500-999  # 排除指定状态码的结果
# exclude-sizes = 0b,123gb      # 排除指定大小的响应
# exclude-text = "Not found"    # 排除包含特定文本的响应
# exclude-regex = "^403$"       # 排除匹配正则表达式的响应
# exclude-redirect = "*/error.html"  # 排除重定向到特定 URL 的响应
# exclude-response = 404.html    # 排除与指定页面内容相同的响应
# skip-on-status = 429,999      # 遇到指定状态码时跳过扫描

[dictionary]
default-extensions = php,aspx,jsp,html,js  # 默认扫描的文件扩展名
force-extensions = False         # 是否强制为每个路径添加扩展名
overwrite-extensions = False     # 是否覆盖默认扩展名
lowercase = False               # 是否将字典转换为小写
uppercase = False               # 是否将字典转换为大写
capitalization = False           # 是否将字典首字母大写
# exclude-extensions = old,log   # 排除的扩展名
# prefixes = .,admin             # 添加到字典项前缀
# suffixes = ~,.bak             # 添加到字典项后缀
# wordlists = /path/to/wordlist1.txt,/path/to/wordlist2.txt  # 自定义字典路径

[request]
http-method = get               # HTTP 请求方法（GET、HEAD 等）
follow-redirects = False        # 是否跟随重定向
# headers-file = /path/to/headers.txt  # 自定义请求头文件
# user-agent = MyUserAgent      # 自定义 User-Agent
# cookie = SESSIONID=123        # 自定义 Cookie

[connection]
timeout = 7.5                   # 请求超时时间（秒）
delay = 0                       # 每个请求之间的延迟（秒）
max-rate = 0                    # 最大请求速率（每秒，0 表示无限制）
max-retries = 1                 # 最大重试次数
# scheme = http                 # 协议（http 或 https，注释后自动检测）
# proxy = localhost:8080        # 代理服务器地址
# proxy-file = /path/to/proxies.txt  # 代理列表文件
# replay-proxy = localhost:8000  # 重放请求的代理

[advanced]
crawl = False                   # 是否启用爬虫模式（解析页面链接）

[view]
full-url = False                # 是否显示完整 URL（而非路径）
quiet-mode = False              # 是否启用安静模式（仅输出结果）
color = True                    # 是否启用彩色输出
show-redirects-history = False   # 是否显示重定向历史

[output]
report-format = plain           # 报告格式（plain、json、xml、csv 等）
autosave-report = True          # 是否自动保存报告
autosave-report-folder = reports/  # 报告保存目录
# log-file = /path/to/dirsearch.log  # 日志文件路径
# log-file-size = 50000000      # 日志文件最大大小（字节）

7. 注意事项与最佳实践

  1. 合法性：

    • 仅对有权限的目标进行扫描，未经授权的扫描可能违法。
    • 在测试前获得书面许可（如渗透测试合同）。

  2. 避免触发防御：

    • 降低线程数和请求速率，模拟正常用户行为。
    • 使用 --random-agent 或自定义 User-Agent。
    • 遇到 429（Too Many Requests）时，启用 --skip-on-status 429。

  3. 优化字典：

    • 使用针对目标技术栈的字典（如 WordPress、Drupal）。
    • 推荐字典来源：SecLists（https://github.com/danielmiessler/SecLists）。

  4. 备份配置文件：

    • 修改 /etc/dirsearch/config.ini 前备份： 
      sudo cp /etc/dirsearch/config.ini /etc/dirsearch/config.ini.bak

  5. 日志和报告管理：

    • 定期清理 reports/ 和 logs/ 目录，避免占用磁盘空间。
    • 示例：删除旧报告： 
      rm -rf reports/*

  6. 结合其他工具：

    • 使用 Burp Suite 捕获 dirsearch 流量，分析响应。
    • 结合 gobuster 或 ffuf 进行交叉验证。

8. 常见问题与解决方法

  • 问题：使用时有如下报错：

    /usr/lib/python3/dist-packages/dirsearch/dirsearch.py:23: DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
from pkg_resources import DistributionNotFound, VersionConflict

    • 原因：pkg_resources 弃用警告是由于 dirsearch 使用了过时的 Python API 引起的，目前不影响工具功能。

    • 如何屏蔽警告：
      使用 Python 的 -W 参数过滤 DeprecationWarning：

    python3 -W ignore::DeprecationWarning /usr/lib/python3/dist-packages/dirsearch/dirsearch.py -u https://example.com

    或设置环境变量 PYTHONWARNINGS：

    export PYTHONWARNINGS="ignore::DeprecationWarning"

  • 问题：扫描速度慢或频繁超时。

    • 解决：
      • 增加线程数：-t 50
      • 调整超时时间：--timeout 15
      • 使用更小的字典：-w small_dict.txt

  • 问题：目标返回大量 403/404。

    • 解决：
      • 过滤无用结果：--exclude-status 403,404
      • 检查是否需要 Cookie 或自定义头：-H "Authorization: Bearer token"

  • 问题：代理配置无效。

    • 解决：
      • 验证代理是否运行：curl --proxy http://localhost:8080 https://example.com
      • 检查配置文件中的 proxy 格式。
# 网络安全
Logo
openEuler 社区

openEuler 是由开放原子开源基金会孵化的全场景开源操作系统项目，面向数字基础设施四大核心场景（服务器、云计算、边缘计算、嵌入式），全面支持 ARM、x86、RISC-V、loongArch、PowerPC、SW-64 等多样性计算架构

更多推荐

cover

开发阶段代码保护怎么做？静态反编译+动态调试防护

avatar openEuler 社区

【2-64G云服务器盘点】持续更新，各大厂云服务器对比选择

所以，写下这篇文章，制成excel汇总表，供大家参考，包括了京东云、阿里云、腾讯云3大厂商（别的小厂怕跑路hhh，别贪图便宜选不知名小厂，到时候跑路服务器连不上，数据丢了，丢了西瓜捡了芝麻，大厂稳定性高，价格首购1年3年也很划算）。99元/年，关键在续费同价，可续2次，也就是297用三年，很合适，对比京东云价格一摸一样。我就像一个互联网的猹，在京东云、阿里云、腾讯云的官网里反复对比、反复横跳，但不

avatar openEuler 社区

【2-64G云服务器盘点】持续更新，各大厂云服务器对比选择

所以，写下这篇文章，制成excel汇总表，供大家参考，包括了京东云、阿里云、腾讯云3大厂商（别的小厂怕跑路hhh，别贪图便宜选不知名小厂，到时候跑路服务器连不上，数据丢了，丢了西瓜捡了芝麻，大厂稳定性高，价格首购1年3年也很划算）。99元/年，关键在续费同价，可续2次，也就是297用三年，很合适，对比京东云价格一摸一样。我就像一个互联网的猹，在京东云、阿里云、腾讯云的官网里反复对比、反复横跳，但不

avatar openEuler 社区