crhacky/blhackbox

BLHACKBOX — Docker Reference

MCP-based Autonomous Pentesting Framework

---

Quick Reference

All custom images are published to a single Docker Hub repository, differentiated by tag.

---

Images & Tags

Four custom images are published to crhacky/blhackbox on Docker Hub:

Official images (pulled directly, no custom build):

Pulling Images

bash
docker compose pull    # pull ALL images (custom + official) in one command

---

Architecture

In v2, **Claude (or *) IS the orchestrator natively via MCP.

Claude Code in Docker — Direct SSE (no gateway)

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 / *** — via MCP Gateway

Claude Desktop ──▶ MCP Gateway (localhost:8080/mcp) ──┬──▶ Kali MCP
(host app)                                             ├──▶ WireMCP
                                                       └──▶ Screenshot MCP

---

Usage

Quick Start (Recommended)

bash
git clone https://github.com/valITino/blhackbox.git
cd blhackbox
./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
cp .env.example .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

With Claude Code (Recommended)

bash
make claude-code    # builds + launches Claude Code in Docker

With MCP Gateway (for Claude Desktop / ***)

bash
make up-gateway     # starts core + gateway on port 8080

With Neo4j

bash
docker compose --profile neo4j up -d

Verify

bash
make status         # container status table
make health         # MCP server health check

---

Compose Services

---

MCP Connection Modes

Claude Code in Docker (Direct SSE — no gateway)

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://wire-mcp:9003/sse" },
    "screenshot": { "type": "sse", "url": "http://screenshot-mcp:9004/sse" }
  }
}

Claude Desktop (via MCP Gateway)

Add to claude_desktop_config.json:

json
{
  "mcpServers": {
    "blhackbox": {
      "transport": "streamable-http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Requires --profile gateway (make up-gateway).

---

Environment Variables

---

Image Details

Kali MCP — crhacky/blhackbox:kali-mcp

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, mapexec, evil-winrm, enum4linux-ng, responder, netexec, air-ng, ***, 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

Tools (7): capture_packets, read_pcap, get_conversations, get_statistics, extract_credentials, follow_stream, list_interfaces

Inspired by: https://github.com/0xKoda/WireMCP, https://github.com/khuynh22/mcp-wireshark

Screenshot MCP — crhacky/blhackbox:screenshot-mcp

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

---

Portainer

Portainer CE provides a web dashboard for all blhackbox containers.

Note: Your browser will warn about the self-signed HTTPS certificate. This is expected — click "Advanced" and proceed.

---

Volumes

Named volumes (persistent data)

Host bind mounts (accessible on your local filesystem)

---

CI/CD Pipeline

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

Manual     ──────────────────▶  Build & Push (4 images)  ─────▶  Docker Hub

---

Useful Commands

bash
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.

This tool is for authorized security testing only. Unauthorized access to computer systems is illegal.

---

Source

https://github.com/valITino/blhackbox · https://hub.docker.com/r/crhacky/blhackbox