# Keel
### The MCP control plane that turns scanner noise into hunter-grade, non-destructive proofs
[](https://www.python.org/)
[](https://github.com/lutfizp/keel/blob/main/LICENSE)
[](https://modelcontextprotocol.io/)
[](https://pypi.org/project/keel-pentest/)
[](https://github.com/lutfizp/keel)
[](https://github.com/lutfizp/keel)
**Thirteen MCP tools. Semantic dedup. Per-host rate limits. Safe proofs that show what a hunter can do โ without damaging the target.**
[Why Keel](#why-keel) ยท [Install](#installation) ยท [Clients](#mcp-client-setup) ยท [Proofs](#safe-proofs-that-still-prove-impact) ยท [Tools](#mcp-tools)
---
Dumping 150 tools on an agent is easy. The hard problems are **dedup across tools**, **exploitable vs noise**, and **not hammering the target**. Keel is the control plane for those three.
An AI client talks to Keel, not to `httpx`, `nuclei`, or a shell. Keel drafts one wave at a time, enforces scope and rate limits, merges scanner hits into semantic cards, and runs **GET-only playbooks on tester-owned data**. When a playbook returns `proven`, you get a curl replay a hunter can follow โ still without writes, shells, or payload spam.
Use it on programs you are authorized to test.
## Why Keel
| Hard problem | What scanner dumps do | What Keel does |
|---|---|---|
| Dedup across tools | One Nuclei template id per row; the same IDOR appears five times | Semantic key from vulnerability class + normalized route + method + parameter. UUID/id/hex tokens collapse. Compatible observations merge. |
| Exploitable vs noise | High severity = "ship it" | Cards move through `observed` โ `hypothesis` โ `corroborated` โ `proven` / `refuted`. Informational and hardening stay hidden. Typed exploitability names the missing evidence and the negative control. |
| Not hammering the target | Fire every template at once, retry on 429 | One active wave per host, token buckets, Nuclei concurrency 1, no OAST, no redirects, no unsigned templates, no dos/fuzz/bruteforce/intrusive tags. HTTP 429 becomes a cooldown. |
A wrapper that shells out to a huge toolbox does not have that layer. Keel does โ in the scheduler, in the adapters, and in the proof broker.
## Architecture
```mermaid
flowchart TD
A[AI coding client] -->|stdio MCP| B[Keel]
B --> C[Scope and rate gate]
C --> W[Background job and wave scheduler]
W --> H[httpx: one target]
W --> N[nuclei: HTTP templates, bounded]
C --> P[Proof broker: GET only]
P --> T[Tester-owned resource]
H --> S[Semantic card store]
N --> S
P --> S
S --> Q[Triage and evidence states]
```
1. `begin_engagement` with the hostname you are authorized to test.
2. `draft_waves` proposes reachability plus template micro-waves. No traffic yet.
3. `execute_wave` returns a job immediately. Poll `wave_status`. `cancel_wave` kills the scanner.
4. `query_cards` returns hunter-relevant cards. `assess_exploitability` says what would prove it.
5. `draft_proof` then `execute_proof` run a GET-only playbook against tester data. `proven` means the invariant held. `protected` means the control worked.
## Installation
macOS (Homebrew). `pipx` is a separate tool โ install it first. Apple's `/usr/bin/python3` is often 3.9 and cannot install Keel.
```bash
brew install pipx python@3.12
pipx ensurepath
# open a new terminal, then:
pipx install keel-pentest
keel-pentest setup
keel-pentest doctor
```
If `python3.12` is already on the machine and you do not want Homebrew pipx:
```bash
python3.12 -m pip install --user pipx
python3.12 -m pipx ensurepath
python3.12 -m pipx install keel-pentest
```
`setup` downloads ProjectDiscovery `httpx` and `nuclei` into `~/.keel/bin`. Keel finds them there even when a GUI client has a thin `PATH`. No extra `KEEL_HTTPX_BIN` for a first scan.
Then point your MCP client at the `keel-pentest` executable:
```bash
claude mcp add --scope user --transport stdio keel -- keel-pentest
codex mcp add keel -- keel-pentest
hermes mcp add keel --command keel-pentest
```
OpenCode: `"command": ["keel-pentest"]`.
Python 3.10+. Do not `pip install keel` โ that is a different project. OS notes and pip/venv: [INSTALL.md](https://github.com/lutfizp/keel/blob/HEAD/INSTALL.md). Client shapes: [clients/README.md](https://github.com/lutfizp/keel/blob/HEAD/clients/README.md).
Optional later: `KEEL_APPROVAL_FILE` for a team manifest that pins scope, template IDs, and proof targets. Default mode is self-attested โ `begin_engagement` is the authorization. Rate limits, one-wave-per-host, signed templates, and sanitized evidence still apply.
## Safe proofs that still prove impact
Scanner output is a hypothesis. Keel proves (or refutes) it with disposable tester accounts and a unique canary. Every playbook is GET-only, budgeted, and returns a curl replay. The replay is the report artifact: *if this is not fixed, a hunter with a normal account can do this*.
| Playbook | Proves | How, without damage |
|---|---|---|
| `cross_account_read` | IDOR / BOLA | Tester A reads its canary; tester B GETs the same A-owned URL. Identical canary + 2xx = `proven`. 401/403/404 or 2xx without the canary = `protected` (refuted). |
| `reflected_marker` | Reflected XSS / HTML injection | Inject a unique marker plus a harmless `