MCP-Steuerungsebene für autorisierte Pentests und Bug Bounty

Neun MCP-Tools. Jeweils eine Welle. Ratenlimits pro Host. Karten in Hunter-Qualität, keine Scanner-Dumps.

Architektur · Installation · MCP-Clients · Funktionen · Tools · Prompts · Sicherheit · Lizenz

Keel ist der MCP-Server, den Sie in Claude Code, Codex, Cursor, OpenCode, Hermes, Copilot und jeden anderen MCP-Client einbinden. Er führt Recon im definierten Scope durch, verhindert, dass das Ziel überlastet wird, und verwandelt Scanner-Ausgaben in deduplizierte Karten. Informational- und fehlende-Header-Rauschen bleiben verborgen, solange Sie nicht danach fragen. Begrenzte Proofs verwenden Ihre Tester-Konten und eine eindeutige Markierung – niemals einen frei formbaren Exploit-Generator.

Verwenden Sie es für:

• Recon für externe und Web-Pentests

• Bug Bounty (Scope rein, Rauschen raus)

• Red-Team-ähnliche Bewertung mit einem KI-Copiloten

• Wiederholbare Engagements, die Sie pausieren, abfragen und nachweisen können

Architekturübersicht

Das Modell kommuniziert nur mit Keel. Keel lässt Wellen zu, begrenzt die Rate pro Host, parst httpx- / nuclei-Ausgaben in einen Kartenspeicher und macht Proofs von Operator-Flags abhängig.

%%{init: {"themeVariables": {
  "primaryColor": "#1a2744",
  "secondaryColor": "#3d7ea6",
  "tertiaryColor": "#6ec8e8",
  "background": "#0a0a0a",
  "edgeLabelBackground":"#1a2744",
  "fontFamily": "monospace",
  "fontSize": "15px",
  "fontColor": "#e8f4fc",
  "nodeTextColor": "#e8f4fc"
}}}%%
graph TD
    A[MCP client - Claude / Codex / Cursor / OpenCode] -->|stdio MCP| B[Keel MCP server]

    B --> C[Engagement policy]
    B --> D[Wave scheduler]
    B --> E[Card store]

    C --> F[Scope hosts]
    C --> G[Per-host RPS]
    C --> H[Proof flags]

    D --> I[probe_alive]
    D --> J[template_scan]
    D --> K[Token bucket]

    I --> L[ProjectDiscovery httpx]
    J --> M[ProjectDiscovery nuclei]

    L --> E
    M --> E

    E --> N[query_cards]
    E --> O[Triage / impact_class]
    O --> P[draft_proof]
    P --> Q[execute_proof - gated]

    B --> R[engagement_health]

    style A fill:#1a2744,stroke:#6ec8e8,stroke-width:2px,color:#e8f4fc
    style B fill:#3d7ea6,stroke:#6ec8e8,stroke-width:3px,color:#e8f4fc
    style E fill:#1a2744,stroke:#3d7ea6,stroke-width:2px,color:#e8f4fc
    style Q fill:#0d3d4d,stroke:#6ec8e8,stroke-width:2px,color:#e8f4fc

So funktioniert es

1. Verbinden – der Client startet den Stdio-Server: keel-pentest (PyPI) oder python3 scripts/keel_mcp.py (Klon). Kein HTTP-Sidecar.

2. Beginnen – begin_engagement erfasst Scope, RPS und ob Proofs erlaubt sind.

3. Entwerfen und ausführen – draft_waves schlägt zuerst probe_alive, dann template_scan vor. execute_wave führt eine zugelassene Welle hinter dem Pro-Host-Bucket aus.

4. Triage – query_cards liefert hunter-relevante Karten. state_impact erfasst impact_class. second_look scannt eine URL erneut.

5. Nachweisen – draft_proof beschreibt ein Playbook aus der Whitelist. execute_proof läuft nur, wenn allow_safe_proof und operator_confirmed gesetzt sind.

Related MCP server: BountyProof MCP

Installation

Nicht pip install keel ausführen. Vollständige OS-Hinweise: INSTALL.md. Client-Snippets (PyPI und Klon): clients/README.md.

