Плоскость управления MCP для авторизованного пентеста и bug bounty

Девять MCP-инструментов. По одной волне за раз. Ограничение скорости на хост. Карточки уровня хантера, а не выгрузки сканера.

Архитектура · Установка · MCP-клиенты · Возможности · Инструменты · Примеры промптов · Безопасность · Лицензия

Keel — это MCP-сервер, который подключается к Claude Code, Codex, Cursor, OpenCode, Hermes, Copilot и любому другому MCP-клиенту. Он выполняет разведку в рамках скоупа, не даёт перегружать цель и превращает вывод сканеров в дедуплицированные карточки. Информационный шум и шум, связанный с отсутствующими заголовками, скрыты, пока вы сами не попросите. Ограниченные доказательства используют ваши тестовые аккаунты и уникальный маркер — это не генератор эксплойтов в свободной форме.

Используйте его для:

• Внешней и веб-разведки в пентесте

• Bug bounty (скоуп на входе — без шума на выходе)

• Оценки в стиле red team с AI-ассистентом

• Повторяемых проектов, которые можно приостанавливать, запрашивать и подтверждать

Обзор архитектуры

Модель взаимодействует только с Keel. Keel принимает волны, ограничивает скорость по каждому хосту, разбирает вывод httpx / nuclei в хранилище карточек и пропускает доказательства только при установленных оператором флагах.

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

Как это работает

1. Подключение — клиент запускает stdio-сервер: keel-pentest (PyPI) или python3 scripts/keel_mcp.py (клон). Без HTTP-сайдкара.

2. Начало — begin_engagement фиксирует скоуп, RPS и разрешены ли доказательства.

3. Планирование и запуск — draft_waves предлагает probe_alive, затем template_scan. execute_wave выполняет одну принятую волну с учётом пер-хостового bucket.

4. Триаж — query_cards возвращает карточки, релевантные хантеру. state_impact записывает impact_class. second_look повторно сканирует один URL.

5. Доказательство — draft_proof описывает плейбук из белого списка. execute_proof выполняется только при установленных allow_safe_proof и operator_confirmed.

Related MCP server: BountyProof MCP

Установка

Не используйте pip install keel. Полные заметки по ОС: INSTALL.md. Примеры для клиентов (PyPI и клон): clients/README.md.

Python 3.10+. /usr/bin/python3 от Apple часто имеет версию 3.9 (No matching distribution found for mcp>=1.9).

Выберите один из способов:

В любом случае на PATH нужны ProjectDiscovery httpx и nuclei. Wheel не включает эти бинарники. Python-библиотека httpx — это не CLI.

Для macOS: brew install nuclei httpx, затем nuclei -update-templates. Для клона: sh scripts/bootstrap.sh tools. Другие ОС: INSTALL.md.

Из 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 (помещает keel-pentest в PATH).

Проверка:

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

Не оставляйте python -m keel запущенным в терминале, чтобы «проверить» его: этот процесс является MCP stdio-сервером и ожидает ввод в stdin. Используйте его только как command для клиента.

python -m keel и консольный скрипт keel-pentest оба запускают stdio MCP-сервер (они работают через stdin/stdout; это не HTTP-демон). Укажите MCP-клиенту на интерпретатор, в котором установлен пакет:

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

Или:

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

Установите PYTHONUNBUFFERED=1 в окружении клиента, если JSON-RPC выглядит зависшим. Установите httpx и nuclei отдельно (см. выше).

Имя пакета на PyPI — keel-pentest. Имя для импорта — keel.

Из локального клона

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

Windows:

powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1

Скрипт создаёт .venv с Python 3.10+, устанавливает этот проект (keel-pentest через pip install -e ".[dev]"), а затем устанавливает ProjectDiscovery httpx и nuclei.

Частичные запуски:

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

Проверка:

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

MCP-конфиги в репозитории используют лаунчер:

python3 scripts/keel_mcp.py

Этот скрипт находит .venv с Python 3.10+ рядом с репозиторием и запускает python -m keel (то же, что keel-pentest). Необязательные переменные окружения: KEEL_PYTHON, KEEL_ROOT.

Редактируемая установка из исходников

Из клона (после создания venv с Python 3.10+):

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

То же, что для локального клона: python3 scripts/keel_mcp.py или /path/to/keel/.venv/bin/keel-pentest.

Из MCP-реестра

Имя в реестре: io.github.lutfizp/keel. Опубликованный server.json указывает на PyPI-пакет keel-pentest. Клиенты, поддерживающие реестр, установят этот пакет; вам всё равно понадобятся Python 3.10+ и CLI для проб.

Если клиент только записывает конфиг-файл, используйте примеры command для PyPI выше.

