Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Python ai-agentsautonomous-agentskali-linuxllm-agentsoffensive-securityooda-looppentestingplaywrightsecurity
feat: bring vulnerator-mcp up by default (4-container stack)
irraza89e2ca37073
diff --git a/.env.example b/.env.exampleindex 5a16946..23fe462 100644--- a/.env.example+++ b/.env.example@@ -52,26 +52,27 @@ HERMES_API_SERVER_KEY=# controlled environment. If you don't want to open the port, use 'docker compose exec' (see README).HERMES_API_HOST_PORT=-# --- vulnerator-mcp (OPTIONAL MCP front door — docker-compose.mcp.yml) ---------# These vars matter ONLY when you bring up the OPTIONAL vulnerator-mcp service with-# docker compose -f docker-compose.yml -f docker-compose.mcp.yml up -d --build-# The default 3-container stack does NOT use them, and stdio mode (local Claude Code / Kiro)-# needs neither of them.+# --- vulnerator-mcp (MCP front door — UP BY DEFAULT in docker-compose.yml) ----+# The vulnerator-mcp service is part of the DEFAULT stack (4th container). It exposes Hermes'+# :8642 runs API as MCP tools so an MCP client (Claude Code / Kiro / BugTraceAI) can drive a+# pentest. Because it comes up by default in streamable-HTTP mode, the token below is REQUIRED.#-# REQUIRED only for the optional streamable-HTTP service. Inbound Bearer that gates the+# REQUIRED (the default stack is fail-closed on this). Inbound Bearer that gates the# clients -> vulnerator-mcp edge. Generate one with:# openssl rand -hex 32# It is a SEPARATE secret from HERMES_API_SERVER_KEY and protects a DIFFERENT edge (it does-# NOT re-protect the :8642 host exposure). The service is FAIL-CLOSED: it will not start-# without this, and every request must carry 'Authorization: Bearer <this>'.+# NOT re-protect the :8642 host exposure). The service is FAIL-CLOSED: `docker compose up` will+# abort without it, and every request must carry 'Authorization: Bearer <this>'.+# NOTE: the LOCAL stdio mode for Claude Code / Kiro (`docker run -i …`, see README) needs+# NEITHER this token NOR a host port — it has zero network surface.VULNERATOR_MCP_INBOUND_TOKEN=-# OPTIONAL. HOST port where the vulnerator-mcp streamable-HTTP server is published. Relevant-# ONLY if you uncomment the 'ports:' block in docker-compose.mcp.yml. By DEFAULT the service-# publishes NO host port and is reachable only on the internal docker network at-# vulnerator-mcp:8700. Set this (and uncomment the block) to publish on a controlled machine.-# WARNING: publishing exposes the no-guardrails engine's trigger API to the host; do it-# deliberately and keep VULNERATOR_MCP_INBOUND_TOKEN secret.+# OPTIONAL. HOST port where the vulnerator-mcp streamable-HTTP server is published. By DEFAULT+# the service publishes NO host port and is reachable only on the internal docker network at+# vulnerator-mcp:8700 (in-docker consumers like BugTraceAI reach it there). To publish on a+# CONTROLLED machine, set this AND uncomment the 'ports:' block of the vulnerator-mcp service+# in docker-compose.yml. WARNING: publishing exposes the no-guardrails engine's trigger API to+# the host; do it deliberately and keep VULNERATOR_MCP_INBOUND_TOKEN secret.VULNERATOR_MCP_HOST_PORT=# --- AWS read-only (OPTIONAL) -------------------------------------------------diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 6e057ab..7adf551 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,7 +8,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [1.4.0] - 2026-10-16### Added-- **Optional `vulnerator-mcp` MCP front door over the Hermes `:8642` runs API.** A thin+- **`vulnerator-mcp` MCP front door over the Hermes `:8642` runs API (up by default).** A thinFastMCP wrapper (`docker/mcp/`) that lets external MCP clients (Claude Code / Kiro locallyover stdio; remote/containerized consumers like BugTraceAI over streamable-HTTP) trigger,observe, steer and stop a Hermes OODA pentest as MCP tools. It WRAPS, does not replace, the@@ -21,12 +21,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0from `GET /health` and reported verbatim, never branched on. `stream_run_events` uses theevent `seq` as a portable cursor (batched pages with `next_cursor`/`done`) and additionallyemits MCP progress notifications over streamable-HTTP, degrading to pure batching on stdio.- Shipped as a NEW **optional layered `docker-compose.mcp.yml`** — NOT part of the default- stack, which stays 3 containers (`kali`, `ooda-agent`, `playwright-mcp`) — brought up with- `docker compose -f docker-compose.yml -f docker-compose.mcp.yml up -d --build`. The- streamable-HTTP service binds the internal docker network with host publication OFF by- default (no `ports:` block; opt-in by uncommenting it and/or setting- `VULNERATOR_MCP_HOST_PORT`) and is **fail-closed on a mandatory inbound token**+ Shipped as a **4th service in the default `docker-compose.yml`** — the default stack is now+ 4 containers (`kali`, `ooda-agent`, `playwright-mcp`, `vulnerator-mcp`), brought up with a+ plain `docker compose up -d --build` — because the product's intended UX is driving the+ engine from an MCP client. The streamable-HTTP service binds the internal docker network with+ host publication OFF by default (no `ports:` block; opt-in by setting+ `VULNERATOR_MCP_HOST_PORT` and uncommenting the service's `ports:` block) and is **fail-closed+ on a mandatory inbound token**(`VULNERATOR_MCP_INBOUND_TOKEN`): it refuses to start without one and rejects any requestwithout the matching `Authorization: Bearer` (constant-time compare), with an exact-matchcarve-out for a dedicated `/healthz` route only. The same image also runs stdio for localdiff --git a/README.md b/README.mdindex 30d9b55..74e50ea 100644--- a/README.md+++ b/README.md@@ -45,11 +45,12 @@ tools run on a Kali governed by an MCP server. Hermes decides whatto run and launches it **directly** against the target through the Kali MCP.It is a deliberately minimal design: **no core, no REST API, no UI, no gates**.-Three containers (the agent and two MCP servers) and the agent driving end to end.+Four containers (the agent, two tool MCP servers and the MCP front door) and the agent driving+end to end.-## Architecture (3 containers)+## Architecture (4 containers)-+- **kali** — deterministic runtime for pentest and collection tools (nmap, Prowler,ScoutSuite, Cloudsplaining, ...). Exposes a `kali-mcp` server on `:8900` (and the artifacts@@ -63,14 +64,19 @@ Three containers (the agent and two MCP servers) and the agent driving end to en**published to the host** by default so you can pilot it from an external assistant — see"Pilot Hermes from an external assistant").-There are no `api` or `ui` services: the agent talks directly to the MCPs (Kali and browser).+- **vulnerator-mcp** — a thin MCP **front door** over Hermes' `:8642` runs API so external MCP+ clients (Claude Code / Kiro, BugTraceAI, ...) can trigger/observe/steer/stop a pentest as MCP+ tools. It is **up by default** (4th container) because the intended UX is driving the engine+ from an MCP client. In the default stack it runs **streamable-HTTP on the internal network**+ (`http://vulnerator-mcp:8700`, **no host port**) and is **fail-closed** on+ `VULNERATOR_MCP_INBOUND_TOKEN`. For **local** Claude Code / Kiro the recommended path is instead+ the **stdio** mode (`docker run -i …`, zero network surface, no token). It wraps, does **not**+ replace, the HTTP API: it exposes **only** the runs lifecycle (no raw `kali_run`, no+ `/v1/chat/completions`) so the client stays a trigger/observer, never the brain. See "Consume+ Hermes from an MCP client (`vulnerator-mcp`)" below.-There is an **OPTIONAL 4th container** you can layer on top: **vulnerator-mcp** — a thin MCP-front door over Hermes' `:8642` runs API so external MCP clients (Claude Code / Kiro,-BugTraceAI, ...) can trigger/observe/steer/stop a pentest as MCP tools. It is **not** part of-the default stack (the default `docker compose up` stays the 3 containers above); it is an-opt-in overlay, the same way the Juice Shop target is. See "Consume Hermes from an MCP client-(`vulnerator-mcp`)" below.+There are no `api` or `ui` services: the agent talks directly to the MCPs (Kali and browser),+and the MCP front door only forwards the runs lifecycle.### Tools included in the Kali image@@ -106,12 +112,13 @@ the template, which documents every variable:cp .env.example .env```-Open the `.env` and fill in the values. At a minimum you need the two required ones:+Open the `.env` and fill in the values. At a minimum you need the three required ones:| Variable | Required | Where to put it / how to get it || --- | --- | --- || `OPENROUTER_API_KEY` | **Yes** | Your OpenRouter API key (the provider of the LLM that reasons the OODA). Create it at <https://openrouter.ai/keys> and paste it into the `.env`. || `HERMES_API_SERVER_KEY` | **Yes** | Key for Hermes' API server (min. 8 chars). Generate one with `openssl rand -hex 32` and paste it into the `.env`. It is also the Bearer to pilot Hermes over HTTP. |+| `VULNERATOR_MCP_INBOUND_TOKEN` | **Yes** | Inbound Bearer for the `vulnerator-mcp` front door, which is **up by default** in streamable-HTTP mode. Generate one with `openssl rand -hex 32` and paste it into the `.env`. The default stack is **fail-closed** on this: `docker compose up` aborts without it. It is a **separate** secret from `HERMES_API_SERVER_KEY` and gates a different edge. (The local **stdio** mode for Claude Code / Kiro does not need it.) |The **AWS credentials are OPTIONAL**: they are only needed if you are going to use the cloudcollection tools (Prowler / ScoutSuite / Cloudsplaining). If you are not auditing AWS, leave these@@ -124,7 +131,7 @@ variables empty in the `.env`:| `AWS_SESSION_TOKEN` | No | Only for temporary credentials (STS). In the `.env`. || `AWS_REGION` | No | Default region (e.g. `us-east-1`). In the `.env`. || `OPENROUTER_MODEL` | No | Overrides the OpenRouter model Hermes reasons with. Empty = the profile default (`mistralai/mistral-large-4-0`). **Caveat:** the project uses Mistral Large on purpose because models like Claude (`anthropic/*`) refuse the authorized-offensive pentest framing (OpenRouter/Anthropic returns "violative cyber content"); overriding with such a model may make the agent refuse to work. |-| `VULNERATOR_MCP_INBOUND_TOKEN` | Only for the optional `vulnerator-mcp` HTTP service | Inbound Bearer for the opt-in `docker-compose.mcp.yml` streamable-HTTP service. Generate with `openssl rand -hex 32`. It is a **separate** secret from `HERMES_API_SERVER_KEY` and gates a different edge. The service is **fail-closed**: it will not start without this. NOT needed for the default stack or for stdio mode. See "Consume Hermes from an MCP client". |+| `VULNERATOR_MCP_HOST_PORT` | No | HOST port to publish the `vulnerator-mcp` streamable-HTTP server. By default it publishes **no** host port (internal docker network only). Set this **and** uncomment the service's `ports:` block in `docker-compose.yml` to publish on a controlled machine. |The rest of the `.env.example` variables (host ports, artifacts token, Prowlerscoping) are optional and come with defaults; leave them empty unless you need to@@ -333,10 +340,14 @@ scope rests entirely with the operator.## Consume Hermes from an MCP client (`vulnerator-mcp`)If your tooling speaks **MCP** rather than raw HTTP (Claude Code, Kiro, Cursor, BugTraceAI, …),-there is an OPTIONAL thin MCP server — **`vulnerator-mcp`** (`docker/mcp/`) — that wraps Hermes'+the stack ships a thin MCP server — **`vulnerator-mcp`** (`docker/mcp/`) — that wraps Hermes'`:8642` runs API and exposes it as MCP tools. It wraps, it does **not** replace, the HTTP API: itexposes **only** the runs lifecycle, so the client stays a trigger/observer and never the brain.+It runs in **two modes**: a **streamable-HTTP** service that is **up by default** with the stack+(for in-docker consumers like BugTraceAI, and for host-published use), and a **stdio** mode that+**local** Claude Code / Kiro spawn as a subprocess (recommended locally; zero network surface).+Five tools + a health check, mapped 1:1 onto `:8642`:| Tool | Does |@@ -394,28 +405,28 @@ entry (copy-paste; the stdio process reaches the host-published `:8642` viaThe upstream Bearer is a **pass-through** of `HERMES_API_SERVER_KEY` (no second secret is mintedfor the `:8642` hop).-### In-docker / remote: streamable-HTTP (optional layered service)+### In-docker / remote: streamable-HTTP (up by default)-For an in-docker consumer (e.g. a BugTraceAI container on the same network) or a remote-orchestrator, bring up the OPTIONAL layered service — it is **not** in the default stack:+The streamable-HTTP service is part of the **default** stack, so a plain```sh# requires VULNERATOR_MCP_INBOUND_TOKEN in .env (generate: openssl rand -hex 32)-docker compose -f docker-compose.yml -f docker-compose.mcp.yml up -d --build+docker compose up -d --build```-A plain `docker compose up` is unchanged (3 containers); this adds a 4th, `vulnerator-mcp`,-reachable on the internal network at `http://vulnerator-mcp:8700` (upstream Hermes at-`http://ooda-agent:8642`). Key properties:+brings it up as the 4th container, `vulnerator-mcp`, reachable on the internal network at+`http://vulnerator-mcp:8700` (upstream Hermes at `http://ooda-agent:8642`). An in-docker consumer+(e.g. a BugTraceAI container on the same network) reaches it there with no extra steps. Key+properties:- **Host publication is OFF by default.** The service declares no `ports:` block (internal- network only, like `playwright-mcp`/`juice-shop`). To publish on a **controlled** machine,- uncomment the `ports:` block in `docker-compose.mcp.yml` (optionally set- `VULNERATOR_MCP_HOST_PORT`).-- **Mandatory, fail-closed inbound token.** The streamable-HTTP mode refuses to start without- `VULNERATOR_MCP_INBOUND_TOKEN`, and every request must carry- `Authorization: Bearer <VULNERATOR_MCP_INBOUND_TOKEN>` (a dedicated `/healthz` route is the one- exact-match exception). This token is **separate** from `HERMES_API_SERVER_KEY`.+ network only, like `playwright-mcp`/`juice-shop`), so by default nothing is exposed to the+ host. To publish on a **controlled** machine, set `VULNERATOR_MCP_HOST_PORT` in `.env` **and**+ uncomment the `ports:` block of the `vulnerator-mcp` service in `docker-compose.yml`.+- **Mandatory, fail-closed inbound token.** The default stack refuses to start without+ `VULNERATOR_MCP_INBOUND_TOKEN` (compose `:?` guard + an in-process guard), and every request+ must carry `Authorization: Bearer <VULNERATOR_MCP_INBOUND_TOKEN>` (a dedicated `/healthz` route+ is the one exact-match exception). This token is **separate** from `HERMES_API_SERVER_KEY`.- **Threat model (read this).** The inbound token gates only the *clients → vulnerator-mcp* edge.It does **not** re-protect the pre-existing `:8642` host exposure, which stays under its own`HERMES_API_SERVER_KEY` Bearer (see "Security note" above). Publishing the MCP port is andiff --git a/docker-compose.mcp.yml b/docker-compose.mcp.ymldeleted file mode 100644index 894f784..0000000--- a/docker-compose.mcp.yml+++ /dev/null@@ -1,73 +0,0 @@-# =============================================================================-# docker-compose.mcp.yml — OPTIONAL MCP front door over Hermes' :8642 runs API.-# =============================================================================-# OPTIONAL layered override, NOT part of the base stack (docker-compose.yml). Bring it up-# explicitly alongside the base to expose a thin MCP server (vulnerator-mcp) that external-# MCP clients (Claude Code / Kiro / BugTraceAI) can use to trigger/observe/steer/stop a-# Hermes OODA pentest as MCP tools:-#-# docker compose -f docker-compose.yml -f docker-compose.mcp.yml up -d --build-#-# A plain `docker compose up` is UNCHANGED (3 containers: kali, ooda-agent, playwright-mcp).-# This file adds a 4th container only when brought up explicitly. The service lives on the-# SAME internal docker network: it reaches Hermes at http://ooda-agent:8642, and in-docker-# MCP consumers reach it at http://vulnerator-mcp:8700 (service DNS).-#-# It wraps, does NOT replace, the HTTP API: it exposes ONLY the runs lifecycle (no raw-# kali_run, no /v1/chat/completions) so the client stays a trigger/observer, never the brain.-#-# SECURITY (read this): this service is FAIL-CLOSED on VULNERATOR_MCP_INBOUND_TOKEN — it will-# NOT start without it (both at the compose `:?` level below and inside the server). That-# token gates the clients -> vulnerator-mcp edge ONLY; it is a SEPARATE token from-# HERMES_API_SERVER_KEY and does NOT re-protect the pre-existing :8642 host exposure (which-# stays under its own Bearer). By default NO host port is published (internal network only).-# This MCP layer adds REACHABILITY, not safety: the engine has no scope-guard/consent/audit.--services:- vulnerator-mcp:- build:- context: .- dockerfile: docker/mcp/Dockerfile- platforms:- - linux/arm64- - linux/amd64- image: vulnerator-ai-mcp:dev- environment:- # Hop upstream a Hermes por DNS de servicio (red interna docker).- HERMES_API_BASE_URL: "http://ooda-agent:8642"- # Bearer de PASS-THROUGH upstream — fail-closed `:?` como el ooda-agent base.- 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}"- # Token de ENTRADA (clientes -> vulnerator-mcp). REQUERIDO, fail-closed `:?`: traer este- # archivo sin token aborta con mensaje claro (defensa en profundidad: compose + proceso).- # Separado de HERMES_API_SERVER_KEY (gatea otra frontera). Solo necesario para ESTE- # servicio opt-in; el stack base de 3 contenedores no lo referencia.- VULNERATOR_MCP_INBOUND_TOKEN: "${VULNERATOR_MCP_INBOUND_TOKEN:?Falta VULNERATOR_MCP_INBOUND_TOKEN - genera uno con 'openssl rand -hex 32' y ponlo en .env (lo exige el servicio MCP streamable-http)}"- VULNERATOR_MCP_TRANSPORT: "streamable-http"- # Bind DENTRO del contenedor (no es una publicacion al host).- VULNERATOR_MCP_HOST: "0.0.0.0"- VULNERATOR_MCP_PORT: "8700"- # Host publication is OPT-IN and OFF by default: with NO ports: block the service is- # reachable ONLY on the internal docker network (http://vulnerator-mcp:8700), exactly- # like playwright-mcp/juice-shop. To publish on a CONTROLLED machine, UNCOMMENT the block- # below (set VULNERATOR_MCP_HOST_PORT in .env or accept the 8700 default). Publishing- # exposes the no-guardrails engine's trigger API to the host — do it deliberately and keep- # the inbound token secret. (Do NOT use ":8700": that publishes on a RANDOM host port.)- # ports:- # - "${VULNERATOR_MCP_HOST_PORT:-8700}:8700"- depends_on:- # service_started (implicito): el ooda-agent base NO define healthcheck, asi que- # service_healthy no es usable contra el. La readiness se maneja en la capa de tools:- # cada tool devuelve upstream_unreachable hasta que Hermes esta vivo, asi que este- # servidor puede arrancar antes de que Hermes termine de bootear sin romperse. NO- # subir esto a service_healthy.- - ooda-agent- restart: unless-stopped- # HEALTHCHECK: stdlib python (python:3.13-slim no trae curl) sondeando la ruta DEDICADA- # /healthz, que el middleware de auth deja abierta con un carve-out de match exacto (no- # necesita el token). "/" es el endpoint MCP y SI requiere token.- healthcheck:- test: ["CMD", "python3", "-c", "import sys,os,urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:%s/healthz' % os.environ.get('VULNERATOR_MCP_PORT','8700'), timeout=3).status==200 else 1)"]- interval: 15s- timeout: 5s- retries: 5- start_period: 20sdiff --git a/docker-compose.yml b/docker-compose.ymlindex 544c89d..5690426 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -251,6 +251,69 @@ services:# NO ports section: the browser MCP is NOT published to the host; internal docker network only.restart: unless-stopped+ vulnerator-mcp:+ # 4th container (DEFAULT): a thin MCP front door over Hermes' :8642 runs API so external+ # MCP clients (Claude Code / Kiro / BugTraceAI) can trigger/observe/steer/stop a pentest+ # as MCP tools. It is UP BY DEFAULT because the product's intended UX is driving the engine+ # from an MCP client. It wraps, does NOT replace, the HTTP API: it exposes ONLY the runs+ # lifecycle (no raw kali_run, no /v1/chat/completions) so the client stays a trigger/observer,+ # never the brain.+ #+ # SECURITY: this service is FAIL-CLOSED on VULNERATOR_MCP_INBOUND_TOKEN — it will NOT start+ # without it (both at the compose `:?` level below and inside the server). That token gates+ # the clients -> vulnerator-mcp edge ONLY; it is a SEPARATE token from HERMES_API_SERVER_KEY+ # and does NOT re-protect the pre-existing :8642 host exposure (which stays under its own+ # Bearer). By default NO host port is published (internal docker network only, like+ # playwright-mcp). This MCP layer adds REACHABILITY, not safety: the engine has no+ # scope-guard/consent/audit. For LOCAL Claude Code / Kiro the RECOMMENDED path is the stdio+ # mode (zero network surface, no token) via `docker run -i` — see README; this default-up+ # service is the streamable-http front door for in-docker consumers and host-published use.+ build:+ context: .+ dockerfile: docker/mcp/Dockerfile+ platforms:+ - linux/arm64+ - linux/amd64+ image: vulnerator-ai-mcp:dev+ environment:+ # Upstream hop to Hermes by service DNS (internal docker network).+ HERMES_API_BASE_URL: "http://ooda-agent:8642"+ # Upstream PASS-THROUGH Bearer — fail-closed `:?` like the base ooda-agent.+ 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}"+ # INBOUND token (clients -> vulnerator-mcp). REQUIRED, fail-closed `:?`: bringing the+ # default stack up without it aborts with a clear message (defense in depth: compose ++ # process). SEPARATE from HERMES_API_SERVER_KEY (gates a different edge). stdio mode does+ # NOT need it, but the default-up streamable-http service does.+ VULNERATOR_MCP_INBOUND_TOKEN: "${VULNERATOR_MCP_INBOUND_TOKEN:?Falta VULNERATOR_MCP_INBOUND_TOKEN - genera uno con 'openssl rand -hex 32' y ponlo en .env (lo exige el servicio MCP streamable-http, que viene levantado por defecto)}"+ VULNERATOR_MCP_TRANSPORT: "streamable-http"+ # Bind INSIDE the container (not a host publication).+ VULNERATOR_MCP_HOST: "0.0.0.0"+ VULNERATOR_MCP_PORT: "8700"+ # Host publication is OPT-IN and OFF by default: with NO ports: block the service is+ # reachable ONLY on the internal docker network (http://vulnerator-mcp:8700), exactly like+ # playwright-mcp/juice-shop. To publish on a CONTROLLED machine, UNCOMMENT the block below+ # (optionally set VULNERATOR_MCP_HOST_PORT in .env; empty => the 8700 default). Publishing+ # exposes the no-guardrails engine's trigger API to the host — do it deliberately and keep+ # the inbound token secret. (Do NOT use ":8700": that publishes on a RANDOM host port.)+ # ports:+ # - "${VULNERATOR_MCP_HOST_PORT:-8700}:8700"+ depends_on:+ # service_started (implicit): the base ooda-agent defines NO healthcheck, so+ # service_healthy is not usable against it. Readiness is handled at the tool layer: every+ # tool returns upstream_unreachable until Hermes is live, so this server can start before+ # Hermes finishes booting without crashing. Do NOT upgrade this to service_healthy.+ - ooda-agent+ restart: unless-stopped+ # HEALTHCHECK: stdlib python (python:3.13-slim ships no curl) probing the DEDICATED /healthz+ # route, which the auth middleware leaves open with an exact-match carve-out (no token+ # needed). "/" is the MCP endpoint and DOES require the token.+ healthcheck:+ test: ["CMD", "python3", "-c", "import sys,os,urllib.request; sys.exit(0 if urllib.request.urlopen('http://127.0.0.1:%s/healthz' % os.environ.get('VULNERATOR_MCP_PORT','8700'), timeout=3).status==200 else 1)"]+ interval: 15s+ timeout: 5s+ retries: 5+ start_period: 20s+volumes:# Hermes state (profile + SQLite WAL). NAMED on purpose: avoids the bind-mount# that corrupts the SQLite WAL on macOS virtiofs.diff --git a/docker/mcp/Dockerfile b/docker/mcp/Dockerfileindex 55c9922..70e89b4 100644--- a/docker/mcp/Dockerfile+++ b/docker/mcp/Dockerfile@@ -2,7 +2,7 @@## UNA imagen, DOS modos de ejecucion (los selecciona entrypoint.sh):# - stdio (default) : el cliente arranca el proceso (docker run -i). Superficie cero.-# - streamable-http : servicio opt-in (docker-compose.mcp.yml), fail-closed en el+# - streamable-http : servicio por defecto (docker-compose.yml), fail-closed en el# token de entrada VULNERATOR_MCP_INBOUND_TOKEN.## Multi-arch (linux/arm64 + linux/amd64). Base python:3.13-slim (NO Kali): este componentediff --git a/docker/mcp/vulnerator_mcp_server.py b/docker/mcp/vulnerator_mcp_server.pyindex fd09bdc..51a7695 100644--- a/docker/mcp/vulnerator_mcp_server.py+++ b/docker/mcp/vulnerator_mcp_server.py@@ -25,7 +25,7 @@ Transportes (uno/una imagen, dos modos, design §6):token, sin puerto). El cliente arranca el proceso (``docker run -i``).- streamable-http: para consumidores in-docker/remotos. FAIL-CLOSED en el token de entrada(``VULNERATOR_MCP_INBOUND_TOKEN``): NO arranca sin él. Bind interno a la red docker; sin- publicación al host por defecto (ver docker-compose.mcp.yml).+ publicación al host por defecto (ver el servicio vulnerator-mcp en docker-compose.yml)."""from __future__ import annotationsdiff --git a/docs/architecture.svg b/docs/architecture.svgindex 8f2ee76..cac8ac7 100644--- a/docs/architecture.svg+++ b/docs/architecture.svg@@ -45,7 +45,7 @@<text x="40" y="84" fill="#8a8a8a" font-size="13" letter-spacing="2">SYSTEM ARCHITECTURE · OODA pentest driven by Hermes · piloted over HTTP from an external assistant</text><text x="40" y="104" fill="#5a5a5a" font-size="11" letter-spacing="1">- no core · no REST facade · no UI · no scope-gate — the agent drives tools over MCP (an OPTIONAL MCP front door is available)</text>+ no core · no REST facade · no UI · no scope-gate — the agent drives tools over MCP (an MCP front door ships by default)</text><line x1="40" y1="116" x2="1440" y2="116" stroke="#2f2f2f" stroke-width="1"/><!-- ===================== OPERATOR COLUMN ===================== -->@@ -200,11 +200,11 @@<text x="930" y="832" fill="#b03a3a" font-size="9" text-anchor="middle">"which tactic comes next?"</text><path d="M930,836 L930,842" fill="none" stroke="#b03a3a" stroke-width="1.3" marker-end="url(#aLoop)"/>- <!-- ===================== VULNERATOR-MCP (OPTIONAL overlay front door) ===================== -->- <rect x="36" y="800" width="638" height="150" rx="6" fill="#0a0a0a" stroke="#6a6a6a" stroke-width="1.4" stroke-dasharray="7 5"/>- <text x="54" y="826" fill="#cfcfcf" font-size="13.5" font-weight="700" letter-spacing="1">[∞] VULNERATOR-MCP — OPTIONAL MCP FRONT DOOR (overlay)</text>- <text x="54" y="844" fill="#8a8a8a" font-size="10">docker-compose.mcp.yml · NOT in the default stack · wraps the :8642 runs API as MCP tools</text>- <rect x="54" y="856" width="602" height="54" rx="4" fill="#101010" stroke="#6a6a6a" stroke-width="1.2" stroke-dasharray="7 5"/>+ <!-- ===================== VULNERATOR-MCP (default MCP front door) ===================== -->+ <rect x="36" y="800" width="638" height="150" rx="6" fill="#0a0a0a" stroke="#9a9a9a" stroke-width="1.6"/>+ <text x="54" y="826" fill="#f2f2f2" font-size="13.5" font-weight="700" letter-spacing="1">[∞] VULNERATOR-MCP — MCP FRONT DOOR (4th container, default)</text>+ <text x="54" y="844" fill="#8a8a8a" font-size="10">in docker-compose.yml · up by default · wraps the :8642 runs API as MCP tools</text>+ <rect x="54" y="856" width="602" height="54" rx="4" fill="#101010" stroke="#9a9a9a" stroke-width="1.3"/><text x="70" y="878" fill="#e8e8e8" font-size="12" font-weight="700">[∞] streamable-HTTP · :8700 (internal; no host port by default)</text><text x="70" y="896" fill="#8a8a8a" font-size="9.5">trigger / observe / steer / stop ONLY · no raw kali_run · mandatory inbound Bearer (fail-closed)</text><text x="54" y="930" fill="#6a6a6a" font-size="9">stdio mode for local Claude Code / Kiro (zero network surface, no token) · two tokens / two trust boundaries</text>@@ -260,7 +260,7 @@<text x="54" y="644" fill="#cfcfcf" font-size="9.5">:8900 kali-mcp</text><text x="54" y="660" fill="#cfcfcf" font-size="9.5">:8901 artifacts data-plane</text><text x="54" y="675" fill="#7f8c8d" font-size="9">:8931 playwright (internal only)</text>- <text x="54" y="689" fill="#7f8c8d" font-size="9">:8700 vulnerator-mcp (OPTIONAL; internal only)</text>+ <text x="54" y="689" fill="#7f8c8d" font-size="9">:8700 vulnerator-mcp (default; internal only)</text><line x1="54" y1="700" x2="286" y2="700" stroke="#2f2f2f"/><text x="54" y="717" fill="#8a8a8a" font-size="9">assistant triggers · Hermes reasons the OODA</text>