dirsearch 使用教程：详细指南与配置解析

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

---

1. dirsearch 简介

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

• 渗透测试：发现隐藏的管理后台、配置文件或其他敏感资源。
• 安全审计：检查 Web 服务器是否存在不当暴露的目录或文件。
• 漏洞挖掘：结合其他工具（如 Burp Suite），定位潜在漏洞点。

关键特性

• 多线程扫描：支持高并发，提高扫描效率。
• 灵活的规则配置：通过配置文件或命令行选项自定义扫描行为。
• 多种输出格式：支持 plain、JSON、XML、CSV 等格式，便于结果分析。
• 代理支持：可通过代理扫描，适合匿名测试。
• 递归扫描：自动深入子目录，发现更多资源。
• 过滤机制：基于状态码、文件大小或响应内容过滤结果。

2. 安装 dirsearch

2.1 环境要求

• 操作系统：Linux、Windows、macOS
• Python 版本：Python 3.6 或更高
• 依赖：无额外依赖，dirsearch 包含所有必要库

2.2 安装方法

方法 1：通过 Git 克隆

1. 克隆官方仓库：

   git clone https://github.com/maurosoria/dirsearch.git
   cd dirsearch
   

2. 安装（可选，复制到系统路径）：

   sudo pip3 install .
   

3. 运行：

   python3 dirsearch.py --help
   

方法 2：通过 PyPI

1. 使用 pip 安装：

   pip3 install dirsearch
   

2. 验证安装：

   dirsearch --help
   

方法 3：Docker 安装

1. 拉取 Docker 镜像：

   docker pull maurosoria/dirsearch
   

2. 运行容器：

   docker run -it --rm maurosoria/dirsearch -u https://target.com
   

方法 4：Kali Linux

Kali Linux 可以通过 apt install dirsearch 直接安装 dirsearch。

2.3 验证安装

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

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

3. dirsearch 默认配置文件解析

dirsearch 的默认配置文件（Kali Linux下位于/etc/dirsearch/config.ini） 定义了全局扫描行为。以下是默认配置文件内容的详细解析，我会结合实际用途说明每个选项的作用。

# 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      # 日志文件最大大小（字节）

配置文件关键选项解析

• threads：控制并发线程数，默认 25。增加线程可提高速度，但可能触发目标服务器的防御机制（如 429 状态码）。
• recursive：启用后，dirsearch 会扫描发现的子目录。适合深度挖掘，但可能增加扫描时间。
• default-extensions：指定默认扫描的文件扩展名（如 .php、.html）。可根据目标技术栈调整。
• http-method：默认使用 GET 请求，可改为 HEAD 减少流量，或 POST 用于特定场景。
• timeout：请求超时时间，7.5 秒适合大多数场景。网络不稳定时可适当增加。
• report-format：输出格式，plain 适合快速查看，json 或 csv 适合后续分析。
• exclude-subdirs：排除常见无关目录（如 .git/、..），减少无效请求。

修改配置文件

1. 定位配置文件：

   • 默认位置：/etc/dirsearch/config.ini（系统安装）或 dirsearch/config.ini（Git 克隆）。
   • 检查：

     ls /etc/dirsearch/
     ls /path/to/dirsearch/
     

2. 编辑配置文件：

   • 使用文本编辑器（如 nano、vim）：

     sudo nano /etc/dirsearch/config.ini
     

   • 示例：增加线程数并启用递归扫描：

     [general]
     threads = 50
     recursive = True
     

3. 验证配置：

   • 运行 dirsearch 测试：

     python3 dirsearch.py -u https://example.com --config=/etc/dirsearch/config.ini
     

4. 自定义配置文件：

   • 复制默认配置文件到用户目录：

     mkdir ~/.dirsearch
     cp /etc/dirsearch/config.ini ~/.dirsearch/config.ini
     

   • 设置环境变量：

     export DIRSEARCH_CONFIG=~/.dirsearch/config.ini
     

4. 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. 配置文件设置与优化

6.1 优化线程和速率

• 场景：目标服务器对高并发敏感。
• 配置：

  [general]
  threads = 10
  max-rate = 20
  

• 减少线程数（threads）和请求速率（max-rate），降低被封禁风险。

6.2 自定义扩展名和字典

• 场景：目标使用特定技术栈（如 ASP.NET）。
• 配置：

  [dictionary]
  default-extensions = aspx,asp,config
  wordlists = /path/to/aspnet_wordlist.txt
  

• 设置 ASP.NET 相关扩展名，使用专用字典。

6.3 启用递归扫描

• 场景：需要深入扫描子目录。
• 配置：

  [general]
  recursive = True
  recursion-status = 200-299,301
  max-recursion-depth = 3
  

• 启用递归，仅扫描返回 200-299 和 301 状态码的目录，限制深度为 3 层。

6.4 配置代理

• 场景：需要匿名扫描或通过本地代理。
• 配置：

  [connection]
  proxy = http://localhost:8080
  

• 设置代理服务器（如 Burp Suite 或 Tor）。

6.5 自定义输出

• 场景：需要 JSON 格式报告便于自动化处理。
• 配置：

  [output]
  report-format = json
  autosave-report-folder = /home/user/dirsearch_reports/
  

• 输出 JSON 报告，保存到指定目录。

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 格式。