v1.4.0 — vulnerator-mcp MCP front door

vulnerator-ai 1.4.0 — MCP front door

This release adds vulnerator-mcp, a thin MCP server that wraps Hermes' :8642 runs API so any MCP client (Claude Code, Kiro, Cursor, BugTraceAI, …) can trigger, observe, steer and stop an OODA pentest as MCP tools. It wraps — it does not replace — the HTTP API, and exposes only the runs lifecycle so the client stays a trigger/observer, never the brain. It also ships an install.sh easy installer that reduces first-run setup to a single input (your OpenRouter key).

Added

• vulnerator-mcp MCP front door (up by default). Thin FastMCP wrapper (docker/mcp/) over the :8642 runs API. Five tools (start_pentest, get_run_status, stream_run_events, steer_run, stop_run) + health(). Never exposes /v1/chat/completions or raw kali_run.
  • Stateless & version-tolerant: the run object and events are forwarded opaquely; terminality is derived from the run booleans (completed/interrupted), never from the status string; the upstream version is read from GET /health and reported verbatim.
  • stream_run_events uses the event seq as a portable cursor (batched pages with next_cursor/done), plus MCP progress notifications over streamable-HTTP.
  • Up by default as a 4th container in docker-compose.yml (plain docker compose up). Internal docker network only — host publication is opt-in via VULNERATOR_MCP_HOST_PORT.
  • Fail-closed inbound auth: streamable-HTTP refuses to start without VULNERATOR_MCP_INBOUND_TOKEN (separate secret from HERMES_API_SERVER_KEY); /healthz is the one exact-match carve-out. The local stdio mode (recommended for Claude Code / Kiro) needs no token and no port.
  • Advisory scope argument folded into the prompt (the MCP layer enforces no scope; the v1.3.0 Kali-layer scope-guard remains the opt-in deterministic gate).
• install.sh easy installer. One input — your OPENROUTER_API_KEY — and the installer checks prerequisites (docker, docker compose v2, openssl), auto-generates the two secret tokens (HERMES_API_SERVER_KEY, VULNERATOR_MCP_INBOUND_TOKEN) as separate 32-byte hex values, writes the .env from the template (keeping every other default and the comments), and brings the default stack up (no Juice Shop lab). Flags: --with-juice-shop, --no-up, --force. The manual cp .env.example .env path still works.
• README "Let an AI assistant set it up for you" block. A copy-paste prompt you hand to an LLM coding assistant (Claude Code / Kiro / Cursor) with shell access, so it runs install.sh and wires up the vulnerator-mcp stdio server end to end — you only supply the OpenRouter key when asked.

Changed

• README trimmed to a short Quick Start; long-form detail split into docs/. The README now leads with the ./install.sh Quick Start (plus a collapsed manual fallback) and a documentation index. The detail moved into new topic docs: docs/configuration.md (every .env variable, AWS credentials, local Ollama inference), docs/usage.md (driving a pentest via TUI / MCP client / raw HTTP, the Juice Shop lab, clean restarts), and docs/security.md (the no-guardrails model, the opt-in scope-guard, the MCP inbound token). Documentation only; no behavior changed.
• pentest-report now emits the report in English, aligned with the public docs, plus a redacted English sample deliverable (docs/example-report.md) and its findings store (docs/example-findings.jsonl).

Fixed

• Kali image clean-build crash. The v1.3.0 scope_guard.py was imported by kali_mcp_server.py but never COPY-ed into the image, so a clean docker compose up --build crashed the kali container with ModuleNotFoundError: No module named 'scope_guard'. The Dockerfile now copies it; the kali container builds and reaches a healthy state.

Verified

End-to-end against a live hermes-agent 0.22.0 stack: MCP client → vulnerator-mcp (stdio) → :8642, full health → start_pentest → stream_run_events (cursor) → steer/stop → get_run_status round-trip, plus the 4-container default stack building and starting cleanly with the kali fix. The install.sh .env generation was dry-run verified (three keys correct, the two tokens distinct 32-byte hex, every other variable left as the template).