Skip to content

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

31.4 KB
Raw Blame
# =============================================================================
# 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: