当前位置：首页 > news >正文

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

news 来源：原创 2025/6/28 19:43:01

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 克隆

克隆官方仓库：

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

安装（可选，复制到系统路径）：
```
sudo pip3 install .
```
运行：
```
python3 dirsearch.py --help
```

方法 2：通过 PyPI

使用 pip 安装：
```
pip3 install dirsearch
```
验证安装：
```
dirsearch --help
```

方法 3：Docker 安装

拉取 Docker 镜像：
```
docker pull maurosoria/dirsearch
```

运行容器：

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/、..），减少无效请求。

修改配置文件

定位配置文件：
- 默认位置：/etc/dirsearch/config.ini（系统安装）或 dirsearch/config.ini（Git 克隆）。
- 检查：
```
ls /etc/dirsearch/
ls /path/to/dirsearch/
```
编辑配置文件：
- 使用文本编辑器（如 nano、vim）：
```
sudo nano /etc/dirsearch/config.ini
```
- 示例：增加线程数并启用递归扫描：
```
[general]
threads = 50
recursive = True
```

验证配置：

运行 dirsearch 测试：

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

自定义配置文件：

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

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/

7. 注意事项与最佳实践

合法性：
- 仅对有权限的目标进行扫描，未经授权的扫描可能违法。
- 在测试前获得书面许可（如渗透测试合同）。
避免触发防御：
- 降低线程数和请求速率，模拟正常用户行为。
- 使用 --random-agent 或自定义 User-Agent。
- 遇到 429（Too Many Requests）时，启用 --skip-on-status 429。
优化字典：
- 使用针对目标技术栈的字典（如 WordPress、Drupal）。
- 推荐字典来源：SecLists（https://github.com/danielmiessler/SecLists）。

备份配置文件：

修改 /etc/dirsearch/config.ini 前备份：

sudo cp /etc/dirsearch/config.ini /etc/dirsearch/config.ini.bak

日志和报告管理：
- 定期清理 reports/ 和 logs/ 目录，避免占用磁盘空间。
- 示例：删除旧报告：
```
rm -rf reports/*
```
结合其他工具：
- 使用 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 格式。