Skip to content

Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.

feat: cableado raiz hermes-pentest (compose 2 servicios kali+ooda-agent, .env.example, README)

Sergio Jimenez8f671a6e21dd
diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..21f6bc3
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,39 @@
+# =============================================================================
+# hermes-pentest — plantilla de variables de entorno.
+# Copia este fichero a .env y rellena los valores. NO pongas secretos reales aquí.
+# cp .env.example .env
+# =============================================================================
+
+# --- LLM (OpenRouter) ---------------------------------------------------------
+# OBLIGATORIO. Es la MISMA key de OpenRouter que usa Hermes como proveedor del LLM.
+# Hermes la lee de esta variable directamente (no de HERMES_LLM_API_KEY).
+OPENROUTER_API_KEY=
+
+# OPCIONAL. Modelo por defecto de OpenRouter (si se omite, usa el del perfil).
+OPENROUTER_MODEL=
+
+# --- API server de Hermes -----------------------------------------------------
+# OBLIGATORIO. Clave del API server interno de Hermes (mín. 8 chars). Genera una con:
+# openssl rand -hex 32
+HERMES_API_SERVER_KEY=
+
+# --- AWS read-only (OPCIONAL) -------------------------------------------------
+# Solo si vas a usar las tools de recolección cloud (Prowler/ScoutSuite/Cloudsplaining).
+# Si no las usas, deja estas variables vacías. Usa credenciales read-only de la cuenta
+# que estés AUTORIZADO a auditar.
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+# Solo para credenciales temporales (STS).
+AWS_SESSION_TOKEN=
+AWS_REGION=
+
+# --- Canal de artefactos (OPCIONAL) -------------------------------------------
+# Token compartido del canal de datos del contenedor kali.
+KALI_ARTIFACTS_TOKEN=
+
+# --- Prowler (OPCIONAL) -------------------------------------------------------
+# Acotan el escaneo cloud si usas Prowler. Vacío = valores por defecto del compose.
+PROWLER_STATUS=
+PROWLER_REGIONS=
+PROWLER_SERVICES=
+PROWLER_TIMEOUT=
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7d0beb5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,59 @@
+# hermes-pentest
+
+OODA pentest conducido por **Hermes** hablando **directo** a un contenedor **Kali** vía MCP.
+
+## Qué es
+
+`hermes-pentest` ejecuta un bucle OODA (Observe-Orient-Decide-Act) de pentest donde
+el cerebro conductor es [Hermes](https://github.com/NousResearch/hermes) y las
+herramientas corren en un Kali gobernado por un servidor MCP. Hermes decide qué
+ejecutar y lo lanza **directamente** contra el objetivo a través del MCP de Kali.
+
+A diferencia de PentAgent, aquí **no hay core, ni API REST, ni UI, ni gates**. Es un
+diseño deliberadamente mínimo: solo dos contenedores y el agente conduciendo de punta
+a punta.
+
+## Arquitectura (2 contenedores)
+
+- **kali** — runtime determinista de tools de pentest y recolección (nmap, Prowler,
+ ScoutSuite, Cloudsplaining, ...). Expone un servidor `kali-mcp` en `:8900`.
+- **ooda-agent** — Hermes (`nousresearch/hermes-agent`) como conductor del bucle OODA.
+ Es cliente directo del MCP de Kali (`kali:8900`) y ejecuta las tools de pentest con
+ `kali_run`. Mantiene vivo su gateway con `hermes gateway run` (API server interno en
+ `:8642`, **no publicado al host**).
+
+No hay servicios `api` ni `ui`: el agente habla directo con Kali.
+
+## Cómo levantarlo
+
+```sh
+cp .env.example .env
+# Rellena como mínimo:
+# OPENROUTER_API_KEY (tu key de OpenRouter)
+# HERMES_API_SERVER_KEY (genera una: openssl rand -hex 32)
+docker compose up -d --build
+```
+
+## Cómo conducir el pentest (TUI interactivo)
+
+```sh
+docker compose up -d --build
+docker compose exec -it ooda-agent hermes chat
+```
+
+`hermes chat` abre el TUI/REPL interactivo del agente. Desde ahí le pides un pentest
+en lenguaje natural; Hermes conduce el OODA y ejecuta las herramientas en Kali
+**directamente** con la tool `kali_run` (hablando con `kali:8900`).
+
+`hermes gateway run` (el comando del contenedor) mantiene el contenedor vivo y arranca
+el API server interno de Hermes en `:8642`. Ese API server es una vía **programática
+alternativa** (OpenAI-compatible), accesible solo por la red interna de docker.
+
+## ⚠️ Advertencia (importante)
+
+Este producto **NO tiene los guardarraíles de PentAgent**: **no hay scope-guard, no hay
+consentimiento, no hay audit, no hay gate E4**. Hermes ejecuta directamente lo que
+decida contra el objetivo, sin portero que valide el alcance.
+
+Esto es **intencional**. Úsalo **solo contra targets explícitamente autorizados** y en
+un **entorno controlado**. Toda la responsabilidad del alcance recae en el operador.
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..53e6dc3
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,123 @@
+# =============================================================================
+# hermes-pentest — OODA pentest con Hermes hablando DIRECTO a Kali-MCP.
+# =============================================================================
+# Qué es: un bucle OODA de pentest conducido por Hermes (nousresearch/hermes-agent)
+# que ejecuta herramientas DIRECTAMENTE en un contenedor Kali vía su servidor MCP.
+# NO hay core/API/UI de PentAgent: solo DOS contenedores.
+# - kali : runtime determinista de tools (kali-mcp escuchando en :8900).
+# - ooda-agent : Hermes como CEREBRO conductor del bucle OODA, cliente directo del
+# MCP de kali (kali:8900). Driver del OODA, sin intermediarios.
+#
+# Arranque:
+# cp .env.example .env # y rellena OPENROUTER_API_KEY y HERMES_API_SERVER_KEY
+# docker compose up -d --build
+# docker compose exec -it ooda-agent hermes chat # TUI interactivo
+#
+# ADVERTENCIA (intencional): este producto NO tiene los guardarraíles de PentAgent.
+# NO hay scope-guard, NO hay consentimiento, NO hay audit, NO hay gate E4. Hermes
+# ejecuta lo que decida directamente contra el objetivo. Úsalo SOLO contra targets
+# explícitamente autorizados y en un entorno controlado. La responsabilidad del
+# alcance recae enteramente en el operador.
+#
+# Multi-arch: cada build declara platforms [linux/arm64, linux/amd64]. En Mac M2
+# se ejecuta arm64 nativo.
+
+services:
+ kali:
+ build:
+ context: .
+ dockerfile: docker/kali/Dockerfile
+ platforms:
+ - linux/arm64
+ - linux/amd64
+ image: hermes-pentest-kali:dev
+ environment:
+ # --- AWS read-only (OPCIONAL en este producto) ---
+ # Prowler/ScoutSuite/Cloudsplaining corren DENTRO de este contenedor. Si se van
+ # a usar las tools de recolección cloud, define estas credenciales en .env; si no,
+ # quedan vacías y las tools cloud simplemente no tendrán con qué autenticar.
+ AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID:-}"
+ AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY:-}"
+ # Opcional: solo para credenciales temporales (STS).
+ AWS_SESSION_TOKEN: "${AWS_SESSION_TOKEN:-}"
+ AWS_REGION: "${AWS_REGION:-us-east-1}"
+ # Puerto del servidor kali-mcp dentro del contenedor. Overridable sin reconstruir.
+ KALI_MCP_PORT: "8900"
+ # --- Plano de DATOS de artefactos (puerto dedicado, red interna) ---
+ KALI_ARTIFACTS_PORT: "8901"
+ # Token compartido del canal de datos (opcional en este producto).
+ KALI_ARTIFACTS_TOKEN: "${KALI_ARTIFACTS_TOKEN:-}"
+ # --- Prowler (opcional): acota el escaneo cloud si se usa ---
+ PROWLER_STATUS: "${PROWLER_STATUS:-FAIL}"
+ PROWLER_REGIONS: "${PROWLER_REGIONS-${AWS_REGION:-us-east-1}}"
+ PROWLER_SERVICES: "${PROWLER_SERVICES-iam s3}"
+ PROWLER_TIMEOUT: "${PROWLER_TIMEOUT:-1800}"
+ # Puerto del servidor kali-mcp (expuesto para inspección directa desde el host si
+ # hace falta; ooda-agent lo alcanza por la red interna como kali:8900).
+ ports:
+ - "8900:8900"
+ # HEALTHCHECK: comprueba que el servidor MCP acepta conexiones TCP en :8900, para
+ # que ooda-agent pueda depender con condition: service_healthy antes de arrancar.
+ healthcheck:
+ test: ["CMD", "python", "-c", "import socket,sys; s=socket.socket(); s.settimeout(3); sys.exit(0 if s.connect_ex(('localhost',8900))==0 else 1)"]
+ interval: 10s
+ timeout: 5s
+ retries: 6
+ start_period: 20s
+ restart: unless-stopped
+
+ ooda-agent:
+ # Imagen oficial de registry (NO se construye desde este repo).
+ image: nousresearch/hermes-agent
+ # Arranque (modelo "perfil default"): recrea el perfil DEFAULT (/opt/data) copiando
+ # la plantilla declarativa del repo (bind-mount read-only en /opt/profile-src),
+ # inyecta la key del API server y arranca el gateway en foreground. 'hermes gateway
+ # run' mantiene el contenedor VIVO y arranca platforms.api_server (:8642 interno).
+ command:
+ - sh
+ - -c
+ - |
+ set -e
+ # El perfil DEFAULT es el home raíz /opt/data (no /opt/data/profiles/<p>).
+ DEF=/opt/data
+ # (a) copia la plantilla declarativa (config/SOUL/skills) al home del perfil default.
+ mkdir -p "$$DEF/skills"
+ cp /opt/profile-src/profile/config.yaml "$$DEF/config.yaml"
+ cp /opt/profile-src/profile/SOUL.md "$$DEF/SOUL.md"
+ cp -r /opt/profile-src/skills/. "$$DEF/skills/" 2>/dev/null || true
+ # (b) inyecta la KEY del API server (secreto, no se versiona) ANTES de arrancar.
+ hermes config set platforms.api_server.key "$$HERMES_API_SERVER_KEY" >/dev/null
+ # (c) arranca el gateway del perfil default: foreground (contenedor vivo) + API server.
+ exec hermes gateway run
+ environment:
+ # Clave del API server de Hermes — obligatoria (fail-closed): mín 8 chars. Hacen
+ # falta DOS vías: el command la escribe en platforms.api_server.key (arrancar el
+ # API server) y API_SERVER_KEY la valida en cada petición (autenticar el Bearer).
+ HERMES_API_SERVER_KEY: "${HERMES_API_SERVER_KEY:?Falta HERMES_API_SERVER_KEY - genera uno con 'openssl rand -hex 32' (min 8 chars) y ponlo en .env}"
+ API_SERVER_KEY: "${HERMES_API_SERVER_KEY}"
+ # API key del proveedor LLM de Hermes. Hermes lee la key del LLM de ESTA env var
+ # (OPENROUTER_API_KEY), por eso NO se declara HERMES_LLM_API_KEY. Obligatoria
+ # fail-closed: sin ella el agente no puede razonar.
+ OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:?Falta OPENROUTER_API_KEY - define la API key de OpenRouter en .env}"
+ volumes:
+ # VOLUMEN CON NOMBRE OBLIGATORIO (nunca bind-mount): el state.db SQLite en modo WAL
+ # de Hermes SE CORROMPE en bind-mounts que cruzan la VM de macOS (virtiofs).
+ - hermes-data:/opt/data
+ # Plantilla declarativa del perfil, READ-ONLY y FUERA de /opt/data (no toca el WAL).
+ - ./agent-ooda:/opt/profile-src:ro
+ # TUI interactivo: 'docker compose exec -it ooda-agent hermes chat' necesita stdin+tty.
+ stdin_open: true
+ tty: true
+ # SIN sección ports: el API server de Hermes (:8642) NO se publica al host; solo es
+ # accesible por la red interna de docker.
+ depends_on:
+ # Espera a que kali esté healthy (MCP escuchando) antes de arrancar.
+ kali:
+ condition: service_healthy
+ restart: unless-stopped
+ # Red default del compose: alcanza kali:8900 por DNS interno de docker.
+
+volumes:
+ # Estado de Hermes (perfil + SQLite WAL). CON NOMBRE a propósito: evita el bind-mount
+ # que corrompe el SQLite WAL en virtiofs de macOS.
+ hermes-data: