HexStrike AI — Docker + MCP remoto

HexStrike AI dockerizado sobre la imagen base Kali de linuxserver.io, con un nuevo servidor MCP remoto, HTTP transmisible para que todo el conjunto de herramientas de HexStrike pueda manejarse a través de la red (p. ej., desde Claude Code) en lugar de solo desde un cliente stdio local.

[!ADVERTENCIA] Esto expone la ejecución autónoma de herramientas de seguridad ofensiva a través de la red. Un cliente conectado al endpoint MCP puede efectivamente realizar ejecución remota de comandos en todo el arsenal de herramientas del contenedor. Lea la sección Seguridad antes de ejecutarlo en cualquier lugar que no sea un laboratorio aislado. Siempre establezca HEXSTRIKE_MCP_TOKEN, ejecútelo solo en una red o VPN de confianza/aislada, y solo apunte a sistemas que esté explícitamente autorizado a probar.

[!NOTA] No se publica ninguna imagen precompilada. Debido a que el conjunto completo de herramientas de Kali hace que la imagen sea grande (>10 GB — aproximadamente ~17 GB compilada), no se sube a Docker Hub ni a ningún registro. Usted mismo la compila desde este repositorio (consulte Inicio rápido); asegúrese de que el host de Docker tenga suficiente espacio libre en disco.

Contenido

• Características

• Resumen

• Arquitectura

• Puertos

• Inicio rápido

• Conexión desde Claude Code

• Variables de entorno

• Persistencia

• Acceso al escritorio web

• Comprobación de salud

• Seguridad

• Cobertura de herramientas

• Actualización del pin upstream

• Créditos y licencia

Related MCP server: MCP Tools

Características

• El kit de herramientas completo de HexStrike AI upstream — más de 150 herramientas de seguridad manejadas a través de su API Flask — preinstalado en una imagen basada en Kali, sin configuración manual del entorno.

• Nuevo: hexstrike_mcp_http.py, un servidor MCP HTTP transmisible que expone cada definición @mcp.tool() upstream a través de la red en el puerto 8889 (ruta /mcp), para que pueda manejarse de forma remota en lugar de solo mediante stdio local.

• Autenticación opcional por token de portador que protege el endpoint MCP.

• Escritorio KDE accesible desde el navegador (Selkies/KasmVNC, heredado de la imagen base) para trabajo interactivo junto con ejecuciones automatizadas de herramientas.

• Supervisión de procesos s6-overlay v3 con orden de servicios explícito: el servicio MCP espera a que el servidor API de HexStrike esté definido como dependencia.

• Volumen persistente /config: los virtualenvs por herramienta y el estado del administrador de archivos sobreviven a los reinicios del contenedor.

• Compilaciones reproducibles: uv gestiona el entorno de Python, y las fuentes upstream se obtienen en un commit git fijado en lugar de incluirse como vendor.

Resumen

HexStrike AI upstream incluye dos puntos de entrada de Python:

• hexstrike_server.py — un servidor API Flask que escucha en el puerto 8888 y ejecuta más de 150 herramientas de seguridad externas mediante subprocess, exponiendo sus resultados a través de HTTP (incluido un endpoint /health que informa de la disponibilidad de las herramientas).

• hexstrike_mcp.py — un servidor FastMCP que traduce las llamadas de herramientas MCP en llamadas HTTP al servidor API anterior. Upstream solo lo ejecuta sobre el transporte stdio, por lo que solo puede ser manejado por un cliente MCP en la misma máquina que el contenedor.

Este repositorio añade hexstrike_mcp_http.py, que importa el módulo hexstrike_mcp.py de upstream y reutiliza su función setup_mcp_server() íntegramente — cada definición de herramienta, sin cambios — pero lo sirve sobre el transporte MCP HTTP transmisible en el puerto 8889 en la ruta /mcp en lugar de stdio. Esa es la única diferencia funcional: la misma superficie de herramientas, accesible de forma remota (p. ej., desde Claude Code ejecutándose en otra máquina) en lugar de solo desde un proceso co-ubicado.

uv (Astral) gestiona el intérprete de Python y el entorno de dependencias, y se utiliza para ejecutar ambos procesos al iniciar el contenedor.

Arquitectura

• Imagen base: lscr.io/linuxserver/kali-linux:latest, que proporciona un escritorio KDE accesible desde el navegador (Selkies/KasmVNC) en los puertos 3000 (HTTP) y 3001 (HTTPS), repositorios apt de Kali-rolling e init s6-overlay v3.

• Servicios añadidos: dos servicios longrun de s6-overlay se superponen al sistema init de la imagen base y se registran en el paquete de servicios user:

  • root/etc/s6-overlay/s6-rc.d/hexstrike-server — ejecuta uv run --no-sync python hexstrike_server.py --port 8888 como el usuario abc.

  • root/etc/s6-overlay/s6-rc.d/hexstrike-mcp — ejecuta uv run --no-sync python hexstrike_mcp_http.py --server http://127.0.0.1:8888 --host 0.0.0.0 --port 8889 como el usuario abc. Su entrada dependencies.d/hexstrike-server lo ordena para que se inicie después del servidor API.