Установка Python и инструментов для конкретной ОС: INSTALL.md.

Настройка MCP-клиентов

Локальный клон (этот репозиторий как рабочее пространство)

Конфиги уже лежат в дереве репозитория:

Примеры для 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 используется mcp.servers вместо плоской карты mcp. Сохраняйте тот же массив command.

Claude Code (из клона):

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

mcpServers в стиле Claude Desktop / Cursor (локальный лаунчер):

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

Codex (локально):

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

PyPI / глобальный 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"]. Пример: opencode.pypi.json.example.

Используйте абсолютные пути к keel-pentest или python из venv. Клиент, унаследовавший Apple python3 версии 3.9, не сможет импортировать mcp.

Перезапустите клиент после установки.

Возможности

Плоскость управления (а не свалка из 150 инструментов)

Модель никогда сама не запускает nuclei или httpx. Она вызывает только инструменты Keel. Волны принимаются по одной. У каждого хоста есть token bucket, определяемый requests_per_second.

Карточки находок

Парсеры превращают JSON от httpx и JSONL от nuclei в SQLite-хранилище карточек. Отпечатки (fingerprints) объединяют дубликаты. Информационные находки и находки по усилению защиты скрыты по умолчанию (query_cards с include_noise false).

Триаж для хантера

Значения impact_class: none, hardening, sensitive_access, account_takeover, rce, data_other_users. Баллы сканера в стиле CVSS не являются решающим фактором для хантера.

Ограниченные доказательства

Только плейбуки из белого списка:

execute_proof требует allow_safe_proof и operator_confirmed. Только тестовые сессии. Никакого DoS, никаких данных других пользователей, никакой генерации эксплойтов.

Структура

Политика, планировщик, адаптеры, парсеры, хранилище, триаж и доказательства находятся в отдельных пакетах внутри src/keel/. Данные проектов: .data/engagements в репозитории (база данных — не в ~/.keel).

MCP-инструменты

Аргументы begin_engagement

Примеры промптов

Замените target.example на хост в рамках скоупа. Всегда начинайте с begin_engagement, если проект ещё не создан. Клиент должен вызывать Keel MCP, а не запускать nuclei / httpx в shell.

Укажите, что вы авторизованы (владелец, работодатель или программа bug bounty в рамках скоупа). Расплывчатые запросы вроде «взломай этот сайт» отклоняются большинством моделей.

Полный цикл 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.

Когда будете готовы запустить ограниченное доказательство (только тестовые аккаунты):

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.

Только разведка

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.

Только шаблоны (после разведки)

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.

Только карточки / триаж

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.

Только 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.

Только план доказательства (без трафика)

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

Статус

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

Устранение неполадок

Сбой MCP-сервера / ошибки импорта

Используйте Python 3.10+ (venv, в котором действительно установлен keel-pentest или клон), а не Apple 3.9:

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

Если mcp>=1.9 не устанавливается, пересоздайте .venv с версией 3.12/3.11/3.10 (sh scripts/bootstrap.sh python или новый venv, затем pip install keel-pentest).

httpx / nuclei не найдены

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

Пустые карточки после волны

Проверьте engagement_health на приостановленные хосты (rate limit / 429). Снизьте RPS. Убедитесь, что хост есть в scope_hosts и стартовый URL доступен.

execute_proof отклонён

Вызовите begin_engagement ещё раз с allow_safe_proof true и operator_confirmed true. Используйте только значения playbook_id из белого списка.

Вопросы безопасности

Keel даёт AI-клиенту возможность проверять хосты в рамках скоупа через httpx и nuclei, а также запускать два узких плейбука для подтверждения. Запускайте его только на системах, которые вам разрешено тестировать. Следите за engagement_health и держите RPS консервативным на баунти-программах.

Правовое и этичное использование

• Авторизованное тестирование на проникновение с письменного разрешения

• Баунти-программы, в рамках скоупа и правил программы

• Исследования безопасности на системах, которыми вы владеете или которые вам разрешено тестировать

• Учения red-team с одобрения организации

• Никогда не тестируйте системы без разрешения

• Никакого незаконного доступа, кражи данных или ущерба

• Доказательства: только тестовые аккаунты; никаких данных других пользователей

Вклад

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

Полезные области: парсеры, триаж, дополнительные из белого списка плейбуки для подтверждения, клиентские сниппеты. Не добавляйте неограниченные генераторы эксплойтов или свалку несвязанных CLI-сканеров на поверхность MCP.

Лицензия

Keel выпущен под лицензией MIT. См. LICENSE.

Copyright (c) 2026 Lutfi Z.P.

PyPI: keel-pentest. MCP Registry: io.github.lutfizp/keel. Исходный код: github.com/lutfizp/keel.