Plano de control MCP para pentest autorizadas y bug bounty

Nueve herramientas MCP. Una ola a la vez. Límites de tasa por host. Tarjetas de nivel cazador, no volcados de escáner.

Arquitectura · Instalación · Clientes MCP · Funciones · Herramientas · Ejemplos de prompts · Seguridad · Licencia

Keel es el servidor MCP que conectas a Claude Code, Codex, Cursor, OpenCode, Hermes, Copilot y cualquier otro cliente MCP. Ejecuta reconocimiento acotado, evita que el objetivo reciba demasiado tráfico y convierte la salida del escáner en tarjetas deduplicadas. El ruido informativo y de cabeceras faltantes permanece oculto salvo que lo pidas. Las pruebas acotadas usan tus cuentas de tester y un marcador único, nunca un generador de exploits de forma libre.

Úsalo para:

• Reconocimiento de pentest externo y web

• Bug bounty (alcance dentro, ruido fuera)

• Evaluación estilo red team con un copiloto de IA

• Compromisos repetibles que puedes pausar, consultar y probar

Descripción general de la arquitectura

El modelo solo habla con Keel. Keel admite olas, limita la tasa por host, analiza la salida de httpx / nuclei en un almacén de tarjetas y luego condiciona las pruebas a los indicadores del operador.