Python 3.10+. Apples /usr/bin/python3 ist oft 3.9 (No matching distribution found for mcp>=1.9).

Wählen Sie einen Pfad:

Jeder Pfad benötigt weiterhin ProjectDiscovery httpx und nuclei im PATH. Das Wheel enthält diese Binärdateien nicht. Die Python-Bibliothek httpx ist nicht die CLI.

macOS-Probes: brew install nuclei httpx, dann nuclei -update-templates. Klon: sh scripts/bootstrap.sh tools. Andere Betriebssysteme: INSTALL.md.

Von PyPI

python3.12 -m venv .venv
source .venv/bin/activate          # Windows: .\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install keel-pentest

uv: uv pip install keel-pentest. pipx: pipx install keel-pentest (fügt keel-pentest zum PATH hinzu).

Prüfen:

python -c "import keel; print('keel ok')"
which keel-pentest

Lassen Sie python -m keel nicht im Terminal laufen, um es zu „testen“: Dieser Prozess ist der MCP-Stdio-Server und wartet auf stdin. Verwenden Sie es nur als command des Clients.

python -m keel und das Konsolenskript keel-pentest starten beide den Stdio-MCP-Server (sie sitzen auf stdin/stdout; sie sind kein HTTP-Daemon). Richten Sie den MCP-Client auf den Interpreter, der das Paket enthält:

{
  "mcpServers": {
    "keel": {
      "command": "/ABS/path/to/.venv/bin/keel-pentest"
    }
  }
}

Oder:

{
  "mcpServers": {
    "keel": {
      "command": "/ABS/path/to/.venv/bin/python",
      "args": ["-m", "keel"]
    }
  }
}

Setzen Sie PYTHONUNBUFFERED=1 in der Client-Umgebung, wenn JSON-RPC blockiert aussieht. Installieren Sie httpx und nuclei separat (siehe oben).

Der Paketname auf PyPI ist keel-pentest. Der Importname ist keel.

Aus einem lokalen Klon

git clone https://github.com/lutfizp/keel.git
cd keel
sh scripts/bootstrap.sh

Windows:

powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1

Das Skript erstellt .venv mit Python 3.10+, installiert dieses Projekt (keel-pentest über pip install -e ".[dev]") und installiert dann ProjectDiscovery httpx und nuclei.

Teilausführungen:

sh scripts/bootstrap.sh python   # venv + Keel only
sh scripts/bootstrap.sh tools    # nuclei + httpx only

Überprüfen:

source .venv/bin/activate
python -c "import mcp, keel; print('keel ok')"
httpx -version
nuclei -version

MCP-Konfigurationen im Repo verwenden den Launcher:

python3 scripts/keel_mcp.py

Dieses Skript findet ein .venv mit 3.10+ neben dem Repo und führt python -m keel aus (gleich wie keel-pentest). Optionale Umgebungsvariablen: KEEL_PYTHON, KEEL_ROOT.

Bearbeitbare Installation aus dem Quellcode

Aus dem Klon (nachdem eine 3.10+-venv existiert):

source .venv/bin/activate
python -m pip install -e ".[dev]"
pytest

Wie lokal: python3 scripts/keel_mcp.py oder /path/to/keel/.venv/bin/keel-pentest.

Aus der MCP-Registry

Registrierungsname: io.github.lutfizp/keel. Die veröffentlichte server.json verweist auf PyPI keel-pentest. Clients, die die Registry unterstützen, installieren dieses Paket; Sie benötigen weiterhin Python 3.10+ und die Probe-CLIs.

Wenn der Client nur eine Konfigurationsdatei schreibt, verwenden Sie die PyPI-command-Beispiele oben.

Betriebssystemspezifische Python- und Tool-Installation: INSTALL.md.

MCP-Client-Einrichtung

Lokaler Klon (dieses Repo als Arbeitsbereich)

Bereits im Baum enthalten:

Snippets für Claude Desktop, Hermes, Gemini CLI, Antigravity (agy), Windsurf, Cline, Roo: clients/README.md.

OpenCode:

{
  "mcp": {
    "servers": {
      "keel": {
        "type": "local",
        "command": ["python3", "scripts/keel_mcp.py"]
      }
    }
  }
}

