S1YOL/W3BSPID3R
GitHub: S1YOL/W3BSPID3R
一款专为 CI/CD 和企业安全审计设计的 Python Web 漏洞扫描器，支持自动化检测 OWASP 漏洞并生成多种格式报告。
Stars: 1 | Forks: 0
# W3BSP1D3R
**使用 Python 构建的 Web 漏洞扫描器 —— 包含 17 个测试模块、5 种报告格式、YAML 配置文件、企业级认证、插件系统、REST API 和结构化日志。专为实验室、授权渗透测试和 CI/CD 流水线构建。**
```
╦ ╦╔═╗╔╗ ╔═╗╔═╗╦╔╦╗╔═╗╦═╗
║║║ ═╣╠╩╗╚═╗╠═╝║ ║║ ═╣╠╦╝
╚╩╝╚═ ╚═╝╚═╝╩ ╩═╩╝╚═ ╩╚═
```
[](https://www.python.org/downloads/)
[](LICENSE)
[](#)
[](#running-tests)
[](#)
## 法律免责声明
## v2.0.0 版本更新内容
| 功能 | 描述 |
|---------|-------------|
| **YAML 配置文件** | 通过 `--config` 和 `--profile` 加载可复用的配置 |
| **企业级认证** | OAuth2, NTLM, API key, 自定义 Header 认证 |
| **结构化 JSON 日志** | 适配 SIEM/ELK 的 `--log-format json` 输出 |
| **扫描范围控制** | `--include` 和 `--exclude` URL 模式匹配 |
| **发现结果去重** | 自动 SHA-256 指纹识别以消除重复项 |
| **检查点/恢复** | 通过 `--checkpoint` 为长时间扫描提供崩溃恢复 |
| **审计追踪** | 通过 `--audit-log` 进行符合合规要求的审计日志记录 |
| **历史数据库** | 通过 `--database` 使用 SQLite 进行趋势追踪 |
| **插件系统** | 通过 `--plugins-dir` 加载自定义测试器 |
| **PDF 报告** | 通过 `fpdf2` 原生生成 PDF |
| **报告差异/比较** | 使用 `--compare-with` 比较扫描结果 |
| **REST API 服务器** | 通过 `--api-server` 进行远程控制 |
| **Webhook 通知** | Slack, Teams, Discord 和自定义 webhook 告警 |
| **速率限制仪表盘** | 通过 `--dashboard` 显示实时终端指标 |
| **异步 HTTP** | 使用 `httpx` 进行高吞吐量扫描 |
| **OWASP Top 10 映射** | 每个发现都映射到 OWASP 2021 类别 |
| **Jira / ServiceNow** | 从发现结果自动创建工单 |
| **邮件通知** | 带有 HTML 格式的 SMTP 扫描报告 |
| **扫描调度器** | 基于 Cron 的周期性扫描 |
| **自定义 Payload** | 从 YAML/JSON 文件加载 payload |
| **Docker 支持** | Dockerfile + docker-compose 用于容器化部署 |
| **GitHub Actions CI** | 在 push/PR 时自动测试和 Lint |
| **API 认证** | REST API 服务器上的 API key 认证 |
| **环境变量** | 完整的 `W3BSP1D3R_*` 环境变量支持 |
## 功能简介
W3BSP1D3R 会爬取目标网站，映射所有的表单和 URL 参数，针对每一个发动攻击 payload，并报告哪些存在漏洞 —— 包含触发漏洞的确切 payload 以及修复建议。
### 测试模块
| 类别 | 模块 |
|----------|---------|
| **注入** | SQL 注入 (报错型, UNION, 布尔盲注, 时间盲注) · NoSQL 注入 · 命令注入 · SSTI |
| **客户端** | 反射型 XSS · 存储型 XSS · CSRF · 开放重定向 |
| **访问控制** | 路径遍历 · IDOR · 敏感文件暴露 (`.env`, `.git/`, 备份文件, 管理面板) |
| **配置** | 安全头 · Cookie 安全性 · CORS 错误配置 · SSL/TLS · WAF 检测 |
| **侦查** | 子域名枚举 · CVE 查询 (NVD) · VirusTotal 威胁情报 |
### 检测质量
这不是一个简单的字符串匹配扫描器。它使用真实的检测技术来最大限度地减少误报：
- **基线对比** —— 在注入之前获取干净的响应，跳过正常输出中已存在的错误特征
- **三步布尔 SQLi** —— TRUE 必须匹配基线 并且 FALSE 必须不同，外加一个二次检查门
- **结构化 XSS 验证** —— 确认 payload 元素（标签、事件处理器）在响应中经过编码后依然存在
- **正则确认的命令注入** —— 匹配 `uid=\d+\(\w+\) gid=\d+` 格式，而不仅仅是子字符串 "uid="
- **SSRF 保护** —— 扫描器本身会阻止重定向到私有 IP 和超出范围的源
- **XXE 安全的 XML 解析** —— sitemap 解析使用 defusedxml 以防止扫描器受到攻击
- **发现结果去重** —— SHA-256 指纹防止同一个漏洞被报告两次
## 系统要求
- **Python 3.10 或更新版本**
- **pip** (随 Python 附带)
- **Docker** (可选 —— 仅在运行 DVWA / Juice Shop 目标时需要)
- **Git** (可选 —— 您也可以下载 .zip)
### 检查 Python 版本
```
python3 --version # Linux / macOS
python --version # Windows
```
如果您没有安装 Python，请从 [python.org](https://www.python.org/downloads/) 下载。
## 安装说明
### 方式 1: Git Clone (全平台)
```
git clone https://github.com/S1YOL/W3BSPID3R.git
cd W3BSP1D3R
```
### 方式 2: 从 Releases 下载
前往 [Releases](https://github.com/S1YOL/W3BSPID3R/releases) 并下载：
- **Windows** → `W3BSP1D3R-beta.zip` — 右键点击 → 全部解压缩
- **macOS / Linux** → `W3BSP1D3R-beta.tar.gz` — 使用 `tar -xzf W3BSP1D3R-beta.tar.gz` 解压
然后 `cd` 进入解压后的文件夹。
## 配置
### Linux
```
chmod +x setup.sh
./setup.sh
source venv/bin/activate
```
或者手动执行：
```
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### macOS
```
chmod +x setup.sh
./setup.sh
source venv/bin/activate
```
或者手动执行：
```
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
### Windows (命令提示符)
```
setup.bat
venv\Scripts\activate
```
或者手动执行：
```
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
```
### Windows (PowerShell)
```
.\setup.bat
.\venv\Scripts\Activate.ps1
```
### 验证是否正常工作 (全平台)
```
python main.py --help
```
您应该看到包含所有可用选项的完整帮助输出。如果看到错误，请确保您的虚拟环境已激活（您应该在终端提示符的开头看到 `(venv)`）。
## 设置扫描目标
您需要一个故意存在漏洞的应用程序进行扫描。**未经明确授权，请勿扫描任何系统。作者不对因未经授权使用而产生的任何后果负责。**
### DVWA (推荐新手使用)
需要 [Docker](https://docs.docker.com/get-docker/)。
```
docker run --rm -d -p 80:80 --name dvwa vulnerables/web-dvwa
```
前往 `http://localhost/dvwa/setup.php` → 点击 **Create / Reset Database** → 使用 `admin` / `password` 登录。
### OWASP Juice Shop
```
docker run --rm -d -p 3000:3000 --name juiceshop bkimminich/juice-shop
```
### 同时运行两者 (Docker Compose)
```
# docker-compose.yml
version: "3.9"
services:
dvwa:
image: vulnerables/web-dvwa
ports: ["80:80"]
juiceshop:
image: bkimminich/juice-shop
ports: ["3000:3000"]
```
```
docker compose up -d
```
## 使用方法
### 运行您的第一次扫描
**Linux / macOS:**
```
python main.py \
--url http://localhost/dvwa \
--login-user admin \
--login-pass password \
--scan-type full
```
**Windows (命令提示符):**
```
python main.py --url http://localhost/dvwa --login-user admin --login-pass password --scan-type full
```
**Windows (PowerShell):**
```
python main.py `
--url http://localhost/dvwa `
--login-user admin `
--login-pass password `
--scan-type full
```
扫描器将会：
1. 自动登录 DVWA
2. 爬取网站以查找所有页面和表单
3. 测试它发现的所有内容
4. 在终端打印彩色编码的发现结果
5. 保存报告：`scan_report.md`, `scan_report.html`, `scan_report.json`, `scan_report.sarif`
在浏览器中打开 `scan_report.html` 查看易读的报告。
### 速查表
| 需求 | 命令 |
|---------------|---------|
| 完整扫描 (所有内容) | `python main.py --url http://localhost/dvwa --login-user admin --login-pass password` |
| 仅 SQL 注入 | `python main.py --url http://localhost/dvwa --scan-type sqli` |
| 仅 XSS | `python main.py --url http://localhost/dvwa --scan-type xss` |
| 仅被动模式 (无 payload) | `python main.py --url http://localhost/dvwa --scan-type passive` |
| 自定义报告名称 | `python main.py --url http://localhost/dvwa --output reports/my_scan` |
| 详细日志 | `python main.py --url http://localhost/dvwa --verbose` |
| 通过 Burp Suite 代理 | `python main.py --url http://localhost/dvwa --proxy http://127.0.0.1:8080` |
| JWT/API token 认证 | `python main.py --url http://api.example.com --auth-token eyJhbG...` |
| VirusTotal 威胁情报 | `python main.py --url http://target.com --vt-api-key YOUR_KEY` |
| CVE 查询 | `python main.py --url http://localhost/dvwa --nvd-api-key YOUR_KEY` |
| 自签名 HTTPS 证书 | `python main.py --url https://localhost:8443 --no-verify-ssl` |
| 慢速礼貌扫描 | `python main.py --url http://localhost/dvwa --delay 2.0 --threads 1` |
| CI/CD — 高危及以上则失败 | `python main.py --url http://localhost/dvwa --fail-on high` |
| 使用 YAML 配置 | `python main.py --config w3bsp1d3r.yaml` |
| 使用带 profile 的配置 | `python main.py --config w3bsp1d3r.yaml --profile thorough` |
| PDF + 所有报告格式 | `python main.py --url http://localhost/dvwa --formats html md json sarif pdf` |
| 与之前的扫描对比 | `python main.py --url http://localhost/dvwa --compare-with previous_scan.json` |
| 启动 REST API 服务器 | `python main.py --api-server --api-port 8888` |
| 实时仪表盘 | `python main.py --url http://localhost/dvwa --dashboard` |
### Streamlit GUI
```
pip install streamlit
streamlit run gui.py
```
## YAML 配置文件
无需传递数十个 CLI 参数，您可以在 YAML 文件中定义扫描配置。参阅 [`w3bsp1d3r.example.yaml`](w3bsp1d3r.example.yaml) 获取完整的注释参考。
```
# 复制示例并进行自定义
cp w3bsp1d3r.example.yaml w3bsp1d3r.yaml
# 使用配置文件运行
python main.py --config w3bsp1d3r.yaml
# 从命令行覆盖 profile
python main.py --config w3bsp1d3r.yaml --profile thorough
```
### 扫描配置方案 (Scan Profiles)
`--profile` 标志选择针对不同用例优化的预设配置：
| Profile | 线程数 | 延迟 | 最大页面数 | 用例 |
|---------|---------|-------|-----------|----------|
| **quick** | 2 | 0.2s | 10 | 快速冒烟测试，CI 流水线 |
| **standard** | 4 | 0.5s | 50 | 默认 —— 平衡速度和覆盖率 |
| **thorough** | 8 | 1.0s | 500 | 深度扫描，全覆盖，较慢 |
| **stealth** | 1 | 3.0s | 30 | 低速慢跑以避免 WAF/IDS 检测 |
CLI 标志始终优先于配置文件值，配置文件值优先于 profile 默认值。
### 环境变量引用
配置值可以使用 `${VAR_NAME}` 语法引用环境变量，并支持可选的默认值：
```
auth:
oauth2_client_id: ${W3BSP1D3R_OAUTH_CLIENT_ID}
oauth2_client_secret: ${W3BSP1D3R_OAUTH_CLIENT_SECRET}
integrations:
virustotal:
api_key: ${W3BSP1D3R_VT_API_KEY:-}
```
## 企业级认证
W3BSP1D3R v2 支持多种超越简单表单登录的认证方式。
### 基于表单的登录 (默认)
```
python main.py --url http://localhost/dvwa --login-user admin --login-pass password
```
### Bearer / JWT token
```
python main.py --url http://api.example.com --auth-token eyJhbGciOiJIUzI1NiIs...
```
### OAuth2 Client Credentials
```
python main.py --url http://api.example.com \
--auth-type oauth2 \
--oauth2-token-url https://auth.example.com/oauth/token \
--oauth2-client-id YOUR_CLIENT_ID \
--oauth2-client-secret YOUR_CLIENT_SECRET \
--oauth2-scope "read write"
```
### NTLM / Windows Authentication
需要 `pip install requests-ntlm`。
```
python main.py --url http://intranet.corp.local \
--auth-type ntlm \
--login-user admin \
--login-pass password \
--ntlm-domain CORP
```
### API Key 认证
```
python main.py --url http://api.example.com \
--auth-type apikey \
--auth-token "sk-abc123..."
```
### 自定义 Header 认证
```
python main.py --url http://api.example.com \
--auth-type header \
--auth-token "X-Custom-Auth: my-secret-token"
```
### 用于认证的 YAML 配置
所有认证方式均可在 YAML 配置文件中配置：
```
auth:
auth_type: oauth2
oauth2_token_url: https://auth.example.com/oauth/token
oauth2_client_id: ${W3BSP1D3R_OAUTH_CLIENT_ID}
oauth2_client_secret: ${W3BSP1D3R_OAUTH_CLIENT_SECRET}
oauth2_scope: "read write"
```
## 结构化 JSON 日志
对于 SIEM, ELK stack, Splunk 或任何日志聚合平台，W3BSP1D3R 可以输出结构化 JSON 日志。
```
# JSON 日志输出到文件
python main.py --url http://localhost/dvwa \
--log-format json \
--log-file scan.log
# JSON 日志输出到 stdout（通过管道传输到 jq、Logstash 等）
python main.py --url http://localhost/dvwa --log-format json
# 详细模式（DEBUG 级别）
python main.py --url http://localhost/dvwa \
--log-format json \
--verbose \
--log-file scan.log
```
每条日志都是一个 JSON 对象：
```
{
"timestamp": "2026-03-20T14:32:01.123Z",
"level": "WARNING",
"module": "sqli",
"event": "finding_detected",
"severity": "CRITICAL",
"url": "http://localhost/dvwa/vulnerabilities/sqli/",
"parameter": "id",
"method": "GET"
}
```
日志级别：`WARNING` (默认), `DEBUG` (使用 `--verbose`)。
## 扫描范围控制
使用 `--include` 和 `--exclude` glob 模式来控制爬虫和测试器将处理哪些 URL。
```
# 仅扫描 /dvwa/vulnerabilities/ 下的 URL
python main.py --url http://localhost/dvwa \
--include "http://localhost/dvwa/vulnerabilities/*"
# 排除注销和设置页面
python main.py --url http://localhost/dvwa \
--exclude "*/logout*" \
--exclude "*/setup.php*"
# 结合两者
python main.py --url http://localhost/dvwa \
--include "http://localhost/dvwa/vulnerabilities/*" \
--exclude "*/logout*"
```
范围模式也适用于 YAML 配置：
```
target:
url: http://localhost/dvwa
scope:
include:
- "http://localhost/dvwa/vulnerabilities/*"
exclude:
- "*/logout*"
- "*/setup.php*"
```
## 发现结果去重
W3BSP1D3R 使用 SHA-256 指纹自动对发现结果进行去重。每个发现都根据其 URL、参数、漏洞类型和 payload 类别进行哈希处理。如果通过多个爬取路径检测到相同的漏洞，它在报告中只会出现一次。
这对于以下情况特别有用：
- 多个页面共享同一个易受攻击组件的大型站点
- 具有较高 `--max-pages` 值的全面扫描
- 减少 CI/CD 流水线中的噪音
去重功能始终开启，配置。
## 检查点/恢复
长时间运行的扫描可能会因崩溃、网络故障或系统重启而中断。检查点系统将扫描进度保存到磁盘，以便您可以从上次中断的地方恢复。
```
# 启用 checkpointing
python main.py --url http://localhost/dvwa \
--checkpoint \
--max-pages 500
# 恢复中断的扫描（从 checkpoint 目录自动检测）
python main.py --url http://localhost/dvwa --checkpoint
```
检查点文件默认存储在 `.w3bsp1d3r/checkpoints/` 中。完成的扫描会自动清理其检查点文件。
YAML 配置：
```
checkpoint:
enabled: true
directory: .w3bsp1d3r/checkpoints
```
## 审计追踪
出于合规性要求 (SOC 2, ISO 27001, PCI-DSS)，W3BSP1D3R 可以写入每次扫描操作的不可变审计日志。
```
python main.py --url http://localhost/dvwa \
--audit-log .w3bsp1d3r/audit.log
```
审计日志记录：
- 扫描开始/停止时间戳
- 目标 URL 和使用的认证方式
- 执行的每个测试模块
- 发现的漏洞 (严重程度、类型、URL)
- 配置更改和覆盖
- 操作员身份 (来自 OS 用户名)
YAML 配置：
```
audit:
enabled: true
log_file: .w3bsp1d3r/audit.log
```
## 历史数据库
使用本地 SQLite 数据库跟踪随时间变化的漏洞趋势，该数据库存储跨运行的扫描结果。
```
# 启用数据库
python main.py --url http://localhost/dvwa \
--database .w3bsp1d3r/scans.db
# 将当前扫描与历史数据进行比较（启用数据库时自动进行）
```
该数据库支持：
- **趋势追踪** —— 查看漏洞是被修复还是随时间引入
- **回归检测** —— 当以前修复的漏洞再次出现时发出警报
- **指标** —— 某个目标所有扫描中按严重程度统计的总发现数
YAML 配置：
```
database:
enabled: true
path: .w3bsp1d3r/scans.db
```
## 插件系统
在不修改核心代码的情况下，使用自定义漏洞测试器扩展 W3BSP1D3R。
```
# 从目录加载插件
python main.py --url http://localhost/dvwa \
--plugins-dir plugins/
# 从多个目录加载
python main.py --url http://localhost/dvwa \
--plugins-dir plugins/ \
--plugins-dir /opt/company-plugins/
```
### 编写插件
在您的插件目录中创建一个 Python 文件，该文件继承 `BaseTester` 子类：
```
# plugins/my_custom_tester.py
from scanner.testers.base import BaseTester
from scanner.crawler import CrawledPage
from scanner.reporting.models import Finding
class MyCustomTester(BaseTester):
"""Check for a company-specific vulnerability."""
def __init__(self):
super().__init__(name="My Custom Tester")
def run(self, pages: list[CrawledPage]) -> list[Finding]:
for page in pages:
# Your detection logic here
# Use self._inject_form(), self._inject_get_param(), self._log_finding()
pass
return self.findings
```
插件在启动时自动发现。任何继承自 `BaseTester` 的类都会被注册并包含在 `full` 扫描中。
YAML 配置：
```
plugins:
enabled: true
directories:
- plugins
- /opt/shared-plugins
```
## 报告格式
每次扫描都会以您选择的格式生成报告文件：
| 格式 | 文件 | 用例 |
|--------|------|----------|
| **Markdown** | `scan_report.md` | GitHub PR, 漏洞赏金提交, 通过 `pandoc` 转 PDF |
| **HTML** | `scan_report.html` | 自包含的单个文件 —— 在任何浏览器中打开，与客户分享 |
| **JSON** | `scan_report.json` | CI/CD 流水线, SIEM 接收, 自定义工具 |
| **SARIF** | `scan_report.sarif` | GitHub Code Scanning, VS Code SARIF Viewer, CI/CD 安全门禁 |
| **PDF** | `scan_report.pdf` | 执行摘要, 客户交付物, 离线分享 |
默认情况下，扫描生成 HTML, Markdown, JSON 和 SARIF。要包含 PDF 或选择特定格式：
```
# 全部 5 种格式
python main.py --url http://localhost/dvwa --formats html md json sarif pdf
# 仅 PDF
python main.py --url http://localhost/dvwa --formats pdf
# 用于 CI/CD 的 JSON + SARIF
python main.py --url http://localhost/dvwa --formats json sarif
```
## 报告差异/比较
将当前扫描与之前的扫描进行比较，查看变化 —— 新发现、已解决发现和回归。
```
python main.py --url http://localhost/dvwa \
--compare-with previous_scan.json
```
差异报告显示：
- **新发现** —— 基线扫描中不存在的漏洞
- **已解决发现** —— 自基线以来已修复的漏洞
- **持续存在发现** —— 仍然存在的漏洞
- **回归** —— 以前已解决但又重新出现的漏洞
这在 CI/CD 流水线中特别有用，可以捕获新引入的漏洞：
```
# CI/CD 示例：仅对新发现失败
python main.py --url http://staging.example.com \
--compare-with last_known_good.json \
--fail-on high
```
## REST API 服务器
将 W3BSP1D3R 作为 REST API 服务器运行，用于远程扫描管理、与编排工具集成或构建自定义仪表盘。
```
# 启动 API 服务器
python main.py --api-server --api-port 8888
# 启用身份验证（通过环境变量设置 API key）
W3BSP1D3R_API_KEY="your-secret-key" python main.py --api-server --api-port 8888
```
### API 端点
| Method | Endpoint | 描述 |
|--------|----------|-------------|
| `POST` | `/api/v1/scans` | 启动新扫描 |
| `GET` | `/api/v1/scans` | 列出所有扫描 |
| `GET` | `/api/v1/scans/{id}` | 获取扫描状态和结果 |
| `GET` | `/api/v1/scans/{id}/findings` | 获取某次扫描的发现结果 |
| `GET` | `/api/v1/targets` | 列出所有已扫描的目标 |
| `GET` | `/api/v1/stats` | 数据库统计信息 |
| `GET` | `/api/v1/health` | 健康检查 (无需认证) |
### 示例：通过 API 启动扫描
```
curl -X POST http://localhost:8888/api/v1/scans \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secret-key" \
-d '{
"url": "http://localhost/dvwa",
"login_user": "admin",
"login_pass": "password",
"scan_type": "full"
}'
```
### 示例：轮询结果
```
curl http://localhost:8888/api/v1/scans/abc123 \
-H "X-API-Key: your-secret-key"
```
## Webhook 通知
当扫描完成或发现严重漏洞时收到通知。支持 Slack, Microsoft Teams, Discord 和任意 webhook URL。
```
# Slack
python main.py --url http://localhost/dvwa \
--slack-webhook https://hooks.slack.com/services/T00/B00/xxxx
# Microsoft Teams
python main.py --url http://localhost/dvwa \
--teams-webhook https://outlook.office.com/webhook/xxxx
# Discord
python main.py --url http://localhost/dvwa \
--discord-webhook https://discord.com/api/webhooks/xxxx/yyyy
# 自定义 webhook（接收 JSON POST）
python main.py --url http://localhost/dvwa \
--webhook-url https://your-server.com/hooks/w3bsp1d3r
```
单次扫描可以组合多个 webhook。通知内容包括：
- 扫描完成摘要 (按严重程度统计的总发现数)
- 发现严重/高危漏洞时的实时通知
- 扫描失败警报
## 速率限制仪表盘
使用实时终端仪表盘监控扫描进度。
```
python main.py --url http://localhost/dvwa --dashboard
```
仪表盘显示：
- 每秒请求数 (当前 / 平均 / 峰值)
- HTTP 状态码分布
- 已爬取页面 vs 总发现页面
- 活动测试模块及进度
- 速率限制退避事件 (429/503 响应)
- 按严重程度统计的发现数量 (实时更新)
仪表盘使用 Rich 库，在您的终端中与正常输出并排运行。
## 异步 HTTP 客户端
为了对大型目标进行高吞吐量扫描，W3BSP1D3R 可以使用 `httpx` 作为异步 HTTP 后端，替代默认的同步 `requests` 库。
```
# 启用 async 模式
python main.py --url http://localhost/dvwa --async
# 具有更高并发性的 Async
python main.py --url http://localhost/dvwa --async --threads 16
```
异步模式的优势：
- 在 I/O 密集型目标上显著加快爬取和测试速度
- 更好地利用较高的 `--threads` 值
- 减少大型扫描队列的内存使用
## 环境变量
所有配置选项都可以通过环境变量设置。CLI 标志和配置文件值具有优先权。
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `W3BSP1D3R_URL` | 目标 URL | — |
| `W3BSP1D3R_SCAN_TYPE` | 扫描类型 | `full` |
| `W3BSP1D3R_THREADS` | 并发线程数 | `4` |
| `W3BSP1D3R_DELAY` | 请求之间的延迟 (秒) | `0.5` |
| `W3BSP1D3R_TIMEOUT` | 单个请求超时 (秒) | `10` |
| `W3BSP1D3R_OUTPUT` | 报告基本文件名 | `scan_report` |
| `W3BSP1D3R_VT_API_KEY` | VirusTotal API key | — |
| `W3BSP1D3R_NVD_API_KEY` | NVD API key | — |
| `W3BSP1D3R_PROXY` | HTTP/HTTPS/SOCKS5 代理 URL | — |
| `W3BSP1D3R_AUTH_TOKEN` | Bearer/JWT token | — |
| `W3BSP1D3R_LOGIN_USER` | 登录用户名 | — |
| `W3BSP1D3R_LOGIN_PASS` | 登录密码 | — |
| `W3BSP1D3R_API_KEY` | REST API 服务器认证密钥 | — |
| `W3BSP1D3R_FAIL_ON` | CI/CD 失败阈值 | — |
## CLI 参考
```
python main.py --url URL [options]
Required:
--url URL Target base URL (http:// or https://)
Configuration:
--config FILE YAML configuration file (see w3bsp1d3r.example.yaml)
--profile PROFILE Scan profile: quick | standard | thorough | stealth
Authentication:
--login-user USERNAME Form-based login username
--login-pass PASSWORD Form-based login password
--auth-token TOKEN Bearer/JWT token (Authorization header)
--auth-type TYPE Auth method: form | bearer | oauth2 | ntlm | apikey | header
--oauth2-token-url URL OAuth2 token endpoint
--oauth2-client-id ID OAuth2 client ID
--oauth2-client-secret SEC OAuth2 client secret
--oauth2-scope SCOPE OAuth2 scope string
--ntlm-domain DOMAIN NTLM domain (Windows auth)
Scan Configuration:
--scan-type TYPE full | passive | sqli | xss | csrf | headers | files |
traversal | redirect | cmdi | cve | idor | waf | ssti |
cors | ssl | cookies | nosqli | subdomains (default: full)
--threads N Concurrent tester threads (default: 4)
--max-pages N Max pages to crawl (default: 50)
--delay SECS Delay between requests (default: 0.5)
--timeout SECS Per-request timeout (default: 10)
--no-verify-ssl Disable TLS verification
--include PATTERN URL include pattern (glob, repeatable)
--exclude PATTERN URL exclude pattern (glob, repeatable)
Output:
--output FILENAME Report base filename, no extension (default: scan_report)
--formats FMT [FMT ...] Report formats: html md json sarif pdf (default: html md json sarif)
--verbose Debug logging — shows every HTTP request
--compare-with FILE Compare results against a previous scan JSON file
--dashboard Show live rate-limit and progress dashboard in terminal
Logging:
--log-format FORMAT Log output format: text | json (default: text)
--log-file FILE Write logs to file
Persistence:
--checkpoint Enable checkpoint/resume for crash recovery
--audit-log FILE Write audit trail to file (for compliance)
--database FILE SQLite database for historical scan tracking
Integrations:
--vt-api-key KEY VirusTotal API key
--vt-delay SECS Delay between VT requests (default: 15)
--nvd-api-key KEY NIST NVD API key for CVE lookups
--proxy URL HTTP/HTTPS/SOCKS5 proxy (e.g. http://127.0.0.1:8080)
--fail-on SEVERITY Exit code 2 if findings >= severity (critical|high|medium|low)
Notifications:
--slack-webhook URL Slack incoming webhook URL
--teams-webhook URL Microsoft Teams webhook URL
--discord-webhook URL Discord webhook URL
--webhook-url URL Custom webhook URL (receives JSON POST)
Notifications:
--slack-webhook URL Slack incoming webhook URL
--teams-webhook URL Microsoft Teams webhook URL
--discord-webhook URL Discord webhook URL
--webhook-url URL Custom webhook URL (JSON POST, repeatable)
API Server:
--api-server Start as REST API server instead of running a scan
--api-host HOST API server host (default: 127.0.0.1)
--api-port PORT API server port (default: 8888)
Plugins:
--plugins-dir DIR Plugin directory (repeatable)
```
## 解读输出
发现结果在终端中以颜色区分：
| 严重程度 | 含义 | 示例 |
|----------|---------|---------|
| **CRITICAL** | 很可能导致完全沦陷 | SQLi, 命令注入, .env 暴露 |
| **HIGH** | 重大风险 | 存储型 XSS, 路径遍历, NoSQL 注入 |
| **MEDIUM** | 应在生产前修复 | CSRF, 缺少 CSP, CORS 错误配置 |
| **LOW** | 轻微信息泄露 | 缺少次要 headers, 服务器版本泄露 |
每个发现包括：**URL**, **参数**, **HTTP 方法**, **确切的 payload**, 响应中的**证据**以及**修复**步骤。
## SQLi 检测方法
| 方法 | 原理 | 速度 |
|--------|-------------|-------|
| **报错型** | 注入破坏语法的字符，查找 DB 错误字符串。跳过基线中已有的特征。 | 快 |
| **UNION 型** | 注入带有唯一标记的 `UNION SELECT`，检查响应中是否出现该标记 | 快 |
| **布尔盲注** | 将 TRUE 和 FALSE 条件响应与干净的基线进行比较。需要绝对阈值 (50B) 和百分比阈值 (15%) 以及二次检查。 | 中 |
| **时间盲注** | 注入 `SLEEP(5)` / `WAITFOR DELAY` / `pg_sleep(5)`，测量响应时间差与基线的对比 | 慢 |
## 故障排除
### 找不到 "python" 或 "python3"
| OS | 修复方法 |
|----|-----|
| **Windows** | 从 [python.org](https://www.python.org/downloads/) 重新安装 Python 并勾选 **"Add Python to PATH"** |
| **macOS** | `brew install python` 或从 [python.org](https://www.python.org/downloads/) 下载 |
| **Linux (Debian/Ubuntu)** | `sudo apt install python3 python3-venv python3-pip` |
| **Linux (Arch)** | `sudo pacman -S python` |
| **Linux (Fedora)** | `sudo dnf install python3` |
### “No module named venv”（Linux）
```
sudo apt install python3-venv # Debian / Ubuntu
```
### PowerShell 脚本执行错误 (Windows)
```
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### “xcrun: error”（macOS）
```
xcode-select --install
```
### 端口 80 已被占用
DVWA 需要端口 80，但 Windows 通常有 IIS 或 Skype 占用。使用不同的端口：
```
docker run --rm -d -p 8080:80 --name dvwa vulnerables/web-dvwa
python main.py --url http://localhost:8080/dvwa --login-user admin --login-pass password
```
### 扫描器无法连接 / 超时错误
- 确保目标正在运行：先在浏览器中打开 URL
- 如果使用 Docker，检查 `docker ps` 确认容器已启动
- 如果在企业代理后面，尝试 `--proxy http://your-proxy:port`
- 对于自签名 HTTPS 证书，添加 `--no-verify-ssl`
### Rich 终端颜色显示异常
- **Windows:** 使用 [Windows Terminal](https://aka.ms/terminal) 而不是旧的 `cmd.exe` —— 它支持全彩
- **macOS / Linux:** 应该开箱即用。如果不行，尝试 `export TERM=xterm-256color`
## 项目结构
```
W3BSP1D3R/
├── main.py CLI entry point
├── gui.py Streamlit GUI
├── setup.sh Setup script (Linux / macOS)
├── setup.bat Setup script (Windows)
├── requirements.txt
├── pyproject.toml
├── w3bsp1d3r.example.yaml Annotated YAML config reference
│
├── scanner/
│ ├── core.py Orchestrator: auth → crawl → test → report
│ ├── crawler.py BFS crawler: links, forms, GET params, sitemap, robots.txt
│ ├── auth.py DVWA + generic form-based auth
│ ├── auth_enterprise.py OAuth2, NTLM, API key, custom header auth
│ ├── virustotal.py VirusTotal API v3
│ ├── checkpoint.py Checkpoint/resume for crash recovery
│ ├── audit.py Audit trail logging for compliance
│ ├── db.py Historical SQLite scan database
│ ├── plugins.py Plugin loader and registry
│ ├── api.py REST API server (Flask) with API key auth
│ ├── webhooks.py Slack / Teams / Discord / generic notifications
│ ├── scheduler.py Cron-based recurring scan scheduler
│ ├── payloads.py Custom payload loader (YAML/JSON)
│ │
│ ├── integrations/
│ │ ├── ticketing.py Jira + ServiceNow ticket creation
│ │ └── email_notifier.py SMTP email notifications
│ │
│ ├── testers/
│ │ ├── base.py BaseTester — template method pattern
│ │ ├── sqli.py SQL injection (4 methods)
│ │ ├── xss.py Reflected + stored XSS
│ │ ├── csrf.py Token analysis
│ │ ├── cmdi.py Command injection (output + time-based)
│ │ ├── path_traversal.py 15+ encoding variants
│ │ ├── open_redirect.py 3xx + body reflection
│ │ ├── sensitive_files.py 60+ path probes
│ │ ├── headers.py Security header checks
│ │ ├── nosql_injection.py MongoDB/CouchDB injection
│ │ ├── ssti.py Server-side template injection
│ │ ├── idor.py Insecure direct object references
│ │ ├── cors.py CORS misconfiguration
│ │ ├── ssl_tls.py SSL/TLS configuration
│ │ ├── cookie_security.py Cookie flags analysis
│ │ ├── waf.py WAF detection
│ │ ├── subdomain.py Subdomain enumeration
│ │ └── cve.py NVD CVE lookup
│ │
│ ├── reporting/
│ │ ├── models.py Finding + ScanSummary dataclasses
│ │ ├── markdown_report.py
│ │ ├── html_report.py
│ │ ├── json_report.py
│ │ ├── sarif_report.py SARIF v2.1.0
│ │ ├── pdf_report.py PDF generation (fpdf2)
│ │ └── diff_report.py Scan comparison / diff engine
│ │
│ └── utils/
│ ├── http.py Thread-safe session, SSRF guard, retry, rate limiting
│ ├── http_async.py Async HTTP client (httpx)
│ ├── display.py Rich terminal UI + rate limit dashboard
│ └── logging_config.py Structured logging (text + JSON)
│
├── Dockerfile Multi-stage container build
├── docker-compose.yml Scanner + API + DVWA + Juice Shop
├── .github/workflows/ci.yml GitHub Actions CI (lint + test)
├── plugins/ Custom plugin directory (user-created)
│
├── tests/ 122 unit tests
│ ├── test_baseline_error.py Baseline FP suppression (SQLi, NoSQL, CMDi, PathTraversal)
│ ├── test_sqli_boolean.py 3-way boolean SQLi logic
│ ├── test_xss_reflected.py Structural XSS verification
│ ├── test_crawler_xxe.py XXE-safe XML parsing
│ ├── test_http_safety.py SSRF guard + response size limit
│ ├── test_sensitive_files.py .env detection
│ ├── test_enterprise.py Config, checkpoint, audit, dedup, scope, metrics, webhooks, DB
│ └── test_enterprise_phase3.py OWASP mapping, API auth, cron, payloads, ticketing, email
│
└── examples/
└── dvwa_scan.sh
```
## 运行测试
**Linux / macOS:**
```
source venv/bin/activate
python -m pytest tests/ -v
```
**Windows:**
```
venv\Scripts\activate
python -m pytest tests/ -v
```
```
122 passed in 0.32s
```
测试覆盖范围：布尔 SQLi 逻辑、XSS 结构验证、所有报错型测试器的基线误报抑制、SSRF 重定向阻止、XXE 防护、响应大小限制、敏感文件检测、发现去重、检查点序列化、审计日志格式化、插件加载、配置 profile 合并、报告差异逻辑、JSON 日志输出、OWASP Top 10 映射、API key 认证 (401/403/200)、Cron 表达式解析、扫描调度、自定义 payload 加载、Jira/ServiceNow 格式化、邮件通知渲染以及 webhook 消息构建。
## 扩展扫描器
### 方式 1: 插件目录 (v2 推荐)
将 Python 文件放入您的 `plugins/` 目录 —— 参见上方的 [插件系统](#plugin-system)。
### 方式 2: 修改核心代码 (高级)
通过 3 个步骤添加新的漏洞测试器：
**1.** 创建 `scanner/testers/my_tester.py`:
```
from scanner.testers.base import BaseTester
from scanner.crawler import CrawledPage
from scanner.reporting.models import Finding
class MyTester(BaseTester):
def __init__(self):
super().__init__(name="My Tester")
def run(self, pages: list[CrawledPage]) -> list[Finding]:
# Your detection logic here
# Use self._inject_form(), self._inject_get_param(), self._log_finding()
return self.findings
```
**2.** 在 `scanner/core.py` 中注册它：
```
from scanner.testers.my_tester import MyTester
_TESTER_MAP["mytester"] = MyTester
```
**3.** 在 `main.py` 的 `--scan-type` 选项中添加 `"mytester"`。
## 依赖项
| 库 | 用途 |
|---------|---------|
| [requests](https://github.com/psf/requests) | HTTP 会话, cookies, 认证 |
| [Beautiful Soup 4](https://www.crummy.com/software/BeautifulSoup/) | HTML 解析, 表单提取 |
| [lxml](https://lxml.de/) | 快速 HTML/XML 解析器后端 |
| [Rich](https://github.com/Textualize/rich) | 终端颜色, 面板, 进度条, 仪表盘 |
| [defusedxml](https://github.com/tiran/defusedxml) | XXE 安全的 XML 解析 |
| [PyYAML](https://pyyaml.org/) | YAML 配置文件解析 |
| [fpdf2](https://github.com/py-pdf/fpdf2) | PDF 报告生成 |
| [httpx](https://www.python-httpx.org/) | 异步 HTTP 客户端 (可选 — `pip install httpx`) |
| [Flask](https://flask.palletsprojects.com/) | REST API 服务器 (可选 — `pip install flask`) |
| [requests-ntlm](https://github.com/requests/requests-ntlm) | NTLM/Windows 证 (可选 — `pip install requests-ntlm`) |
| [Streamlit](https://streamlit.io/) | GUI (可选 — `pip install streamlit`) |
## 致谢
### 实验环境
- [DVWA](https://github.com/digininja/DVWA) — Ryan Dewhurst 及贡献者
- [OWASP Juice Shop](https://github.com/juice-shop/juice-shop) — Bjorn Kimminich & OWASP
### 参考资料
- [OWASP Top 10](https://owasp.org/Top10/)
- [OWASP 测试指南](https://owasp.org/www-project-web-security-testing-guide/)
- [OWASP 备忘单系列](https://cheatsheetseries.owasp.org/)
- [VirusTotal API v3](https://docs.virustotal.com/reference/overview)
- [NIST NVD](https://nvd.nist.gov/)
## 许可证
MIT 许可证 —— 详情请见 [LICENSE](LICENSE)。
**作者对因使用本软件而产生的任何误用、损害或法律后果不承担任何责任或义务。使用 W3BSP1D3R 即表示您承认您需自行承担全部风险。**
*由 S1YOL 构建。*
标签：C2日志可视化, CI/CD安全, CISA项目, DAST, DevSecOps, Kubernetes, Llama, LNA, OWASP Top 10, PDF报告, Python安全工具, REST API, SQL注入检测, Webhook, Web漏洞扫描, XSS检测, YAML配置, 上游代理, 企业级扫描器, 力导向图, 动态应用安全测试, 多语言支持, 安全测试框架, 对称加密, 恶意软件分析, 指纹识别, 网络安全, 网络测绘, 自动化审计, 请求拦截, 运行时操纵, 逆向工具, 隐私保护