KhaosMCP

Khaos in pixel art font with VHS glitch, Matrix code and its lizard mascot wearing glasses

🌐 Website · 📚 Documentation · 🏗️ Architecture · 🔌 API · 🛡️ Security · 🤖 MCP

Local-first pentest platform operated by an AI agent via MCP. KhaosMCP connects the external operator to the full assessment lifecycle: scope, supervised execution, integrations, evidence, finding review, and reporting.

Visual identity: see the brand guide, the asset catalog, and download the complete pack.

Use Khaos only on systems you own or have explicit authorization to test. The tool does not grant authorization; the operator is responsible for registering and respecting the assessment rules of engagement.

What you get

Area	Features
Projects & scope	Targets, authorization rules, WAF bypass config, exclusions, limits, and per-assessment history
Execution	Stage orchestration, checkpoints, events, assessment resumption, and MCP control
Toolbox	Tool catalog (static + fetchable), readiness checks, audited adapters, and wordlists
MCP operation	TypeScript MCP server — Claude Code and Codex as external operators; 111 skills in catalog
Evidence & findings	Sanitized capture, hash integrity, reviewable candidates, attack chains, and retests
Reporting & learning	Technical and executive reports (with attack-chain section), reusable skills, and assessment metrics
Providers	Explicit provider and model selection per assessment

Quick start

Requirements

Docker Desktop or Docker Engine with Docker Compose v2.
Node.js 20+ and npm.
Git.
Claude Code or Codex as operator.

One command

irm https://raw.githubusercontent.com/henriqqw/KhaosMCP-Pentester-Agent/main/install.ps1 | iex

The script clones the repo to ~/khaos, auto-generates secrets, builds the MCP
server, writes .mcp.json, and starts the backend. When it finishes, restart
Claude Code — the khaos_* tools appear automatically.

Override the install directory:

$env:KHAOS_DIR = "C:\projects\khaos"
irm https://raw.githubusercontent.com/henriqqw/KhaosMCP-Pentester-Agent/main/install.ps1 | iex

Manual setup (already cloned)

.\setup.ps1          # builds MCP + writes .mcp.json
docker compose up -d # starts postgres, redis, backend

Connect Codex

Add the entry to %USERPROFILE%\.codex\config.toml as described in
docs/operator-mcp.md and restart.

Shut down

docker compose down      # preserves volumes (data is kept)
docker compose down -v   # removes volumes (deletes all local data)

How it works

flowchart LR
    MCP[External MCP Agent] <-->|stdio and REST| API[Go + Gin API]
    API --> ORQ[Orchestrator and agents]
    ORQ --> RUNNER[Runner and scoped adapters]
    RUNNER --> TOOLS[Available tools]
    API --> DB[(PostgreSQL)]
    API --> REDIS[(Redis)]
    API --> FILES[Local data, wordlists and evidence]

The backend validates scope and authorization per action, records events, and applies readiness gates before enabling integrations. Tool results are handed off for review; findings require evidence and human validation. Tools that do not meet the execution contract are unavailable and appear as coverage gaps.

Stack

Layer	Technology	Role
API & orchestration	Go 1.27, Gin	REST API, runner, agents, policies, and services
MCP server	Node.js, TypeScript, MCP SDK	stdio transport between external agent and local API
Persistence	PostgreSQL 16	Projects, assessments, events, evidence, and reports
Coordination	Redis 7	Auxiliary service in the Compose environment
Local environment	Docker Compose	Service and dependency startup
Tests & quality	Go test, go vet, TypeScript	Checks run in CI

Development

Backend

With PostgreSQL and Redis available as configured in .env:

cd backend
go run ./cmd/khaos

MCP server

On a fresh clone, just run .\setup.ps1 at the root — it compiles and generates .mcp.json.
To build manually without generating .mcp.json:

cd mcp
npm ci
npm run build

See Claude / Codex as MCP operator for configuration details.
Claude Code uses .mcp.json at the root; Codex uses .codex/config.toml.
The .mcp.json.example at the root serves as a reference if you prefer to create it manually.

Security and current limitations

The supported mode is local-first and single-user; the API does not offer web authentication for multiple users.
Keep the service on loopback/local. Any remote exposure requires designing proper authentication, TLS, CORS, WebSocket origin, and network controls.
Each assessment must have valid authorization and scope. Active or intrusive resources require configuration and confirmation consistent with the engagement rules.
Not every catalog item is ready on every installation. Check readiness in Khaos; do not execute blocked binaries directly to bypass controls.
Findings are candidates until evidence and human review support the conclusion.

Read the security model and the authorization and evidence architecture before configuring assessments.

Documentation

CI

GitHub Actions runs go test ./... and go vet ./... on the backend. The MCP maintains its own Node tests; see mcp/package.json for available commands.

License

This repository does not yet declare an open source license. Until a license is added, all rights are reserved by the code owner.