AshtonVaughan/bountyhound

# BountyHound 安全工具套件 **集成 Claude 的统一安全测试框架，包含 6 种高级工具。** 用于自动化漏洞扫描、漏洞利用测试、网络侦察和安全分析的完整系统——所有这些都可以通过 Claude Code 进行控制。 ## 架构概述 ``` Claude Code ↓ MCP Unified Server (mcp-unified-server/) ├── ↓ HTTP ├─→ Nuclei (8188) — Template-based vuln scanning ├─→ SQLMap (8189) — SQL injection testing ├─→ Nmap (8190) — Network reconnaissance ├─→ Ffuf (8191) — Web fuzzing └─→ Amass (8192) — Subdomain enumeration ``` 每个工具都作为独立的 FastAPI 服务器运行，并带有后台任务处理。 ## 工具 ### Nuclei (`nuclei-claude/`) **基于模板的漏洞扫描** - 根据精选的 Nuclei 模板扫描 URL - 按严重程度、标签、模板进行过滤 - 端口：`8188` **MCP 工具**： - `nuclei_scan(urls, templates, severity)` — 开始扫描 - `nuclei_status(job_id)` — 获取结果 - `nuclei_cancel(job_id)` — 取消任务 - `nuclei_server_status()` — 服务器统计信息 ### SQLMap (`sqlmap-claude/`) **SQL 注入测试与利用** - 自动化 SQL 注入检测 - 支持多种注入类型 - 检测级别和风险控制 - 端口：`8189` **MCP 工具**： - `sqlmap_test(url, method, data, level, risk)` — 开始测试 - `sqlmap_status(job_id)` — 获取发现结果 - `sqlmap_cancel(job_id)` — 取消任务 - `sqlmap_server_status()` — 服务器统计信息 ### Nmap (`nmap-claude/`) **网络侦察与端口扫描** - 服务版本检测 - 多种扫描类型（SYN, TCP, UDP） - 指定端口范围 - 解析 XML 以获取结构化结果 - 端口：`8190` **MCP 工具**： - `nmap_scan(targets, ports, scan_type, aggressive)` — 开始扫描 - `nmap_status(job_id)` — 获取开放端口 - `nmap_cancel(job_id)` — 取消任务 - `nmap_server_status()` — 服务器统计信息 ### Ffuf (`ffuf-claude/`) **Web 模糊测试与参数发现** - 目录/文件枚举 - 参数模糊测试 - 状态码过滤 - 解析 JSON 输出 - 端口：`8191` **MCP 工具**： - `ffuf_fuzz(url, wordlist, method, match_status, filter_status)` — 开始模糊测试 - `ffuf_status(job_id)` — 获取发现的 endpoint - `ffuf_cancel(job_id)` — 取消任务 - `ffuf_server_status()` — 服务器统计信息 ### Amass (`amass-claude/`) **子域名枚举与侦察** - 被动枚举模式 - 多种数据源 - 包含 DNS 解析 - 解析 JSON 输出 - 端口：`8192` **MCP 工具**： - `amass_enum(domain, passive, include_unresolved)` — 开始枚举 - `amass_status(job_id)` — 获取子域名 - `amass_cancel(job_id)` — 取消任务 - `amass_server_status()` — 服务器统计信息 ## 统一 MCP 服务器 **Claude Code 的单一入口点** (`mcp-unified-server/`) 通过一个 MCP 连接暴露所有 5 个工具。 **启动**： ``` cd mcp-unified-server python main.py ``` 这会将请求代理到所有 5 个后端服务。 ## 共享基础库 **`bh-core/` — 可重用组件** - `models.py` — 基础 Pydantic 模型（Job, Finding, Request） - `state.py` — 用于任务追踪的 BaseStateManager - `persistence.py` — 保存/加载状态（JSON/pickle） - `logger.py` — 统一的日志记录 - `mcp_base.py` — MCP 服务器模板 所有工具均扩展了这些类。 ## 安装与运行 ### 设置 1. **安装 bh-core**： ``` cd bh-core pip install -r requirements.txt ``` 2. **安装每个工具**（示例：nuclei-claude）： ``` cd nuclei-claude pip install -r requirements.txt ``` 3. 对以下工具重复操作：`sqlmap-claude`、`nmap-claude`、`ffuf-claude`、`amass-claude` 4. **安装统一 MCP 服务器**： ``` cd mcp-unified-server pip install -r requirements.txt ``` ### 运行单个工具 每个工具在其指定端口上独立运行： ``` # Terminal 1: Nuclei cd nuclei-claude && python main.py # Terminal 2: SQLMap cd sqlmap-claude && python main.py # Terminal 3: Nmap cd nmap-claude && python main.py # Terminal 4: Ffuf cd ffuf-claude && python main.py # Terminal 5: Amass cd amass-claude && python main.py ``` ### 运行统一 MCP 服务器 ``` cd mcp-unified-server python main.py ``` 然后在 Claude Code 中，将 MCP 服务器加载为 `mcp-unified-server`。 ## 使用示例 ### 使用 Nuclei 扫描目标 ``` nuclei_scan(urls="target.com", templates="http,cves", severity="high") ``` 返回：`{"job_id": "a3f2e1c9", "status": "running", ...}` ### 轮询 Nuclei 结果 ``` nuclei_status(job_id="a3f2e1c9") ``` 返回：一旦完成，包含发现结果的完整任务对象。 ### 使用 Nmap 扫描网络 ``` nmap_scan(targets="192.168.1.0/24", ports="80,443,8080", scan_type="sV", aggressive=true) ``` 返回：`{"job_id": "b4f2e2c0", "status": "running", ...}` ### Web 目录模糊测试 ``` ffuf_fuzz(url="http://target.com/FUZZ", wordlist="/usr/share/wordlists/dirbuster/common.txt", filter_status="404") ``` 返回：`{"job_id": "c5f2e3c1", "status": "running", ...}` ### 枚举子域名 ``` amass_enum(domain="example.com", passive=true) ``` 返回：`{"job_id": "d6f2e4c2", "status": "running", ...}` ## 数据流 1. **Claude 调用 MCP 工具**：`nuclei_scan(urls="target.com", templates="http")` 2. **统一 MCP 服务器解析**：请求 → JSON payload 3. **向后端发送 HTTP POST**：`POST http://127.0.0.1:8188/api/scan` 4. **后端创建任务**：返回 `job_id` 5. **生成后台任务**：子进程开始扫描 6. **Claude 轮询状态**：`nuclei_status(job_id)` 7. **后端返回**：包含结果的任务对象（状态：completed、error、cancelled） ## API endpoint 所有工具都遵循相同的 REST 模式： ``` POST /api/{action} — Start job (e.g., /api/scan, /api/test) GET /api/{action}/{job_id} — Get job status & results POST /api/cancel/{job_id} — Cancel job GET /api/status — Server stats ``` ## 目录结构 ``` BountyHound/ ├── bh-core/ # Shared foundation │ ├── __init__.py │ ├── models.py # Base Job, Finding, Request │ ├── state.py # BaseStateManager │ ├── persistence.py # Save/load utilities │ ├── logger.py # Logging config │ ├── mcp_base.py # MCP server template │ └── requirements.txt │ ├── mcp-unified-server/ # Single entry point │ ├── main.py # Unified MCP server │ └── requirements.txt │ ├── nuclei-claude/ # Template-based scanning │ ├── main.py, api.py, mcp_server.py, scanner.py, models.py, state.py │ └── requirements.txt │ ├── sqlmap-claude/ # SQL injection testing ├── nmap-claude/ # Network scanning ├── ffuf-claude/ # Web fuzzing ├── amass-claude/ # Subdomain enumeration │ └── README.md # This file ``` ## 任务管理 所有任务都遵循相同的状态机： ``` running → completed | cancelled | error ``` **自动清理**：每 10 分钟，旧的已完成任务将被删除（最多保留 100 个）。 ## 内存与性能 - **并发任务**：无限制（存储在内存中） - **自动清理**：每个工具最多保留 100 个已完成/出错/取消的任务 - **超时**：可根据请求配置（默认为 30-600 秒） - **并发**：每个工具的设置（例如，Nuclei 为 10，Ffuf 为 50） ## 错误处理 所有工具都在任务对象中返回错误： ``` { "job_id": "a3f2e1c9", "status": "error", "error": "Scan timed out after 300s" } ``` ## 环境变量 每个工具支持： ``` API_PORT=8188 # FastAPI listen port MCP_MODE=1 # Run as MCP-only (no FastAPI) ``` ## 与 Claude 集成 **在 Claude Code 中**： 1. 添加 MCP 服务器：`mcp-unified-server/main.py` 2. 直接使用 MCP 工具： nuclei_scan(urls="target.com", templates="http") **跨工具工作流**： ``` 1. nmap_scan(targets="target.com") # Discover open ports 2. ffuf_fuzz(url="target.com:8080/FUZZ") # Enumerate directories 3. nuclei_scan(urls="target.com:8080/*") # Scan found endpoints ``` ## 可扩展性 添加新工具的步骤： 1. 创建 `{tool-name}-claude/` 目录 2. 从 `bh-core` 扩展模型： - `BaseJob` → `{Tool}Job` - `BaseFinding` → `{Tool}Finding` - `BaseRequest` → `{Tool}Request` 3. 创建 `state.py`：`{Tool}StateManager(BaseStateManager)` 4. 创建 `scanner.py`：`start_{tool}_task()` 函数 5. 创建 `api.py`：FastAPI endpoint（POST /api/{action}, GET /api/{action}/{job_id} 等） 6. 创建 `mcp_server.py`：MCP 工具定义（使用 `@mcp.tool()` 注册） 7. 创建 `main.py`：运行 FastAPI + 任务清理 8. 将新工具添加到 `mcp-unified-server/main.py` ## 未来工具 计划添加： - **gobuster** — 目录枚举 - **BloodHound** — Active Directory 枚举 - **Metasploit Framework** — 漏洞利用执行 - **Nessus** — 漏洞扫描 - **Volatility** — 内存取证 - **Zeek** — 网络分析 该模式对于任何 CLI 工具均完全可扩展。 ## 支持 如有疑问或问题，请参阅：`/help`

标签：AV绕过, CISA项目, Claude集成, CTI, DNS枚举, DOE合作, FastAPI, MCP, 主机安全, 安全测试, 密码管理, 插件系统, 攻击性安全, 网络安全工具, 逆向工具