irraz/vulnerator-ai

_{Built with}

_{Containerized with Docker · driven by Hermes Agent from Nous Research · tooling on Kali Linux}

OODA pentest driven by Hermes talking directly to a Kali container via MCP.

vulnerator-ai runs an OODA (Observe-Orient-Decide-Act) pentest loop where the driving brain is Hermes and the 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. Four containers (the agent, two tool MCP servers and the MCP front door) and the agent driving end to end.

• kali — deterministic runtime for pentest and collection tools (nmap, whatweb, nuclei, ffuf, sqlmap, Prowler, ...) over a kali-mcp server (:8900).
• playwright-mcp — real browser (headless Chromium) over MCP (:8931), the web surface used by the web-pentest skill.
• ooda-agent — Hermes (nousresearch/hermes-agent) as the OODA loop driver and client of both MCPs. Keeps its OpenAI-compatible API server alive on :8642.
• vulnerator-mcp — thin MCP front door over Hermes' :8642 runs API so MCP clients (Claude Code / Kiro, BugTraceAI, ...) can trigger/observe/steer/stop a run. Up by default; it exposes only the runs lifecycle, never raw kali_run or /v1/chat/completions.

No api or ui service: the agent talks directly to the MCPs. See docs/design.md for the full architecture and the curated Kali toolset.

The installer is the fast path: the only thing you provide is your OpenRouter API key. It checks prerequisites (docker, docker compose v2, openssl), auto-generates the two secret tokens, writes the .env from the template, and brings the default stack up.

./install.sh

Then open the interactive TUI:

docker compose exec -it ooda-agent hermes chat

Useful flags: --with-juice-shop (also start the OWASP Juice Shop practice lab), --no-up (just write the .env), --force (overwrite an existing .env).

Don't want to read any of this? Paste the block below to an LLM coding assistant (Claude Code, Kiro, Cursor, …) that has shell access in this repo. It tells the assistant everything it needs to install the stack and wire up the MCP server — you provide only your OpenRouter key when asked.

You are setting up the "vulnerator-ai" repo for me. Do the following, in order:

1. From the repo root, run the installer:  ./install.sh
   It is interactive and will ask for ONE value, OPENROUTER_API_KEY — ask me for it
   and pass it through (or run it non-interactively as
   `OPENROUTER_API_KEY=<the key> ./install.sh`). The installer auto-generates the two
   secret tokens (HERMES_API_SERVER_KEY, VULNERATOR_MCP_INBOUND_TOKEN), writes the .env,
   and brings the default 4-container stack up (no Juice Shop lab). Do NOT invent or ask
   me for the two tokens — the installer makes them.

2. Wait until the stack is healthy, then verify with:  docker compose ps

3. Register the local MCP server (stdio mode — zero network surface, no inbound token).
   First build the image once:
       docker build -f docker/mcp/Dockerfile -t vulnerator-ai-mcp:dev .
   Then add this entry to my assistant's MCP config (mcpServers), filling HERMES_API_SERVER_KEY
   with the value the installer wrote into the repo's .env (read it from there, do not print it):
       {
         "mcpServers": {
           "vulnerator-mcp": {
             "command": "docker",
             "args": [
               "run", "-i", "--rm",
               "--add-host", "host.docker.internal:host-gateway",
               "-e", "HERMES_API_SERVER_KEY",
               "-e", "HERMES_API_BASE_URL=http://host.docker.internal:8642",
               "vulnerator-ai-mcp:dev"
             ],
             "env": { "HERMES_API_SERVER_KEY": "<value from .env>" }
           }
         }
       }

4. Confirm the MCP tools are available (health(), start_pentest, get_run_status,
   stream_run_events, steer_run, stop_run). Then tell me it's ready and remind me this engine
   has NO scope-guard/consent/audit by default: it must be used only against authorized targets.

cp .env.example .env
# edit .env: set OPENROUTER_API_KEY, and generate the two tokens with `openssl rand -hex 32`:
#   HERMES_API_SERVER_KEY, VULNERATOR_MCP_INBOUND_TOKEN
docker compose up -d --build

The README is intentionally short. The detail lives under docs/:

By default this product has no guardrails: no scope-guard, no consent, no audit, no authorization gate. Hermes runs directly whatever it decides against the target. This is intentional. Use it only against explicitly authorized targets and in a controlled environment. All responsibility for the scope and for lawful use rests with the operator.

There are two opt-in controls (a deterministic scope-guard for kali_run/kali_exec, and the MCP inbound token). Neither is consent or a firewall. See docs/security.md for what each does and does not cover.

Official artwork lives in media/ (see media/README.md for the full catalog). Death-metal / cyberpunk identity — use it for wallpapers, stickers and shirts. There's also a theme song (media/vulnerator-ai-song.mp3, lyrics in docs/lyrics.md) — a nod to the project's death-metal band aesthetic.

_{transparent logo (stickers / shirts) · desktop wallpaper · smartphone wallpaper}

We are grateful for the support of companies that believe in advancing cybersecurity knowledge and making security insights accessible to the community.

Special thanks to Aktios: vulnerator-ai was born inside the Aktios cybersecurity team, and we extend our sincere gratitude for their continued support. Their commitment to cybersecurity made this project possible.

Released under the MIT License. You are free to use, modify and distribute this software, including commercially, as long as the copyright notice and permission notice are preserved. The software is provided "as is", without warranty of any kind.

Note on responsible use. The MIT license governs the code, not how you may use it. This is an offensive security tool with no scope-guard, consent or authorization gate by default (see the ⚠️ Warning above). Use it only against explicitly authorized targets; responsibility for the scope and for lawful use rests entirely with the operator.