%%{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

Cómo funciona

1. Conectar — el cliente inicia el servidor stdio: keel-pentest (PyPI) o python3 scripts/keel_mcp.py (clon). Sin sidecar HTTP.

2. Comenzar — begin_engagement registra el alcance, RPS y si las pruebas están permitidas.

3. Redactar y luego ejecutar — draft_waves propone probe_alive y luego template_scan. execute_wave ejecuta una ola admitida detrás del bucket por host.

4. Triaje — query_cards devuelve tarjetas relevantes para el cazador. state_impact registra impact_class. second_look vuelve a escanear una URL.

5. Probar — draft_proof describe un playbook en lista blanca. execute_proof solo se ejecuta si allow_safe_proof y operator_confirmed están activados.

Related MCP server: BountyProof MCP

Instalación

No hagas pip install keel. Notas completas por SO: INSTALL.md. Fragmentos para clientes (PyPI y clon): clients/README.md.

Python 3.10+. El /usr/bin/python3 de Apple suele ser 3.9 (No matching distribution found for mcp>=1.9).

Elige una vía:

Todas las vías siguen necesitando httpx y nuclei de ProjectDiscovery en PATH. La rueda no incluye esos binarios. La librería Python httpx no es el CLI.

Sondas macOS: brew install nuclei httpx y luego nuclei -update-templates. Clon: sh scripts/bootstrap.sh tools. Otros SO: INSTALL.md.

Desde 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 (coloca keel-pentest en PATH).

Comprueba:

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

No dejes python -m keel ejecutándose en la terminal para "probarlo": ese proceso es el servidor MCP stdio y espera en stdin. Úsalo solo como command del cliente.

python -m keel y el script de consola keel-pentest inician ambos el servidor MCP stdio (se quedan en stdin/stdout; no son un daemon HTTP). Apunta el cliente MCP al intérprete que tenga el paquete:

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

O:

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

Establece PYTHONUNBUFFERED=1 en el entorno del cliente si JSON-RPC parece atascado. Instala httpx y nuclei por separado (ver arriba).

El nombre del paquete en PyPI es keel-pentest. El nombre de importación es keel.

Desde un clon local

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

Windows:

powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1

El script crea .venv con Python 3.10+, instala este proyecto (keel-pentest vía pip install -e ".[dev]") y luego instala httpx y nuclei de ProjectDiscovery.

Ejecuciones parciales:

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

Verifica:

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

Las configs MCP en el repo usan el lanzador:

python3 scripts/keel_mcp.py

Ese script encuentra un .venv 3.10+ junto al repo y ejecuta python -m keel (igual que keel-pentest). Env opcional: KEEL_PYTHON, KEEL_ROOT.

Instalación editable desde el código fuente

Desde el clon (después de que exista un venv 3.10+):

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

Igual que el local: python3 scripts/keel_mcp.py, o /path/to/keel/.venv/bin/keel-pentest.

Desde el Registro MCP

Nombre del registro: io.github.lutfizp/keel. El server.json publicado apunta a PyPI keel-pentest. Los clientes que hablen el registro instalarán ese paquete; aún necesitas Python 3.10+ y los CLIs de sondas.

Si el cliente solo escribe un archivo de configuración, usa los ejemplos de command de PyPI de arriba.

Instalación de Python y herramientas específica por SO: INSTALL.md.

Configuración del cliente MCP

Clon local (este repo como espacio de trabajo)

Configs ya en el árbol:

Fragmentos para 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 usa mcp.servers en lugar de un mapa mcp plano. Mantén el mismo array command.

Claude Code (desde el clon):

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

Claude Desktop / estilo Cursor mcpServers (lanzador local):

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

Codex (local):

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

PyPI / venv global

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"]. Ejemplo: opencode.pypi.json.example.

Usa rutas absolutas a keel-pentest o al python del venv. Un cliente que herede el python3 3.9 de Apple fallará al importar mcp.

Reinicia el cliente después de instalar.

Funciones

Plano de control (no un volcado de 150 herramientas)

El modelo nunca ejecuta nuclei o httpx por sí mismo. Solo llama a las herramientas de Keel. Las olas se admiten una a la vez. Cada host tiene un bucket de tokens desde requests_per_second.

Tarjetas de hallazgos

Los analizadores convierten el JSON de httpx y el JSONL de nuclei en un almacén de tarjetas SQLite. Las huellas digitales fusionan duplicados. Los hallazgos informativos y de endurecimiento están ocultos por defecto (query_cards con include_noise falso).

Triaje de cazador

Valores de impact_class: none, hardening, sensitive_access, account_takeover, rce, data_other_users. Las puntuaciones de escáner estilo CVSS no son la puerta del cazador.

Pruebas acotadas

Solo playbooks en lista blanca:

execute_proof requiere allow_safe_proof y operator_confirmed. Solo sesiones de tester. Sin DoS, sin datos de otros usuarios, sin generación de exploits.

Estructura

La política, el programador, los adaptadores, los analizadores, el almacén, el triaje y la prueba viven en paquetes separados bajo src/keel/. Datos de compromiso: .data/engagements en el repo (no ~/.keel para la base de datos).

Herramientas MCP

Argumentos de begin_engagement

Ejemplos de prompts

Reemplaza target.example con un host en alcance. Siempre comienza con begin_engagement a menos que el compromiso ya exista. El cliente debe llamar al MCP de Keel, no a nuclei / httpx por shell.

Indica que estás autorizado (propietario, empleador o recompensa en alcance). Los prompts vagos de "hackea este sitio" suelen ser rechazados por la mayoría de los modelos.

Bug bounty de extremo a extremo

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.

Cuando estés listo para ejecutar una prueba acotada (solo cuentas de tester):

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.

Solo reconocimiento

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.

Solo plantillas (después del reconocimiento)

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.

Solo tarjetas / triaje

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.

Solo impacto

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.

Solo plan de prueba (sin tráfico)

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

Estado

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

Solución de problemas

El servidor MCP falló / errores de importación

Usa Python 3.10+ (venv que realmente tenga keel-pentest o la instalación del clon), no el 3.9 de Apple:

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

Si mcp>=1.9 no se puede instalar, recrea .venv con 3.12/3.11/3.10 (sh scripts/bootstrap.sh python o un venv nuevo y luego pip install keel-pentest).

httpx / nuclei no encontrados

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

Tarjetas vacías después de una ola

Revisa engagement_health para hosts en pausa (límite de tasa / 429). Baja el RPS. Confirma que el host está en scope_hosts y que la URL semilla es alcanzable.

execute_proof denegado

Llama a begin_engagement de nuevo con allow_safe_proof verdadero y operator_confirmed verdadero. Usa solo valores playbook_id en lista blanca.

Consideraciones de seguridad

Keel permite que un cliente de IA pruebe hosts dentro del alcance mediante httpx y nuclei, y ejecute dos playbooks de prueba específicos. Ejecútalo solo en sistemas que tengas permiso para probar. Vigila engagement_health y mantén un RPS conservador en los programas de recompensas.

Uso legal y ético

• Pruebas de penetración autorizadas con permiso por escrito

• Programas de recompensas por errores (bug bounty), dentro del alcance y las reglas del programa

• Investigación de seguridad en sistemas que posees o que estás autorizado a probar

• Ejercicios de red team con aprobación de la organización

• Nunca pruebes sistemas sin permiso

• Sin acceso ilegal, robo de datos ni daños

• Pruebas: solo cuentas de prueba; ningún dato de otros usuarios

Contribuciones

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

Áreas útiles: parsers, triaje, playbooks de prueba adicionales en lista blanca y fragmentos de cliente. No añadas generadores de exploits sin límites ni un volcado de CLIs de escáneres no relacionados a la superficie de MCP.

Licencia

Keel se publica bajo la Licencia MIT. Consulta LICENSE.

Copyright (c) 2026 Lutfi Z.P.

PyPI: keel-pentest. Registro MCP: io.github.lutfizp/keel. Fuente: github.com/lutfizp/keel.