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
# =============================================================================
# vulnerator-ai — OODA pentest with Hermes talking DIRECTLY to Kali-MCP.
# =============================================================================
# What it is: an OODA pentest loop driven by Hermes (nousresearch/hermes-agent)
# that runs tools DIRECTLY via MCP servers (no intermediate core/API/UI):
# - kali : deterministic pentest tool runtime (kali-mcp on :8900).
# - playwright-mcp : real browser (headless Chromium) over MCP (:8931) for the web part.
# - ooda-agent : Hermes as the BRAIN driving the OODA loop, client of both MCPs
# (kali:8900, playwright-mcp:8931). OODA driver, no intermediaries.
#
# Startup:
# cp .env.example .env # and fill in OPENROUTER_API_KEY and HERMES_API_SERVER_KEY
# docker compose up -d --build
# docker compose exec -it ooda-agent hermes chat # interactive TUI
#
# WARNING (intentional): this product has NO scope-guard, consent, or
# audit. Hermes runs whatever it decides directly against the target, with no gatekeeper
# validating the scope. Use it ONLY against explicitly authorized targets and in a
# controlled environment. Responsibility for the scope rests entirely with the operator.
#
# Multi-arch: each build declares platforms [linux/arm64, linux/amd64]. On a Mac M2
# it runs arm64 natively.
services:
kali:
build:
context: .
dockerfile: docker/kali/Dockerfile
platforms:
- linux/arm64
- linux/amd64
image: vulnerator-ai-kali:dev
environment:
# --- AWS read-only (OPTIONAL in this product) ---
# Prowler/ScoutSuite/Cloudsplaining run INSIDE this container. If you are going
# to use the cloud collection tools, set these credentials in .env; otherwise
# they stay empty and the cloud tools simply won't have anything to authenticate with.
AWS_ACCESS_KEY_ID: "${AWS_ACCESS_KEY_ID:-}"
AWS_SECRET_ACCESS_KEY: "${AWS_SECRET_ACCESS_KEY:-}"
# Optional: only for temporary credentials (STS).
AWS_SESSION_TOKEN: "${AWS_SESSION_TOKEN:-}"
AWS_REGION: "${AWS_REGION:-us-east-1}"
# kali-mcp server port inside the container. Overridable without rebuilding.
KALI_MCP_PORT: "8900"
# --- Artifacts DATA plane (dedicated port, internal network) ---
KALI_ARTIFACTS_PORT: "8901"
# Shared token for the data channel (optional in this product).
KALI_ARTIFACTS_TOKEN: "${KALI_ARTIFACTS_TOKEN:-}"
# --- Prowler (optional): scopes the cloud scan if used ---
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}"
# --- Recon / fingerprint APIs (optional) ---
# DNSDumpster API key for the `dns_recon` tool; WPScan token for `webtech_scan`
# (optional: enables CVE data). Both empty = those tools run without them
# (dns_recon fails fail-closed without a key; webtech_scan still enumerates).
DNSDUMPSTER_API_KEY: "${DNSDUMPSTER_API_KEY:-}"
WPSCAN_API_TOKEN: "${WPSCAN_API_TOKEN:-}"
# --- Scope-guard (OPT-IN, off by default) ---
# The scope-guard validates the DESTINATION of kali_run/kali_exec BEFORE executing,
# deterministically (code, not prompt). It activates ONLY if a scope file exists at
# SCOPE_FILE and contains `enabled: true` (see the commented volume below and
# scope.example.json). Without that file, behavior is IDENTICAL to today (no gate).
# SCOPE_FILE: path INSIDE the container where the guard looks for the scope (default
# /scope/scope.json). SCOPE_ENFORCE: kill-switch — set to "0" to force-DISABLE the
# guard even if the file says enabled:true (leave empty to honor the file).
SCOPE_FILE: "${SCOPE_FILE:-/scope/scope.json}"
SCOPE_ENFORCE: "${SCOPE_ENFORCE:-}"
# --- Caido (toolkit web: proxy + Replay + HTTPQL + scope + workflows) ---
# kali-mcp habla la API GraphQL de Caido para las tools caido_graphql/caido_request/
# caido_history (ver docs/caido.md). El servicio `caido` (abajo) vive en la MISMA red
# interna: se alcanza por DNS en http://caido:8080 (NO publicado al host). ZERO-TOUCH: el
# servicio arranca con --allow-guests y caido_client inicia sesión como invitado y elige/
# crea un proyecto solo, así que NO hace falta token. CAIDO_PAT/CAIDO_ACCESS_TOKEN son
# OPCIONALES (Caido sin --allow-guests, o externo); CAIDO_ALLOW_GUEST=0 fuerza exigirlos.
# Sin credenciales válidas las tools devuelven `unauthenticated` (no se finge).
CAIDO_URL: "${CAIDO_URL:-http://caido:8080}"
CAIDO_PAT: "${CAIDO_PAT:-}"
CAIDO_ACCESS_TOKEN: "${CAIDO_ACCESS_TOKEN:-}"
CAIDO_ALLOW_GUEST: "${CAIDO_ALLOW_GUEST:-1}"
# Captura por proxy OPT-IN: a "1" el arranque de kali-mcp baja la CA de Caido y enruta el
# tráfico HTTP de kali_run (curl/nuclei/ffuf/sqlmap/wget) por el proxy de Caido, para que
# quede en su historial; HTTPS incluido al confiar en la CA. Vacío/0 = off (comportamiento
# de siempre). Sólo clientes que respetan HTTP(S)_PROXY; nmap/masscan (socket crudo) no.
CAIDO_PROXY_CAPTURE: "${CAIDO_PROXY_CAPTURE:-}"
# Tuning (empty = built-in default): per-HTTP-call timeout in seconds (60), cap in bytes
# of the response body returned by caido_request (20000), and the name of the project
# created when the instance has none ("vulnerator").
CAIDO_TIMEOUT: "${CAIDO_TIMEOUT:-}"
CAIDO_MAX_RESPONSE_BYTES: "${CAIDO_MAX_RESPONSE_BYTES:-}"
CAIDO_PROJECT: "${CAIDO_PROJECT:-}"
# Scope-guard mount (OPT-IN): to turn the guard ON, create a `scope.json` at the repo
# root (copy scope.example.json), set `enabled: true`, and UNCOMMENT the mount line
# below (under this same volumes: block), then recreate the kali service. Keep it
# commented for the default "no gate" behavior. Create the file BEFORE `docker compose up`
# so Docker bind-mounts a file (not a dir).
volumes:
# Artifacts plane: /artifacts holds the staged raw output served over the data channel
# (KALI_ARTIFACTS_DIR). A NAMED volume makes it persist across container recreations;
# additive, nothing else changes. A plugin can declare it needs this via needs_volume().
- kali-artifacts:/artifacts
# - ./scope.json:/scope/scope.json:ro
# kali-mcp server port (exposed for direct inspection from the host if
# needed; ooda-agent reaches it over the internal network as kali:8900). The host
# port is configurable with KALI_MCP_HOST_PORT (default 8900) without editing this file;
# the container's internal port stays 8900.
ports:
- "${KALI_MCP_HOST_PORT:-8900}:8900"
# HEALTHCHECK: checks that the MCP server accepts TCP connections on :8900, so that
# ooda-agent can depend on it with condition: service_healthy before starting.
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:
# Official registry image (NOT built from this repo).
image: nousresearch/hermes-agent
# Startup ("default profile" model): recreates the DEFAULT profile (/opt/data) by copying
# the repo's declarative template (read-only bind-mount at /opt/profile-src),
# injects the API server key and starts the gateway in the foreground. 'hermes gateway
# run' keeps the container ALIVE and starts platforms.api_server (:8642, published to the
# host via the 'ports:' block below to drive Hermes from an external assistant).
command:
- sh
- -c
- |
set -e
# The DEFAULT profile is the root home /opt/data (not /opt/data/profiles/<p>).
DEF=/opt/data
# (a) copy the declarative template (config/SOUL/skills/skins) to the default profile home.
mkdir -p "$$DEF/skills" "$$DEF/skins"
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
# (a2) PLUGIN SKILLS (SHIELDED). Copy each live plugin's skill/ (bind-mounted at
# /opt/plugins) into the default profile's skills/, under a dir named after the plugin.
# INVARIANT: nothing here may trip `set -e` or abort Hermes startup — the whole block
# is gated on the dir existing and runs inside a `set +e` subshell with per-statement
# guards. A plugin dir ending in .disabled is skipped (SAME suffix as the Python loader,
# plugin_api.DISABLED_SUFFIX = ".disabled"; kept in sync by test_disabled_parity.py).
if [ -d /opt/plugins ]; then ( set +e; for d in /opt/plugins/*/; do [ -d "$$d" ] || continue; [ -d "$${d}skill" ] || continue; name="$$(basename "$$d")"; case "$$name" in *.disabled) continue ;; esac; mkdir -p "$$DEF/skills/$$name" 2>/dev/null || { echo "[plugins] skip $$name (mkdir)"; continue; }; cp -r "$${d}skill/." "$$DEF/skills/$$name/" 2>/dev/null || echo "[plugins] skip $$name (cp)"; done ); fi
# Copy custom skin(s) so Hermes skin_engine finds them under <hermes_home>/skins/.
cp -r /opt/profile-src/profile/skins/. "$$DEF/skins/" 2>/dev/null || true
# (b) inject the API server KEY (secret, not versioned) BEFORE starting.
hermes config set platforms.api_server.key "$$HERMES_API_SERVER_KEY" >/dev/null
# (b1.5) FALLBACK PROVIDERS: apply from config.yaml's fallback_providers section
hermes config set fallback_providers '[{"provider": "openrouter", "model": "z-ai/glm-5.3-flash"}]' >/dev/null
# (b2) LLM PROVIDER SELECTION (opt-in, fallback = OpenRouter):
if [ -n "$$OLLAMA_BASE_URL" ]; then
# --- Ollama mode -------------------------------------------------------
# OLLAMA_BASE_URL is set => point Hermes at a local/remote Ollama endpoint
# (OpenAI-compatible). OPENROUTER_API_KEY is NOT required in this branch.
# Hermes reaches the endpoint via the generic OpenAI-compatible "custom"
# provider: provider=custom + model.base_url (confirmed key names against the
# nousresearch/hermes-agent image: `hermes config set model.provider|base_url|default`).
hermes config set model.provider custom >/dev/null
hermes config set model.base_url "$$OLLAMA_BASE_URL" >/dev/null
# Ollama model name (only if provided; otherwise the profile default is kept,
# though for Ollama you normally want an Ollama-served model name here).
if [ -n "$$OLLAMA_MODEL" ]; then
hermes config set model.default "$$OLLAMA_MODEL" >/dev/null
else
# D1 warning (non-fatal): no OLLAMA_MODEL set, so the profile default model NAME
# (mistralai/mistral-large-4-0) is now pointed at the Ollama endpoint, which almost
# certainly does NOT serve a model by that name. Warn but DO NOT abort: the operator
# most likely wants to set OLLAMA_MODEL to an Ollama-served model name.
echo "WARNING: OLLAMA_BASE_URL is set but OLLAMA_MODEL is empty. The profile default model name (mistralai/mistral-large-4-0) will be used against the Ollama endpoint, which probably does not serve it. Set OLLAMA_MODEL to an Ollama-served model name (e.g. qwen2.5-coder:32b)." >&2
fi
else
# --- OpenRouter mode (default, OLLAMA_BASE_URL empty) ------------------
# Preserve EXACTLY today's v1.0.1 behavior. The compose var no longer uses the
# fail-closed `:?` form (so Ollama mode can boot without a key), so re-create the
# fail-closed guarantee here: a missing OPENROUTER_API_KEY aborts with non-zero exit.
if [ -z "$$OPENROUTER_API_KEY" ]; then
echo "ERROR: OPENROUTER_API_KEY is empty. Set it in .env (OpenRouter mode) or set OLLAMA_BASE_URL to use Ollama instead." >&2
exit 1
fi
# OPTIONAL model override: if OPENROUTER_MODEL is set and non-empty, override
# model.default at runtime. If empty/unset, do nothing so the profile's model.default
# (mistralai/mistral-large-4-0) is used as-is (fallback).
if [ -n "$$OPENROUTER_MODEL" ]; then
hermes config set model.default "$$OPENROUTER_MODEL" >/dev/null
fi
fi
# (c) print a custom Vulnerator startup banner before handing off to the gateway.
printf '\033[1;31m┌────────────────────────────────────────────────────────────┐\033[0m\n'
printf '\033[1;31m│\033[0m \033[1;32m⚡ VULNERATOR-AI — OODA Pentest Engine\033[0m \033[1;31m│\033[0m\n'
printf '\033[1;31m│\033[0m \033[2;37mkali-mcp · playwright-mcp · vulnerator-mcp\033[0m \033[1;31m│\033[0m\n'
printf '\033[1;31m└────────────────────────────────────────────────────────────┘\033[0m\n'
# (c2) brand the default profile as "Vulnerator" (display name; canonical id stays
# 'default') and install + select its pet (petdex gat-reaper) so both survive
# rebuilds and a clean volume. Non-fatal: a transient petdex/network hiccup must
# NOT abort container startup, hence the '|| true'.
hermes profile rename default Vulnerator >/dev/null 2>&1 || true
hermes pets install gat-reaper --select >/dev/null 2>&1 || true
# (d) start the default profile gateway: foreground (live container) + API server.
exec hermes gateway run
environment:
# --- Hermes Web Dashboard (OPT-IN via HERMES_DASHBOARD=1) -------------------
# The s6-managed dashboard service only starts when HERMES_DASHBOARD is truthy.
# Auth for non-loopback binding is provided via basic auth env vars.
# Credentials default to admin/vulnerator; override in .env if needed.
HERMES_DASHBOARD: "1"
HERMES_DASHBOARD_HOST: "0.0.0.0"
HERMES_DASHBOARD_PORT: "9119"
HERMES_DASHBOARD_BASIC_AUTH_USERNAME: "${HERMES_DASHBOARD_USER:-admin}"
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: "${HERMES_DASHBOARD_PASSWORD:-vulnerator}"
# Hermes API server key — required (fail-closed): min 8 chars. TWO paths are
# needed: the command writes it into platforms.api_server.key (to start the
# API server) and API_SERVER_KEY validates it on every request (to authenticate the 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 for Hermes' LLM provider. Hermes reads the LLM key from THIS env var
# (OPENROUTER_API_KEY), which is why HERMES_LLM_API_KEY is NOT declared. NO LONGER
# fail-closed at the compose level (`:-` default), so the stack can boot in Ollama mode
# without an OpenRouter key. The fail-closed guarantee is re-created IN the startup script:
# when OLLAMA_BASE_URL is empty (OpenRouter mode) an empty OPENROUTER_API_KEY aborts startup.
OPENROUTER_API_KEY: "${OPENROUTER_API_KEY:-}"
# OPTIONAL OpenRouter model override (NOT fail-closed): empty default. When set and
# non-empty, the startup command runs 'hermes config set model.default' to override the
# profile's model.default; when empty/unset, the profile default is used (fallback).
OPENROUTER_MODEL: "${OPENROUTER_MODEL:-}"
# --- Local/remote Ollama inference (OPTIONAL, opt-in) ---
# OLLAMA_BASE_URL: empty/unset => use OpenRouter (default, unchanged). Set to an Ollama
# OpenAI-compatible endpoint (local http://host.docker.internal:11434/v1, or a remote
# http://<host>:11434/v1) to make Hermes use Ollama instead; OPENROUTER_API_KEY is then
# not required. The startup script branches on this var.
OLLAMA_BASE_URL: "${OLLAMA_BASE_URL:-}"
# OLLAMA_MODEL: the Ollama model name used when OLLAMA_BASE_URL is set (e.g. qwen2.5-coder:32b).
OLLAMA_MODEL: "${OLLAMA_MODEL:-}"
volumes:
# NAMED VOLUME REQUIRED (never a bind-mount): Hermes' state.db SQLite in WAL mode
# GETS CORRUPTED on bind-mounts that cross the macOS VM (virtiofs).
- hermes-data:/opt/data
# Declarative profile template, READ-ONLY and OUTSIDE /opt/data (does not touch the WAL).
- ./agent-ooda:/opt/profile-src:ro
# LIVE plugins tree, READ-ONLY, at /opt/plugins (DISTINCT from the Kali image's frozen
# /opt/kali-mcp/plugins). The command's shielded loop below copies each plugin's skill/
# into the Hermes profile, so activating a plugin's skill only needs an ooda-agent
# restart (no rebuild). See docs/plugins/discovery.md for the two-paths rule.
- ./plugins:/opt/plugins:ro
# Interactive TUI: 'docker compose exec -it ooda-agent hermes chat' needs stdin+tty.
stdin_open: true
tty: true
# Publishes Hermes' OpenAI-compatible API server (:8642) to the host so you can DRIVE
# Hermes from an external assistant (Kiro/Claude) over HTTP, without entering the TUI. The host
# port is configurable with HERMES_API_HOST_PORT (default 8642) without editing this file;
# the container's internal port stays 8642.
#
# SECURITY: publishing this port LOWERS the network barrier the stack had on purpose
# (before, :8642 was only reachable over the internal docker network). From here on the
# endpoint's protection is the HERMES_API_SERVER_KEY Bearer (same key from .env): use it
# ONLY on a controlled machine/environment. If you don't want to open the port, delete this
# 'ports:' block and drive Hermes with 'docker compose exec ooda-agent curl ...' (see README).
ports:
- "${HERMES_API_HOST_PORT:-8642}:8642"
# Web dashboard (hermes dashboard --host 0.0.0.0): started by the command block above.
# Configurable with HERMES_DASHBOARD_HOST_PORT in .env; default 9119.
- "${HERMES_DASHBOARD_HOST_PORT:-9119}:9119"
# Webapp — the Desktop workspace in a browser (config.yaml `webapp.enabled: true`, host
# 0.0.0.0, port 9120). Sign in with the dashboard account (admin / vulnerator). Requires
# Hermes >= 0.23 (the image is `latest`, which now resolves to 0.23.x). Configurable with
# HERMES_WEBAPP_HOST_PORT in .env; default 9120. SECURITY: a signed-in Webapp user can run
# commands as the account running the no-guardrails agent — keep this on a controlled host.
- "${HERMES_WEBAPP_HOST_PORT:-9120}:9120"
depends_on:
# Wait until kali is healthy (MCP listening) before starting.
kali:
condition: service_healthy
# Wait until the browser MCP is healthy before starting.
playwright-mcp:
condition: service_healthy
# host.docker.internal mapping so a host-run Ollama (OLLAMA_BASE_URL=http://host.docker.internal:11434/v1)
# is reachable on LINUX too (Docker Desktop on macOS/Windows resolves it automatically; the explicit
# host-gateway mapping is harmless there and makes the Linux host case work out of the box). Only
# relevant when using host Ollama; ignored otherwise.
extra_hosts:
- "host.docker.internal:host-gateway"
restart: unless-stopped
# Default compose network: reaches kali:8900 and playwright-mcp:8931 via internal DNS.
playwright-mcp:
# Second MCP server of the stack: real browser (headless Chromium) for the
# WEB part of the pentest. Official Microsoft image (NOT built from this repo).
# Hermes registers it as the `playwright` MCP (see agent-ooda/profile/config.yaml) and gains
# the `mcp_playwright_*` tools WITHOUT re-enabling any native toolset: it follows the
# "everything goes through MCP" principle. The web part is NOT limited to kali_run: nmap/whatweb/nuclei/
# ffuf/sqlmap go through the Kali (kali_run) and navigation/DOM/XSS go through this MCP.
image: mcr.microsoft.com/playwright/mcp
# HTTP (streamable-http) on :8931, MCP endpoint at /mcp. --no-sandbox: Chromium runs
# as root in the container without userns. --headless: no display. Internal network only.
entrypoint: ["node"]
command:
- /app/cli.js
- --headless
- --browser
- chromium
- --no-sandbox
- --port
- "8931"
- --host
- "0.0.0.0"
# Playwright server anti-DNS-rebinding protection: by default it ONLY accepts the
# host it is bound to (localhost), so it rejects Hermes' connection with 403,
# which arrives with the Host header `playwright-mcp:8931` (the service's internal DNS name).
# That host is EXPLICITLY allowed (not `*`): it keeps the protection scoped to the
# internal docker network, from which ooda-agent connects.
- --allowed-hosts
- "playwright-mcp:8931"
# IN-MEMORY browser profile (not persisted to disk). A persistent profile can ONLY
# be used by ONE instance at a time and LOCKS ("Browser is already in use ...") if
# an orphan Chrome process remains or there are concurrent calls; that left the
# mcp_playwright_* tools unusable mid-engagement. With --isolated each session starts its
# own ephemeral profile: no shared profile lock.
- --isolated
init: true
# HEALTHCHECK: the MCP endpoint responds on :8931 (a live process responds to the
# HTTP handshake), so that ooda-agent can depend on it with condition: service_healthy.
healthcheck:
test: ["CMD", "node", "-e", "require('http').get('http://127.0.0.1:8931/mcp',r=>process.exit(r.statusCode?0:1)).on('error',()=>process.exit(1))"]
interval: 10s
timeout: 5s
retries: 6
start_period: 20s
# 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
caido-init:
# One-shot: make the caido-data named volume writable by Caido's non-root user.
# Docker creates a NEW named volume root-owned, but the image runs as `caido` (uid/gid
# 996, checked with `id`), so without this Caido panics at startup with "Unable to create
# logging directory: Permission denied" (reproduced live). Uses the Caido image itself
# (already pulled; no extra image) overriding the user to root just for the chown.
image: "${CAIDO_IMAGE:-caido/caido:0.59.0}"
user: "0:0"
entrypoint: ["chown", "-R", "996:996", "/data"]
command: []
volumes:
- caido-data:/data
restart: "no"
caido:
# Caido — modern, Rust-powered web security toolkit (proxy + Replay + HTTPQL + scope +
# workflows + findings), the engine behind the caido_graphql/caido_request/caido_history
# tools in kali-mcp. Official image. It serves its GraphQL API (the one kali-mcp talks to)
# and the GUI on :8080. It lives on the SAME internal compose network, so kali reaches it
# by DNS as http://caido:8080. NO host port is published by default (internal network
# only, like playwright-mcp/juice-shop), which keeps the surface confined to the
# controlled environment; to reach the GUI from your machine, tunnel over SSH or
# temporarily uncomment the ports: block below on a controlled host.
#
# VERSION: pinned by default to 0.59.0, the release the caido_request/caido_history queries
# were verified against (Caido's GraphQL schema changes between releases; the caido_graphql
# passthrough is version-agnostic). Override with CAIDO_IMAGE in .env to try another tag.
image: "${CAIDO_IMAGE:-caido/caido:0.59.0}"
# The image's ENTRYPOINT is ["tini","--"] and its default CMD is the full
# `caido-cli --no-renderer-sandbox --no-open --listen 0.0.0.0:8080`. We restate that CMD
# explicitly (binary INCLUDED — overriding with just flags drops caido-cli and tini fails
# "exec --listen: No such file or directory") so a base-image change can't silently move
# the listener off the address kali-mcp expects. --no-renderer-sandbox/--no-open are
# required for headless (no GUI renderer, don't try to open a browser).
#
# --allow-guests is what makes the integration ZERO-TOUCH (verified live): without it a
# fresh instance only hands out tokens after a human logs into the GUI with a Caido
# account. With it, kali-mcp's caido_client calls the `loginAsGuest` GraphQL mutation and
# gets a working token headlessly.
#
# TRADE-OFF (read this): "not published to the host" is NOT isolation from the other
# services on this compose network. Any container on it — including a deliberately
# vulnerable lab target such as juice-shop/DVWA, or an SSRF in one — can reach
# http://caido:8080/graphql, call `loginAsGuest`, and obtain a full-privilege token (read
# all captured traffic, send arbitrary Replay requests). This is acceptable for a local lab
# and for engagements whose targets are EXTERNAL; if you put untrusted workloads on this
# network, drop --allow-guests, set CAIDO_ALLOW_GUEST=0 and use a CAIDO_PAT instead (mint it
# once via an SSH tunnel to the GUI). The same applies if you publish the port.
command:
- caido-cli
- --no-renderer-sandbox
- --no-open
- --allow-guests
# Caido's own anti-DNS-rebinding protection (same mechanism as playwright-mcp's
# --allowed-hosts above): by default it ONLY accepts requests whose Host matches
# localhost, so it rejects kali-mcp's calls with 403 ("Domain caido not allowed" in
# the logs — reproduced live), which arrive with Host: caido:8080 (the service's
# internal DNS name). That name is EXPLICITLY allowed (not a wildcard): it keeps the
# protection scoped to the internal docker network, from which kali connects.
- --ui-domain
- caido
- --listen
- 0.0.0.0:8080
depends_on:
caido-init:
condition: service_completed_successfully
volumes:
# Persist projects/sessions/token across recreates. The official image stores Caido
# data under /home/caido/.local/share/caido; without this, projects created in the
# container are lost on each `up`. NAMED volume (not a bind-mount) by the same WAL/
# virtiofs discipline the rest of the stack follows.
- caido-data:/home/caido/.local/share/caido
# To reach the GUI from the host (optional; the tools do NOT need it), tunnel over SSH to
# this service, or UNCOMMENT on a CONTROLLED machine (exposes the proxy/GUI to the host;
# see the --allow-guests note above before doing so):
# ports:
# - "${CAIDO_HOST_PORT:-7000}:8080"
healthcheck:
# The image ships neither curl nor nc (checked), but it has bash: probe with a raw TCP
# connect through /dev/tcp.
test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8080"]
interval: 10s
timeout: 5s
retries: 12
start_period: 30s
restart: unless-stopped
# Default compose network: kali reaches it as caido:8080 via internal DNS.
volumes:
# Hermes state (profile + SQLite WAL). NAMED on purpose: avoids the bind-mount
# that corrupts the SQLite WAL on macOS virtiofs.
hermes-data:
# Kali artifacts plane (/artifacts). NAMED so the staged raw output persists across
# container recreations.
kali-artifacts:
# Caido projects/sessions/token — persisted across recreates (see the caido service).
caido-data: