From 1073404256ffcf975407e0baccbbf7d5c37f9746 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 13 Mar 2026 17:38:48 +0000 Subject: [PATCH] docs: polish README.md and DOCKER.md formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Restructure ToC into a compact grouped table layout - Replace raw badge lines with centered header block + badges - Standardize all tables with left-aligned columns - Use Unicode arrows (▶, │, ▼) in architecture/flow diagrams - Convert Makefile shortcuts from code block to a proper table - Restructure DOCKER.md image details into key-value tables - Improve section headers with em-dash separators for tutorials - Tighten prose and remove redundant wording throughout - Keep ASCII art banner as-is per user preference https://claude.ai/code/session_01Y98MjXqwEby44mfgvqiAgd --- DOCKER.md | 248 ++++++++++----------- README.md | 630 +++++++++++++++++++++++------------------------------- 2 files changed, 394 insertions(+), 484 deletions(-) diff --git a/DOCKER.md b/DOCKER.md index 8d5b0cc..52ebfe8 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -1,4 +1,4 @@ -# crhacky/blhackbox +# BLHACKBOX — Docker Reference **MCP-based Autonomous Pentesting Framework** @@ -9,65 +9,72 @@ All custom images are published to a single Docker Hub repository, differentiated by tag. | | | -|---|---| -| **Repository** | `crhacky/blhackbox` | +|:--|:--| +| **Repository** | [`crhacky/blhackbox`](https://hub.docker.com/r/crhacky/blhackbox) | | **Registry** | [Docker Hub](https://hub.docker.com/r/crhacky/blhackbox) | | **Source** | [GitHub](https://github.com/valITino/blhackbox) | | **License** | MIT | --- -## Images and Tags +## Images & Tags Four custom images are published to `crhacky/blhackbox` on Docker Hub: -| Service | Tag | Dockerfile | Base | -|---|---|---|---| +| Service | Tag | Dockerfile | Base Image | +|:--|:--|:--|:--| | **Kali MCP** | `crhacky/blhackbox:kali-mcp` | `docker/kali-mcp.Dockerfile` | `kalilinux/kali-rolling` | | **WireMCP** | `crhacky/blhackbox:wire-mcp` | `docker/wire-mcp.Dockerfile` | `debian:bookworm-slim` | | **Screenshot MCP** | `crhacky/blhackbox:screenshot-mcp` | `docker/screenshot-mcp.Dockerfile` | `python:3.13-slim` | | **Claude Code** | `crhacky/blhackbox:claude-code` | `docker/claude-code.Dockerfile` | `node:22-slim` | -Official images pulled directly (no custom build): -- `portainer/portainer-ce:latest` — Docker management UI -- `docker/mcp-gateway:latest` — MCP Gateway (optional, `--profile gateway`) -- `neo4j:5` — Knowledge graph (optional, `--profile neo4j`) +Official images (pulled directly, no custom build): + +| Image | Purpose | +|:--|:--| +| `portainer/portainer-ce:latest` | Docker management UI | +| `docker/mcp-gateway:latest` | MCP Gateway (optional, `--profile gateway`) | +| `neo4j:5` | Knowledge graph (optional, `--profile neo4j`) | ### Pulling Images ```bash -# Pull ALL images (custom + official) in one command -docker compose pull +docker compose pull # pull ALL images (custom + official) in one command ``` --- ## Architecture -In v2, **Claude (or OpenAI) IS the orchestrator** natively via MCP. +In v2, **Claude (or ChatGPT) IS the orchestrator** natively via MCP. -**Claude Code (Docker)** connects directly to each MCP server via SSE: +### Claude Code in Docker — Direct SSE (no gateway) ``` -Claude Code ──┬──> Kali MCP (SSE, port 9001) -(container) │ 70+ tools: nmap, sqlmap, hydra, msfconsole, msfvenom, etc. - ├──> WireMCP (SSE, port 9003) - ├──> Screenshot MCP (SSE, port 9004) +Claude Code ──┬──▶ Kali MCP (SSE :9001) +(container) │ 70+ tools: nmap, sqlmap, hydra, msfconsole, msfvenom… + │ + ├──▶ WireMCP (SSE :9003) + │ 7 tools: packet capture, pcap analysis, credential extraction + │ + ├──▶ Screenshot MCP (SSE :9004) + │ 4 tools: web screenshots, element capture, annotations │ │ After collecting raw outputs, Claude structures them directly: │ get_payload_schema() → parse/dedup/correlate → aggregate_results() - + │ + ▼ output/ Host-mounted directory for reports, screenshots, sessions Portainer Docker UI (https://localhost:9443) Neo4j Cross-session memory (optional) ``` -**Claude Desktop / ChatGPT (host)** connect via the MCP Gateway: +### Claude Desktop / ChatGPT — via MCP Gateway ``` -Claude Desktop ──> MCP Gateway (localhost:8080/mcp) ──┬──> Kali MCP -(host app) ├──> WireMCP - └──> Screenshot MCP +Claude Desktop ──▶ MCP Gateway (localhost:8080/mcp) ──┬──▶ Kali MCP +(host app) ├──▶ WireMCP + └──▶ Screenshot MCP ``` --- @@ -79,16 +86,15 @@ Claude Desktop ──> MCP Gateway (localhost:8080/mcp) ──┬──> Kali MC ```bash git clone https://github.com/valITino/blhackbox.git cd blhackbox -./setup.sh # interactive wizard: prereqs, .env, pull, start, health +./setup.sh # interactive wizard: prereqs, .env, pull, start, health ``` ### Manual — Core Stack (4 containers) ```bash -git clone https://github.com/valITino/blhackbox.git -cd blhackbox +git clone https://github.com/valITino/blhackbox.git && cd blhackbox cp .env.example .env -# REQUIRED: Uncomment and set ANTHROPIC_API_KEY=sk-ant-... in .env +# REQUIRED: set ANTHROPIC_API_KEY=sk-ant-... in .env mkdir -p output/reports output/screenshots output/sessions docker compose pull docker compose up -d @@ -97,13 +103,13 @@ docker compose up -d ### With Claude Code (Recommended) ```bash -make claude-code # builds + launches Claude Code in Docker +make claude-code # builds + launches Claude Code in Docker ``` ### With MCP Gateway (for Claude Desktop / ChatGPT) ```bash -make up-gateway # starts core + gateway on port 8080 +make up-gateway # starts core + gateway on port 8080 ``` ### With Neo4j @@ -115,8 +121,8 @@ docker compose --profile neo4j up -d ### Verify ```bash -make status # container status table -make health # MCP server health check +make status # container status table +make health # MCP server health check ``` --- @@ -124,14 +130,14 @@ make health # MCP server health check ## Compose Services | Service | Image | Port | Profile | Role | -|---|---|---|---|---| +|:--|:--|:--:|:--:|:--| | `kali-mcp` | `crhacky/blhackbox:kali-mcp` | `9001` | default | Kali Linux security tools + Metasploit (70+) | -| `wire-mcp` | `crhacky/blhackbox:wire-mcp` | `9003` | default | Wireshark/tshark (7 tools) | +| `wire-mcp` | `crhacky/blhackbox:wire-mcp` | `9003` | default | Wireshark / tshark (7 tools) | | `screenshot-mcp` | `crhacky/blhackbox:screenshot-mcp` | `9004` | default | Screenshot MCP (headless Chromium, 4 tools) | | `portainer` | `portainer/portainer-ce:latest` | `9443` | default | Docker management UI (HTTPS) | -| `claude-code` | `crhacky/blhackbox:claude-code` | - | `claude-code` | Claude Code CLI client (Docker) | +| `claude-code` | `crhacky/blhackbox:claude-code` | — | `claude-code` | Claude Code CLI client (Docker) | | `mcp-gateway` | `docker/mcp-gateway:latest` | `8080` | `gateway` | Single MCP entry point (host clients) | -| `neo4j` | `neo4j:5` | `7474` `7687` | `neo4j` | Cross-session knowledge graph | +| `neo4j` | `neo4j:5` | `7474` / `7687` | `neo4j` | Cross-session knowledge graph | --- @@ -144,9 +150,9 @@ The Claude Code container's `.mcp.json` connects directly to each server: ```json { "mcpServers": { - "kali": { "type": "sse", "url": "http://kali-mcp:9001/sse" }, - "wireshark": { "type": "sse", "url": "http://kali-mcp:9003/sse" }, - "screenshot": { "type": "sse", "url": "http://screenshot-mcp:9004/sse" } + "kali": { "type": "sse", "url": "http://kali-mcp:9001/sse" }, + "wireshark": { "type": "sse", "url": "http://wire-mcp:9003/sse" }, + "screenshot": { "type": "sse", "url": "http://screenshot-mcp:9004/sse" } } } ``` @@ -173,52 +179,66 @@ Requires `--profile gateway` (`make up-gateway`). ## Environment Variables | Variable | Default | Description | -|---|---|---| -| `ANTHROPIC_API_KEY` | - | Required for Claude Code in Docker | +|:--|:--|:--| +| `ANTHROPIC_API_KEY` | — | Required for Claude Code in Docker | | `MCP_GATEWAY_PORT` | `8080` | MCP Gateway host port (optional) | | `MSF_TIMEOUT` | `300` | Metasploit command timeout in seconds | | `NEO4J_URI` | `bolt://neo4j:7687` | Neo4j connection URI (optional) | | `NEO4J_USER` | `neo4j` | Neo4j username (optional) | -| `NEO4J_PASSWORD` | - | Neo4j password, min 8 chars (optional) | +| `NEO4J_PASSWORD` | — | Neo4j password, min 8 chars (optional) | | `SCREENSHOT_MCP_PORT` | `9004` | Screenshot MCP server port | -| `OPENAI_API_KEY` | - | For OpenAI MCP clients (optional) | +| `OPENAI_API_KEY` | — | For OpenAI MCP clients (optional) | --- ## Image Details -### Kali MCP (`crhacky/blhackbox:kali-mcp`) +### Kali MCP — `crhacky/blhackbox:kali-mcp` + +| | | +|:--|:--| +| **Base** | `kalilinux/kali-rolling` | +| **Transport** | SSE on port 9001 | +| **Privileged** | Yes (raw socket access) | +| **Entrypoint** | `entrypoint.sh` (starts PostgreSQL for MSF DB, then MCP server) | + +**Tools (70+):** nmap, masscan, hping3, subfinder, amass, fierce, dnsenum, dnsrecon, theharvester, nikto, gobuster, dirb, dirsearch, ffuf, feroxbuster, whatweb, wafw00f, wpscan, arjun, dalfox, sqlmap, hydra, medusa, john, hashcat, crackmapexec, evil-winrm, enum4linux-ng, responder, netexec, aircrack-ng, bettercap, binwalk, foremost, exiftool, steghide, curl, wget, netcat, socat, **msfconsole**, **msfvenom**, and more. + +**Metasploit:** Integrated via CLI (`msfconsole -qx`) — no msfrpcd daemon needed. Includes PostgreSQL for Metasploit DB support. + +**MCP Tools:** `run_kali_tool`, `run_shell_command`, `list_available_tools`, `msf_search`, `msf_module_info`, `msf_run_module`, `msf_payload_generate`, `msf_console_execute`, `msf_status` + +### WireMCP — `crhacky/blhackbox:wire-mcp` + +| | | +|:--|:--| +| **Base** | `debian:bookworm-slim` | +| **Transport** | SSE on port 9003 | +| **Privileged** | Yes (packet capture) | +| **Entrypoint** | WireMCP server (`server.py`) | -- **Base**: `kalilinux/kali-rolling` -- **Tools (70+)**: nmap, masscan, hping3, subfinder, amass, fierce, dnsenum, dnsrecon, theharvester, nikto, gobuster, dirb, dirsearch, ffuf, feroxbuster, whatweb, wafw00f, wpscan, arjun, dalfox, sqlmap, hydra, medusa, john, hashcat, crackmapexec, evil-winrm, enum4linux-ng, responder, netexec, aircrack-ng, bettercap, binwalk, foremost, exiftool, steghide, curl, wget, netcat, socat, **msfconsole**, **msfvenom**, and more -- **Metasploit**: Integrated via CLI (`msfconsole -qx`) — no msfrpcd daemon needed. Includes PostgreSQL for Metasploit DB support. -- **MCP Tools**: `run_kali_tool`, `run_shell_command`, `list_available_tools`, `msf_search`, `msf_module_info`, `msf_run_module`, `msf_payload_generate`, `msf_console_execute`, `msf_status` -- **Entrypoint**: `entrypoint.sh` (starts PostgreSQL for MSF DB, then MCP server) -- **Transport**: SSE on port 9001 -- **Privileged**: Yes (required for raw socket access) +**Tools (7):** `capture_packets`, `read_pcap`, `get_conversations`, `get_statistics`, `extract_credentials`, `follow_stream`, `list_interfaces` -### WireMCP (`crhacky/blhackbox:wire-mcp`) +**Inspired by:** [0xKoda/WireMCP](https://github.com/0xKoda/WireMCP), [khuynh22/mcp-wireshark](https://github.com/khuynh22/mcp-wireshark) -- **Base**: `debian:bookworm-slim` -- **Tools (7)**: capture_packets, read_pcap, get_conversations, get_statistics, extract_credentials, follow_stream, list_interfaces -- **Entrypoint**: WireMCP server (`server.py`) -- **Transport**: SSE on port 9003 -- **Privileged**: Yes (required for packet capture) -- **Inspired by**: [0xKoda/WireMCP](https://github.com/0xKoda/WireMCP), [khuynh22/mcp-wireshark](https://github.com/khuynh22/mcp-wireshark) +### Screenshot MCP — `crhacky/blhackbox:screenshot-mcp` -### Screenshot MCP (`crhacky/blhackbox:screenshot-mcp`) +| | | +|:--|:--| +| **Base** | `python:3.13-slim` | +| **Transport** | SSE on port 9004 | +| **Entrypoint** | Screenshot MCP server (FastMCP + Playwright headless Chromium) | -- **Base**: `python:3.13-slim` -- **Tools (4)**: take_screenshot (full-page web capture), take_element_screenshot (CSS selector targeting), annotate_screenshot (labels and highlight boxes), list_screenshots (evidence inventory) -- **Entrypoint**: Screenshot MCP server (FastMCP + Playwright headless Chromium) -- **Transport**: SSE on port 9004 +**Tools (4):** `take_screenshot` (full-page web capture), `take_element_screenshot` (CSS selector targeting), `annotate_screenshot` (labels and highlight boxes), `list_screenshots` (evidence inventory) -### Claude Code (`crhacky/blhackbox:claude-code`) +### Claude Code — `crhacky/blhackbox:claude-code` -- **Base**: `node:22-slim` -- **Entrypoint**: `claude-code-entrypoint.sh` (health checks + launch) -- **MCP config**: Direct SSE to each server (no gateway dependency) -- **Note**: Requires `ANTHROPIC_API_KEY` in `.env` +| | | +|:--|:--| +| **Base** | `node:22-slim` | +| **Entrypoint** | `claude-code-entrypoint.sh` (health checks + launch) | +| **MCP config** | Direct SSE to each server (no gateway dependency) | +| **Requires** | `ANTHROPIC_API_KEY` in `.env` | --- @@ -226,30 +246,31 @@ Requires `--profile gateway` (`make up-gateway`). Portainer CE provides a web dashboard for all blhackbox containers. -- **URL**: `https://localhost:9443` -- **First run**: Create an admin account within 5 minutes of startup -- **Missed the window?** `docker compose restart portainer` +| | | +|:--|:--| +| **URL** | `https://localhost:9443` | +| **First run** | Create an admin account within 5 minutes of startup | +| **Missed the window?** | `docker compose restart portainer` | -> Your browser will warn about the self-signed HTTPS certificate. This is -> expected. Click "Advanced" and proceed. +> **Note:** Your browser will warn about the self-signed HTTPS certificate. This is expected — click "Advanced" and proceed. --- ## Volumes -Named volumes for persistent data: +### Named volumes (persistent data) | Volume | Service | Purpose | -|---|---|---| +|:--|:--|:--| | `neo4j_data` | neo4j | Neo4j graph database (optional) | | `neo4j_logs` | neo4j | Neo4j logs (optional) | | `portainer_data` | portainer | Portainer configuration | -| `wordlists` | - | Fuzzing wordlists | +| `wordlists` | — | Fuzzing wordlists | -Host bind mounts for output (accessible on your local filesystem): +### Host bind mounts (accessible on your local filesystem) -| Host Path | Container Path | Purpose | -|---|---|---| +| Host Path | Container Path | Contents | +|:--|:--|:--| | `./output/reports/` | `/root/reports/` | Generated pentest reports (.md, .pdf) | | `./output/screenshots/` | `/tmp/screenshots/` | PoC evidence screenshots (.png) | | `./output/sessions/` | `/root/results/` | Aggregated session JSON files | @@ -261,13 +282,14 @@ Host bind mounts for output (accessible on your local filesystem): Four custom images are built and pushed to Docker Hub via GitHub Actions: ``` -PR opened ───> CI (lint + test + pip-audit) - │ -PR merged ───> CI ───> Build & Push (4 images) ───> Docker Hub - (on CI success) -Tag v* ──────────────> Build & Push (4 images) ───> Docker Hub +PR opened ─────▶ CI (lint + test + pip-audit) + │ +PR merged ─────▶ CI ─────▶ Build & Push (4 images) ─────▶ Docker Hub + (on CI success) + +Tag v* ──────────────────▶ Build & Push (4 images) ─────▶ Docker Hub -Manual ──────────────> Build & Push (4 images) ───> Docker Hub +Manual ──────────────────▶ Build & Push (4 images) ─────▶ Docker Hub ``` --- @@ -275,54 +297,34 @@ Manual ──────────────> Build & Push (4 images) ## Useful Commands ```bash -# Interactive setup wizard (recommended for first-time setup) -make setup - -# Pull all pre-built images from Docker Hub -docker compose pull - -# Start core stack (4 containers) -docker compose up -d - -# Start with MCP Gateway for Claude Desktop (5 containers) -make up-gateway - -# Start with Neo4j (5 containers) -docker compose --profile neo4j up -d - -# Launch Claude Code in Docker -make claude-code - -# Check health of all MCP servers -make health - -# Container status -make status - -# View service logs -make logs-kali -make logs-wireshark -make logs-screenshot -make gateway-logs - -# Stop and clean up -make down -make clean # also removes volumes +make setup # Interactive setup wizard (first-time setup) +docker compose pull # Pull all pre-built images +docker compose up -d # Start core stack (4 containers) +make up-gateway # Start with MCP Gateway (5 containers) +make claude-code # Launch Claude Code in Docker +make health # Health check all MCP servers +make status # Container status table +make logs-kali # Kali MCP logs +make logs-wireshark # WireMCP logs +make logs-screenshot # Screenshot MCP logs +make gateway-logs # MCP Gateway logs +make down # Stop all services +make clean # Stop + remove volumes ``` --- ## Security -- **Docker socket**: MCP Gateway (optional) and Portainer mount `/var/run/docker.sock`. This grants effective root on the host. Never expose ports 8080 or 9443 to the public internet. -- **Authorization**: Ensure you have written permission before scanning any target. -- **Neo4j**: Set a strong password in `.env`. Never use defaults in production. -- **Portainer**: Uses HTTPS with a self-signed certificate. Create a strong admin password on first run. +- **Docker socket** — MCP Gateway (optional) and Portainer mount `/var/run/docker.sock`. This grants effective root on the host. Never expose ports 8080 or 9443 to the public internet. +- **Authorization** — Ensure you have written permission before scanning any target. +- **Neo4j** — Set a strong password in `.env`. Never use defaults in production. +- **Portainer** — Uses HTTPS with a self-signed certificate. Create a strong admin password on first run. -**This tool is for authorized security testing only.** Unauthorized access to computer systems is illegal. +> **This tool is for authorized security testing only.** Unauthorized access to computer systems is illegal. --- ## Source -[GitHub Repository](https://github.com/valITino/blhackbox) +[GitHub Repository](https://github.com/valITino/blhackbox) · [Docker Hub](https://hub.docker.com/r/crhacky/blhackbox) diff --git a/README.md b/README.md index 61c50fa..b20c556 100644 --- a/README.md +++ b/README.md @@ -40,41 +40,25 @@ ## Table of Contents -- [How It Works](#how-it-works) -- [Architecture](#architecture) -- [Output Files](#output-files) -- [Components](#components) -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Tutorial 1: Claude Code (Docker) — Recommended](#tutorial-1-claude-code-docker--recommended) -- [Tutorial 2: Claude Code (Web)](#tutorial-2-claude-code-web) -- [Tutorial 3: Claude Desktop (Host + Gateway)](#tutorial-3-claude-desktop-host--gateway) -- [Tutorial 4: ChatGPT / OpenAI (Host + Gateway)](#tutorial-4-chatgpt--openai-host--gateway) -- [How Prompts Flow Through the System](#how-prompts-flow-through-the-system) -- [Do I Need the MCP Gateway?](#do-i-need-the-mcp-gateway) -- [Portainer Setup](#portainer-setup) -- [Troubleshooting](#troubleshooting) -- [CLI Reference](#cli-reference) -- [Makefile Shortcuts](#makefile-shortcuts) -- [Docker Hub Images](#docker-hub-images) -- [Neo4j (Optional)](#neo4j-optional) -- [Authorization & Verification](#authorization--verification) -- [Security Notes](#security-notes) -- [Project Structure](#project-structure) -- [License](#license) +| | | +|---|---| +| **Getting Started** | [How It Works](#how-it-works) · [Architecture](#architecture) · [Prerequisites](#prerequisites) · [Installation](#installation) | +| **Tutorials** | [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) | +| **Reference** | [Components](#components) · [Output Files](#output-files) · [CLI Reference](#cli-reference) · [Makefile Shortcuts](#makefile-shortcuts) · [Docker Hub Images](#docker-hub-images) | +| **Operations** | [Prompt Flow](#how-prompts-flow-through-the-system) · [MCP Gateway](#do-i-need-the-mcp-gateway) · [Portainer Setup](#portainer-setup) · [Neo4j](#neo4j-optional) · [Troubleshooting](#troubleshooting) | +| **Security** | [Authorization & Verification](#authorization--verification) · [Security Notes](#security-notes) | +| **Project** | [Project Structure](#project-structure) · [Build from Source](#build-from-source-optional) · [License](#license) | --- ## How It Works -In v2, **your AI client (Claude or ChatGPT) IS the orchestrator**. There is no -internal LangGraph orchestrator or LLM planner. Here is what happens when you -type a prompt: +In v2, **your AI client (Claude or ChatGPT) IS the orchestrator**. There is no internal LangGraph orchestrator or LLM planner. Here is what happens when you type a prompt: 1. **You type a prompt** in your AI client (Claude Code, Claude Desktop, or ChatGPT). -2. **The AI decides which tools to call** from three MCP servers: Kali Linux MCP (70+ security tools including Metasploit), WireMCP (7 packet analysis tools), and Screenshot MCP (4 evidence capture tools). -3. **Each MCP server executes the tool call** in its Docker container and returns raw output to the AI. -4. **The AI structures the results itself** — parsing, deduplicating, correlating, and building an `AggregatedPayload` directly. +2. **The AI decides which tools to call** from three MCP servers — Kali MCP (70+ security tools including Metasploit), WireMCP (7 packet analysis tools), and Screenshot MCP (4 evidence capture tools). +3. **Each MCP server executes the tool** in its Docker container and returns raw output. +4. **The AI structures the results** — parsing, deduplicating, correlating, and building an `AggregatedPayload` directly. 5. **The AI validates and persists** the payload via `aggregate_results()`, then writes the final pentest report. Everything runs inside Docker containers. No tools are installed on your host machine. @@ -83,56 +67,65 @@ Everything runs inside Docker containers. No tools are installed on your host ma ## Architecture -Claude Code in Docker connects **directly** to each MCP server via SSE over -the internal Docker network. No MCP Gateway needed. +Claude Code in Docker connects **directly** to each MCP server via SSE over the internal Docker network — no MCP Gateway needed. ``` YOU (the user) - | - | "docker compose run --rm claude-code" (or attach via Portainer) - | - v + │ + │ 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, port 9001) ─────────────> KALI MCP SERVER - | 70+ tools: nmap, nikto, gobuster, - | sqlmap, hydra, msfconsole, msfvenom, - | john, hashcat, etc. - | - |--- wireshark (SSE, port 9003) ────────> WIREMCP SERVER - | 7 tools: packet capture, pcap - | analysis, credential extraction - | - |--- screenshot (SSE, port 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() - | - v + │ + │ 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 - | - v (optional) + │ + ▼ (optional) NEO4J — cross-session memory -PORTAINER (https://localhost:9443) — Web UI for all containers +PORTAINER (https://localhost:9443) — web UI for all containers ``` -For host-based clients (Claude Desktop, ChatGPT), an **optional MCP Gateway** -aggregates all servers behind `localhost:8080/mcp`. See -[Do I Need the MCP Gateway?](#do-i-need-the-mcp-gateway). +For host-based clients (Claude Desktop, ChatGPT), an **optional MCP Gateway** aggregates all servers behind `localhost:8080/mcp`. See [Do I Need the MCP Gateway?](#do-i-need-the-mcp-gateway) + +--- + +## Components + +| Container | Description | Port | Profile | +|:--|:--|:--:|:--:| +| **Kali MCP** | Kali Linux security tools + Metasploit — 70+ tools (nmap, sqlmap, hydra, msfconsole, msfvenom, etc.) | `9001` | default | +| **WireMCP** | Wireshark / tshark — 7 packet capture and analysis tools | `9003` | default | +| **Screenshot MCP** | Headless Chromium — 4 screenshot and annotation tools | `9004` | default | +| **Portainer** | Web UI for managing all containers | `9443` | default | +| **Claude Code** | Anthropic CLI MCP client in Docker | — | `claude-code` | +| **MCP Gateway** | Single entry point for host-based MCP clients | `8080` | `gateway` | +| **Neo4j** | Cross-session knowledge graph | `7474` / `7687` | `neo4j` | --- ## Output Files -All output files (reports, screenshots, session data) are stored in the `./output/` -directory on your host machine via Docker bind mounts. You can access them directly -from your file system — no need to `docker cp`. +All output files are stored in `./output/` on your host via Docker bind mounts — no need to `docker cp`. ``` output/ @@ -141,39 +134,23 @@ output/ └── sessions/ ← Aggregated session JSON files ``` -| Container Path | Host Path | What goes there | -|---------------|-----------|-----------------| -| `/root/reports/` | `./output/reports/` | Generated pentest reports (markdown, PDF) | +| Container Path | Host Path | Contents | +|:--|:--|:--| +| `/root/reports/` | `./output/reports/` | Generated pentest reports (Markdown, PDF) | | `/tmp/screenshots/` | `./output/screenshots/` | Screenshot MCP captures and annotations | | `/root/results/` | `./output/sessions/` | `AggregatedPayload` session JSONs | -The `output/` directory is created automatically by `setup.sh`. If you installed -manually, create it with: `mkdir -p output/reports output/screenshots output/sessions` - -> **Note:** The `output/` directory is git-ignored. Back up important reports separately. - ---- - -## Components +The `output/` directory is created automatically by `setup.sh`. For manual installs: `mkdir -p output/reports output/screenshots output/sessions` -| Container | What it does | Internal Port | Default Profile | -|-----------|-------------|:---:|:---:| -| **Kali MCP** | Kali Linux security tools + Metasploit Framework — 70+ tools (nmap, sqlmap, hydra, msfconsole, msfvenom, etc.) | 9001 | default | -| **WireMCP** | Wireshark/tshark — 7 packet capture and analysis tools | 9003 | default | -| **Screenshot MCP** | Headless Chromium — 4 screenshot and annotation tools | 9004 | default | -| **Portainer** | Web UI for managing all containers | 9443 | default | -| **Claude Code** | Anthropic CLI MCP client in Docker | — | `claude-code` | -| **MCP Gateway** | Single entry point for host-based MCP clients | 8080 | `gateway` | -| **Neo4j** | Cross-session knowledge graph | 7474/7687 | `neo4j` | +> **Note:** `output/` is git-ignored. Back up important reports separately. --- ## Prerequisites - **Docker** and **Docker Compose** (Docker Engine on Linux, or Docker Desktop) -- At least **8 GB RAM** recommended (4 containers in the core stack). -- An **Anthropic API key** from [console.anthropic.com](https://console.anthropic.com) (**required** for Claude Code) - +- At least **8 GB RAM** recommended (4 containers in the core stack) +- An **Anthropic API key** from [console.anthropic.com](https://console.anthropic.com) (required for Claude Code) --- @@ -188,6 +165,7 @@ cd blhackbox ``` The setup wizard will: + 1. Check prerequisites (Docker, Docker Compose, disk space) 2. Let you choose optional components (Neo4j, MCP Gateway) 3. Prompt for your `ANTHROPIC_API_KEY` (required for Claude Code in Docker) @@ -195,87 +173,69 @@ The setup wizard will: 5. Pull Docker images and start all services 6. Wait for health checks to pass -You can also pass flags for non-interactive use: +Non-interactive flags: ```bash -./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 +./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 ``` -Or use the Makefile shortcut: - -```bash -make setup -``` +Or use the Makefile shortcut: `make setup` ### Manual Installation -If you prefer to set up manually: - ```bash -# 1. Clone the repo -git clone https://github.com/valITino/blhackbox.git -cd blhackbox +# 1. Clone +git clone https://github.com/valITino/blhackbox.git && cd blhackbox -# 2. Create your .env file +# 2. Configure cp .env.example .env -# REQUIRED: Uncomment and set your Anthropic API key in .env: -# ANTHROPIC_API_KEY=sk-ant-... +# REQUIRED: set ANTHROPIC_API_KEY=sk-ant-... in .env -# 3. Create output directories (reports, screenshots, sessions) +# 3. Create output directories mkdir -p output/reports output/screenshots output/sessions -# 4. Pull all pre-built Docker images +# 4. Pull images and start docker compose pull - -# 5. Start the core stack (4 containers) docker compose up -d ``` -**Set up authorization (required before running pentests):** +**Set up authorization** (required before running pentests): ```bash -# 6. Edit verification.env with your engagement details +# 5. Fill in engagement details nano verification.env -# Set AUTHORIZATION_STATUS=ACTIVE after filling in all fields +# Set AUTHORIZATION_STATUS=ACTIVE after completing all fields -# 7. Render the active verification document +# 6. Render the active verification document make inject-verification ``` -See [Authorization & Verification](#authorization--verification) for full details. +See [Authorization & Verification](#authorization--verification) for details. **Verify everything is running:** ```bash make status # Container status -make health # Quick health check of all MCP servers +make health # MCP server health check ``` -You should see 4 containers, all "Up" or "healthy": -- `blhackbox-kali-mcp` -- `blhackbox-wire-mcp` -- `blhackbox-screenshot-mcp` -- `blhackbox-portainer` +You should see 4 healthy containers: `blhackbox-kali-mcp`, `blhackbox-wire-mcp`, `blhackbox-screenshot-mcp`, `blhackbox-portainer`. -> **First time?** Open Portainer at `https://localhost:9443` and create an admin -> account within 5 minutes. See [Portainer Setup](#portainer-setup). +> **Tip:** Open Portainer at `https://localhost:9443` and create an admin account within 5 minutes. See [Portainer Setup](#portainer-setup). --- ## Tutorial 1: Claude Code (Docker) — Recommended -Claude Code runs entirely inside a Docker container on the same network as all -other blhackbox services. It connects **directly** to each MCP server via SSE — -no MCP Gateway, no host install, no Node.js. +Claude Code runs entirely inside a Docker container on the same network as all blhackbox services. It connects **directly** to each MCP server via SSE — no MCP Gateway, no host install, no Node.js. -### Step 1: Start the stack +### Step 1 — Start the stack -Follow [Installation](#installation) above. Make sure `ANTHROPIC_API_KEY` is -set in your `.env` file. All core containers must be healthy (`make health`). +Follow [Installation](#installation) above. Make sure `ANTHROPIC_API_KEY` is set in `.env` and all core containers are healthy (`make health`). -### Step 2: Launch Claude Code +### Step 2 — Launch Claude Code ```bash make claude-code @@ -295,14 +255,14 @@ The entrypoint script checks each service and shows a status dashboard: ║ MCP-based Pentesting Framework ║ ╚══════════════════════════════════════════════╝ -Checking service connectivity... + Checking service connectivity... MCP Servers - Kali MCP [ OK ] - WireMCP [ OK ] - Screenshot MCP [ OK ] + Kali MCP [ OK ] + WireMCP [ OK ] + Screenshot MCP [ OK ] -────────────────────────────────────────────────── + ────────────────────────────────────────────── All 3 services connected. MCP servers (connected via SSE): @@ -317,27 +277,27 @@ Checking service connectivity... Quick start: /mcp Check MCP server status Scan example.com for open ports and web vulnerabilities -────────────────────────────────────────────────── + ────────────────────────────────────────────── ``` You are now inside an interactive Claude Code session. -### Step 3: Verify the connection +### Step 3 — Verify the connection ``` /mcp ``` -You should see the MCP servers listed: `kali`, `wireshark`, and -`screenshot`, each with their available tools. +You should see `kali`, `wireshark`, and `screenshot`, each with their available tools. -### Step 4: Run your first pentest +### Step 4 — Run your first pentest ``` Scan example.com for open ports and web vulnerabilities ``` Claude Code will autonomously: + 1. Call Kali tools (nmap, subfinder, nikto, etc.) 2. Search for exploits using Metasploit (`msf_search`) 3. Collect raw outputs from all tools @@ -347,27 +307,23 @@ Claude Code will autonomously: ### Monitoring (separate terminal) ```bash -make logs-kali # Kali MCP server activity (includes Metasploit) -make logs-wireshark # WireMCP activity -make logs-screenshot # Screenshot MCP activity +make logs-kali # Kali MCP server activity (includes Metasploit) +make logs-wireshark # WireMCP activity +make logs-screenshot # Screenshot MCP activity ``` -Or use **Portainer** at `https://localhost:9443` to see all container logs and -resource usage in one dashboard. +Or use **Portainer** at `https://localhost:9443` for a unified dashboard. --- ## Tutorial 2: Claude Code (Web) -Claude Code on [claude.ai/code](https://claude.ai/code) works as a web-based -coding agent. When you open this repo in a web session, the MCP server -configures itself automatically. +Claude Code on [claude.ai/code](https://claude.ai/code) works as a web-based coding agent. When you open this repo in a web session, the MCP server configures itself automatically. ### How it works -1. **`.mcp.json`** (project root) — tells Claude Code to start the blhackbox - MCP server via stdio -2. **`.claude/hooks/session-start.sh`** — auto-installs dependencies on session start +- **`.mcp.json`** (project root) — tells Claude Code to start the blhackbox MCP server via stdio +- **`.claude/hooks/session-start.sh`** — auto-installs dependencies on session start ### Steps @@ -375,33 +331,32 @@ configures itself automatically. 2. Type `/mcp` to verify — you should see `blhackbox` with 6 tools 3. Type your prompt: `Scan example.com for open ports and web vulnerabilities` -> **Note:** The web session uses the blhackbox stdio MCP server directly -> (not the Docker stack). For the full Docker stack with Kali tools and -> Metasploit, use [Tutorial 1](#tutorial-1-claude-code-docker--recommended). +> **Note:** The web session uses the blhackbox stdio MCP server directly (not the Docker stack). For the full Docker stack with Kali tools and Metasploit, use [Tutorial 1](#tutorial-1-claude-code-docker--recommended). --- ## Tutorial 3: Claude Desktop (Host + Gateway) -Claude Desktop is a GUI app that cannot run in Docker. It connects to blhackbox -via the **MCP Gateway** on `localhost:8080`. +Claude Desktop is a GUI app that cannot run in Docker. It connects to blhackbox via the **MCP Gateway** on `localhost:8080`. -### Step 1: Start the stack with the gateway +### Step 1 — Start the stack with the gateway ```bash -docker compose up -d # core stack -docker compose --profile gateway up -d # adds the MCP Gateway +docker compose up -d # core stack +docker compose --profile gateway up -d # adds the MCP Gateway # OR shortcut: make up-gateway ``` -### Step 2: Configure Claude Desktop +### Step 2 — Configure Claude Desktop Open the config file: -- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` -- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` -- **Linux:** `~/.config/Claude/claude_desktop_config.json` +| Platform | Path | +|:--|:--| +| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` | +| Windows | `%APPDATA%\Claude\claude_desktop_config.json` | +| Linux | `~/.config/Claude/claude_desktop_config.json` | Add: @@ -418,31 +373,30 @@ Add: Restart Claude Desktop. You should see a hammer icon with available tools. -### Step 3: Run a pentest +### Step 3 — Run a pentest -Type your prompt in Claude Desktop. The flow is identical to Tutorial 1 — the -gateway routes tool calls to the same MCP servers (kali, wireshark, screenshot). +Type your prompt in Claude Desktop. The flow is identical to Tutorial 1 — the gateway routes tool calls to the same MCP servers. --- ## Tutorial 4: ChatGPT / OpenAI (Host + Gateway) -ChatGPT/OpenAI clients also connect via the **MCP Gateway** on `localhost:8080`. +ChatGPT / OpenAI clients also connect via the **MCP Gateway** on `localhost:8080`. -### Step 1: Start with gateway +### Step 1 — Start with gateway ```bash make up-gateway ``` -### Step 2: Configure your client +### Step 2 — Configure your client Point your MCP-capable OpenAI client at: -``` -URL: http://localhost:8080/mcp -Transport: Streamable HTTP -``` +| Setting | Value | +|:--|:--| +| URL | `http://localhost:8080/mcp` | +| Transport | Streamable HTTP | The gateway is AI-agnostic — it serves the same tools to any MCP client. @@ -451,41 +405,41 @@ The gateway is AI-agnostic — it serves the same tools to any MCP client. ## How Prompts Flow Through the System ``` -STEP 1: YOU TYPE A PROMPT +STEP 1 ─ YOU TYPE A PROMPT "Scan example.com for open ports and web vulnerabilities" - | - v -STEP 2: AI DECIDES WHICH TOOLS TO USE - Claude picks tools from Kali MCP (includes Metasploit), WireMCP, and 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 - | - v -STEP 3: TOOLS EXECUTE IN DOCKER CONTAINERS + │ + ▼ +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. - | - v -STEP 4: AI STRUCTURES THE RESULTS ITSELF - The AI (Claude/ChatGPT) parses, deduplicates, correlates, and - structures all raw outputs into an AggregatedPayload directly. - No external pipeline needed — the MCP host is the brain. - | - v -STEP 5: AI VALIDATES AND PERSISTS - The AI calls aggregate_results(payload=...) to validate the + │ + ▼ +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. - | - v -STEP 6: AI WRITES THE FINAL REPORT + │ + ▼ +STEP 6 ─ AI WRITES THE FINAL REPORT Executive summary, findings by severity, remediation, appendix. - | - v -STEP 7 (OPTIONAL): RESULTS STORED IN NEO4J + │ + ▼ +STEP 7 ─ (OPTIONAL) RESULTS STORED IN NEO4J Cross-session memory for recurring engagements. ``` @@ -493,28 +447,20 @@ STEP 7 (OPTIONAL): RESULTS STORED IN NEO4J ## Do I Need the MCP Gateway? -| MCP Client | Gateway needed? | How it connects | -|------------|:---:|---| -| **Claude Code (Docker)** | **No** | Connects directly to each MCP server via SSE over Docker network | -| **Claude Code (Web)** | **No** | Uses stdio MCP server from `.mcp.json` | -| **Claude Desktop** | **Yes** | GUI app on host; needs `localhost:8080/mcp` gateway | -| **ChatGPT / OpenAI** | **Yes** | GUI/web app on host; needs `localhost:8080/mcp` gateway | - -The MCP Gateway (`docker/mcp-gateway:latest`) aggregates all MCP servers -(kali, wireshark, screenshot) behind a single Streamable -HTTP endpoint at `localhost:8080/mcp`. It requires: -- Docker socket mount (`/var/run/docker.sock`) -- The `--profile gateway` flag to enable +| MCP Client | Gateway? | How it connects | +|:--|:--:|:--| +| **Claude Code (Docker)** | No | Direct SSE to each MCP server over Docker network | +| **Claude Code (Web)** | No | Stdio MCP server from `.mcp.json` | +| **Claude Desktop** | **Yes** | Host GUI app → `localhost:8080/mcp` gateway | +| **ChatGPT / OpenAI** | **Yes** | Host GUI/web app → `localhost:8080/mcp` gateway | -Start the gateway only when you need it: +The MCP Gateway (`docker/mcp-gateway:latest`) aggregates all MCP servers behind a single Streamable HTTP endpoint at `localhost:8080/mcp`. It requires Docker socket mount (`/var/run/docker.sock`) and the `--profile gateway` flag. ```bash make up-gateway # starts core stack + gateway ``` -> **Why is it optional?** The gateway adds complexity, requires Docker socket -> access, and is designed primarily for Docker Desktop environments. On headless -> Linux servers, connecting directly via SSE is simpler and more reliable. +> **Why optional?** The gateway adds complexity, requires Docker socket access, and is designed for Docker Desktop environments. On headless Linux servers, direct SSE is simpler and more reliable. --- @@ -526,8 +472,7 @@ Portainer CE provides a web UI for managing all blhackbox containers. ### First Run -On first launch, Portainer requires you to create an admin account **within 5 -minutes**. If you miss the window: +On first launch, Portainer requires you to create an admin account **within 5 minutes**. If you miss the window: ```bash docker compose restart portainer @@ -535,15 +480,14 @@ docker compose restart portainer Then open `https://localhost:9443` again and create your account. -### What you can do in Portainer +### What you can do - View all container status, logs, and resource usage - Restart individual containers - Inspect environment variables and network configuration - Monitor the health of each service -> **Note:** Your browser will warn about the self-signed HTTPS certificate. -> This is expected — click "Advanced" and proceed. +> **Note:** Your browser will warn about the self-signed HTTPS certificate. This is expected — click "Advanced" and proceed. --- @@ -551,10 +495,10 @@ Then open `https://localhost:9443` again and create your account. ### Claude Code shows "Status: failed" for MCP servers -The MCP servers may not be healthy yet. Check with: +The MCP servers may not be healthy yet: ```bash -make health # quick health check from host +make health # quick health check make status # container status docker compose logs # full logs ``` @@ -562,34 +506,26 @@ docker compose logs # full logs If a service shows `FAIL`, restart it: ```bash -docker compose restart kali-mcp # restart one service +docker compose restart kali-mcp ``` ### Metasploit tools are slow or fail -Metasploit tools (`msf_search`, `msf_run_module`, etc.) use `msfconsole -qx` -for CLI execution. The first invocation takes **10-30 seconds** due to Ruby and -database initialization (cold start). Subsequent calls in the same container -session are faster. +Metasploit tools (`msf_search`, `msf_run_module`, etc.) use `msfconsole -qx` for CLI execution. The first invocation takes **10–30 seconds** due to Ruby and database initialization (cold start). Subsequent calls are faster. If Metasploit commands fail: -1. Check if msfconsole is installed: `docker exec blhackbox-kali-mcp which msfconsole` + +1. Check installation: `docker exec blhackbox-kali-mcp which msfconsole` 2. Check database status: use the `msf_status` tool 3. Check container logs: `make logs-kali` ### Portainer shows "Timeout" on first visit -You have 5 minutes after Portainer starts to create an admin account. If you -missed it, restart: - -```bash -docker compose restart portainer -``` +You have 5 minutes after Portainer starts to create an admin account. Missed it? Run `docker compose restart portainer`. ### MCP Gateway doesn't start -The gateway is **optional** — Claude Code in Docker does not use it. If you -need it for Claude Desktop / ChatGPT: +The gateway is optional — Claude Code in Docker does not use it. If you need it for Claude Desktop / ChatGPT: 1. Ensure Docker socket exists: `ls -la /var/run/docker.sock` 2. Start with the gateway profile: `make up-gateway` @@ -597,67 +533,55 @@ need it for Claude Desktop / ChatGPT: ### Container keeps restarting -Check its logs for the specific error: +Check its logs: ```bash -docker compose logs # e.g., kali-mcp, wire-mcp +docker compose logs # e.g., kali-mcp, wire-mcp ``` -Common causes: -- Port conflict on the host -- Insufficient memory +Common causes: port conflict on the host, insufficient memory. --- ## CLI Reference ```bash -# Show version and config -blhackbox version - -# Run recon -blhackbox recon --target example.com +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 - -# Run a single tool -blhackbox run-tool -c network -t nmap -p '{"target":"example.com"}' -# Knowledge graph (requires Neo4j) -blhackbox graph query "MATCH (n) RETURN n LIMIT 10" -blhackbox graph summary -t example.com - -# Generate reports -blhackbox report -s SESSION_ID --format pdf - -# Start MCP server -blhackbox mcp +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 Shortcuts -```bash -make setup # Interactive setup wizard (prereqs, .env, pull, start, health) -make help # Show all available targets -make pull # Pull all pre-built images from Docker Hub -make up # Start core stack (4 containers) -make up-full # Start with Neo4j (5 containers) -make up-gateway # Start with MCP Gateway for Claude Desktop (5 containers) -make down # Stop all services -make claude-code # Build and launch Claude Code in Docker -make status # Container status table -make health # Quick health check of all services -make test # Run tests -make lint # Run linter -make portainer # Open Portainer dashboard (shows setup instructions) -make gateway-logs # Live MCP Gateway logs (requires --profile gateway) -make logs-kali # Tail Kali MCP logs (includes Metasploit) -make logs-wireshark # Tail WireMCP logs -make logs-screenshot # Tail Screenshot MCP logs -make inject-verification # Render verification.env → active authorization document -make push-all # Build and push all images to Docker Hub -``` +| Target | Description | +|:--|:--| +| `make setup` | Interactive setup wizard (prereqs, .env, pull, start, health) | +| `make help` | Show all available targets | +| `make pull` | Pull all pre-built images from Docker Hub | +| `make up` | Start core stack (4 containers) | +| `make up-full` | Start with Neo4j (5 containers) | +| `make up-gateway` | Start with MCP Gateway for Claude Desktop (5 containers) | +| `make down` | Stop all services | +| `make claude-code` | Build and launch Claude Code in Docker | +| `make status` | Container status table | +| `make health` | Quick health check of all services | +| `make test` | Run tests | +| `make lint` | Run linter | +| `make portainer` | Open Portainer dashboard | +| `make gateway-logs` | Live MCP Gateway logs | +| `make logs-kali` | Tail Kali MCP logs (includes Metasploit) | +| `make logs-wireshark` | Tail WireMCP logs | +| `make logs-screenshot` | Tail Screenshot MCP logs | +| `make inject-verification` | Render verification.env → active authorization document | +| `make push-all` | Build and push all images to Docker Hub | --- @@ -667,7 +591,7 @@ Only needed if you want to modify Dockerfiles or agent code: ```bash git submodule update --init --recursive # fetch kali-mcp source -docker compose build # build all custom images locally +docker compose build # build all images locally docker compose up -d ``` @@ -678,16 +602,19 @@ docker compose up -d All custom images are published to `crhacky/blhackbox`: | Tag | Description | -|-----|-------------| +|:--|:--| | `crhacky/blhackbox:kali-mcp` | Kali Linux MCP Server (70+ tools + Metasploit Framework) | | `crhacky/blhackbox:wire-mcp` | WireMCP Server (tshark, 7 tools) | | `crhacky/blhackbox:screenshot-mcp` | Screenshot MCP Server (headless Chromium, 4 tools) | | `crhacky/blhackbox:claude-code` | Claude Code CLI client (direct SSE to MCP servers) | Official images pulled directly: -- `portainer/portainer-ce:latest` -- `neo4j:5` (optional) -- `docker/mcp-gateway:latest` (optional) + +| Image | Purpose | +|:--|:--| +| `portainer/portainer-ce:latest` | Docker management UI | +| `neo4j:5` | Knowledge graph (optional) | +| `docker/mcp-gateway:latest` | MCP Gateway (optional) | --- @@ -699,60 +626,53 @@ Neo4j provides cross-session memory. Enable with `--profile neo4j`: docker compose --profile neo4j up -d ``` -Stores `AggregatedPayload` results as a graph after each session. -Useful for recurring engagements against the same targets. +Stores `AggregatedPayload` results as a graph after each session. Useful for recurring engagements against the same targets. --- ## Authorization & Verification -Before running any pentest template, blhackbox requires an **active verification -document** — explicit written authorization that confirms you have permission to -test the target. Without it, Claude Code will refuse to execute offensive actions -and prompt you to set one up. +Before running any pentest template, blhackbox requires an **active verification document** — explicit written authorization confirming you have permission to test the target. Without it, Claude Code will refuse to execute offensive actions. ### How it works ``` -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. +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. ``` -When you load a pentest template (via the `get_template` MCP tool), the active -verification document is automatically appended as authorization context. If no -active verification exists, Claude will tell you to set one up. +When you load a pentest template (via the `get_template` MCP tool), the active verification document is automatically appended as authorization context. If none exists, Claude will prompt you to set one up. ### Step-by-step setup **1. Edit `verification.env`** in the project root: ```bash -# Open the file in your editor nano verification.env # or vim, code, etc. ``` Fill in **all** fields across the 6 sections: -| Section | What to fill in | -|---------|----------------| -| **1. Engagement ID** | `ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TESTER_EMAIL`, `CLIENT_CONTACT_NAME`, `CLIENT_CONTACT_EMAIL` | -| **2. Scope** | `TARGET_1` through `TARGET_3` (with `_TYPE` and `_NOTES`), `OUT_OF_SCOPE`, `ENGAGEMENT_TYPE`, `CREDENTIALS` | -| **3. Activities** | Toggle each `PERMIT_*` field (`x` = allowed, blank = denied): recon, scanning, enumeration, exploitation, data extraction, credential testing, post-exploitation, traffic capture, screenshots | -| **4. Testing Window** | `TESTING_START`, `TESTING_END`, `TIMEZONE`, `EMERGENCY_CONTACT`, `EMERGENCY_PHONE` | -| **5. Legal** | `APPLICABLE_STANDARDS`, `REPORT_CLASSIFICATION`, `REPORT_DELIVERY` | -| **6. Signature** | `SIGNATORY_NAME`, `SIGNATORY_TITLE`, `SIGNATORY_ORGANIZATION`, `SIGNATURE_DATE`, `DIGITAL_SIGNATURE` | +| Section | Fields | +|:--|:--| +| **Engagement ID** | `ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TESTER_EMAIL`, `CLIENT_CONTACT_NAME`, `CLIENT_CONTACT_EMAIL` | +| **Scope** | `TARGET_1` through `TARGET_3` (with `_TYPE` and `_NOTES`), `OUT_OF_SCOPE`, `ENGAGEMENT_TYPE`, `CREDENTIALS` | +| **Activities** | Toggle each `PERMIT_*` field (`x` = allowed, blank = denied): recon, scanning, enumeration, exploitation, data extraction, credential testing, post-exploitation, traffic capture, screenshots | +| **Testing Window** | `TESTING_START`, `TESTING_END`, `TIMEZONE`, `EMERGENCY_CONTACT`, `EMERGENCY_PHONE` | +| **Legal** | `APPLICABLE_STANDARDS`, `REPORT_CLASSIFICATION`, `REPORT_DELIVERY` | +| **Signature** | `SIGNATORY_NAME`, `SIGNATORY_TITLE`, `SIGNATORY_ORGANIZATION`, `SIGNATURE_DATE`, `DIGITAL_SIGNATURE` | -**2. Activate** — set the status field at the top of the file: +**2. Activate** — set the status field: ```bash AUTHORIZATION_STATUS=ACTIVE @@ -764,13 +684,9 @@ AUTHORIZATION_STATUS=ACTIVE make inject-verification ``` -Or directly: - -```bash -python -m blhackbox.prompts.inject_verification -``` +Or directly: `python -m blhackbox.prompts.inject_verification` -On success, you'll see: +On success: ``` Verification document activated → .claude/verification-active.md @@ -780,9 +696,7 @@ Window: 2026-03-01 09:00 — 2026-03-31 17:00 UTC Authorized by: Jane Smith ``` -**4. Start your session** — Claude Code will automatically pick up the -verification document. On Claude Code Web, the session-start hook runs -`inject-verification` automatically if `verification.env` exists. +**4. Start your session** — Claude Code will automatically pick up the verification document. On Claude Code Web, the session-start hook runs `inject-verification` automatically if `verification.env` exists. ### Validation rules @@ -792,12 +706,12 @@ The injection script validates before rendering: - All required fields must be filled (`ENGAGEMENT_ID`, `AUTHORIZATION_DATE`, `EXPIRATION_DATE`, `AUTHORIZING_ORGANIZATION`, `TESTER_NAME`, `TARGET_1`, `TESTING_START`, `TESTING_END`, `SIGNATORY_NAME`, `SIGNATURE_DATE`) - `EXPIRATION_DATE` must not be in the past -If any check fails, the script exits with an error message explaining what to fix. +If any check fails, the script exits with an error explaining what to fix. ### Files involved | File | Purpose | -|------|---------| +|:--|:--| | `verification.env` | User-fillable config with engagement details, scope, and permissions | | `blhackbox/prompts/verification.md` | Template with `{{PLACEHOLDER}}` tokens | | `blhackbox/prompts/inject_verification.py` | Renders the template into the active document | @@ -834,16 +748,10 @@ Then run `make inject-verification` and start your Claude Code session. ## Security Notes -- **Docker socket**: MCP Gateway (optional) and Portainer mount - `/var/run/docker.sock`. This grants effective root on the host. Never expose - ports 8080 or 9443 to the public internet. -- **Authorization**: Set up a [verification document](#authorization--verification) before - running any pentest template. Claude Code will not execute offensive actions without - an active authorization. The rendered document (`.claude/verification-active.md`) - is git-ignored and never committed. -- **Neo4j**: Set a strong password in `.env`. Never use defaults in production. -- **Portainer**: Uses HTTPS with a self-signed certificate. Create a strong - admin password on first run. +- **Docker socket** — MCP Gateway (optional) and Portainer mount `/var/run/docker.sock`. This grants effective root on the host. Never expose ports 8080 or 9443 to the public internet. +- **Authorization** — Set up a [verification document](#authorization--verification) before running any pentest. Claude Code will not execute offensive actions without active authorization. The rendered document (`.claude/verification-active.md`) is git-ignored. +- **Neo4j** — Set a strong password in `.env`. Never use defaults in production. +- **Portainer** — Uses HTTPS with a self-signed certificate. Create a strong admin password on first run. --- @@ -851,39 +759,39 @@ Then run `make inject-verification` and start your Claude Code session. ``` blhackbox/ -├── setup.sh # Interactive setup wizard +├── setup.sh Interactive setup wizard ├── .claude/ -│ ├── settings.json # Claude Code hooks config -│ ├── verification-active.md # Rendered authorization doc (git-ignored) +│ ├── settings.json Claude Code hooks config +│ ├── verification-active.md Rendered authorization (git-ignored) │ └── hooks/ -│ └── session-start.sh # auto-setup for web sessions -├── output/ # Host-accessible outputs (git-ignored) -│ ├── reports/ # Generated pentest reports -│ ├── screenshots/ # PoC evidence captures -│ └── sessions/ # Aggregated session JSONs -├── verification.env # Pentest authorization config (edit before testing) -├── .mcp.json # MCP server config (Claude Code Web) +│ └── session-start.sh Auto-setup for web sessions +├── 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 +│ ├── 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) -├── metasploit-mcp/ # [DEPRECATED] Standalone MSF RPC server (kept for reference) +│ ├── 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) +├── metasploit-mcp/ [DEPRECATED] Standalone MSF RPC server ├── blhackbox/ │ ├── mcp/ -│ │ └── server.py # blhackbox MCP server (stdio) +│ │ └── server.py blhackbox MCP server (stdio) │ ├── models/ -│ │ ├── aggregated_payload.py # AggregatedPayload Pydantic model +│ │ ├── aggregated_payload.py AggregatedPayload Pydantic model │ │ ├── base.py │ │ └── graph.py │ ├── prompts/ -│ │ ├── claude_playbook.md # pentest playbook for MCP host -│ │ ├── verification.md # authorization template ({{PLACEHOLDER}} tokens) -│ │ └── inject_verification.py # renders template → active document +│ │ ├── claude_playbook.md Pentest playbook for MCP host +│ │ ├── verification.md Authorization template +│ │ └── inject_verification.py Renders template → active document │ ├── core/ │ │ ├── knowledge_graph.py │ │ ├── graph_exporter.py @@ -898,7 +806,7 @@ blhackbox/ │ ├── main.py │ ├── config.py │ └── exceptions.py -├── blhackbox-mcp-catalog.yaml # MCP Gateway catalog (optional) +├── blhackbox-mcp-catalog.yaml MCP Gateway catalog (optional) ├── docker-compose.yml ├── .env.example ├── Makefile