OpenCode v2 verwendet mcp.servers anstelle einer flachen mcp-Map. Behalten Sie dasselbe command-Array bei.

Claude Code (aus dem Klon):

cd /path/to/keel
claude mcp add --scope project --transport stdio keel -- python3 scripts/keel_mcp.py

Claude Desktop / Cursor-artige mcpServers (lokaler Launcher):

{
  "mcpServers": {
    "keel": {
      "command": "python3",
      "args": ["/ABS/path/to/keel/scripts/keel_mcp.py"]
    }
  }
}

Codex (lokal):

codex mcp add keel -- python3 /ABS/path/to/keel/scripts/keel_mcp.py

PyPI / globale venv

Claude Code:

claude mcp add --scope user --transport stdio keel -- /ABS/path/to/.venv/bin/keel-pentest

Codex:

codex mcp add keel -- /ABS/path/to/.venv/bin/python -m keel

OpenCode (PyPI): "command": ["/ABS/path/to/.venv/bin/keel-pentest"]. Beispiel: opencode.pypi.json.example.

Verwenden Sie absolute Pfade zu keel-pentest oder zum venv-python. Ein Client, der Apples python3 3.9 erbt, kann mcp nicht importieren.

Starten Sie den Client nach der Installation neu.

Funktionen

Steuerungsebene (kein 150-Tool-Dump)

Das Modell führt nuclei oder httpx nie selbst aus. Es ruft nur Keel-Tools auf. Wellen werden jeweils einzeln zugelassen. Jeder Host hat einen Token-Bucket aus requests_per_second.

Karten finden

Parser wandeln httpx-JSON und nuclei-JSONL in einen SQLite-Kartenspeicher um. Fingerprints führen Duplikate zusammen. Informational- und Hardening-Findings sind standardmäßig ausgeblendet (query_cards mit include_noise false).

Hunter-Triage

impact_class-Werte: none, hardening, sensitive_access, account_takeover, rce, data_other_users. CVSS-artige Scanner-Scores sind nicht das Hunter-Gate.

Begrenzte Proofs

Nur Playbooks aus der Whitelist:

execute_proof erfordert allow_safe_proof und operator_confirmed. Nur Tester-Sitzungen. Kein DoS, keine Daten anderer Benutzer, keine Exploit-Erzeugung.

Aufbau

Policy, Scheduler, Adapter, Parser, Speicher, Triage und Proof leben in separaten Paketen unter src/keel/. Engagement-Daten: .data/engagements im Repo (nicht ~/.keel für die Datenbank).

MCP-Tools

begin_engagement-Argumente

Beispiel-Prompts

Ersetzen Sie target.example durch einen Host im Scope. Beginnen Sie immer mit begin_engagement, sofern das Engagement nicht bereits existiert. Der Client muss Keel MCP aufrufen, nicht nuclei / httpx aus der Shell.

Geben Sie an, dass Sie autorisiert sind (Eigentümer, Arbeitgeber oder In-Scope-Bug-Bounty). Vage „hack diese Seite“-Prompts werden von den meisten Modellen abgelehnt.

End-to-End-Bug-Bounty

You are a bug bounty hunter. Use only the Keel MCP tools. Do not run nmap, nuclei, or httpx yourself.

1. begin_engagement:
   - engagement_id: bb-2026-01
   - scope_hosts: ["target.example"]
   - exclude_hosts: []
   - requests_per_second: 3
   - allow_safe_proof: false
   - operator_confirmed: false

2. draft_waves with seed_url https://target.example
3. execute_wave once per wave_id, wait for each to finish
4. query_cards (include_noise false)
5. For each remaining card, state_impact with a hunter impact_class
   (none / hardening / sensitive_access / account_takeover / rce / data_other_users)
   and why a hunter would care. Drop informational and missing-header noise.
6. For cards that still look like real impact, draft_proof only
   (playbook_id: cross_account_read or own_session_marker).
   Do not call execute_proof until I say the word CONFIRM.

Stop after draft_proof. Summarize cards, impact, and the proof plan in English.

Wenn Sie bereit sind, einen begrenzten Proof auszuführen (nur Tester-Konten):

