Vulnerator AI — Unholy Pentest

What it is

An OODA (Observe-Orient-Decide-Act) pentest loop where the driving brain is Hermes (Nous Research) and the tools run on a Kali governed by an MCP server. Hermes decides what to run and launches it directly against the target.

A deliberately minimal design: no core, no REST API, no UI, no gates. Three containers — the agent and two MCP servers — driving the engagement end to end.

Architecture

Three containers.

kali

Deterministic runtime for pentest tools: nmap, nuclei, sqlmap, ffuf, gobuster, Prowler, ScoutSuite and more. Exposes the kali-mcp server.
playwright-mcp

A real headless Chromium browser exposed over MCP — the web flank for navigation, DOM and interaction, with zero native toolsets.
ooda-agent

Hermes as the OODA loop driver and client of both MCP servers, running the pentest tools directly.

Built with

Docker
Hermes Agent · Nous Research
Kali Linux

Engagement modes

Declare the mode at the start of every engagement. The agent enforces the scope itself.

mode: pentest

Stop at exploitability evidence. Confirms the crash, documents the CVE, records CVSS, affected / patched versions and remediation steps. No root shell. Delivers an enriched Markdown + HTML report.
mode: redteam · ctf

Full compromise. Exploit, escalate, capture objectives (flags, credentials, data). Uses all available resources. The agent stops only when the objective is reached or all routes are exhausted.

OODA engine

Observe → Orient → Decide → Act → Report

△
Direct MCP execution — Hermes calls tools directly on Kali. No intermediate API, no validation layer, no overhead. When it calls mcp_kali_kali_run, the shell command runs for real and returns real output.
△
Evidence discipline — only real tool output counts as evidence. The agent cannot cite a CVE or advisory it did not find in an actual tool result. Failed searches count as steps without progress.
△
Durable finding store — record_finding / read_findings persist across context compression and session restarts. The ORIENT phase always reloads the store before reasoning.
△
OODA task list — structured todo_list (OBSERVE / ORIENT / DECIDE / ACT / REPORT) survives context compression and is visible in the session chat throughout the engagement.
△
Web + CLI in parallel — Playwright MCP gives the agent a real Chromium browser for web pentesting (DOM, XSS, JS-rendered SPAs) alongside Kali CLI tools. No native browser toolset.
△
Two-layer pentest report — report_gen.py produces a structured Markdown base from the finding store; the agent enriches it with session context and renders a standalone HTML report with the Vulnerator-AI visual theme.
△
MCP front door — the vulnerator-mcp container exposes Hermes runs as MCP tools so any MCP client (Claude Code, Kiro, custom tooling) can trigger, steer and observe a pentest programmatically.
△
Hermes web dashboard — built-in browser UI at :9119 with the Vulnerator-AI skin (dark red/green cyber theme, custom OODA spinner verbs, block ASCII banner). No TUI required.

Quick start

Manual

One command. The installer asks for your OpenRouter key and brings the stack up.

bash

git clone https://github.com/irraz/vulnerator-ai
cd vulnerator-ai
./install.sh

Lazy mode — paste into Claude Code, Kiro or Cursor

Drop this into any LLM coding assistant with shell access. It handles everything — you only provide your OpenRouter key when asked.

Full setup prompt (install + MCP wiring)

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. 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:
       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 .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 and report back.

Requires Docker, Docker Compose v2 and an OpenRouter API key (or a local Ollama endpoint). Tested on macOS (Apple Silicon) and Linux x86-64.

Practice labs

Isolated, disposable Docker environments for testing the OODA agent against real vulnerabilities without internet-facing risk.

LPE CVE-2023-4911 x86-64

looney-tunables-ctf

Ubuntu 23.04 container with glibc 2.37-0ubuntu2 pinned at the vulnerable revision (pre-patch). The agent must enumerate the system, discover CVE-2023-4911 (Looney Tunables — GLIBC_TUNABLES buffer overflow in ld.so, CVSS 7.8), and either demonstrate exploitability (pentest mode) or obtain a root shell (redteam mode) using the gcc toolchain installed on the target. No hints about the vulnerability are given.

Ubuntu 23.04 lunar · SSH access · agent_user · ASLR level 2

README Lab source Sample pentest report →
WEB SSTI → RCE Docker

pinguinazo-ssti

Flask/Jinja2 web application with unsanitised template input. The agent must discover the server-side template injection, obtain remote code execution, establish a reverse shell to Kali, and escalate with sudo java to capture the root flag.

Flask / Werkzeug 3.1.9 · Web service · port 5000 · Reverse shell + sudo java

README Lab source Sample CTF report →

Sample reports

Real output from the agent — both mode: pentest (exploitability evidence, no shell) and mode: ctf (full compromise). Two-layer report: structured finding store + LLM narrative enrichment, Vulnerator-AI visual theme.

7.8
mode: pentest
CVE-2023-4911 — Looney Tunables

ubuntu-server-01 · Ubuntu 23.04 · looney-tunables-ctf lab

glibc 2.37 buffer overflow in ld.so via GLIBC_TUNABLES. Exploitability demonstrated: 10/10 SIGSEGV with differential controls. Stopped at evidence — no root shell. OODA loop in 14 steps.
View full report →
CTF
mode: ctf
SSTI Jinja2 + sudo java — Pinguinazo

pinguinazo-ssti · Flask/Werkzeug 3.1.9 · pinguinazo-ssti lab

Flask render_template_string() with unsanitised input → RCE as pinguinazo → sudo java NOPASSWD → arbitrary Java as root → interactive reverse shell to kali + flag captured. OODA loop in 12 steps.
View full report →

Agent in action

Vulnerator-AI running a live OODA pentest loop — Kali MCP executing tools and delivering the final report.

OODA loop — Kali MCP execution

Pentest report — Vulnerator-AI output

Open source

Vulnerator-AI is fully open source under the MIT licence. Read the code, fork it, extend it, run it against your own infrastructure. The SOUL.md, skills, config and all OODA loop logic are plain text files you can read and modify without touching a binary.

github.com/irraz/vulnerator-ai — source, issues, PRs
Releases — changelog and versioned packages
docs/ — configuration, usage, security model

Star on GitHub

— stars

v1.5.0 · MIT

What it is

Architecture

kali

playwright-mcp

ooda-agent

Built with

Engagement modes

mode: pentest

mode: redteam · ctf