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

克隆官方倉庫：

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