Vulnerator AI 1.5.0

What's new in 1.5.0

🖥️ Hermes web dashboard

Built-in browser UI on :9119 with Vulnerator-AI custom skin — dark red/green cyber theme, block ASCII banner, OODA spinner verbs.

🧪 Practice labs

• labs/looney-tunables-ctf — CVE-2023-4911 glibc 2.37 LPE (pentest + ctf modes)
• labs/pinguinazo-ssti — Flask SSTI → reverse shell → sudo java → root (inspired by dockerlabs.es)

📋 Pentest report skill v0.3

Two-layer reports: report_gen.py structured base + LLM narrative enrichment + standalone HTML with Vulnerator-AI visual theme.

🧠 SOUL.md improvements

• Engagement modes: mode: pentest (stops at evidence) vs mode: ctf/redteam (full compromise)
• Evidence discipline and tightened 3-step no-progress counter
• ORIENT always reloads finding store (read_findings)
• Structured todo_list OODA template
• Reverse shell guidance via kali_exec
• Container environment awareness

🌐 Landing web

CRT boot screen with lens effect, Whisper-synced karaoke, audio controls, VULNERATOR! flash, scroll animations, screenshot lightbox, CTF + pentest sample reports.

🔧 Config

• todo toolset enabled for OODA state tracking
• display.skin: vulnerator activates custom skin
• HERMES_DASHBOARD=1 publishes dashboard on :9119

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).

Vulnerator AI 1.3.0

What's new

Opt-in scope-guard for kali_run / kali_exec. A deterministic (code, not prompt) layer that validates the DESTINATION of each raw-shell action before executing it. It lives inside the Kali MCP, in front of the two raw-shell runners; it does not touch the cloud tools (Prowler/Pacu/IAM) or the browser MCP.

How it works

• Opt-in. With no scope.json present (path via SCOPE_FILE, default /scope/scope.json), behavior is identical to before — no gate. The guard activates only when the file exists and contains enabled: true.
• Fail-closed when active. Hermes must declare the new optional targets argument (the IP/host/URL the command touches). Any destination outside the allowed scope — or in deny — blocks the whole execution with a structured SCOPE_VIOLATION error without running. If targets is not declared while the scope is active, the call is blocked.
• Validation. IP-against-CIDR plus literal hostname match (no DNS) with optional ports; deny takes priority over allow. A best-effort parse of the command is an extra belt that can only block, never approve.
• Auditable. Each violation is logged into the engagement findings store as a discarded SCOPE_VIOLATION record.
• Kill-switch. SCOPE_ENFORCE=0 force-disables the guard even if the file says enabled: true.

Zero new dependencies (stdlib json/ipaddress/urllib.parse). New scope.example.json template, a commented bind-mount in docker-compose.yml, and a README section document how to turn it on.

Default behavior (no scope.json) is unchanged.

Full Changelog: v1.2.0...v1.3.0

Vulnerator AI 1.2.0

What's new

Curated pentest CLIs baked into the Kali image. The base kali-rolling image is minimal and shipped none of the tools the skills assume. The image now bakes in a curated set so the web-pentest and recon skills work out of the box: nmap, whatweb, nuclei, ffuf, sqlmap, gobuster, impacket-scripts (invoked as impacket-*, e.g. impacket-secretsdump), and bloodhound.py (bloodhound-python). Not the full kali-linux-headless metapackage — curated to keep the image reasonably sized.

Reproducible lab target (OWASP Juice Shop). Documented quickstart to bring the stack up with a deliberately-vulnerable target on the internal network:

docker compose -f docker-compose.yml -f docker-compose.target.yml up -d --build

Hermes reaches it as http://juice-shop:3000; it is not exposed to the host.

Fixed / polish

• Startup now warns (non-fatal) when OLLAMA_BASE_URL is set but OLLAMA_MODEL is empty, instead of silently pointing the profile default model name at the Ollama endpoint.
• Added a regression test for the OpenRouter-vs-Ollama provider-selection startup logic.

Default behavior (OpenRouter, no OLLAMA_BASE_URL) is unchanged.

Full Changelog: v1.1.0...v1.2.0

Vulnerator AI 1.1.0

What's new

Opt-in local / remote Ollama inference. You can now run Vulnerator with Ollama instead of OpenRouter — set OLLAMA_BASE_URL in your .env and Hermes talks to that endpoint; leave it empty and everything behaves exactly like v1.0.1 (OpenRouter).

• OLLAMA_BASE_URL — empty = OpenRouter (default). Set it to a local (http://host.docker.internal:11434/v1) or remote (http://<host>:11434/v1) Ollama OpenAI-compatible endpoint to use Ollama.
• OLLAMA_MODEL — the Ollama model name used in that mode (e.g. qwen2.5-coder:32b).
• OPENROUTER_API_KEY is not required in Ollama mode (the fail-closed guard now only applies to OpenRouter mode).
• Added extra_hosts: host.docker.internal:host-gateway so a host-run Ollama is reachable on Linux too.

⚠️ Experimental — parity not guaranteed. The model you point at MUST support reliable tool/function-calling (everything routes through MCP) and must not refuse the authorized-offensive pentest framing, or the agent won't work well. Ollama must also serve a context window of at least ~64K tokens (OLLAMA_CONTEXT_LENGTH=64000) or Hermes refuses to start. Local parity with Mistral-Large-on-OpenRouter is not guaranteed.

Full Changelog: v1.0.1...v1.1.0

Vulnerator AI 1.0.1

What's new

Configurable OpenRouter model. The LLM model is no longer hardcoded — set OPENROUTER_MODEL in your .env to override it. Leave it empty to keep the profile default (mistralai/mistral-large-4-0), so existing setups are unaffected.

⚠️ Caveat: the project deliberately uses Mistral Large because models like Claude (anthropic/*) refuse the authorized-offensive pentest framing. Overriding with such a model may make the agent refuse to work.

Changes

• docker-compose.yml: optional OPENROUTER_MODEL env var; startup injects it via hermes config set model.default only when non-empty (fallback, not fail-closed).
• agent-ooda/profile/config.yaml, .env.example, README.md: documented the override and its caveat.
• Added VERSION file.

Full Changelog: ...v1.0.1