• Las fuentes upstream no se incluyen como vendor. El Dockerfile hace git clone de 0x4m4/hexstrike-ai en tiempo de compilación y verifica un commit fijado (ARG HEXSTRIKE_REF, por defecto d689933ff579d839c676c82b231f8e98326c5f04), copiando solo hexstrike_server.py, hexstrike_mcp.py y hexstrike-ai-mcp.json a /app. Esto mantiene el repositorio pequeño y la actualización upstream es un cambio de una línea.

• Entorno de Python: un CPython 3.12 gestionado por uv (fijado mediante .python-version), con las dependencias de pyproject.toml instaladas en /app/.venv mediante uv sync --no-dev en tiempo de compilación.

• Arranque de persistencia: root/custom-cont-init.d/10-hexstrike-persist se ejecuta como root antes de que se inicien los servicios longrun (consulte Persistencia).

Puertos

Inicio rápido

Docker Compose (recomendado)

Toda la configuración vive directamente en docker-compose.yml — no hay archivo .env. Antes del primer lanzamiento, edite el bloque environment: y establezca:

• HEXSTRIKE_MCP_TOKEN — el token de portador para el endpoint MCP. Genere un valor fuerte con openssl rand -hex 32 y péguelo (o déjelo vacío para un endpoint abierto — solo laboratorio/CTF en una red aislada).

• CUSTOM_USER / PASSWORD — el inicio de sesión de autenticación básica del escritorio web.

Luego compile e inicie:

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

docker compose up -d --build

La compilación es grande y lenta, y no hay imagen precompilada que descargar — la imagen resultante es >10 GB (~17 GB), por lo que no se publica en ningún registro y debe compilarse localmente. Instala el metapaquete kali-linux-headless más una larga lista de herramientas nombradas, compila las ruedas de angr / pwntools (de ahí build-essential + cabeceras de desarrollo en la imagen), compila tres herramientas Go desde el código fuente y descarga un paquete de lanzamiento de rustscan. Espere que la primera compilación tome una cantidad significativa de tiempo y mucho espacio libre en disco (presupueste ~20 GB+ de margen, más mientras itera).

Docker simple

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 y --shm-size=1g son obligatorios — consulte Seguridad y los comentarios de docker-compose.yml para saber por qué.

Conexión desde Claude Code

Una vez que el contenedor esté en marcha, apunte Claude Code al endpoint MCP en el puerto 8889. Si HEXSTRIKE_MCP_TOKEN está establecido (muy recomendado — consulte Seguridad), cada solicitud debe incluir un encabezado Authorization: Bearer <token> coincidente; el endpoint solo acepta solicitudes no autenticadas si el token se deja sin establecer.

Configuración MCP de proyecto/usuario (.mcp.json o ajustes de Claude Code):

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

O mediante la CLI:

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

Reemplace <HOST> con la dirección/nombre de host del contenedor y <HEXSTRIKE_MCP_TOKEN> / <TOKEN> con el valor que generó anteriormente. Si deliberadamente dejó HEXSTRIKE_MCP_TOKEN sin establecer, omita el argumento headers / --header — el endpoint está abierto en ese caso.

¿Invalid Host header o HTTP 421? El transporte MCP HTTP transmisible tiene protección integrada contra el rebinding de DNS que, por defecto, solo confía en un encabezado Host de localhost. Esta imagen desactiva esa comprobación por defecto para que pueda llegar al endpoint a través de la LAN por IP o nombre de host. Si en cambio ve este error, o bien actualice a esta imagen (el valor predeterminado ya lo maneja) o establezca HEXSTRIKE_MCP_ALLOWED_HOSTS con el/los valor(es) exactos de host:port que envían sus clientes.

Variables de entorno

hexstrike_mcp_http.py también acepta las sobrescrituras --server / HEXSTRIKE_SERVER_URL, --path / HEXSTRIKE_MCP_PATH, --timeout / HEXSTRIKE_TIMEOUT y --allowed-hosts / HEXSTRIKE_MCP_ALLOWED_HOSTS. El script de ejecución s6 incluido solo pasa --server, --host y --port; el resto se lee de sus respaldos de entorno (por lo que HEXSTRIKE_MCP_ALLOWED_HOSTS funciona cuando se define en el contenedor) o conserva sus valores predeterminados integrados (/mcp, el tiempo de espera de solicitud predeterminado de upstream y la comprobación de Host deshabilitada).

Persistencia

El volumen /config es el directorio de inicio según la convención de linuxserver y es la única ruta que sobrevive a la recreación del contenedor. El script de cont-init root/custom-cont-init.d/10-hexstrike-persist se ejecuta como root antes de que arranquen los servicios longrun y:

1. Crea /config/hexstrike/envs, /config/hexstrike/files y /config/hexstrike/output.

2. Reemplaza las rutas hardcoded de upstream /tmp/hexstrike_envs y /tmp/hexstrike_files con enlaces simbólicos a /config/hexstrike/envs y /config/hexstrike/files, respectivamente, para que los entornos virtuales de Python por herramienta que HexStrike construye bajo demanda, y su área de lectura/escritura del gestor de archivos, sobrevivan a los reinicios del contenedor.

