Skip to content

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

feat: bring vulnerator-mcp up by default (4-container stack)

irraza89e2ca37073
diff --git a/.env.example b/.env.example
index 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.md
index 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 thin
FastMCP wrapper (`docker/mcp/`) that lets external MCP clients (Claude Code / Kiro locally
over 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.0
from `GET /health` and reported verbatim, never branched on. `stream_run_events` uses the
event `seq` as a portable cursor (batched pages with `next_cursor`/`done`) and additionally
emits 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 request
without the matching `Authorization: Bearer` (constant-time compare), with an exact-match
carve-out for a dedicated `/healthz` route only. The same image also runs stdio for local
diff --git a/README.md b/README.md
index 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 what
to 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)
-![Vulnerator AI system architecture: an external assistant (Kiro/Claude) triggers and observes Hermes over HTTP (:8642, Bearer); Hermes is the OODA brain, reasoning with mistralai/mistral-large on OpenRouter and driving the kali-mcp (:8900) and playwright-mcp (:8931) servers over MCP; kali runs the pentest tools against the authorized target. ATT&CK is the Orient language of the loop.](docs/architecture.svg)
+![Vulnerator AI system architecture: an MCP client (Claude Code / Kiro / BugTraceAI) drives a pentest THROUGH the vulnerator-mcp front door (MCP, :8700 internal), which forwards to Hermes' :8642 runs API over HTTP Bearer; an external assistant can still trigger/observe Hermes directly over :8642. Hermes is the OODA brain, reasoning with mistralai/mistral-large on OpenRouter and driving the kali-mcp (:8900) and playwright-mcp (:8931) servers over MCP; kali runs the pentest tools against the authorized target. ATT&CK is the Orient language of the loop.](docs/architecture.svg)
- **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 cloud
collection 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, Prowler
scoping) 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: it
exposes **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` via
The upstream Bearer is a **pass-through** of `HERMES_API_SERVER_KEY` (no second secret is minted
for 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 an
diff --git a/docker-compose.mcp.yml b/docker-compose.mcp.yml
deleted file mode 100644
index 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: 20s
diff --git a/docker-compose.yml b/docker-compose.yml
index 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/Dockerfile
index 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 componente
diff --git a/docker/mcp/vulnerator_mcp_server.py b/docker/mcp/vulnerator_mcp_server.py
index 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 annotations
diff --git a/docs/architecture.svg b/docs/architecture.svg
index 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 &#183; OODA pentest driven by Hermes &#183; piloted over HTTP from an external assistant</text>
<text x="40" y="104" fill="#5a5a5a" font-size="11" letter-spacing="1">
- no core &#183; no REST facade &#183; no UI &#183; no scope-gate &#8212; the agent drives tools over MCP (an OPTIONAL MCP front door is available)</text>
+ no core &#183; no REST facade &#183; no UI &#183; no scope-gate &#8212; 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">[&#8734;] VULNERATOR-MCP &#8212; OPTIONAL MCP FRONT DOOR (overlay)</text>
- <text x="54" y="844" fill="#8a8a8a" font-size="10">docker-compose.mcp.yml &#183; NOT in the default stack &#183; 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">[&#8734;] VULNERATOR-MCP &#8212; MCP FRONT DOOR (4th container, default)</text>
+ <text x="54" y="844" fill="#8a8a8a" font-size="10">in docker-compose.yml &#183; up by default &#183; 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">[&#8734;] streamable-HTTP &#183; :8700 (internal; no host port by default)</text>
<text x="70" y="896" fill="#8a8a8a" font-size="9.5">trigger / observe / steer / stop ONLY &#183; no raw kali_run &#183; 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) &#183; 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 &#183; Hermes reasons the OODA</text>