HexStrike AI — Docker + Remote MCP

Dockerisiertes HexStrike AI auf dem linuxserver.io Kali-Basisimage, mit einem neuen Remote-Streamable-HTTP-MCP-Server, sodass das gesamte HexStrike-Toolset über das Netzwerk gesteuert werden kann (z. B. von Claude Code) anstatt nur von einem lokalen stdio-Client.

[!WARNUNG] Dies setzt autonome Ausführung von Offensiv-Sicherheitstools über das Netzwerk frei. Ein Client, der mit dem MCP-Endpunkt verbunden ist, kann effektiv Remote-Befehlsausführung über das gesamte Tool-Arsenal des Containers durchführen. Lesen Sie den Abschnitt Sicherheit, bevor Sie dies irgendwo außerhalb eines isolierten Labors ausführen. Setzen Sie immer HEXSTRIKE_MCP_TOKEN, führen Sie nur in einem vertrauenswürdigen/isolierten Netzwerk oder VPN aus und zielen Sie nur auf Systeme, die Sie ausdrücklich testen dürfen.

[!HINWEIS] Es wird kein vorgefertigtes Image veröffentlicht. Da das vollständige Kali-Toolset das Image groß macht (>10 GB — ungefähr ~17 GB gebaut), wird es nicht auf Docker Hub oder in eine Registry gepusht. Sie bauen es selbst aus diesem Repository (siehe Schnellstart); stellen Sie sicher, dass der Docker-Host genügend freien Speicherplatz hat.

Inhalt

• Funktionen

• Überblick

• Architektur

• Ports

• Schnellstart

• Verbindung von Claude Code

• Umgebungsvariablen

• Persistenz

• Web-Desktop-Zugriff

• Gesundheitscheck

• Sicherheit

• Tool-Abdeckung

• Aktualisieren des Upstream-Pins

• Danksagungen & Lizenz

Related MCP server: MCP Tools

Funktionen

• Das vollständige Upstream-HexStrike-AI-Toolkit — 150+ Sicherheitstools, gesteuert über seine Flask-API — vorinstalliert auf einem Kali-basierten Image, ohne manuelle Umgebungseinrichtung.

• Neu: hexstrike_mcp_http.py, ein Streamable-HTTP-MCP-Server, der jede Upstream-@mcp.tool()-Definition über das Netzwerk auf Port 8889 (Pfad /mcp) bereitstellt, sodass er remote gesteuert werden kann, anstatt nur über lokales stdio.

• Optionale Bearer-Token-Authentifizierung, die den MCP-Endpunkt schützt.

• Über den Browser erreichbarer KDE-Desktop (Selkies/KasmVNC, vom Basisimage geerbt) für interaktive Arbeit neben automatisierten Tool-Läufen.

• s6-overlay v3-Prozessüberwachung mit expliziter Dienstreihenfolge — der MCP-Dienst wartet darauf, dass der HexStrike-API-Server als Abhängigkeit definiert ist.

• Persistenter /config-Volume: Pro-Tool-virtualenvs und Dateimanager-Zustand überleben Container-Neustarts.

• Reproduzierbare Builds: uv verwaltet die Python-Umgebung, und Upstream-Quellen werden bei einem festgepinnten Git-Commit gezogen, anstatt vendored zu werden.

Überblick

HexStrike AI Upstream liefert zwei Python-Einstiegspunkte:

• hexstrike_server.py — ein Flask-API-Server, der auf Port 8888 lauscht und 150+ externe Sicherheitstools über subprocess ausführt und deren Ergebnisse über HTTP bereitstellt (einschließlich eines /health-Endpunkts, der die Tool-Verfügbarkeit meldet).

• hexstrike_mcp.py — ein FastMCP Server, der MCP-Toolaufrufe in HTTP-Aufrufe gegen den obigen API-Server übersetzt. Upstream führt ihn nur über den stdio-Transport aus, sodass er nur von einem MCP-Client auf demselben Rechner wie der Container gesteuert werden kann.

Dieses Repository fügt hexstrike_mcp_http.py hinzu, das das Upstream-Modul hexstrike_mcp.py importiert und dessen setup_mcp_server()-Funktion vollständig wiederverwendet — jede Tool-Definition, unverändert —, es aber über den MCP-Streamable-HTTP-Transport auf Port 8889 unter dem Pfad /mcp anstatt über stdio bereitstellt. Das ist der einzige funktionale Unterschied: dieselbe Tool-Oberfläche, remote erreichbar (z. B. von Claude Code auf einem anderen Rechner) anstatt nur von einem am selben Ort befindlichen Prozess.

uv (Astral) verwaltet den Python-Interpreter und die Abhängigkeitsumgebung und wird verwendet, um beide Prozesse beim Containerstart auszuführen.

Architektur

• Basisimage: lscr.io/linuxserver/kali-linux:latest, das einen über den Browser erreichbaren KDE-Desktop (Selkies/KasmVNC) auf den Ports 3000 (HTTP) und 3001 (HTTPS), Kali-rolling-apt-Repos und s6-overlay v3-Init bereitstellt.

• Hinzugefügte Dienste: Zwei s6-overlay-longrun-Dienste werden auf das Init-System des Basisimages aufgesetzt und im user-Dienstbundle registriert:

  • root/etc/s6-overlay/s6-rc.d/hexstrike-server — führt uv run --no-sync python hexstrike_server.py --port 8888 als Benutzer abc aus.

  • root/etc/s6-overlay/s6-rc.d/hexstrike-mcp — führt uv run --no-sync python hexstrike_mcp_http.py --server http://127.0.0.1:8888 --host 0.0.0.0 --port 8889 als Benutzer abc aus. Sein dependencies.d/hexstrike-server-Eintrag ordnet an, dass er nach dem API-Server startet.

• Upstream-Quellen werden nicht vendored. Das Dockerfile git clonet 0x4m4/hexstrike-ai zur Build-Zeit und checkt einen festgepinnten Commit aus (ARG HEXSTRIKE_REF, Standard d689933ff579d839c676c82b231f8e98326c5f04), wobei nur hexstrike_server.py, hexstrike_mcp.py und hexstrike-ai-mcp.json nach /app kopiert werden. Das hält das Repository klein und den Upstream-Bump zu einer einzeiligen Änderung.

• Python-Umgebung: Ein uv-verwaltetes CPython 3.12 (festgepinnt über .python-version), mit Abhängigkeiten aus pyproject.toml, installiert in /app/.venv über uv sync --no-dev zur Build-Zeit.

• Persistenz-Bootstrap: root/custom-cont-init.d/10-hexstrike-persist läuft als root, bevor die longrun-Dienste starten (siehe Persistenz).

Ports

Schnellstart

Docker Compose (empfohlen)

Die gesamte Konfiguration befindet sich direkt in docker-compose.yml — es gibt keine .env-Datei. Vor dem ersten Start bearbeiten Sie den Block environment: und setzen:

• HEXSTRIKE_MCP_TOKEN — das Bearer-Token für den MCP-Endpunkt. Generieren Sie einen starken Wert mit openssl rand -hex 32 und fügen Sie ihn ein (oder lassen Sie ihn leer für einen offenen Endpunkt — nur für Lab/CTF in einem isolierten Netzwerk).

• CUSTOM_USER / PASSWORD — die Basic-Auth-Anmeldung für den Web-Desktop.

Dann bauen und starten:

# generate a token to paste into docker-compose.yml:
openssl rand -hex 32

docker compose up -d --build

Der Build ist groß und langsam, und es gibt kein vorgefertigtes Image zum Ziehen — das resultierende Image ist >10 GB (~17 GB), daher wird es nicht in eine Registry veröffentlicht und muss lokal gebaut werden. Es installiert das Metapaket kali-linux-headless plus eine lange Liste benannter Tools, kompiliert angr / pwntools-Wheels (daher build-essential + Dev-Header im Image), baut drei Go-Tools aus dem Quellcode und lädt ein rustscan-Release-Paket herunter. Erwarten Sie, dass der erste Build eine erhebliche Zeit dauert und reichlich freien Speicherplatz benötigt (planen Sie ~20 GB+ Puffer ein, mehr beim Iterieren).

Einfaches Docker

docker build -t hexstrike-ai:local .

docker run -d \
  --name hexstrike-ai \
  --cap-add=NET_RAW --cap-add=NET_ADMIN \
  --shm-size=1g \
  -p 3000:3000 -p 3001:3001 -p 8888:8888 -p 8889:8889 \
  -v "$(pwd)/config:/config" \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e CUSTOM_USER=kali \
  -e PASSWORD=changeme \
  -e HEXSTRIKE_MCP_TOKEN="$(openssl rand -hex 32)" \
  hexstrike-ai:local

--cap-add=NET_RAW --cap-add=NET_ADMIN und --shm-size=1g sind erforderlich — siehe Sicherheit und die Kommentare in docker-compose.yml für Gründe.

Verbindung von Claude Code

Sobald der Container läuft, richten Sie Claude Code auf den MCP-Endpunkt auf Port 8889 aus. Wenn HEXSTRIKE_MCP_TOKEN gesetzt ist (dringend empfohlen — siehe Sicherheit), muss jede Anfrage einen passenden Authorization: Bearer <token>-Header enthalten; der Endpunkt akzeptiert nur unauthentifizierte Anfragen, wenn das Token nicht gesetzt ist.

Projekt-/Benutzer-MCP-Konfiguration (.mcp.json oder Claude-Code-Einstellungen):

{
  "mcpServers": {
    "hexstrike-ai": {
      "type": "http",
      "url": "http://<HOST>:8889/mcp",
      "headers": { "Authorization": "Bearer <HEXSTRIKE_MCP_TOKEN>" }
    }
  }
}

Oder über die CLI:

claude mcp add --transport http hexstrike-ai http://<HOST>:8889/mcp \
  --header "Authorization: Bearer <TOKEN>"

Ersetzen Sie <HOST> mit der Adresse/dem Hostnamen des Container-Hosts und <HEXSTRIKE_MCP_TOKEN> / <TOKEN> mit dem oben generierten Wert. Wenn Sie HEXSTRIKE_MCP_TOKEN absichtlich nicht gesetzt haben, lassen Sie das Argument headers / --header weg — der Endpunkt ist in diesem Fall offen.

Invalid Host header / HTTP 421? Der MCP-Streamable-HTTP-Transport hat einen eingebauten DNS-Rebinding-Schutz, der standardmäßig nur einen localhost Host-Header vertraut. Dieses Image deaktiviert diese Prüfung standardmäßig, damit Sie den Endpunkt über das LAN per IP oder Hostname erreichen können. Wenn Sie diesen Fehler dennoch sehen, aktualisieren Sie entweder auf dieses Image (der Standard behandelt es bereits) oder setzen Sie HEXSTRIKE_MCP_ALLOWED_HOSTS auf die genauen host:port-Werte, die Ihre Clients senden.

Umgebungsvariablen

hexstrike_mcp_http.py akzeptiert auch --server / HEXSTRIKE_SERVER_URL, --path / HEXSTRIKE_MCP_PATH, --timeout / HEXSTRIKE_TIMEOUT und --allowed-hosts / HEXSTRIKE_MCP_ALLOWED_HOSTS-Überschreibungen. Das mitgelieferte s6-Run-Skript übergibt nur --server, --host und --port; der Rest wird aus ihren Umgebungs-Fallbacks gelesen (so funktioniert HEXSTRIKE_MCP_ALLOWED_HOSTS, wenn es am Container gesetzt ist) oder behält ihre eingebauten Standardwerte (/mcp, das Standard-Request-Timeout von upstream und die deaktivierte Host-Prüfung).

Persistenz

Das /config-Volume ist das Home-Verzeichnis nach linuxserver-Konvention und der einzige Pfad, der eine Neuerstellung des Containers übersteht. Das Cont-Init-Skript root/custom-cont-init.d/10-hexstrike-persist läuft als root, bevor die Longrun-Dienste starten, und:

1. Erstellt /config/hexstrike/envs, /config/hexstrike/files und /config/hexstrike/output.

2. Ersetzt die hartcodierten Pfade /tmp/hexstrike_envs und /tmp/hexstrike_files von upstream durch Symlinks in /config/hexstrike/envs bzw. /config/hexstrike/files, sodass die pro Tool von HexStrike bei Bedarf erstellten Python-Virtualenvs und der Lese-/Schreibbereich des Dateimanagers Container-Neustarts überstehen.

3. Führt chown auf den persistenten Baum zu abc:abc (unter Beachtung von PUID/PGID) über lsiown aus.

Dynamische /tmp/<tool>_output-Verzeichnisse, die von einzelnen Tool-Läufen erstellt werden, sind nicht verlinkt und bleiben ephemer – weisen Sie ein bestimmtes Tool explizit auf /config/hexstrike/output hin, wenn dessen Ausgabe einen Neustart überstehen soll.

Web-Desktop-Zugriff

Öffnen Sie https://<HOST>:3001/ in einem Browser und melden Sie sich mit den oben konfigurierten CUSTOM_USER- / PASSWORD-Anmeldedaten an (der HTTP-Desktop ist auch auf Port 3000 ohne TLS verfügbar).

Health Check

curl http://<HOST>:8888/health

Gibt JSON vom HexStrike-API-Server zurück, das auflistet, welche seiner Tools als auf PATH im Container verfügbar erkannt wurden.

Sicherheit

[!WARNUNG] Der MCP-Endpunkt auf 8889 ermöglicht einem verbundenen Client, die Ausführung von Offensiv-Sicherheitstools im Container autonom zu steuern – das ist effektiv Remote-Codeausführung per Design, nur durch das von Ihnen konfigurierte Bearer-Token abgesichert.

• Setzen Sie immer HEXSTRIKE_MCP_TOKEN. Generieren Sie es mit openssl rand -hex 32 und halten Sie es geheim. Wenn Sie es leer lassen, ist der MCP-Endpunkt unauthentifiziert.

• Setzen Sie dies nur in einem vertrauenswürdigen/isolierten Netzwerk oder VPN ein. Veröffentlichen Sie Port 8889 (oder 8888) nicht im offenen Internet.

• Zielen Sie nur auf Systeme, die Sie ausdrücklich testen dürfen. Der Container enthält echte Offensiv-Sicherheitstools, die aktives Scannen, Ausnutzung, Credential-Angriffe und mehr ermöglichen.

• Dem Container werden NET_RAW- und NET_ADMIN-Capabilities gewährt (siehe docker-compose.yml / das docker run-Beispiel), da mehrere Tools – nmap-SYN-Scans, masscan, responder usw. – rohe Sockets benötigen. Diese sind enger gefasst als --privileged, aber dennoch deutlich erhöht; gewähren Sie sie nur, wenn Sie diese Scan-Typen benötigen.

• Die Authentifizierung ist als minimale ASGI-Middleware implementiert (BearerTokenASGIMiddleware in hexstrike_mcp_http.py), die den Authorization-Header mit einem Konstantzeit-Vergleich prüft und unauthentifizierte Anfragen an den MCP-Pfad mit 401 ablehnt, bevor sie die MCP-App erreichen – sie puffert oder beeinträchtigt den Streamable-HTTP/SSE-Antwortstream nicht.

Tool-Abdeckung

Der Tool-Satz ist kuratiert, nicht erschöpfend:

• Das Metapaket kali-linux-headless plus eine Liste von Tools, die explizit im Dockerfile genannt sind (die, die der /health-Endpunkt von HexStrike abfragt, sowie gängige Recon-/Web-/Exploitation-Dienstprogramme) – z. B. nmap, masscan, gobuster, feroxbuster, ffuf, dirb, dirsearch, nikto, sqlmap, wpscan, whatweb, wafw00f, hydra, john, hashcat, medusa, evil-winrm, amass, dnsenum, dnsrecon, fierce, theharvester, responder, nuclei, subfinder, httpx-toolkit, arjun, paramspider, hakrawler, getallurls (gau), netexec, enum4linux-ng, smbclient, seclists, wordlists, binwalk, foremost, steghide, exiftool, radare2 und gdb.

• Drei in Go gebaute Tools, die zur Build-Zeit aus dem Quellcode kompiliert und dann von der Go-Toolchain befreit werden: katana, dalfox, waybackurls.

• rustscan, installiert aus dem neuesten GitHub-Release (die .deb wird in einem rustscan.deb.zip-Asset geliefert, das der Build vor der Installation entpackt; Best-Effort – der Build wird ohne es fortgesetzt, wenn das Asset nicht aufgelöst werden kann).

Einige schwere oder lizenzierte Tools, auf die upstream HexStrike verweist – Ghidra, IDA, Burp Suite Pro, Maltego, Nessus sowie verschiedene Cloud-/Forensik-Dienstprogramme – sind nicht in diesem Image installiert, um den Build handhabbar zu halten.

MCP-Tool-Filterung (weniger Tools für das Modell)

Upstream registriert ~150 MCP-Tools. Das überschreitet das Funktions-Tool-Limit einiger Modellanbieter (OpenAI begrenzt bei ~128) und zeigt Tools an, die nur scheitern können, weil ihre CLI-Binärdatei nicht installiert ist. Um dies zu vermeiden, versteckt der MCP-Server jedes Tool, dessen zugrunde liegende Binärdatei nicht vorhanden ist (beim Start mit which geprüft, da der MCP-Prozess im selben Container wie die Tools läuft). Ein typischer Build stellt ~115 Tools statt 150 bereit. Das Startprotokoll gibt die Anzahl und die versteckte Liste aus.

Steuern Sie es über Umgebungsvariablen am Container:

Aktualisieren des Upstream-Pins

Upstream-Quellen werden zur Build-Zeit bei dem Commit in ARG HEXSTRIKE_REF (Dockerfile) geklont. Um neuere Upstream-Änderungen zu übernehmen, erhöhe diesen Pin und baue neu:

docker build -t hexstrike-ai:local --build-arg HEXSTRIKE_REF=<new-sha> .

oder, mit Compose, kommentiere den Eintrag args: HEXSTRIKE_REF: unter dem Schlüssel build: in docker-compose.yml aus und setze ihn, und führe docker compose up -d --build aus.

Credits & Lizenz

• HexStrike AI von 0x4m4 — die Sicherheitsautomatisierungsplattform, die dieses Image paketiert, veröffentlicht unter der MIT-Lizenz. Die vollständigen Bedingungen finden Sie in der LICENSE-Datei des Upstreams.

• linuxserver.io kali-linux-Image — das Basis-Image, das die Kali-Umgebung und den Web-Desktop bereitstellt.