3. Ejecuta chown del árbol persistente a abc:abc (respetando PUID/PGID) mediante lsiown.

Los directorios dinámicos /tmp/<tool>_output creados por ejecuciones individuales de herramientas no están enlazados simbólicamente y siguen siendo efímeros: apunta una herramienta concreta explícitamente a /config/hexstrike/output si necesitas que su salida sobreviva a un reinicio.

Acceso al escritorio web

Abre https://<HOST>:3001/ en un navegador e inicia sesión con las credenciales CUSTOM_USER / PASSWORD configuradas arriba (el escritorio HTTP también está disponible en el puerto 3000 sin TLS).

Comprobación de salud

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

Devuelve JSON del servidor de la API de HexStrike en el que se listan las herramientas detectadas como disponibles en PATH dentro del contenedor.

Seguridad

[!WARNING] El endpoint MCP en 8889 permite a un cliente conectado impulsar de forma autónoma la ejecución de herramientas de seguridad ofensiva dentro del contenedor; esto es efectivamente ejecución remota de comandos por diseño, restringido únicamente por el token Bearer que configures.

• Configura siempre HEXSTRIKE_MCP_TOKEN. Genéralo con openssl rand -hex 32 y mantenlo en secreto. Dejarlo vacío deja el endpoint MCP sin autenticación.

• Expón esto solo en una red de confianza/aislada o VPN. No publiques el puerto 8889 (ni 8888) a Internet abierta.

• Apunta únicamente a sistemas que estés explícitamente autorizado a probar. El contenedor incluye herramientas reales de seguridad ofensiva capaces de realizar escaneos activos, explotación, ataques de credenciales y más.

• El contenedor tiene concedidas las capacidades NET_RAW y NET_ADMIN (consulta docker-compose.yml / el ejemplo de docker run) porque varias herramientas — escaneos SYN de nmap, masscan, responder, etc. — necesitan sockets en bruto. Son más limitadas que --privileged, pero siguen estando significativamente elevadas; concédelas solo si necesitas esos tipos de escaneo.

• La autenticación se implementa como un middleware ASGI mínimo (BearerTokenASGIMiddleware en hexstrike_mcp_http.py) que inspecciona la cabecera Authorization con una comparación en tiempo constante y rechaza con 401 las solicitudes no autenticadas a la ruta MCP antes de que lleguen a la aplicación MCP: no almacena en búfer ni interfiere de otro modo con el flujo de respuesta streamable-HTTP/SSE.

Cobertura de herramientas

El conjunto de herramientas está seleccionado, no es exhaustivo:

• El metapaquete kali-linux-headless, más una lista de herramientas nombradas explícitamente en el Dockerfile (las que sondea el endpoint /health de HexStrike y utilidades comunes de reconocimiento/web/explotación) — p. ej. 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 y gdb.

• Tres herramientas compiladas con Go desde el código fuente en tiempo de compilación y luego despojadas de la cadena de herramientas de Go: katana, dalfox, waybackurls.

• rustscan, instalado desde su último lanzamiento de GitHub (el .deb se distribuye dentro de un recurso rustscan.deb.zip, que la compilación descomprime antes de instalar; con el mejor esfuerzo posible: la compilación continúa sin él si no se puede resolver el recurso).

Algunas herramientas pesadas o con licencia referenciadas por upstream HexStrike — Ghidra, IDA, Burp Suite Pro, Maltego, Nessus y varias utilidades de nube/forense — no están instaladas en esta imagen para que la compilación siga siendo manejable.

Filtrado de herramientas MCP (menos herramientas para el modelo)

Upstream registra ~150 herramientas MCP. Eso desborda el límite de herramientas de función de algunos proveedores de modelos (OpenAI limita a ~128) y expone herramientas que solo pueden fallar porque su binario CLI no está instalado. Para evitarlo, el servidor MCP oculta cualquier herramienta cuyo binario subyacente no esté presente (se comprueba con which al iniciar, ya que el proceso MCP se ejecuta en el mismo contenedor que las herramientas). Una compilación típica expone ~115 herramientas en lugar de 150. El registro de inicio imprime el recuento y la lista de herramientas ocultas.

Contrólalo mediante variables de entorno en el contenedor:

Actualización del pin de upstream

Las fuentes upstream se clonan en tiempo de compilación en el commit indicado en ARG HEXSTRIKE_REF (Dockerfile). Para incorporar cambios upstream más recientes, actualiza ese pin y recompila:

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

o, con Compose, descomenta y establece la entrada args: HEXSTRIKE_REF: bajo la clave build: en docker-compose.yml y ejecuta docker compose up -d --build.

Créditos y Licencia

• HexStrike AI por 0x4m4 — la plataforma de automatización de seguridad que empaqueta esta imagen, publicada bajo la Licencia MIT. Consulta el archivo LICENSE del upstream para conocer los términos completos.

• Imagen kali-linux de linuxserver.io — la imagen base que proporciona el entorno Kali y el escritorio web.