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.
## What it is
`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.
## Architecture (4 containers)
- **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.
## Quick Start
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.
 [code] 
Then open the interactive TUI:
 [code] 
Useful flags: `--with-juice-shop` (also start the OWASP Juice Shop practice lab), `--no-up`
(just write the `.env`), `--force` (overwrite an existing `.env`).
### Let an AI assistant set it up for you
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.
 [code] 
 Manual setup (without the installer) 
 [code] 
Every variable is documented in **`docs/configuration.md`**.
## Documentation
The README is intentionally short. The detail lives under `docs/`:
| Topic | Doc |
| --- | --- |
| Project website | irraz.github.io/vulnerator-ai |
| Every `.env` variable, AWS creds, local Ollama inference | `docs/configuration.md` |
| Driving a pentest (TUI, MCP client, raw HTTP), the Juice Shop lab, clean restarts | `docs/usage.md` |
| The no-guardrails model, opt-in scope-guard, MCP inbound token | `docs/security.md` |
| Raw HTTP API reference (`:8642`) | `docs/http-api.md` |
|