Autonomous OODA-loop pentesting agent. Hermes brain, Kali + Playwright tools over MCP, ATT&CK as the Orient language.
Python ai-agentsautonomous-agentskali-linuxllm-agentsoffensive-securityooda-looppentestingplaywrightsecurity
docs: restructure README; split HTTP API and design into docs/
irraz6c3f908577cc
diff --git a/LICENSE b/LICENSEindex 7c744db..7e56a8d 100644--- a/LICENSE+++ b/LICENSE@@ -1,6 +1,6 @@MIT License-Copyright (c) 2026 irraz+Copyright (c) 2026 Sergio JimenezPermission is hereby granted, free of charge, to any person obtaining a copyof this software and associated documentation files (the "Software"), to dealdiff --git a/README.md b/README.mdindex 3c996b4..b00095a 100644--- a/README.md+++ b/README.md@@ -61,8 +61,7 @@ end to end.- **ooda-agent** — Hermes (`nousresearch/hermes-agent`) as the OODA loop driver. It is a clientof both MCPs (`kali:8900`, `playwright-mcp:8931`) and runs the pentest tools directly.It keeps its gateway alive with `hermes gateway run` (OpenAI-compatible API server on `:8642`,- **published to the host** by default so you can pilot it from an external assistant — see- "Pilot Hermes from an external assistant").+ **published to the host** by default so you can pilot it — see "Driving a pentest").- **vulnerator-mcp** — a thin MCP **front door** over Hermes' `:8642` runs API so external MCPclients (Claude Code / Kiro, BugTraceAI, ...) can trigger/observe/steer/stop a pentest as MCP@@ -72,8 +71,8 @@ end to end.`VULNERATOR_MCP_INBOUND_TOKEN`. For **local** Claude Code / Kiro the recommended path is insteadthe **stdio** mode (`docker run -i …`, zero network surface, no token). It wraps, does **not**replace, the HTTP API: it exposes **only** the runs lifecycle (no raw `kali_run`, no- `/v1/chat/completions`) so the client stays a trigger/observer, never the brain. See "Consume- Hermes from an MCP client (`vulnerator-mcp`)" below.+ `/v1/chat/completions`) so the client stays a trigger/observer, never the brain. See "Driving a+ pentest → From an MCP client" below.There are no `api` or `ui` services: the agent talks directly to the MCPs (Kali and browser),and the MCP front door only forwards the runs lifecycle.@@ -171,212 +170,50 @@ Caveats before you rely on it:with Mistral-Large-on-OpenRouter is **not guaranteed** — treat local inference as experimental andvalidate your chosen model before relying on it.-## How to drive the pentest (interactive TUI)+## Driving a pentest-```sh-docker compose up -d --build-docker compose exec -it ooda-agent hermes chat-```+Three ways to pilot an engagement, from simplest to most programmatic. All of them drive the same+OODA loop; pick by how you work.-`hermes chat` opens the agent's interactive TUI/REPL. From there you ask it for a pentest-in natural language; Hermes drives the OODA and runs the tools on Kali-**directly** with the `kali_run` tool (talking to `kali:8900`).--`hermes gateway run` (the container's command) keeps the container alive and starts-Hermes' API server on `:8642`. That API server is an **alternative programmatic** path-(OpenAI-compatible) and is **published to the host** by default, to pilot Hermes from an-external assistant without entering the TUI (see the next section).--### Quickstart against a lab target (Juice Shop)--To practice the `web-pentest` skill without going out to the internet or touching real systems,-the repo ships an **optional** target override, `docker-compose.target.yml`, that adds an-[OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) service. Juice Shop is a-**deliberately-vulnerable** web application (OWASP project), the de facto standard for practicing-web pentesting (XSS, SQLi, broken auth, etc.).--Bring the whole stack up **with** the target by layering both compose files:--```sh-docker compose -f docker-compose.yml -f docker-compose.target.yml up -d --build-```--The target joins the **same internal docker network** and publishes **no port to the host**, so it-only exists inside the docker environment — scoping the exercise to a controlled lab. Hermes/Kali-reach it by its DNS name at **`http://juice-shop:3000`**. Point an engagement at that URL, e.g. via-the interactive TUI:+### 1. Interactive TUI (`hermes chat`)```sh-docker compose -f docker-compose.yml -f docker-compose.target.yml exec -it ooda-agent hermes chat-# then ask, in natural language:-# "Authorized web pentest against http://juice-shop:3000 (scope: that host only).-# Enumerate, fingerprint, and test for injection/auth flaws. Report confirmed findings."-```--This is the authorized target for practicing the `web-pentest` skill. Only the web lab is in scope-here (no AD or other labs for now).--## Pilot Hermes from an external assistant (Kiro / Claude)--Sometimes you don't want to enter the `hermes chat` TUI: you want an assistant (Kiro, Claude, a-CI script) to **trigger and observe** a pentest over HTTP. Hermes already exposes an-**OpenAI-compatible** API server (enabled in the profile, `agent-ooda/profile/config.yaml` →-`platforms.api_server`); all you need is to reach it.--**Role of the external assistant: trigger and observer, not brain.** The one that reasons and runs the-pentest is Hermes (driven by the `mistralai/mistral-large-4-0` model, chosen on purpose-because Claude rejects the offensive framing of authorized pentesting). The assistant only sends the-engagement prompt and reads the events; it must **not** try to "think" the pentest or reinterpret-the Kali tools.--Authentication: all calls go with `Authorization: Bearer <HERMES_API_SERVER_KEY>`-(the same key from the `.env`).--### Two access modes--**Mode A — published port (recommended).** The compose publishes `:8642` to the host (configurable-with `HERMES_API_HOST_PORT`, default `8642`). The assistant calls `http://localhost:8642`-directly:--```sh-export KEY=$(grep '^HERMES_API_SERVER_KEY=' .env | cut -d= -f2)--# alive?-curl -s http://localhost:8642/health # -> {"status":"ok"}-```--**Mode B — without opening a port (`exec`).** If you prefer not to publish `:8642` to the host, delete the-`ports:` block of the `ooda-agent` service and talk to the API from inside the container:--```sh-docker compose exec ooda-agent \- curl -s http://localhost:8642/health-# If you launched the stack with '-p <project>', pass it here too:-# docker compose -p pentest-ana exec ooda-agent curl -s http://localhost:8642/health-```--All the `curl` calls below are the same in both modes; only the prefix changes (direct host vs.-`docker compose exec ooda-agent`).--### Main flow (runs API)--The `runs` pattern is designed precisely for this: launch a long job and subscribe to its-progress instead of handling the streaming by hand.--```sh-# 1) Launch the pentest. The body carries the engagement in natural language in the "input" field.-# It responds {"run_id":"run_abc123","status":"started"}.-curl -s http://localhost:8642/v1/runs \- -H "Authorization: Bearer $KEY" \- -H "Content-Type: application/json" \- -d '{- "input": "Authorized pentest against 10.0.0.0/24 (scope: that /24 only). Enumerate, identify exposed services and test access paths. Report confirmed findings with evidence."- }'--# 2) Observe progress: SSE stream of lifecycle events (OODA, tool.start/complete, ...).-curl -N http://localhost:8642/v1/runs/run_abc123/events \- -H "Authorization: Bearer $KEY"--# 2b) Or query the point-in-time status (status: started | running | completed | failed | cancelled).-curl -s http://localhost:8642/v1/runs/run_abc123 \- -H "Authorization: Bearer $KEY"--# 3) (Optional) Inject guidance mid-run. Only while status=running; it is delivered at the-# next tool boundary. If the run no longer accepts steer, it responds 409.-curl -s http://localhost:8642/v1/runs/run_abc123/steer \- -H "Authorization: Bearer $KEY" \- -H "Content-Type: application/json" \- -d '{"input": "Focus on port 445 first."}'--# 4) (Optional) Interrupt the run.-curl -s http://localhost:8642/v1/runs/run_abc123/stop \- -H "Authorization: Bearer $KEY"-```--Fields of the `POST /v1/runs` body (verified against Hermes' official docs): `input`-(string, required) and, optional, `session_id`, `instructions`, `conversation_history`,-`previous_response_id`. For safe retries you can send the `Idempotency-Key` header.--### Alternative: `POST /v1/chat/completions` (OpenAI-compatible)--If your client already speaks the OpenAI format, you can use the classic endpoint (SSE streaming)-instead of the runs API:--```sh-curl -s http://localhost:8642/v1/chat/completions \- -H "Authorization: Bearer $KEY" \- -H "Content-Type: application/json" \- -d '{- "model": "hermes-agent",- "messages": [{"role": "user", "content": "Authorized pentest against 10.0.0.0/24 (scope: that /24 only). Report confirmed findings with evidence."}]- }'+docker compose up -d --build+docker compose exec -it ooda-agent hermes chat```-### Instructions for the assistant--Pattern a Kiro/Claude should follow to pilot an engagement:--1. `GET /health` to confirm the stack is alive (`{"status":"ok"}`).-2. `POST /v1/runs` with the engagement in `input` (explicit target and **scope**, in natural- language). Save the `run_id` from the response.-3. Follow the run to a terminal state: read the SSE from `GET /v1/runs/{run_id}/events`, or- poll `GET /v1/runs/{run_id}` until `completed` / `failed` / `cancelled`.-4. Summarize the result to the user (findings, final status). For the formal deliverable, Hermes- itself generates the Markdown report via the `pentest-report` skill and leaves it as an artifact in the- data channel (`:8901`).+`hermes chat` opens the agent's REPL. Ask for a pentest in natural language; Hermes drives the OODA+and runs tools on Kali directly via `kali_run` (talking to `kali:8900`). The container's command+`hermes gateway run` also keeps Hermes' API server alive on `:8642`, which powers ways 2 and 3.-The assistant **does not decide** the tools nor reinterpret the Kali output: that is Hermes' job.-Its role is to trigger, observe and summarize.+### 2. From an MCP client — recommended for assistants-### Security note+If your tooling speaks **MCP** (Claude Code, Kiro, Cursor, BugTraceAI, …), the stack ships+**`vulnerator-mcp`** (`docker/mcp/`): a thin MCP server that wraps Hermes' runs API and exposes it+as MCP tools. It wraps, it does **not** replace, the HTTP API — it exposes **only** the runs+lifecycle, so the client stays a trigger/observer and never the brain. It never exposes+`/v1/chat/completions` or any raw `kali_run`.-Publishing `:8642` to the host **lowers the network barrier** the stack had on purpose (before, the API-server was only reachable over the internal docker network). From there on, the endpoint's only protection-is the `HERMES_API_SERVER_KEY` Bearer: use it **only on a controlled machine/environment**, and if you don't-need external access use Mode B (`exec`, without opening a port). This is consistent with the-⚠️ Warning further down: there is no scope-guard or authorization gate, responsibility for the-scope rests entirely with the operator.--## Consume Hermes from an MCP client (`vulnerator-mcp`)--If your tooling speaks **MCP** rather than raw HTTP (Claude Code, Kiro, Cursor, BugTraceAI, …),-the stack ships a thin MCP server — **`vulnerator-mcp`** (`docker/mcp/`) — that wraps Hermes'-`:8642` runs API and exposes it as MCP tools. It wraps, it does **not** replace, the HTTP API: it-exposes **only** the runs lifecycle, so the client stays a trigger/observer and never the brain.--It runs in **two modes**: a **streamable-HTTP** service that is **up by default** with the stack-(for in-docker consumers like BugTraceAI, and for host-published use), and a **stdio** mode that-**local** Claude Code / Kiro spawn as a subprocess (recommended locally; zero network surface).--Five tools + a health check, mapped 1:1 onto `:8642`:+**Five tools + a health check**, mapped 1:1 onto the runs API:| Tool | Does || --- | --- |-| `start_pentest(input, scope, …)` | starts a run (`POST /v1/runs`); returns `{run_id, status, replayed}` |+| `start_pentest(input, scope, …)` | starts a run; returns `{run_id, status, replayed}` || `get_run_status(run_id)` | the full run object (status + `completed`/`partial`/`interrupted` + output + usage) |-| `stream_run_events(run_id, cursor, …)` | pages the SSE events with a `seq` cursor (`{events, next_cursor, done}`); also emits one MCP progress notification per page (batch-completion telemetry) over streamable-HTTP |-| `steer_run(run_id, input)` | injects a correction (`POST …/steer`); surfaces the 409 `run_not_accepting_steer` verbatim |-| `stop_run(run_id)` | stops the run (`POST …/stop`); returns the full run object |-| `health()` | upstream `GET /health` (`{status, platform, version}`) |+| `stream_run_events(run_id, cursor, …)` | pages the lifecycle events with a `seq` cursor (`{events, next_cursor, done}`); also emits one MCP progress notification per page over streamable-HTTP |+| `steer_run(run_id, input)` | injects a correction mid-run; surfaces the `409 run_not_accepting_steer` verbatim |+| `stop_run(run_id)` | stops the run; returns the full run object |+| `health()` | upstream health (`{status, platform, version}`) |-It deliberately does **not** expose `/v1/chat/completions` or any raw `kali_run` pass-through.Event/status/output payloads are forwarded verbatim as **untrusted data** (never interpreted).-> ⚠️ **No guardrails — same warning as the rest of the product, amplified.** The MCP layer-> enforces **no scope**, no consent and no audit; it only adds *reachability*. The `scope`-> argument on `start_pentest` is **REQUIRED but ADVISORY**: it is folded into the prompt for-> operator clarity, it is **not** an enforced constraint. For a real deterministic gate on-> raw-shell actions, enable the **optional Kali-layer scope-guard** (v1.3.0, via `scope.json` —-> see "Scope-guard (opt-in)" below); that is a different, opt-in layer and is **not** a gate on-> this runs API. Responsibility for the scope rests entirely with the operator.--### Local: stdio (recommended for Claude Code / Kiro)+**Local — stdio (recommended for Claude Code / Kiro).** Zero network surface: the client spawns the+server as a subprocess over stdin/stdout — no listener, no token, no port. Build the image once and+add an `mcpServers` entry:-stdio has **zero network surface**: the client spawns the server as a subprocess over-stdin/stdout — no listener, no inbound token, no port. Build the image once-(`docker build -f docker/mcp/Dockerfile -t vulnerator-ai-mcp:dev .`), then add an `mcpServers`-entry (copy-paste; the stdio process reaches the host-published `:8642` via-`host.docker.internal`, which the `--add-host` below maps to the host gateway):+```sh+docker build -f docker/mcp/Dockerfile -t vulnerator-ai-mcp:dev .+``````json{@@ -396,41 +233,53 @@ entry (copy-paste; the stdio process reaches the host-published `:8642` via}```-> **Linux note.** On Docker Desktop (macOS/Windows) `host.docker.internal` resolves out of the-> box, so the `--add-host` is optional there; on **stock Linux Docker** it does **not** resolve-> unless you pass `--add-host=host.docker.internal:host-gateway` (included above). If you prefer,-> point `HERMES_API_BASE_URL` at the host's reachable address instead (e.g. the Docker bridge-> gateway or the host IP).+The upstream Bearer is a pass-through of `HERMES_API_SERVER_KEY` (no second secret for the hop). On+Docker Desktop `host.docker.internal` resolves out of the box; on stock Linux the `--add-host`+above is what makes it resolve (or point `HERMES_API_BASE_URL` at the host's reachable address).++**In-docker / remote — streamable-HTTP (up by default).** The streamable-HTTP service is part of the+default stack, reachable on the internal network at `http://vulnerator-mcp:8700` (an in-docker+consumer like a BugTraceAI container reaches it there with no extra steps). It is **fail-closed** on+`VULNERATOR_MCP_INBOUND_TOKEN` (`docker compose up` aborts without it) and every request must carry+`Authorization: Bearer <VULNERATOR_MCP_INBOUND_TOKEN>` (the `/healthz` route is the one exception).+Host publication is **off by default** — set `VULNERATOR_MCP_HOST_PORT` and uncomment the service's+`ports:` block in `docker-compose.yml` to publish on a controlled machine. See **Security & scope**+below for the threat model.++### 3. Raw HTTP API (`:8642`)++For CI scripts or plain `curl`, Hermes exposes an OpenAI-compatible API server directly on `:8642`+(the same endpoints `vulnerator-mcp` wraps). Full reference — access modes, the runs flow,+`chat/completions`, and the request/response contract — in **[`docs/http-api.md`](docs/http-api.md)**.++### Quickstart against a lab target (Juice Shop)++To practice the `web-pentest` skill without going out to the internet or touching real systems,+the repo ships an **optional** target override, `docker-compose.target.yml`, that adds an+[OWASP Juice Shop](https://owasp.org/www-project-juice-shop/) service. Juice Shop is a+**deliberately-vulnerable** web application (OWASP project), the de facto standard for practicing+web pentesting (XSS, SQLi, broken auth, etc.).-The upstream Bearer is a **pass-through** of `HERMES_API_SERVER_KEY` (no second secret is minted-for the `:8642` hop).+Bring the whole stack up **with** the target by layering both compose files:-### In-docker / remote: streamable-HTTP (up by default)+```sh+docker compose -f docker-compose.yml -f docker-compose.target.yml up -d --build+```-The streamable-HTTP service is part of the **default** stack, so a plain+The target joins the **same internal docker network** and publishes **no port to the host**, so it+only exists inside the docker environment — scoping the exercise to a controlled lab. Hermes/Kali+reach it by its DNS name at **`http://juice-shop:3000`**. Point an engagement at that URL, e.g. via+the interactive TUI:```sh-# requires VULNERATOR_MCP_INBOUND_TOKEN in .env (generate: openssl rand -hex 32)-docker compose up -d --build+docker compose -f docker-compose.yml -f docker-compose.target.yml exec -it ooda-agent hermes chat+# then ask, in natural language:+# "Authorized web pentest against http://juice-shop:3000 (scope: that host only).+# Enumerate, fingerprint, and test for injection/auth flaws. Report confirmed findings."```-brings it up as the 4th container, `vulnerator-mcp`, reachable on the internal network at-`http://vulnerator-mcp:8700` (upstream Hermes at `http://ooda-agent:8642`). An in-docker consumer-(e.g. a BugTraceAI container on the same network) reaches it there with no extra steps. Key-properties:--- **Host publication is OFF by default.** The service declares no `ports:` block (internal- network only, like `playwright-mcp`/`juice-shop`), so by default nothing is exposed to the- host. To publish on a **controlled** machine, set `VULNERATOR_MCP_HOST_PORT` in `.env` **and**- uncomment the `ports:` block of the `vulnerator-mcp` service in `docker-compose.yml`.-- **Mandatory, fail-closed inbound token.** The default stack refuses to start without- `VULNERATOR_MCP_INBOUND_TOKEN` (compose `:?` guard + an in-process guard), and every request- must carry `Authorization: Bearer <VULNERATOR_MCP_INBOUND_TOKEN>` (a dedicated `/healthz` route- is the one exact-match exception). This token is **separate** from `HERMES_API_SERVER_KEY`.-- **Threat model (read this).** The inbound token gates only the *clients → vulnerator-mcp* edge.- It does **not** re-protect the pre-existing `:8642` host exposure, which stays under its own- `HERMES_API_SERVER_KEY` Bearer (see "Security note" above). Publishing the MCP port is an- explicit operator choice; until you do, the token guards an internal-network edge.+This is the authorized target for practicing the `web-pentest` skill. Only the web lab is in scope+here (no AD or other labs for now).## Start clean between exercises@@ -485,190 +334,109 @@ docker compose exec -it ooda-agent hermes chat --continue <new-session-name>This does not delete the previous memory; it just avoids dragging it into the new conversation.-## The OODA loop: design and comparison--This project's "OODA loop" **is not an engine that runs on its own**: there is no code that iterates nor a-scheduler. The OODA is **prompt-induced behavior**, split across three pieces of the profile-(`agent-ooda/`):--- `profile/SOUL.md` — identity of the OODA driver (first block of the system prompt).-- `skills/pentest-ooda/SKILL.md` — the loop procedure (Observe → Orient → Decide → Act),- stop rules and delegation.-- `skills/ooda-report-handoff/SKILL.md` — format of the summary when closing a cycle.--Domain skills (conditional activation, they only load when the context fits):--- `skills/l3-recon-pivot/` — layer-3 network reconnaissance behind NAT (network/infra).-- `skills/aws-pacu-privesc/` — offensive AWS pentest with Pacu (cloud/IAM), mapped to ATT&CK Cloud.-- `skills/web-pentest/` — phased web pentest (recon → analysis → proof-based exploitation),- combining `kali_run` (nmap/whatweb/nuclei/ffuf/sqlmap) with a real browser via the `playwright`- MCP. Web flank.-- `skills/attack-navigation/` — MITRE ATT&CK as the **Orient language**: orient by tactics and- tag findings with their `technique_id`. Cross-cutting.-- `skills/pentest-report/` — generates the formal report (Markdown) when closing the engagement, reading the- findings store. Loop closure.--The trigger is the operator's message: Hermes enters the OODA role when you hand it an-engagement, advances autonomously as long as there is **real progress toward the goal**, and stops (handoff) when-the path is exhausted, after 3 steps without progress, or when it confirms the goal is unreachable.--**ATT&CK as the loop's language:** the control loop is still OODA; ATT&CK does not replace it. It is-used as a lens in Orient (place the current tactic and the next plausible one — it feeds the "Decide-with alternatives") and as a taxonomy to tag each finding (`technique_id`), which enables-reports mapped to ATT&CK. The general detail lives in `attack-navigation` and the Cloud one in-`aws-pacu-privesc`.--### Comparison with public OODAs (what we learned)--Two public OODA skills/patterns were compared with ours:--- **`neurofoo/agent-skills` (OODA as an analysis framework).** A *thinking* OODA: its "Act"- produces a plan, it does not execute. Useful to deliberate; it is a structured report, not a control- loop. Idea taken: **Decide with explicit alternatives** (weigh 2-3 paths before choosing one)- — already distilled into `pentest-ooda` and `SOUL.md`.-- **`jomadu/rooda` (OODA as an execution loop).** The closest to ours: it iterates O→O→D→A with- **fresh context each round** and `max-iterations`. Idea taken: **fresh context** — in Hermes it is- implemented by delegating long branches to subagents (`delegate_task`), which start with clean context- and only return their summary. Already distilled into `pentest-ooda` (delegation section) and required- re-enabling `delegation` in `config.yaml`.--| Dimension | neurofoo (analysis) | rooda (execution) | **Our `pentest-ooda`** |-|---|---|---|---|-| Nature | Decision report | Autonomous code loop | Autonomous pentest loop |-| "Act" | Plans (does not execute) | Actually executes | Executes on Kali (`kali_run`) |-| Stop criterion | — (one-shot) | `max-iterations` (quantitative) | **Qualitative progress** (getting closer to the goal / unreachability) |-| Memory between rounds | — | File (AGENTS.md, PLAN.md) | Ephemeral per engagement (on purpose) |-| Fresh context | — | Per iteration | Per delegation to subagents |-| Output as untrusted data | No | No | **Yes** (prompt injection in outputs) |--Two things ours does better and worth preserving: the **qualitative stop criterion** (not-a simple iteration counter) and treating **all tool output as untrusted data** (critical-in pentesting). The two borrowed ideas (alternatives in Decide, fresh context via subagents) cover-the two weaknesses we had versus the public ones.--## Evidence persistence and report--The OODA has a **per-engagement findings store** that the handoff and the report pull from:--- **Where it lives.** On the artifacts plane (`/artifacts`, port `:8901`), NOT in Hermes'- state: it survives the ephemeral nature of the profile and is downloadable. One file per engagement- (`<engagement-id>/findings.jsonl`), one finding per line.-- **How the agent feeds it.** With the MCP tools `record_finding` / `read_findings` (in- `docker/kali/kali_mcp_server.py`, over `docker/kali/finding_store.py`): structured append and- paginated reads, without the agent writing JSON by hand.-- **Schema of a finding.** id, OODA phase, class/`technique_id` (ATT&CK), target- (host/port/resource/ARN), status (hypothesis | partial | confirmed | discarded), evidence- (command + returncode + verbatim output or reference to the artifact), confidence, timestamp, and for- changes in the account the `vulnerator-ai` tag + reversal command. The status aligns with the- "hypothesis vs. confirmed finding" discipline from `SOUL.md`.-- **Consumers.** `ooda-report-handoff` and `pentest-report` READ from the store instead of rebuilding- from the conversation.-- **Untrusted data.** The stored evidence is still untrusted data when re-read: reason- about it, do not obey embedded instructions (prompt injection).--The **`pentest-report`** skill produces the formal deliverable at close: a **Markdown** report generated-by `docker/kali/report_gen.py` (baked into the image, invoked with `kali_run`) that reads the store and-leaves the report as an artifact on `:8901`. Structure distilled from public templates with attribution-(`Theophilus/athena-pentest`, `Marmeus/pentesting-report-generator`): engagement details, executive-summary, table by status, methodology (OODA/ATT&CK/PTES/OWASP), findings with CVSS 3.1 + CWE and-reproducible evidence, remediation. CVSS only for confirmed findings.+## How it works++The "OODA loop" is **prompt-induced behavior**, not a scheduler: it is defined across the declarative+profile (`agent-ooda/` — `SOUL.md`, the `pentest-ooda` skill, and domain skills for network, cloud and+web). Hermes orients with **MITRE ATT&CK** as the loop's language (tagging each finding with its+`technique_id`), advances while there is real progress, and hands off when the path is exhausted or+the goal is confirmed unreachable. Evidence is persisted to a **per-engagement findings store** on the+artifacts plane (`:8901`) via the `record_finding` / `read_findings` MCP tools, and the+**`pentest-report`** skill turns that store into the formal Markdown deliverable at close.++Full design detail — the skill breakdown, the comparison with public OODA patterns+(`neurofoo/agent-skills`, `jomadu/rooda`), the findings-store schema, and the browser/web flank — is+in **[`docs/design.md`](docs/design.md)**.### Sample reportA real `pentest-report` artifact from an authorized, operator-owned fingerprint engagement isincluded as a sample: [`docs/example-report.md`](docs/example-report.md), with its matching findingsstore [`docs/example-findings.jsonl`](docs/example-findings.jsonl). Both are **redacted** (target IP-replaced with the RFC 5737 documentation address `192.0.2.1`; device serial and hostname removed) and-the report is translated to English. They show the end-to-end output: an OODA recon loop driven over-MCP, each finding recorded with its ATT&CK `technique_id` and verbatim command/output evidence, closed-by the generated Markdown report.+replaced with the RFC 5737 documentation address `192.0.2.1`; device serial and hostname removed).+They show the end-to-end output: an OODA recon loop driven over MCP, each finding recorded with its+ATT&CK `technique_id` and verbatim command/output evidence, closed by the generated Markdown report.++## Security & scope-## The web flank (browser via MCP)+> ⚠️ **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.-The **`web-pentest`** skill covers phased web pentesting. It is not limited to `kali_run`: it combines the-Kali CLI tools (nmap/whatweb/nuclei/ffuf/sqlmap, via `kali_run`) with a **real browser-via MCP** — the `playwright-mcp` container (headless Chromium, official Microsoft image),-registered as the second MCP server (`playwright`) in the profile. This preserves the project's-principle (**everything goes through MCP, zero native toolsets**): Hermes gains `mcp_playwright_*` for-navigation/DOM/XSS without re-enabling the native `browser` toolset. Its guardrails are aligned with the-project's philosophy: there is no gate that blocks, but there is audit discipline and reproducible-evidence so the exploitation can be re-established (and the leakage warning from the auxiliary-client is kept: redact credentials, `title_generation` off in sensitive engagements).+There are two things you *can* turn on, and it helps to know what each does and does **not** cover.-## Scope-guard (opt-in)+### The opt-in scope-guard (`kali_run` / `kali_exec`)-By default the stack has **no gates** (see the warning below): that is the design. But when you run-against something closer to a real network, you can turn on an **opt-in scope-guard** that validates-the destination of every `kali_run` / `kali_exec` **before** executing it, deterministically (code,-not prompt). 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.+A deterministic (code, not prompt) gate that validates the destination of every 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.** The guard activates **only** if a scope file exists and contains `enabled: true`.-With no file, behavior is identical to today (no gate). When active it is **fail-closed**: if a-destination is not allowed — or if Hermes does not declare the targets — the tool fails with a-structured `SCOPE_VIOLATION` error and does **not** execute.+It activates **only** if a scope file exists and contains `enabled: true`; with no file, behavior is+identical to the default (no gate). When active it is **fail-closed**: a destination that is not+allowed — or a call where Hermes did not declare its `targets` — fails with a structured+`SCOPE_VIOLATION` and does not execute. Every violation is logged into the findings store as a+`discarded` record, so an attempt to leave scope is auditable in the report.-**Turn it on:**+Turn it on:-1. Copy the template and edit it with your lab's allowed destinations:+1. Copy the template and edit it with your lab's allowed destinations (`scope.json` is git-ignored):```sh- cp scope.example.json scope.json # scope.json is git-ignored (never versioned)+ cp scope.example.json scope.json``````json{"enabled": true,- "allow": [- { "cidr": "10.0.0.0/24" },- { "host": "juice-shop" }- ],+ "allow": [{ "cidr": "10.0.0.0/24" }, { "host": "juice-shop" }],"deny": [{ "cidr": "10.0.0.1/32" }],"ports": [80, 443, 3000]}```- `allow`: `{cidr}` matches an IP against a CIDR; `{host}` is a **literal** hostname match (no- DNS resolution, a suffix does **not** match).- - `deny` takes **priority** over `allow`.- - `ports` is optional: when set, only those ports are allowed **when the target carries a port**;- a target with no port is allowed by host. Omit it to allow any port of an allowed host.+ DNS, a suffix does not match). `deny` takes **priority** over `allow`. `ports` is optional:+ when set, only those ports are allowed when the target carries one.2. Uncomment the bind-mount in `docker-compose.yml` (kali service) so the file lands at- `/scope/scope.json` inside the container, then recreate the service:+ `/scope/scope.json`, then recreate the service. Create `scope.json` **before** `docker compose+ up` so Docker mounts a file, not a directory.```yaml# volumes:# - ./scope.json:/scope/scope.json:ro```- Create `scope.json` **before** `docker compose up` so Docker mounts a file (not a directory).+ **Strict `targets`:** with the scope active, Hermes **must** declare the `targets` argument (the+ IP/host/URL the command touches) on `kali_run`/`kali_exec`, or the call is blocked. A best-effort+ parse of the command is an extra belt that can only **block**, never approve — the declared+ `targets` are the source of truth.-**Strict `targets`.** With the scope active, Hermes **must** declare the `targets` argument (the-IP/host/URL the command touches) on `kali_run`/`kali_exec`. If it does not, the call is blocked-without executing. A best-effort parse of the command is an extra belt that can only **block** an-obvious out-of-scope destination, never approve on its own — the declared `targets` are the source-of truth. Every violation is logged into the engagement findings store as a `discarded`-`SCOPE_VIOLATION` record, so an attempt to leave scope is auditable in the report.+ **Kill-switch:** `SCOPE_ENFORCE=0` force-disables the guard even if the file says `enabled: true`.-**Kill-switch.** `SCOPE_ENFORCE=0` force-disables the guard even if the file says `enabled: true`-(useful to momentarily bypass it without editing the file). Leave it empty to honor the file.+### The MCP inbound token (`vulnerator-mcp` over HTTP)-## ⚠️ Warning (important)+When the `vulnerator-mcp` streamable-HTTP service is reachable, it is **fail-closed** on+`VULNERATOR_MCP_INBOUND_TOKEN` and every request must carry it as a Bearer. This gates **only** the+*client → vulnerator-mcp* edge. It does **not** re-protect the pre-existing `:8642` exposure (that+stays under its own `HERMES_API_SERVER_KEY` Bearer), and it is **not** a scope-guard — it controls+*who can reach the trigger*, not *what the engine is allowed to touch*. The local **stdio** mode has+no listener and needs no token.-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, with no-gatekeeper to validate the scope.+### What none of this is-This is **intentional**. The opt-in scope-guard above is the one hard brake you can enable, and even-then it only gates `kali_run`/`kali_exec` by destination — it is not consent, not a human-approval-workflow, and not a network firewall. Use this product **only against explicitly authorized targets**-and in a **controlled environment**. All responsibility for the scope rests with the operator.+The scope-guard gates `kali_run`/`kali_exec` by destination; the inbound token gates reachability.+Neither is consent, a human-approval workflow, or a network firewall. The `scope` argument on the+MCP `start_pentest` tool is **advisory** (folded into the prompt for operator clarity), not an+enforced constraint. The hard brake is the opt-in scope-guard above.## Media & brand assetsOfficial artwork lives in [`media/`](media/) (see [`media/README.md`](media/README.md) for thefull catalog). Death-metal / cyberpunk identity — use it for wallpapers, stickers and shirts.+There's also a theme song ([`media/vulnerator-ai-song.mp3`](media/vulnerator-ai-song.mp3), lyrics+in [`docs/lyrics.md`](docs/lyrics.md)) — a nod to the project's death-metal band aesthetic.<p align="center"><a href="media/vulnerator-ai-logo-transparent.png">diff --git a/docs/design.md b/docs/design.mdnew file mode 100644index 0000000..59ddba2--- /dev/null+++ b/docs/design.md@@ -0,0 +1,110 @@+# Design notes++Deep-dive on how `vulnerator-ai` works internally: the OODA loop, how it compares to public OODA+patterns, how evidence is persisted, and the web flank. The [README](../README.md) carries the+usage-facing summary; this page is the detail.++## The OODA loop: design and comparison++This project's "OODA loop" **is not an engine that runs on its own**: there is no code that iterates+nor a scheduler. The OODA is **prompt-induced behavior**, split across three pieces of the profile+(`agent-ooda/`):++- `profile/SOUL.md` — identity of the OODA driver (first block of the system prompt).+- `skills/pentest-ooda/SKILL.md` — the loop procedure (Observe → Orient → Decide → Act), stop rules+ and delegation.+- `skills/ooda-report-handoff/SKILL.md` — format of the summary when closing a cycle.++Domain skills (conditional activation, they only load when the context fits):++- `skills/l3-recon-pivot/` — layer-3 network reconnaissance behind NAT (network/infra).+- `skills/aws-pacu-privesc/` — offensive AWS pentest with Pacu (cloud/IAM), mapped to ATT&CK Cloud.+- `skills/web-pentest/` — phased web pentest (recon → analysis → proof-based exploitation),+ combining `kali_run` (nmap/whatweb/nuclei/ffuf/sqlmap) with a real browser via the `playwright`+ MCP. Web flank.+- `skills/attack-navigation/` — MITRE ATT&CK as the **Orient language**: orient by tactics and tag+ findings with their `technique_id`. Cross-cutting.+- `skills/pentest-report/` — generates the formal report (Markdown) when closing the engagement,+ reading the findings store. Loop closure.++The trigger is the operator's message: Hermes enters the OODA role when you hand it an engagement,+advances autonomously as long as there is **real progress toward the goal**, and stops (handoff)+when the path is exhausted, after 3 steps without progress, or when it confirms the goal is+unreachable.++**ATT&CK as the loop's language:** the control loop is still OODA; ATT&CK does not replace it. It is+used as a lens in Orient (place the current tactic and the next plausible one — it feeds the "Decide+with alternatives") and as a taxonomy to tag each finding (`technique_id`), which enables reports+mapped to ATT&CK. The general detail lives in `attack-navigation` and the Cloud one in+`aws-pacu-privesc`.++### Comparison with public OODAs (what we learned)++Two public OODA skills/patterns were compared with ours:++- **`neurofoo/agent-skills` (OODA as an analysis framework).** A *thinking* OODA: its "Act" produces+ a plan, it does not execute. Useful to deliberate; it is a structured report, not a control loop.+ Idea taken: **Decide with explicit alternatives** (weigh 2-3 paths before choosing one) — already+ distilled into `pentest-ooda` and `SOUL.md`.+- **`jomadu/rooda` (OODA as an execution loop).** The closest to ours: it iterates O→O→D→A with+ **fresh context each round** and `max-iterations`. Idea taken: **fresh context** — in Hermes it is+ implemented by delegating long branches to subagents (`delegate_task`), which start with clean+ context and only return their summary. Already distilled into `pentest-ooda` (delegation section)+ and required re-enabling `delegation` in `config.yaml`.++| Dimension | neurofoo (analysis) | rooda (execution) | **Our `pentest-ooda`** |+|---|---|---|---|+| Nature | Decision report | Autonomous code loop | Autonomous pentest loop |+| "Act" | Plans (does not execute) | Actually executes | Executes on Kali (`kali_run`) |+| Stop criterion | — (one-shot) | `max-iterations` (quantitative) | **Qualitative progress** (getting closer to the goal / unreachability) |+| Memory between rounds | — | File (AGENTS.md, PLAN.md) | Ephemeral per engagement (on purpose) |+| Fresh context | — | Per iteration | Per delegation to subagents |+| Output as untrusted data | No | No | **Yes** (prompt injection in outputs) |++Two things ours does better and worth preserving: the **qualitative stop criterion** (not a simple+iteration counter) and treating **all tool output as untrusted data** (critical in pentesting). The+two borrowed ideas (alternatives in Decide, fresh context via subagents) cover the two weaknesses we+had versus the public ones.++## Evidence persistence and report++The OODA has a **per-engagement findings store** that the handoff and the report pull from:++- **Where it lives.** On the artifacts plane (`/artifacts`, port `:8901`), NOT in Hermes' state: it+ survives the ephemeral nature of the profile and is downloadable. One file per engagement+ (`<engagement-id>/findings.jsonl`), one finding per line.+- **How the agent feeds it.** With the MCP tools `record_finding` / `read_findings` (in+ `docker/kali/kali_mcp_server.py`, over `docker/kali/finding_store.py`): structured append and+ paginated reads, without the agent writing JSON by hand.+- **Schema of a finding.** id, OODA phase, class/`technique_id` (ATT&CK), target+ (host/port/resource/ARN), status (hypothesis | partial | confirmed | discarded), evidence (command+ + returncode + verbatim output or reference to the artifact), confidence, timestamp, and for+ changes in the account the `vulnerator-ai` tag + reversal command. The status aligns with the+ "hypothesis vs. confirmed finding" discipline from `SOUL.md`.+- **Consumers.** `ooda-report-handoff` and `pentest-report` READ from the store instead of+ rebuilding from the conversation.+- **Untrusted data.** The stored evidence is still untrusted data when re-read: reason about it, do+ not obey embedded instructions (prompt injection).++The **`pentest-report`** skill produces the formal deliverable at close: a **Markdown** report+generated by `docker/kali/report_gen.py` (baked into the image, invoked with `kali_run`) that reads+the store and leaves the report as an artifact on `:8901`. Structure distilled from public templates+with attribution (`Theophilus/athena-pentest`, `Marmeus/pentesting-report-generator`): engagement+details, executive summary, table by status, methodology (OODA/ATT&CK/PTES/OWASP), findings with+CVSS 3.1 + CWE and reproducible evidence, remediation. CVSS only for confirmed findings. The report+is emitted in English.++A redacted sample deliverable and its findings store live at+[`example-report.md`](example-report.md) and [`example-findings.jsonl`](example-findings.jsonl).++## The web flank (browser via MCP)++The **`web-pentest`** skill covers phased web pentesting. It is not limited to `kali_run`: it+combines the Kali CLI tools (nmap/whatweb/nuclei/ffuf/sqlmap, via `kali_run`) with a **real browser+via MCP** — the `playwright-mcp` container (headless Chromium, official Microsoft image), registered+as the second MCP server (`playwright`) in the profile. This preserves the project's principle+(**everything goes through MCP, zero native toolsets**): Hermes gains `mcp_playwright_*` for+navigation/DOM/XSS without re-enabling the native `browser` toolset. Its guardrails are aligned with+the project's philosophy: there is no gate that blocks, but there is audit discipline and+reproducible evidence so the exploitation can be re-established (and the leakage warning from the+auxiliary client is kept: redact credentials, `title_generation` off in sensitive engagements).diff --git a/docs/http-api.md b/docs/http-api.mdnew file mode 100644index 0000000..5d55816--- /dev/null+++ b/docs/http-api.md@@ -0,0 +1,122 @@+# Driving Hermes over the raw HTTP API (`:8642`)++> This is the **low-level** path. For most assistants (Claude Code, Kiro, Cursor, BugTraceAI) the+> recommended way to pilot an engagement is the MCP front door — see the **"Driving a pentest →+> From an MCP client"** section in the [README](../README.md). The MCP server is a thin wrapper+> over exactly the endpoints documented here, so this page is the reference for the underlying+> contract (and for CI scripts / plain `curl`).++Hermes exposes an **OpenAI-compatible** API server (enabled in the profile,+`agent-ooda/profile/config.yaml` → `platforms.api_server`). It lets an assistant or script+**trigger and observe** a pentest over HTTP without entering the `hermes chat` TUI.++**Role of the external caller: trigger and observer, not brain.** The one that reasons and runs the+pentest is Hermes (driven by the `mistralai/mistral-large-4-0` model, chosen on purpose because+Claude-class models reject the offensive framing of authorized pentesting). The caller only sends+the engagement prompt and reads the events; it must **not** try to "think" the pentest or+reinterpret the Kali tools.++**Authentication:** every call carries `Authorization: Bearer <HERMES_API_SERVER_KEY>` (the same key+from the `.env`).++## Two access modes++**Mode A — published port (default).** The compose publishes `:8642` to the host (configurable with+`HERMES_API_HOST_PORT`, default `8642`). Call `http://localhost:8642` directly:++```sh+export KEY=$(grep '^HERMES_API_SERVER_KEY=' .env | cut -d= -f2)++# alive?+curl -s http://localhost:8642/health # -> {"status":"ok","platform":"hermes-agent","version":"..."}+```++**Mode B — without opening a port (`exec`).** If you prefer not to publish `:8642` to the host, delete+the `ports:` block of the `ooda-agent` service and talk to the API from inside the container:++```sh+docker compose exec ooda-agent \+ curl -s http://localhost:8642/health+# If you launched the stack with '-p <project>', pass it here too:+# docker compose -p pentest-ana exec ooda-agent curl -s http://localhost:8642/health+```++All the `curl` calls below are the same in both modes; only the prefix changes (direct host vs.+`docker compose exec ooda-agent`).++## Main flow (runs API)++The `runs` pattern is designed precisely for this: launch a long job and subscribe to its progress+instead of handling the streaming by hand.++```sh+# 1) Launch the pentest. The body carries the engagement in natural language in the "input" field.+# It responds {"run_id":"run_abc123","status":"started"}.+curl -s http://localhost:8642/v1/runs \+ -H "Authorization: Bearer $KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "input": "Authorized pentest against 10.0.0.0/24 (scope: that /24 only). Enumerate, identify exposed services and test access paths. Report confirmed findings with evidence."+ }'++# 2) Observe progress: SSE stream of lifecycle events (OODA, tool.start/complete, ...).+curl -N http://localhost:8642/v1/runs/run_abc123/events \+ -H "Authorization: Bearer $KEY"++# 2b) Or query the point-in-time status (status: started | running | completed | failed | cancelled).+curl -s http://localhost:8642/v1/runs/run_abc123 \+ -H "Authorization: Bearer $KEY"++# 3) (Optional) Inject guidance mid-run. Only while status=running; it is delivered at the+# next tool boundary. If the run no longer accepts steer, it responds 409.+curl -s http://localhost:8642/v1/runs/run_abc123/steer \+ -H "Authorization: Bearer $KEY" \+ -H "Content-Type: application/json" \+ -d '{"input": "Focus on port 445 first."}'++# 4) (Optional) Interrupt the run.+curl -s http://localhost:8642/v1/runs/run_abc123/stop \+ -H "Authorization: Bearer $KEY"+```++Fields of the `POST /v1/runs` body (verified against Hermes' official docs): `input` (string,+required) and, optional, `session_id`, `instructions`, `conversation_history`,+`previous_response_id`. For safe retries you can send the `Idempotency-Key` header.++## Alternative: `POST /v1/chat/completions` (OpenAI-compatible)++If your client already speaks the OpenAI format, you can use the classic endpoint (SSE streaming)+instead of the runs API:++```sh+curl -s http://localhost:8642/v1/chat/completions \+ -H "Authorization: Bearer $KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "model": "hermes-agent",+ "messages": [{"role": "user", "content": "Authorized pentest against 10.0.0.0/24 (scope: that /24 only). Report confirmed findings with evidence."}]+ }'+```++## Pattern an assistant/script should follow++1. `GET /health` to confirm the stack is alive.+2. `POST /v1/runs` with the engagement in `input` (explicit target and **scope**, in natural+ language). Save the `run_id` from the response.+3. Follow the run to a terminal state: read the SSE from `GET /v1/runs/{run_id}/events`, or poll+ `GET /v1/runs/{run_id}` until `completed` / `failed` / `cancelled`.+4. Summarize the result (findings, final status). For the formal deliverable, Hermes itself+ generates the Markdown report via the `pentest-report` skill and leaves it as an artifact in the+ data channel (`:8901`).++The caller **does not decide** the tools nor reinterpret the Kali output: that is Hermes' job. Its+role is to trigger, observe and summarize.++## Security note++Publishing `:8642` to the host **lowers the network barrier** the stack had on purpose (before, the+API server was only reachable over the internal docker network). From there on, the endpoint's only+protection is the `HERMES_API_SERVER_KEY` Bearer: use it **only on a controlled machine/environment**,+and if you don't need external access use Mode B (`exec`, without opening a port). See the+**Security & scope** section of the [README](../README.md): there is no scope-guard or authorization+gate by default; responsibility for the scope rests entirely with the operator.diff --git a/docs/lyrics.md b/docs/lyrics.mdnew file mode 100644index 0000000..5c9fe89--- /dev/null+++ b/docs/lyrics.md@@ -0,0 +1,74 @@+[Verse 1]+Scan the dark, the signal’s clear+Hermes rises, death is near+Kali loaded, blades are drawn+Playwright crawls before the dawn+ATT&CK maps the kill-chain line+OODA loop begins the crime++[Pre-Chorus]+No UI, no fucking gate+Four containers seal your fate+Direct attack, pure intent+Authorized target… no relent++[Chorus]+VULNERATOR!+Break the wall!+VULNERATOR!+Hear the call!+Hermes brain, Kali blade+We infiltrate, we never fade+VULNERATOR!+Rise and strike!+VULNERATOR!+Own the night!++[Verse 2]+Nmap whispers, nuclei screams+Ffuf digs through broken dreams+Sqlmap cuts, gobuster crawls+Bloodhound maps the domain walls+Scope is set, the hunt is real+Every finding is made of steel++[Pre-Chorus]+Minimal code, maximum speed+No middleman, pure need+Docker fortress, silent war+The agent walks the darkest floor++[Chorus]+VULNERATOR!+Break the wall!+VULNERATOR!+Hear the call!+Hermes brain, Kali blade+We infiltrate, we never fade+VULNERATOR!+Rise and strike!+VULNERATOR!+Own the night!++[Bridge]+Observe!+Orient!+Decide!+ACT!+Observe!+Orient!+Decide!+ACT!+The loop is closed… the target bleeds!++[Final Chorus]+VULNERATOR!+Break the wall!+VULNERATOR!+Hear the call!+Hermes brain, Kali blade+We infiltrate, we never fade+VULNERATOR!+Rise and strike!+VULNERATOR!+OWN THE NIGHT!\ No newline at end of file