valITino/blhackbox

``` ╔═══════════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ██████╗ ██╗ ██╗ ██╗ █████╗ ██████╗██╗ ██╗██████╗ ██████╗ ██╗ ██╗ ║ ║ ██╔══██╗██║ ██║ ██║██╔══██╗██╔════╝██║ ██╔╝██╔══██╗██╔═══██╗╚██╗██╔╝ ║ ║ ██████╔╝██║ ███████║███████║██║ █████╔╝ ██████╔╝██║ ██║ ╚███╔╝ ║ ║ ██╔══██╗██║ ██╔══██║██╔══██║██║ ██╔═██╗ ██╔══██╗██║ ██║ ██╔██╗ ║ ║ ██████╔╝███████╗ ██║ ██║██║ ██║╚██████╗██║ ██╗██████╔╝╚██████╔╝██╔╝ ██╗ ║ ║ ╚═════╝ ╚══════╝ ╚═╝ ╚═╝╚═╝ ╚═╝ ╚═════╝╚═╝ ╚═╝╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ║ ║ MCP-based Autonomous Pentesting Framework ║ ║ Recon · Exploitation · Post-Exploitation · Reporting ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ by valITino · Docker · Python · FastMCP · Metasploit ║ ║ ║ ╠═══════════════════════════════════════════════════════════════════════════════╣ ║ ⚠ Authorized security testing only — unauthorized use is illegal ║ ║ ║ ╚═══════════════════════════════════════════════════════════════════════════════╝ ``` # BLHACKBOX v2.0.0 [](https://github.com/valITino/blhackbox/actions/workflows/ci.yml) [](https://github.com/valITino/blhackbox/actions/workflows/build-and-push.yml) [](https://www.python.org/downloads/) [](LICENSE) [](https://hub.docker.com/r/crhacky/blhackbox) **基于 MCP 的自主渗透测试框架** ## 目录 | | | |---|---| | **入门** | [工作原理](#how-it-works) · [架构](#architecture) · [前置条件](#prerequisites) · [安装](#installation) | | **技能** | [技能概述](#skills--slash-commands) · [可用技能](#available-skills) · [技能工作原理](#how-skills-work) | | **教程** | [Claude Code (Docker)](#tutorial-1-claude-code-docker--recommended) · [Claude Code (Web)](#tutorial-2-claude-code-web) · [Claude Desktop](#tutorial-3-claude-desktop-host--gateway) · [ChatGPT / OpenAI](#tutorial-4-chatgpt--openai-host--gateway) | | **进阶** | [进阶用法与 FAQ](#advanced-usage--faq) | | **参考** | [组件](#components) · [输出文件](#output-files) · [CLI 参考](#cli-reference) · [Makefile 快捷方式](#makefile-shortcuts) · [Docker Hub 镜像](#docker-hub-images) | | **运维** | [提示词流程](#how-prompts-flow-through-the-system) · [MCP 网关](#do-i-need-the-mcp-gateway) · [Portainer 设置](#portainer-setup) · [Neo4j](#neo4j-optional) · [故障排除](#troubleshooting) | | **安全** | [授权与验证](#authorization--verification) · [安全说明](#security-notes) | | **项目** | [项目结构](#project-structure) · [从源码构建](#build-from-source-optional) · [许可证](#license) | ## 工作原理 在 v2 版本中，**您的 AI 客户端（Claude 或 ChatGPT）即编排器**。这里没有内部的 LangGraph 编排器或 LLM 规划器。当您输入提示词时，流程如下： 1. **您在 AI 客户端中输入提示词**（Claude Code、Claude Desktop 或 ChatGPT）。 2. **AI 决定调用哪些工具**，这些工具来自三个 MCP 服务器 —— Kali MCP（包含 Metasploit 在内的 70 多种安全工具）、WireMCP（7 种数据包分析工具）和 Screenshot MCP（4 种证据捕获工具）。 3. **每个 MCP 服务器在其 Docker 容器中执行工具**，并返回原始输出。 4. **AI 整理结果** —— 解析、去重、关联，并直接构建 `AggregatedPayload`。 5. **AI 验证并持久化** payload，通过 `aggregate_results()`，然后撰写最终的渗透测试报告。 一切都在 Docker 容器内运行。您的主机上不会安装任何工具。 ## 架构 Docker 中的 Claude Code 通过内部 Docker 网络上的 SSE **直接**连接到每个 MCP 服务器 —— 无需 MCP 网关。 ``` YOU (the user) │ │ docker compose run --rm claude-code │ (or attach via Portainer) │ ▼ CLAUDE CODE (Docker container on blhackbox_net) │ │ Reads your prompt, decides which tools to call. │ Connects directly to each MCP server via SSE. │ ├── kali (SSE :9001) ──────────────▶ KALI MCP SERVER │ 70+ tools: nmap, nikto, gobuster, sqlmap, │ hydra, msfconsole, msfvenom, john, hashcat… │ ├── wireshark (SSE :9003) ─────────▶ WIREMCP SERVER │ 7 tools: packet capture, pcap analysis, │ credential extraction │ ├── screenshot (SSE :9004) ────────▶ SCREENSHOT MCP SERVER │ 4 tools: web page screenshots, element │ capture, annotations │ │ After collecting raw outputs, Claude structures them directly: │ get_payload_schema() → parse/dedup/correlate → aggregate_results() │ ▼ AggregatedPayload → generate_report() → final pentest report │ ▼ (optional) NEO4J — cross-session memory PORTAINER (https://localhost:9443) — web UI for all containers ``` 对于基于主机的客户端（Claude Desktop、ChatGPT），一个**可选的 MCP 网关**将所有服务器聚合在 `localhost:8080/mcp` 之后。请参阅 [我需要 MCP 网关吗？](#do-i-need-the-mcp-gateway) ## 技能 / 斜杠命令 技能是 Claude Code 的原生命令，用于启动自主渗透测试工作流。您无需复制粘贴模板或编辑占位符，只需输入带有目标的斜杠命令即可。 ### 可用技能 | 技能 | 描述 | 示例 | |:--|:--|:--| | `/full-pentest` | 完整的端到端渗透测试 | `/full-pentest example.com` | | `/full-attack-chain` | 构建攻击链的最大化影响测试 | `/full-attack-chain 10.0.0.0/24` | | `/quick-scan` | 快速分类 —— 现场利用关键发现 | `/quick-scan 192.168.1.100` | | `/recon-deep` | 全面的攻击面映射 | `/recon-deep example.com` | | `/web-app-assessment` | 针对性的 Web 应用安全测试 | `/web-app-assessment https://app.example.com` | | `/network-infrastructure` | 包含凭据测试的网络级评估 | `/network-infrastructure 10.0.0.0/24` | | `/osint-gathering` | 仅被动情报收集 | `/osint-gathering example.com` | | `/vuln-assessment` | 系统性的漏洞识别与利用 | `/vuln-assessment example.com` | | `/api-security` | REST/GraphQL API 测试 (OWASP API Top 10) | `/api-security https://api.example.com` | | `/bug-bounty` | 漏洞赏金狩猎，附带利用驱动的 PoC 报告 | `/bug-bounty target.com` | ### 技能工作原理 技能位于 `.claude/skills//SKILL.md`。Claude Code 会自动发现它们。 **简单技能**（单一目标） —— 直接传递目标： ``` /quick-scan example.com ``` **多输入技能**（bug-bounty、full-attack-chain、api-security、web-app-assessment） —— Claude 会以交互方式询问更多细节： ``` /bug-bounty example.com ``` Claude 随后会询问： 这通过对话式 UX 取代了旧的手动占位符编辑（`[TARGET]`、`[SCOPE]` 等）。 ### 技能 vs MCP 模板 | | 技能 (`/slash-command`) | MCP 模板 (`get_template`) | |---|---|---| | **客户端** | 仅 Claude Code | 任何 MCP 客户端 (Claude Desktop, ChatGPT) | | **输入** | `$ARGUMENTS` + 交互式提示 | `[TARGET]` 占位符替换 | | **调用** | `/full-pentest example.com` | `get_template("full-pentest", target="example.com")` | | **Docker** | 挂载到 claude-code 容器中 | 通过 blhackbox MCP 服务器提供 | 两种路径并存。对于 Claude Code 用户，技能是首选的 UX。MCP 模板仍然通过网关提供给 Claude Desktop 和 ChatGPT。 ## 组件 | 容器 | 描述 | 端口 | 配置 | |:--|:--|:--:|:--:| | **Kali MCP** | Kali Linux 安全工具 + Metasploit —— 70+ 工具 (nmap, sqlmap, hydra, msfconsole, msfvenom 等) | `9001` | default | | **WireMCP** | Wireshark / tshark —— 7 种数据包捕获和分析工具 | `9003` | default | | **Screenshot MCP** | 无头 Chromium —— 4 种截图和标注工具 | `9004` | default | | **Portainer** | 管理所有容器的 Web UI | `9443` | default | | **Claude Code** | Docker 中的 Anthropic CLI MCP 客户端 | — | `claude-code` | | **MCP Gateway** | 基于主机的 MCP 客户端的单一入口点 | `8080` | `gateway` | | **Neo4j** | 跨会话知识图谱 | `7474` / `7687` | `neo4j` | ## 输出文件 所有输出文件通过 Docker 绑定挂载存储在您主机的 `./output/` 中 —— 无需 `docker cp`。 ``` output/ ├── reports/ ← Pentest reports (.md, .pdf) ├── screenshots/ ← PoC evidence screenshots (.png) └── sessions/ ← Aggregated session JSON files ``` | 容器路径 | 主机路径 | 内容 | |:--|:--|:--| | `output/reports/` | `./output/reports/` | 生成的渗透测试报告 | | `output/screenshots/` | `./output/screenshots/` | Screenshot MCP 捕获和标注（在 Claude Code 中只读） | | `output/sessions/` | `./output/sessions/` | `AggregatedPayload` 会话 JSON 文件 | 此外，一个共享的 Docker 卷（`shared-output`）连接了 Kali MCP 和 Claude Code： | 容器 | 挂载路径 | 访问权限 | 用途 | |:--|:--|:--:|:--| | Kali MCP | `/root/output/` | 读写 | 工具输出文件（侦察数据、payload） | | Claude Code | `/root/kali-data/` | 只读 | 访问 Kali 的侦察产物 | `output/` 目录由 `setup.sh` 自动创建。对于手动安装：`mkdir -p output/reports output/screenshots output/sessions` ## 前置条件 - **Docker** 和 **Docker Compose**（Linux 上的 Docker Engine，或 Docker Desktop） - 建议至少 **8 GB RAM**（核心堆栈中有 4 个容器） - 来自 [console.anthropic.com](https://console.anthropic.com) 的 **Anthropic API key**（Docker 中的 Claude Code 必需） ## 安装 ### 快速开始（推荐） ``` git clone https://github.com/valITino/blhackbox.git cd blhackbox ./setup.sh ``` 设置向导将： 1. 检查前置条件（Docker、Docker Compose、磁盘空间） 2. 让您选择可选组件（Neo4j、MCP Gateway） 3. 提示输入您的 `ANTHROPIC_API_KEY`（Docker 中的 Claude Code 必需） 4. 生成 `.env` 并创建 `output/` 目录 5. 拉取 Docker 镜像并启动所有服务 6. 等待健康检查通过 非交互式标志： ``` ./setup.sh --api-key sk-ant-... --minimal # Core stack only ./setup.sh --api-key sk-ant-... --with-neo4j # Core + Neo4j ./setup.sh --help # All options ``` 或使用 Makefile 快捷方式：`make setup` ### 手动安装 ``` # 1. Clone git clone https://github.com/valITino/blhackbox.git && cd blhackbox # 2. Configure cp .env.example .env # 必需：在 .env 中设置 ANTHROPIC_API_KEY=sk-ant-... # 3. 创建输出目录 mkdir -p output/reports output/screenshots output/sessions # 4. Pull 镜像并启动 docker compose pull docker compose up -d ``` **设置授权**（运行渗透测试前必需）： ``` # 5. 填写 engagement 详情 nano verification.env # 完成所有字段后设置 AUTHORIZATION_STATUS=ACTIVE # 6. 渲染活动验证文档 make inject-verification ``` 详情请参阅 [授权与验证](#authorization--verification)。 **验证一切正在运行：** ``` make status # Container status make health # MCP server health check ``` 您应该看到 4 个健康的容器：`blhackbox-kali-mcp`、`blhackbox-wire-mcp`、`blhackbox-screenshot-mcp`、`blhackbox-portainer`。 ## 教程 1：Claude Code (Docker) —— 推荐 Claude Code 完全在与所有 blhackbox 服务相同的网络中的 Docker 容器内运行。它通过 SSE **直接**连接到每个 MCP 服务器 —— 无需 MCP 网关，无需主机安装，无需 Node.js。 ### 步骤 1 —— 启动堆栈 请按照上面的 [安装](#installation) 进行。确保 `.env` 中设置了 `ANTHROPIC_API_KEY`，并且所有核心容器都处于健康状态（`make health`）。 ### 步骤 2 —— 启动 Claude Code ``` make claude-code ``` 或手动： ``` docker compose --profile claude-code run --rm claude-code ``` 入口点脚本会检查每个服务，并显示包含可用技能的状态仪表板。 您现在处于一个交互式的 Claude Code 会话中。 ### 步骤 3 —— 验证连接 ``` /mcp ``` 您应该看到 `kali`、`wireshark` 和 `screenshot`，以及它们各自的可用工具。 ### 步骤 4 —— 运行您的第一次渗透测试 使用带有目标的技能（斜杠命令）： ``` /quick-scan example.com ``` 或者进行完整的测试： ``` /full-pentest example.com ``` Claude Code 将自主地： 1. 调用 Kali 工具（nmap、subfinder、nikto、sqlmap、msfconsole 等） 2. 通过 WireMCP 捕获网络流量并提取凭据 3. 通过 Screenshot MCP 截取证据截图 4. 将发现结果结构化、去重并关联到 `AggregatedPayload` 5. 通过 `aggregate_results()` 验证并撰写结构化的渗透测试报告 请参阅 [可用技能](#available-skills) 以了解所有 10 种渗透测试工作流。 ### 监控（单独终端） ``` make logs-kali # Kali MCP server activity (includes Metasploit) make logs-wireshark # WireMCP activity make logs-screenshot # Screenshot MCP activity ``` 或使用位于 `https://localhost:9443` 的 **Portainer** 获取统一仪表板。 ## 教程 2：Claude Code (Web) [claude.ai/code](https://claude.ai/code) 上的 Claude Code 可作为基于 Web 的代码代理使用。当您在 Web 会话中打开此仓库时，MCP 服务器会自动配置。 ### 工作原理 - **`.mcp.json`**（项目根目录）—— 告诉 Claude Code 通过 stdio 启动 blhackbox MCP 服务器 - **`.claude/hooks/session-start`** —— 在会话开始时自动安装依赖项 ### 步骤 1. 前往 [claude.ai/code](https://claude.ai/code) 并打开此仓库 2. session-start 钩子自动安装依赖项并注入验证 3. 输入 `/mcp` 进行验证 —— 您应该看到 `blhackbox` 及其工具 4. 使用技能：`/quick-scan example.com` 技能（`.claude/skills/`）在 Web 会话中自动可用，因为它们已提交到仓库中。 ## 教程 3：Claude Desktop（主机 + 网关） Claude Desktop 是一个 GUI 应用程序，无法在 Docker 中运行。它通过 `localhost:8080` 上的 **MCP Gateway** 连接到 blhackbox。 ### 步骤 1 —— 启动带有网关的堆栈 ``` docker compose up -d # core stack docker compose --profile gateway up -d # adds the MCP Gateway # 或者快捷方式： make up-gateway ``` ### 步骤 2 —— 配置 Claude Desktop 打开配置文件： | 平台 | 路径 | |:--|:--| | macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | | Windows | `%APPDATA%\Claude\claude_desktop_config.json` | | Linux | `~/.config/Claude/claude_desktop_config.json` | 添加： ``` { "mcpServers": { "blhackbox": { "transport": "streamable-http", "url": "http://localhost:8080/mcp" } } } ``` 重启 Claude Desktop。您应该会看到一个包含可用工具的锤子图标。 ### 步骤 3 —— 运行渗透测试 在 Claude Desktop 中输入您的提示词。流程与教程 1 完全相同 —— 网关将工具调用路由到相同的 MCP 服务器。 ## 教程 4：ChatGPT / OpenAI（主机 + 网关） ChatGPT / OpenAI 客户端也通过 `localhost:8080` 上的 **MCP Gateway** 连接。 ### 步骤 1 —— 启动带有网关 ``` make up-gateway ``` ### 步骤 2 —— 配置您的客户端 将您支持 MCP 的 OpenAI 客户端指向： | 设置 | 值 | |:--|:--| | URL | `http://localhost:8080/mcp` | | 传输方式 | Streamable HTTP | 网关是 AI 无关的 —— 它向任何 MCP 客户端提供相同的工具。 ## 进阶用法与 FAQ ### 如何从头到尾运行完整的渗透测试？ ``` /full-pentest example.com ``` 这个单一命令触发 6 阶段的自主工作流：被动侦察、主动扫描、Web 枚举、带数据提取的漏洞利用、数据聚合到 `AggregatedPayload`，以及专业报告生成。Claude 处理一切 —— 工具选择、证据收集、PoC 创建和最终报告。 ### 如何在范围限制下运行漏洞赏金狩猎？ ``` /bug-bounty target.com ``` Claude 会在开始之前以交互方式询问您项目范围、排除范围和项目规则。它会根据您的范围过滤所有发现的资产，仅测试范围内的目标。 ### 如何测试带认证的 API？ ``` /api-security https://api.example.com/v1 ``` Claude 会询问您是否有 API 文档、API 密钥或认证令牌。提供您拥有的信息 —— Claude 会相应调整评估，测试已认证和未认证的路径。 ### 如何将侦察链接到完整渗透测试中？ 先运行侦察，然后使用相同目标跟进完整渗透测试： ``` /recon-deep example.com ``` 查看侦察报告，然后： ``` /full-pentest example.com ``` 完整渗透测试将独立重新发现攻击面并深入进行漏洞利用。如果您启用了 Neo4j（`--profile neo4j`），两个会话的发现结果都会存储在知识图谱中以进行跨会话关联。 ### 如何使用凭据测试 Web 应用？ ``` /web-app-assessment https://app.example.com ``` Claude 会询问：“您是否有用于认证测试的凭据或会话令牌？” 提供您的 cookie、认证头或用户名/密码。Claude 测试已认证和未认证区域。 ### 如何快速分类新目标？ ``` /quick-scan 192.168.1.100 ``` 快速扫描运行并行发现（端口、子域名、技术、WAF 检测），并立即利用其发现的任何关键或高严重性发现。最后提供简洁报告并建议下一步运行哪个更深入的评估。 ### 我可以使用自然语言代替技能吗？ 可以。技能是捷径，不是要求。您随时可以输入自由格式的提示词： ``` Scan example.com for open ports, test for SQL injection on any web services found, and write a report with PoC evidence for every finding. ``` Claude 将直接使用 MCP 工具。技能只是为 Claude 提供了结构化的行动指南。 ### 如何创建自己的自定义技能？ 在 `.claude/skills/` 中创建包含 `SKILL.md` 文件的目录： ``` .claude/skills/my-custom-scan/ └── SKILL.md ``` `SKILL.md` 文件包含 YAML 前言和 markdown 说明： ``` --- name: my-custom-scan description: Custom scan focusing on specific vulnerability class --- # 我的自定义 Scan The target is: **$ARGUMENTS** If no target was provided, ask the user for one. ## Steps 1. ...your custom methodology... ``` Claude Code 会自动将其发现为 `/my-custom-scan`。 ### 子目录中的 CLAUDE.md 文件如何工作？ 仓库具有目录作用域的 `CLAUDE.md` 文件，用于强制执行本地开发规则： | 文件 | 规则 | |:--|:--| | `blhackbox/mcp/CLAUDE.md` | MCP 工具验证，验证文档处理 | | `blhackbox/models/CLAUDE.md` | `AggregatedPayload` schema 契约，PoC 字段强制 | | `blhackbox/backends/CLAUDE.md` | `shell=False` 强制，工具白名单 | | `blhackbox/reporting/CLAUDE.md` | 报告路径约定，WeasyPrint 兼容性 | 当 Claude Code 触及这些目录中的文件时，它们会按需加载。这不会增加不相关工作的上下文负担。 ### 报告存储在哪里？ 所有输出存储在您主机的 `./output/` 中（从 Docker 绑定挂载）： ``` output/ ├── reports/ ← Pentest reports (.md, .pdf) organized by date ├── screenshots/ ← PoC evidence screenshots (.png) └── sessions/ ← AggregatedPayload session JSONs ``` 报告遵循命名约定：`output/reports/reports-DDMMYYYY/report--DDMMYYYY.md` ### 如何为实验室/CTF 设置授权？ 在 `verification.env` 中的最小自授权设置： ``` AUTHORIZATION_STATUS=ACTIVE ENGAGEMENT_ID=LAB-2026-001 AUTHORIZATION_DATE=2026-03-15 EXPIRATION_DATE=2026-12-31 AUTHORIZING_ORGANIZATION=My Lab TESTER_NAME=Your Name TARGET_1=192.168.1.0/24 TARGET_1_TYPE=network TESTING_START=2026-03-15 00:00 TESTING_END=2026-12-31 23:59 SIGNATORY_NAME=Your Name SIGNATURE_DATE=2026-03-15 ``` 然后：`make inject-verification` 完整设置请参阅 [授权与验证](#authorization--verification)。 ## 提示词如何在系统中流转 ``` STEP 1 ─ YOU TYPE A PROMPT "Scan example.com for open ports and web vulnerabilities" │ ▼ STEP 2 ─ AI DECIDES WHICH TOOLS TO USE Claude picks tools from Kali MCP (incl. Metasploit), WireMCP, Screenshot MCP: • subfinder (Kali) → find subdomains • nmap -sV -sC (Kali) → port scan + service detection • nikto (Kali) → web server scanning • msf_search (Kali/MSF) → find matching exploits • capture_packets (WireMCP) → capture traffic during scanning │ ▼ STEP 3 ─ TOOLS EXECUTE IN DOCKER CONTAINERS Claude Code (Docker) connects directly via SSE. Claude Desktop / ChatGPT connect via the MCP Gateway. Each tool runs in its container and returns raw text. │ ▼ STEP 4 ─ AI STRUCTURES THE RESULTS The AI parses, deduplicates, correlates, and structures all raw outputs into an AggregatedPayload directly. No external pipeline — the MCP host is the brain. │ ▼ STEP 5 ─ AI VALIDATES AND PERSISTS Calls aggregate_results(payload=...) to validate the AggregatedPayload against the Pydantic schema and save it. │ ▼ STEP 6 ─ AI WRITES THE FINAL REPORT Executive summary, findings by severity, remediation, appendix. │ ▼ STEP 7 ─ (OPTIONAL) RESULTS STORED IN NEO4J Cross-session memory for recurring engagements. ``` ## 我需要 MCP 网关吗？ | MCP 客户端 | 需要网关？ | 连接方式 | |:--|:--:|:--| | **Claude Code (Docker)** | 否 | 通过 Docker 网络直接 SSE 连接到每个 MCP 服务器 | | **Claude Code (Web)** | 否 | 来自 `.mcp.json` 的 Stdio MCP 服务器 | | **Claude Desktop** | **是** | 主机 GUI 应用 → `localhost:8080/mcp` 网关 | | **ChatGPT / OpenAI** | **是** | 主机 GUI/Web 应用 → `localhost:8080/mcp` 网关 | MCP Gateway（`docker/mcp-gateway:latest`）将所有 MCP 服务器聚合在 `localhost:8080/mcp` 的单一 Streamable HTTP 端点后。它需要 Docker socket 挂载（`/var/run/docker.sock`）和 `--profile gateway` 标志。 ``` make up-gateway # starts core stack + gateway ``` ## Portainer 设置 Portainer CE 提供了一个用于管理所有 blhackbox 容器的 Web UI。 **URL：** `https://localhost:9443` ### 首次运行 首次启动时，Portainer 要求您在 **5 分钟内**创建管理员账户。如果您错过了时间窗口： ``` docker compose restart portainer ``` 然后再次打开 `https://localhost:9443` 并创建您的账户。 ### 您可以做什么 - 查看所有容器状态、日志和资源使用情况 - 重启单个容器 - 检查环境变量和网络配置 - 监控每个服务的健康状况 ## 故障排除 ### Claude Code 对 MCP 服务器显示“Status: failed” MCP 服务器可能尚未就绪： ``` make health # quick health check make status # container status docker compose logs # full logs ``` 如果服务显示 `FAIL`，重启它： ``` docker compose restart kali-mcp ``` ### Metasploit 工具缓慢或失败 Metasploit 工具（`msf_search`、`msf_run_module` 等）使用 `msfconsole -qx` 进行 CLI 执行。由于 Ruby 和数据库初始化（冷启动），首次调用需要 **10–30 秒**。后续调用会更快。 如果 Metasploit 命令失败： 1. 检查安装：`docker exec blhackbox-kali-mcp which msfconsole` 2. 检查数据库状态：使用 `msf_status` 工具 3. 检查容器日志：`make logs-kali` ### Portainer 首次访问显示“Timeout” Portainer 启动后，您有 5 分钟时间创建管理员账户。错过了？运行 `docker compose restart portainer`。 ### MCP 网关无法启动 网关是可选的 —— Docker 中的 Claude Code 不使用它。如果您需要它用于 Claude Desktop / ChatGPT： 1. 确保 Docker socket 存在：`ls -la /var/run/docker.sock` 2. 使用网关配置文件启动：`make up-gateway` 3. 检查日志：`make gateway-logs` ### 容器不断重启 检查其日志： ``` docker compose logs # e.g., kali-mcp, wire-mcp ``` 常见原因：主机上的端口冲突，内存不足。 ## CLI 参考 ``` blhackbox version # Show version and config blhackbox recon --target example.com # Run recon blhackbox recon --target example.com --attacks nmap,subfinder blhackbox recon --target example.com --full # Full recon suite blhackbox run-tool -c network -t nmap -p '{"target":"example.com"}' # Single tool blhackbox graph query "MATCH (n) RETURN n LIMIT 10" # Neo4j query blhackbox graph summary -t example.com # Target summary blhackbox report -s SESSION_ID --format pdf # Generate report blhackbox mcp # Start MCP server ``` ## Makefile 快捷方式 | 目标 | 描述 | |:--|:--| | `make setup` | 交互式设置向导（前置条件、.env、拉取、启动、健康检查） | | `make help` | 显示所有可用目标 | | `make pull` | 从 Docker Hub 拉取所有预构建镜像 | | `make up` | 启动核心堆栈（4 个容器） | | `make up-full` | 启动并包含 Neo4j（5 个容器） | | `make up-gateway` | 启动并包含 Claude Desktop 的 MCP Gateway（5 个容器） | | `make down` | 停止所有服务 | | `make claude-code` | 构建并在 Docker 中启动 Claude Code | | `make status` | 容器状态表 | | `make health` | 所有服务的快速健康检查 | | `make test` | 运行测试 | | `make lint` | 运行代码检查 | | `make portainer` | 打开 Portainer 仪表板 | | `make gateway-logs` | 实时 MCP Gateway 日志 | | `make logs-kali` | 查看 Kali MCP 日志（包括 Metasploit） | | `make logs-wireshark` | 查看 WireMCP 日志 | | `make logs-screenshot` | 查看 Screenshot MCP 日志 | | `make inject-verification` | 渲染 verification.env → 活跃授权文档 | | `make push-all` | 构建并将所有镜像推送到 Docker Hub | ## 从源码构建（可选） 仅当您想修改 Dockerfile 或代理代码时需要： ``` git submodule update --init --recursive # fetch kali-mcp source docker compose build # build all images locally docker compose up -d ``` ## Docker Hub 镜像 所有自定义镜像发布到 `crhacky/blhackbox`： | 标签 | 描述 | |:--|:--| | `crhacky/blhackbox:kali-mcp` | Kali Linux MCP 服务器（70+ 工具 + Metasploit Framework） | | `crhacky/blhackbox:wire-mcp` | WireMCP 服务器（tshark，7 种工具） | | `crhacky/blhackbox:screenshot-mcp` | Screenshot MCP 服务器（无头 Chromium，4 种工具） | | `crhacky/blhackbox:claude-code` | Claude Code CLI 客户端（直接 SSE 连接到 MCP 服务器） | 直接拉取的官方镜像： | 镜像 | 用途 | |:--|:--| | `portainer/portainer-ce:latest` | Docker 管理 UI | | `neo4j:5` | 知识图谱（可选） | | `docker/mcp-gateway:latest` | MCP 网关（可选） | ## Neo4j（可选） Neo4j 提供跨会话记忆。使用 `--profile neo4j` 启用： ``` docker compose --profile neo4j up -d ``` 每次会话后将 `AggregatedPayload` 结果存储为图谱。对于针对相同目标的重复测试非常有用。 ## 授权与验证 在运行任何渗透测试模板之前，blhackbox 需要一份**活跃的验证文档** —— 明确的书面授权，确认您有权限测试目标。没有它，Claude Code 将拒绝执行攻击性操作。 ### 工作原理 ``` verification.env You fill in engagement details (target, scope, │ testing window, authorized activities, signatory) │ ▼ inject_verification.py Renders the template with your values │ ▼ verification.md Template with {{PLACEHOLDER}} tokens │ ▼ .claude/verification- Active document loaded into Claude Code session. active.md Automatically appended to every pentest template. ``` 当您加载渗透测试模板（通过 `get_template` MCP 工具）时，活跃的验证文档会自动作为授权上下文附加。如果不存在，Claude 将提示您进行设置。 ### 逐步设置 **1. 编辑项目根目录下的 `verification.env`**： ``` nano verification.env # or vim, code, etc. ``` 填写 6 个部分中的**所有**字段： | 部分 | 字段 | |:--|:--| | **测试 ID** | `ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TESTER_EMAIL`, `CLIENT_CONTACT_NAME`, `CLIENT_CONTACT_EMAIL` | | **范围** | `TARGET_1` 到 `TARGET_3`（带有 `_TYPE` 和 `_NOTES`），`OUT_OF_SCOPE`, `ENGAGEMENT_TYPE `CREDENTIALS` | | **活动** | 切换每个 `PERMIT_*` 字段（`x` = 允许，空白 = 拒绝）：侦察、扫描、枚举、利用、数据提取、凭据测试、后渗透、流量捕获、截图 | | **测试窗口** | `TESTING_START`, `TESTING_END`, `TIMEZONE`, `EMERGENCY_CONTACT`, `EMERGENCY_PHONE` | | **法律** | `APPLICABLE_STANDARDS`, `REPORT_CLASSIFICATION`, `REPORT_DELIVERY` | | **签名** | `SIGNATORY_NAME`, `SIGNATORY_TITLE`, `SIGNATORY_ORGANIZATION`, `SIGNATURE_DATE`, `DIGITAL_SIGNATURE` | **2. 激活** —— 设置状态字段： ``` AUTHORIZATION_STATUS=ACTIVE ``` **3. 注入** —— 渲染活跃文档： ``` make inject-verification ``` 或直接运行：`python -m blhackbox.prompts.inject_verification` 成功后： ``` Verification document activated → .claude/verification-active.md Engagement: PENTEST-2026-001 Targets: example.com, 10.0.0.0/24 Window: 2026-03-01 09:00 — 2026-03-31 17:00 UTC Authorized by: Jane Smith ``` **4. 开始您的会话** —— Claude Code 将自动获取验证文档。在 Claude Code Web 上，如果存在 `verification.env`，session-start 钩子会自动运行 `inject-verification`。 ### 验证规则 注入脚本在渲染前进行验证： - `AUTHORIZATION_STATUS` 必须为 `ACTIVE` - 所有必填字段必须填写（`ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TARGET_1`, `TESTING_START`, `TESTING_END`, `SIGNATORY_NAME`, `SIGNATURE_DATE`） - `EXPIRATION_DATE` 不能是过去的日期 如果任何检查失败，脚本将退出并显示解释需要修复内容的错误。 ### 涉及文件 | 文件 | 用途 | |:--|:--| | `verification.env` | 用户可填写的配置，包含测试详情、范围和权限 | | `blhackbox/prompts/verification.md` | 带有 `{{PLACEHOLDER}}` 标记的模板 | | `blhackbox/prompts/inject_verification.py` | 将模板渲染为活跃文档 | | `.claude/verification-active.md` | 渲染后的活跃授权（git-ignored） | 有关最小自授权实验室设置，请参阅进阶 FAQ 中的 [如何为实验室/CTF 设置授权？](#how-do-i-set-up-authorization-for-a-labctf)。 ## 安全说明 - **Docker socket** —— MCP Gateway（可选）和 Portainer 挂载 `/var/run/docker.sock`。这授予了主机上的有效 root 权限。切勿将端口 8080 或 9443 暴露给公共互联网。 - **授权** —— 在运行任何渗透测试之前设置 [验证文档](#authorization--verification)。没有活跃授权，Claude Code 将不执行攻击性操作。渲染后的文档（`.claude/verification-active.md`）已被 git-ignore。 - **Neo4j** —— 在 `.env` 中设置强密码。切勿在生产环境中使用默认值。 - **Portainer** —— 使用带有自签名证书的 HTTPS。首次运行时创建强管理员密码。 ## 项目结构 ``` blhackbox/ ├── setup.sh Interactive setup wizard ├── CLAUDE.md Project-wide development rules ├── .claude/ │ ├── settings.json Claude Code hooks config │ ├── verification-active.md Rendered authorization (git-ignored) │ ├── hooks/ │ │ └── session-start.sh Auto-setup for web sessions │ └── skills/ Pentesting skill slash commands │ ├── full-pentest/SKILL.md /full-pentest │ ├── full-attack-chain/SKILL.md /full-attack-chain │ ├── quick-scan/SKILL.md /quick-scan │ ├── recon-deep/SKILL.md /recon-deep │ ├── web-app-assessment/SKILL.md /web-app-assessment │ ├── network-infrastructure/SKILL.md /network-infrastructure │ ├── osint-gathering/SKILL.md /osint-gathering │ ├── vuln-assessment/SKILL.md /vuln-assessment │ ├── api-security/SKILL.md /api-security │ └── bug-bounty/SKILL.md /bug-bounty ├── output/ Host-accessible outputs (git-ignored) │ ├── reports/ Generated pentest reports │ ├── screenshots/ PoC evidence captures │ └── sessions/ Aggregated session JSONs ├── verification.env Pentest authorization config ├── .mcp.json MCP server config (Claude Code Web) ├── docker/ │ ├── kali-mcp.Dockerfile Kali Linux + Metasploit Framework │ ├── wire-mcp.Dockerfile │ ├── screenshot-mcp.Dockerfile │ ├── claude-code.Dockerfile MCP client container │ └── claude-code-entrypoint.sh Startup script with health checks ├── kali-mcp/ Kali MCP server (70+ tools + Metasploit) ├── wire-mcp/ WireMCP server (tshark, 7 tools) ├── screenshot-mcp/ Screenshot MCP server (Playwright, 4 tools) ├── blhackbox/ │ ├── mcp/ │ │ ├── server.py blhackbox MCP server (stdio) │ │ └── CLAUDE.md MCP development rules │ ├── models/ │ │ ├── aggregated_payload.py AggregatedPayload Pydantic model │ │ ├── base.py, graph.py │ │ └── CLAUDE.md Schema contract rules │ ├── backends/ │ │ ├── local.py CLI tool execution backend │ │ └── CLAUDE.md Backend safety rules (shell=False) │ ├── prompts/ │ │ ├── templates/ 10 pentest template .md files │ │ ├── claude_playbook.md Pentest playbook for MCP host │ │ ├── verification.md Authorization template │ │ └── inject_verification.py Renders template → active document │ ├── reporting/ │ │ ├── html_generator.py, pdf_generator.py, md_generator.py │ │ └── CLAUDE.md Reporting path conventions │ ├── core/ Knowledge graph, exporters │ ├── modules/ Custom analysis modules │ ├── utils/ Logging, tool catalog │ ├── data/ tools_catalog.json │ ├── main.py CLI interface │ ├── config.py Centralized settings │ └── exceptions.py Custom exception hierarchy ├── blhackbox-mcp-catalog.yaml MCP Gateway catalog (optional) ├── docker-compose.yml ├── .env.example ├── Makefile ├── tests/ └── .github/workflows/ ├── ci.yml └── build-and-push.yml ``` ## 许可证 MIT

标签：AI智能体, ChatGPT, CISA项目, Claude, CVE检测, Docker容器化, HTTP工具, LLM评估, MCP协议, MetaSploit, Nmap, Ollama, PE 加载器, Promptflow, SQLMap, Web报告查看器, Wireshark, 句柄查看, 大模型编排, 安全报告, 密码管理, 插件系统, 攻击模拟, 无头浏览器, 特征检测, 网络安全, 自动化渗透, 虚拟驱动器, 请求拦截, 逆向工具, 隐私保护, 驱动签名利用