## 立即运行
### 桌面 GUI
```
git clone https://github.com/K0NGR3SS/WAFPierce.git blackthorn
cd blackthorn
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .
python3 run_gui.py
```
安装完成后，可以通过以下命令打开相同的 GUI：
```
blackthorn gui
```
在 Windows 上，请使用 `.venv\Scripts\activate` 激活环境，并使用 `python run_gui.py`。
### CLI
```
git clone https://github.com/K0NGR3SS/WAFPierce.git blackthorn
cd blackthorn
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
blackthorn doctor
blackthorn scan https://target.example --dry-run --safe-mode
```
在不指定子命令的情况下传入 URL，将默认执行 `scan`：
```
blackthorn https://target.example --dry-run
```
### Docker
```
docker build -t blackthorn .
docker run --rm blackthorn doctor
docker run --rm blackthorn scan https://target.example --safe-mode
```
Docker 的 entrypoint 是无头 CLI。
## 功能概览
以下计数来源于 1.8 版本中已注册的扫描器和工具目录。一个技术组是一种独立的测试实现；许多组会发送多种 payload、编码、标头、路径、方法或确认请求。
| 功能 | 当前覆盖率 |
| --- | ---: |
| 已编目的 Web 安全技术组 | **128** |
| 具备漏洞特定确认的证明能力组 | **18** |
| 仅作为候选的、需分析师验证的差分组 | **79** |
| 仅作为观察结果的清单/配置组 | **23** |
| 可在常规非侵入式扫描中运行 | **101** |
| 需要 `--intrusive` 的额外可运行组 | **19** |
| 在原生引擎出现前被禁用的原始传输组 | **7** |
| 在具备证明能力的引擎出现前被禁用的 DNS rebinding 组 | **1** |
| 可在安全模式及非侵入式默认设置下运行 | **87** |
| 扫描类别 | **16** |
| 外部工具驱动程序 | **23** |
| 导出格式 | **9** |
| 已记录流量导入格式 | **3** |
| AI 提供商类型 | **3** |
| 桌面工作区分区 | **22** |
目录覆盖并不代表每个组都能证明漏洞的存在。
Blackthorn 将每个已注册的组暴露为：具备证明能力、仅作为候选、仅作为观察结果或不可用。
候选组和外部工具警报在经过验证之前，会与已确认的发现结果保持分离。
要从已安装的版本验证当前的扫描器目录，请使用：
```
blackthorn scan --list-categories
blackthorn scan --list-techniques
```
## Blackthorn 能做什么
### 攻击面发现
- 抓取同主机链接、表单和参数。
- 解析 `robots.txt` 和 `sitemap.xml`。
- 提取 OpenAPI/Swagger 文档和 GraphQL schema。
- 发现 API 路由、调试 endpoint、敏感文件、JavaScript bundle 和内容路径。
- 枚举子域名，并检查 DNS 解析、证书透明度、历史 DNS 和 zone-transfer 暴露情况。
- 识别框架、服务器、CMS 平台、云提供商、边缘控制和已知存在漏洞的软件版本的指纹。
- 通过受支持的提供商签名检测子域名接管情况。
- 运行专门用于发现的 workflow，集成了 Subfinder、Amass、Certificate Transparency、dnsx 和 ProjectDiscovery httpx；Nmap 是一个单独确认的活动选项。
- 根据 DNS 状态、HTTP 可用性、响应类别或确切的状态码过滤已完成的主机清单，并支持直接从对应行复制 URL。
### 主动 Web 安全测试
- 测试身份验证、授权、IDOR、批量赋值、API 版本暴露和角色相关逻辑。
- 测试 SQL injection、XSS、command injection、NoSQL、LDAP、SSTI、XXE、CRLF、SSI、XSLT、CSS injection、deserialization、prototype pollution 和遍历行为。
- 利用针对证明的特定检查和影响门控，测试 JWT、OAuth/OIDC、SAML、GraphQL、WebSocket、SSRF、云元数据、文件上传、缓存和 race 行为。
- 利用交替的方法、编码、内容类型、重复参数、multipart boundary、transfer encoding 和 HTTP 协议变体来测试解析器差异。
- 运行可选的、基于浏览器的 DOM XSS 和客户端 path traversal 检查。
- 探测基于 AI/LLM 的 endpoint 是否存在 prompt-injection 行为。
### 漏洞发现验证与证据
- 建立多样本响应基准，并在比较前标准化动态值。
- 比较状态、大小、内容相似度和响应行为，而不是仅依赖状态码。
- 在禁用缓存的情况下重新运行候选绕过测试，并记录确认次数。
- 在可用时附加置信度、严重程度、CVSS v3.1 分数/向量、CWE、请求详情以及用于复现的 `curl` 数据。
- 通过 Interactsh 或自托管的 OOB 监听器确认 blind SSRF、XXE 和基于 JNDI 的行为。
- 默认情况下，从保存的报告中隐藏 cookies、token、authorization header 和其他敏感信息。
- 保存扫描历史记录，比较多次运行结果，识别新增/已解决的发现，并长期监控目标。
### 真实流量与身份验证测试
- 导入 HAR 抓包记录、Postman v2 集合和 Burp items XML。
- 从真实的应用程序路由和参数启动测试，而不是仅从目标根目录开始。
- 提供 cookies、可重复的自定义标头、bearer token 或 HTTP Basic 凭据。
- 通过带有表单数据和可配置成功标记的 login URL 进行身份验证。
- 当配置的会话在扫描期间过期时重新进行身份验证。
- 在浏览器、代理、Repeater、Fuzzer 和发现 workflow 之间发送捕获的请求。
### 执行控制
- 运行特定类别或完整目录。
- 使用 `stealth`、`normal` 或 `aggressive` 配置文件。
- 控制线程、单次请求延迟、超时、抖动、种子和最大运行时间。
- 轮换代理池或通过 Tor 路由流量。
- 从 checkpoint 恢复中断的扫描。
- 通过 GUI 队列运行多个目标，显示每个目标及整体的进度。
- 使用 dry-run 模式检查计划而不发送请求。
- 安全模式默认开启，会跳过嘈杂、拒绝服务和改变状态的探测。
- 仅当业务活动明确允许额外探测时，才使用 `--full-impact`。
- 仅当业务活动明确允许执行诸如上传、电子邮件、缓存、race 和元数据测试等猜测性改变状态的 workflow 时，才使用 `--intrusive`。
### 报告与自动化
- 导出 HTML、JSON、PDF、SARIF、Nuclei YAML、JUnit XML、CSV、Prometheus/OpenMetrics 或 HAR。
- 向标准输出 (stdout) 输出 JSON 以便对接 pipeline。
- 当发现结果达到配置的 `--fail-on` 严重性阈值时，返回退出代码 `10`。
- 根据之前的 JSON 结果集生成独立的 HTML 差异报告。
- 将摘要推送到 Slack、Discord、Microsoft Teams 或通用的 webhook。
- 将确认的发现映射为兼容 DefectDojo 的记录。
- 将发现结果移交给 Metasploit RPC，或通过 Caido 重放/导出它们。
- 通过标准输入/输出运行本地 JSON-lines agent bridge。
### 可扩展性与 AI
- 无需更改核心扫描器即可加载用户插件。
- 添加受数据库支持的自定义 payload 和规避配置。
- 从 Blackthorn 扫描、外部工具和报告阶段构建带类型的 pipeline。
- 使用 Anthropic Claude、本地 Ollama 模型或兼容 OpenAI 的 endpoint。
- 运行选择性开启的误报分类、报告起草和 payload 变异辅助。
- 当可选的 AI 提供商不可用时继续扫描；核心引擎绝对不依赖 AI。
## 详细扫描器覆盖范围：128 个已编目技术组
Blackthorn 目前在常规非侵入式扫描中运行 101 个组。
另外 19 个有状态、可计费或内部网络组需要单独通过
`--intrusive` 授予影响权限。7 个模棱两可的 HTTP framing/race
组保持可见状态但被禁用，直到 Blackthorn 拥有原生的 HTTP/1.1 和
HTTP/2 传输能力。DNS rebinding 同样被禁用，直到由用户拥有的权威
DNS workflow 能够更改应答并捕获证明；仅仅 Host 标头大小的差异是不够的。
### 标头操纵 (Header Manipulation) — 9
- Host header injection
- `X-Forwarded-For` 行为
- `X-Forwarded-Host` 行为
- `X-Original-URL` / rewrite-path 行为
- Header injection
- Origin 标头操纵
- 自定义标头 fuzz
- IP 欺骗标头变体
- 扩展的 host-header 攻击
### 编码与混淆 (Encoding & Obfuscation) — 9
- URL 编码变体
- 双重编码
- 大小写操纵
- Comment injection
- 空格操纵
- Unicode 标准化
- Payload 变异
- Polyglot payload
- 扩展的路径标准化
### 协议级攻击 (Protocol-Level Attacks) — 19
- HTTP 方法绕过
- HTTP 方法重写
- Content-type 绕过
- HTTP 参数污染
- Transfer-Encoding 请求走私 *(已禁用：需要原始传输)*
- HTTP/2 降级行为
- HTTP/2 特定攻击 *(已禁用：需要原始 HTTP/2 传输)*
- WebSocket 升级行为
- WebSocket 安全检查
- Chunked transfer 变体 *(已禁用：需要原始传输)*
- HTTP pipelining
- 扩展的请求走私 *(已禁用：需要原始传输)*
- HTTP desync *(已禁用：需要原始传输)*
- 扩展的 verb tampering *(`--intrusive`；仅限只读方法)*
- Multipart boundary 绕过
- WebSocket fuzz
- CL.0 / 0.CL 走私 *(已禁用：需要原始传输)*
- gRPC 检测
- HTTP/3 检测
### 缓存与控制 (Cache & Control) — 6
- Cache-Control 操纵
- Range 标头行为
- Cache poisoning
- Web cache deception
- 扩展的 Range 攻击
- 深度 cache poisoning
### 注入测试 (Injection Testing) — 22
- SQL injection 绕过
- XSS 绕过
- Command injection 绕过
- Windows command injection
- Path traversal 绕过
- NoSQL injection
- LDAP injection
- Server-side template injection
- XML external entity injection
- CRLF injection
- Prototype pollution
- JSON injection 和解析器差异
- Insecure deserialization
- Server-Side Includes injection
- Log4Shell/JNDI 模式
- Dangling markup
- CSS injection
- XSLT injection
- 基于 JSON 的 SQL injection 绕过
- DOM XSS
- 客户端 path traversal
- 变异 fuzz
### 安全配置错误 (Security Misconfigurations) — 8
- CORS 配置错误
- Open redirect
- 安全标头审计
- Cookie 安全审计
- Clickjacking
- Content sniffing *(`--intrusive`；惰性上传 Canary)*
- HTTP 响应拆分
- Content Security Policy 分析
### 业务逻辑与授权 (Business Logic & Authorization) — 8
- API 版本控制绕过
- Mass assignment
- IDOR 模式
- 业务逻辑边界检查
- Email-header injection
- 文件上传绕过
- Rate-limit 检测
- Race-condition 测试
### JWT 与身份验证攻击 — 6
- JWT/OAuth 绕过案例
- JWT 算法、密钥和声明攻击
- OAuth/OIDC 配置和重定向行为
- 嵌入式 JWK 自签名
- SAML XML Signature Wrapping 表面检查
- 身份验证和授权逻辑检查
### GraphQL 攻击 — 3
- GraphQL 绕过案例
- 深度 GraphQL 测试、内省、批处理、深度和别名行为
- GraphQL CSRF
### AI / LLM 攻击 — 1
- LLM endpoint 和直接指令遵循行为 *(`--intrusive`)*
### SSRF 高级 — 3
- SSRF 绕过变体
- SSRF 协议走私
- DNS rebinding *(已禁用：需要权威 DNS 证明引擎)*
### PDF / 文档攻击 — 3
- PDF 生成表面发现 *(`--intrusive`；仅限惰性标记)*
- `postMessage` 安全检查
- 相对路径覆盖 (Relative Path Overwrite)
### 云安全 (Cloud Security) — 8
- Azure Blob 枚举
- Google Cloud Storage bucket 发现
- Serverless function 检测
- Kubernetes API 暴露
- 云提供商检测
- 云元数据枚举
- 扩展的多云元数据测试
- Amazon S3 bucket 枚举
### 高级 Payload — 7
- 基于时间的检测
- Buffer 和大小限制
- 整数溢出边界
- Bot 检测规避
- IPv6 表示绕过
- Charset 和超长 UTF-8 混淆
- HTTP/2 单包 race 测试 *(已禁用：需要同步的原始 HTTP/2)*
### 信息泄露 (Information Disclosure) — 6
敏感文件和配置泄露
- 子域名接管检测
- API 密钥和机密信息暴露
- 基于时间的发现
- 基于错误的泄露
- JavaScript bundle 中的机密信息
### 检测与侦察 (Detection & Reconnaissance) — 10
- 边缘规则版本检测
- JavaScript challenge 和 bot 控制检测
- API endpoint 发现
- DNS zone-transfer 测试
- 子域名枚举
- 历史 DNS 查找
- 证书透明度查找
- 技术栈指纹识别
- CVE 指纹识别
- 内容发现
## 桌面 GUI 工作区
基于 PySide6 的桌面应用程序保持了五个主要工作流目标的可见性，
并将专业界面移至一个 Workbench 选择器中：
| 区域 | 板块与工具 |
| --- | --- |
| Workflow | Scope & scan, Discover, Test plan, Analyze, Report |
| Workbench | External Tools, Browser, Proxy, Repeater, Fuzzer, SQLi, Secrets, Payloads, ZAP/Burp, AD / Internal, AI assistance, Live Logs, Timeline, Schedule, Plugins |
| Utilities | Engagements, Settings |
GUI 功能包括：
- 带有基于任务的配置文件的多目标队列，支持可选的高级类别、可配置的并发、线程和延迟。
- 业务活动选择、授权文件、包含/排除范围规则、安全模式、dry run、重新确认、模拟、AI 分类和 OOB 设置。
- 以证据为导向的结果工作区，具有目标分组、验证/workflow 过滤器、确切的请求复现、授权重测、Repeater 移交、分析师笔记和导出功能。
- 仪表盘统计、扫描比较、历史时间轴和实时日志。
- 内置拦截代理、本地 CA 管理、流量历史和 Repeater。
- 浏览器工作区和 ZAP/Burp 移交。
- Fuzzer、SQLi 助手、机密工作流、payload 管理和自定义 payload 包。
- 外部工具检测、执行、输出流式传输和标准化发现。
- 业务活动管理、计划扫描、扫描配置文件导入/导出、插件和持久化设置。
## 外部工具驱动程序 — 23
Blackthorn 不会静默安装这些工具。当主机上已经提供这些工具时，它可以检测并驱动：
| 用途 | 工具 |
| --- | --- |
| 侦察 | Nmap, Masscan, Naabu, Subfinder, OWASP Amass, dnsx, httpx, WhatWeb, Katana |
| 内容发现 | ffuf, Feroxbuster, Gobuster, dirsearch |
| 漏洞测试 | Nuclei, Nikto, WPScan, Dalfox, SSLyze, sqlmap |
| 机密与云 | TruffleHog, Gitleaks, ScoutSuite, Prowler |
该表描述的是受支持的适配器，而不是与 Blackthorn 捆绑的工具。
可用性、二进制路径和版本是在 runtime 检测的。空输出将被报告为
空运行——不会被伪造为发现结果——并且工具警报会进入
候选 workflow，直到 Blackthorn 独立验证它们。
专用的 `blackthorn recon` workflow 需要用到 Subfinder、Amass、dnsx
以及 ProjectDiscovery httpx 二进制文件（不是同名的 Python 包）。
它会将这些来源与公共 Certificate Transparency 名称合并，
并区分 DNS 已解析、HTTP 存活、仅 DNS 可解析和未解析的主机。
独立的被动源会并发运行，其完整结果将与来源归因一起合并，
从而减少等待时间且不丢失任何来源。
支持通配符范围表示法并进行标准化：
```
blackthorn doctor
blackthorn recon '*.example.com'
```
Nmap 默认被禁用，因为它是主动扫描，可能会触发
网络或 endpoint 安全警报。仅针对已授权目标启用其
非特权、受限的 connect 扫描：
```
blackthorn recon example.com --ports
```
## CLI 命令
| 命令 | 功能 |
| --- | --- |
| `blackthorn scan
` | 运行内置的 128 组 Web 安全扫描器 |
| `blackthorn recon ` | 运行外部工具侦察 workflow |
| `blackthorn chain ` | 将发现、测试、侦察和报告作为一个 workflow 运行 |
| `blackthorn msf ...` | 检查 Metasploit RPC、运行辅助扫描器或推送发现结果 |
| `blackthorn caido ...` | 检查 Caido、通过其代理重放发现结果或导出原始请求 |
| `blackthorn agent-server --stdio` | 启动本地 JSON-lines agent bridge |
| `blackthorn doctor` | 检查依赖项、配置、OOB 支持、侦察工具和集成情况 |
| `blackthorn gui` | 打开桌面应用程序 |
| `blackthorn version` | 显示版本和可选组件的可用性 |
### 实用扫描示例
```
# 在不发送流量的情况下检查默认安全的请求计划
blackthorn scan https://target.example --dry-run
# 带有浏览器模拟的已授权、已加入 allowlist 的扫描
blackthorn scan https://target.example \
--authorize scope.txt \
--impersonate chrome \
--export report.html \
--export-format html
# 认证扫描
blackthorn scan https://target.example \
--bearer "$TOKEN" \
--header "X-Researcher: handle" \
--scope-include '^https://target\.example/'
# 从捕获的流量中进行 Seed 测试
blackthorn scan https://target.example \
--import-har session.har \
--safe-mode
# 针对 blind 发现的 OOB 确认
blackthorn scan https://target.example \
--oob interactsh \
--oob-wait 15
# 仅在进行明确允许的 engagement 时禁用 safe mode
blackthorn scan https://target.example \
--authorize scope.txt \
--full-impact
# CI 输出和 severity gate
blackthorn scan https://target.example \
--json \
--export findings.sarif \
--export-format sarif \
--fail-on high
# 恢复和监控
blackthorn scan https://target.example --resume --monitor
```
运行 `blackthorn scan --help` 查看所有参数。
## 配置文件
Blackthorn 接受 JSON 或 TOML 配置。显式的 CLI 参数优先于文件中的值。
```
threads = 10
delay = 0.2
impersonate = "chrome"
safe_mode = true
[profiles.staging]
target = "https://staging.example.com"
oob = "interactsh"
```
```
blackthorn scan --config blackthorn.toml --config-profile staging
```
## 可选组件
```
# Headless browser 检查
pip install -e ".[browser]"
python -m playwright install chromium
# Anthropic AI provider
pip install -e ".[ai]"
# 为通过 GUI 输入的 integration secrets 提供 OS keychain 存储
pip install -e ".[secrets]"
# Browser、AI、keychain 和开发依赖项
pip install -e ".[full,dev]"
```
其他可选集成包括通过 `pymetasploit3` 连接的 Metasploit RPC、一个正在运行的 Caido 实例、本地 Ollama 服务器或兼容 OpenAI 的 API endpoint。
### 凭据存储
Blackthorn 不会将 AI 密钥、外部工具 API 密钥、代理密码、ZAP 密钥或 Metasploit RPC 密码写入其首选项 JSON 或 SQLite 数据库中。环境变量优先。安装了可选的 `keyring` 扩展后，在 GUI 中输入的机密信息将保存在操作系统凭据存储中；否则，它们仅在当前进程中可用。
常见变量包括 `ANTHROPIC_API_KEY`、`AI_API_KEY`、`OPENAI_API_KEY`、`MSF_RPC_PASSWORD` 和 `ZAP_API_KEY`。外部工具密钥使用 `BLACKTHORN_TOOL__API_KEY`。
## 构建桌面可执行文件
```
pip install -r requirements.txt
python3 build_exe.py
```
PyInstaller 配置捆绑了 Blackthorn 身份资产、Qt runtime、字典、扫描器模块和支持的原生依赖项。
## 开发
```
pip install -e ".[dev]"
python3 -m pytest
ruff check .
```
在品牌重塑期间，Python 包保留了其前 WAFPierce 内部模块路径，
以确保现有的 import、插件和存储的配置保持兼容。
面向用户的命令和产品文案使用 Blackthorn。
UI 和增强计划位于 [docs/BLACKTHORN_PRODUCT_PLAN.md](docs/BLACKTHORN_PRODUCT_PLAN.md) 中。
有关贡献指南，请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)；有关私密漏洞报告，请参阅 [SECURITY.md](SECURITY.md)。
## 负责任的使用与披露
如果 Blackthorn 帮助识别出漏洞：
1. 停留在计划记录的范围内和规则内。
2. 尽量减少数据访问和服务影响。
3. 保留清晰、经过脱敏处理的证据。
4. 通过组织批准的渠道进行报告。
5. 在协调披露之前，留出合理的修复时间。
## 作者
- [Nazariy Buryak](https://github.com/K0NGR3SS)
- [Marwan Fayad](https://github.com/Marwan-verse)
- [Mykhailo Kholiev](https://github.com/classified-mick)
## 许可证与法律声明
Blackthorn 根据 [MIT 许可证](LICENSE) 发布。
本软件专用于授权的安全测试和研究。在测试您不拥有的系统之前，您必须获得明确的许可。作者和贡献者对误用、损害、服务中断、数据丢失或法律后果不承担任何责任。本软件按“原样”提供，不提供任何保证。