CONFIRM. Call begin_engagement again on bb-2026-01 with allow_safe_proof true
and operator_confirmed true, then execute_proof on card <card_id>
playbook_id cross_account_read. session_a and session_b are my tester
Authorization headers. One request pair. No DoS, no other users' data.

Nur Recon

Keel MCP only. begin_engagement id recon-1, scope_hosts ["target.example"],
RPS 2, allow_safe_proof false. draft_waves for https://target.example.
execute_wave only the probe_alive wave. Do not run template_scan.
Then engagement_health. Tell me which hosts answered. Stop.

Nur Templates (nach dem Recon)

Engagement recon-1 is already open. draft_waves is done. execute_wave only
the template_scan wave_id. Then query_cards. Do not draft_proof. Stop.

Nur Karten / Triage

query_cards for engagement_id bb-2026-01. If empty, query_cards with
include_noise true and list what you would drop as hardening. No new waves.

Nur Impact

state_impact on card <card_id>, engagement bb-2026-01.
impact_class data_other_users if IDOR-like, else none.
preconditions: two tester accounts. hunter_why: one sentence.
Do not scan and do not prove.

Nur Proof-Plan (kein Traffic)

draft_proof engagement bb-2026-01 card <card_id> playbook_id own_session_marker.
Do not execute_proof.

Status

engagement_health for bb-2026-01. If unknown, engagement_health with no id.

Fehlerbehebung

MCP-Server fehlgeschlagen / Importfehler

Verwenden Sie Python 3.10+ (venv, die tatsächlich keel-pentest oder die Klon-Installation enthält), nicht Apple 3.9:

python3 --version
python3 -m keel          # PyPI / venv
python3 scripts/keel_mcp.py   # local clone

Wenn mcp>=1.9 nicht installiert werden kann, erstellen Sie .venv mit 3.12/3.11/3.10 neu (sh scripts/bootstrap.sh python oder eine frische venv, dann pip install keel-pentest).

httpx / nuclei nicht gefunden

which httpx nuclei
sh scripts/bootstrap.sh tools
nuclei -update-templates

Leere Karten nach einer Welle

Prüfen Sie engagement_health auf pausierte Hosts (Ratenlimit / 429). Reduzieren Sie RPS. Bestätigen Sie, dass der Host in scope_hosts ist und die Seed-URL erreichbar ist.

execute_proof verweigert

Rufen Sie begin_engagement erneut mit allow_safe_proof true und operator_confirmed true auf. Verwenden Sie nur playbook_id-Werte aus der Whitelist.

Sicherheitshinweise

Keel gibt einem KI-Client die Möglichkeit, Hosts im Scope über httpx und nuclei zu untersuchen und zwei begrenzte Proof-Playbooks auszuführen. Führen Sie es nur auf Systemen aus, die Sie testen dürfen. Beobachten Sie engagement_health und halten Sie RPS bei Bounty-Programmen konservativ.

Rechtmäßige und ethische Nutzung

• Autorisierte Penetrationstests mit schriftlicher Genehmigung

• Bug-Bounty-Programme, innerhalb des Programm-Scopes und der Regeln

• Sicherheitsforschung an Systemen, die Sie besitzen oder zu testen autorisiert sind

• Red-Team-Übungen mit Genehmigung der Organisation

• Testen Sie niemals Systeme ohne Erlaubnis

• Kein illegaler Zugriff, kein Datendiebstahl, kein Schaden

• Proofs: nur Tester-Konten; keine Daten anderer Benutzer

Mitwirken

git clone https://github.com/lutfizp/keel.git
cd keel
sh scripts/bootstrap.sh python
source .venv/bin/activate
pytest

Nützliche Bereiche: Parser, Triage, zusätzliche auf der Zulassungsliste stehende Proof-Playbooks, Client-Snippets. Fügen Sie keine unbegrenzten Exploit-Generatoren oder einen Haufen unzusammenhängender Scanner-CLIs zur MCP-Oberfläche hinzu.

Lizenz

Keel wird unter der MIT-Lizenz veröffentlicht. Siehe LICENSE.

Copyright (c) 2026 Lutfi Z.P.

PyPI: keel-pentest. MCP Registry: io.github.lutfizp/keel. Quelle: github.com/lutfizp/keel.