Keel

---

向 Agent 倾倒 150 个工具很容易。真正棘手的问题是：跨工具去重、区分可利用的问题与噪声，以及避免对目标狂轰滥炸。Keel 是处理这三个问题的控制平面。

AI 客户端与 Keel 通信，而不是与 httpx、nuclei 或 shell 通信。Keel 一次只起草一个波次，强制执行范围和速率限制，将扫描器发现合并为语义卡片，并在测试人员自有数据上运行仅使用 GET 的操作手册。当操作手册返回 proven 时，你会得到一段猎手可按步骤重放的 curl 命令——仍然不会执行写入、shell 命令或大量发送载荷。

仅在你获准测试的项目上使用。

为何选择 Keel

难题	扫描器输出的做法	Keel 的做法
跨工具去重	每行对应一个 Nuclei 模板 ID；同一个 IDOR 会出现五次	根据漏洞类别、规范化路由、方法和参数生成语义键。UUID/id/十六进制令牌会合并。兼容的观察结果会合并。
区分可利用的问题与噪声	严重性高 =“直接上线”	卡片依次经过 observed → hypothesis → corroborated → proven / refuted。信息性问题和安全加固问题会隐藏。类型化的可利用性评估会指出缺少的证据和负向对照。
避免对目标狂轰滥炸	一次发起所有模板，遇到 429 就重试	每台主机同时只运行一个活动波次，使用令牌桶，Nuclei 并发数为 1，不使用 OAST、不跟随重定向、不运行未签名模板，也不运行带有 dos/fuzz/bruteforce/intrusive 标签的模板。HTTP 429 会触发冷却。

仅仅通过 shell 调用一大堆工具的包装器并不具备这一层能力。Keel 做到了——在调度器、适配器和证明代理中都实现了这一点。

架构

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。
2. draft_waves 会提出可达性检查和模板微波次，但不会产生任何流量。
3. execute_wave 会立即返回一个作业。轮询 wave_status。cancel_wave 会终止扫描器。
4. query_cards 会返回与猎手相关的卡片。assess_exploitability 会说明需要什么证据才能证明问题。
5. draft_proof 随后由 execute_proof 在测试人员的数据上运行仅使用 GET 的操作手册。proven 表示不变量成立。protected 表示控制措施有效。

安装

macOS（Homebrew）。pipx 是独立工具——请先安装。Apple 的 /usr/bin/python3 通常是 3.9，无法安装 Keel。

brew install pipx [email protected]
pipx ensurepath
# open a new terminal, then:
pipx install keel-pentest
keel-pentest setup
keel-pentest doctor

如果机器上已有 python3.12，且不想使用 Homebrew pipx：

python3.12 -m pip install --user pipx
python3.12 -m pipx ensurepath
python3.12 -m pipx install keel-pentest

setup 会将 ProjectDiscovery 的 httpx 和 nuclei 下载到 ~/.keel/bin。即使 GUI 客户端的 PATH 配置不完整，Keel 也能在该目录找到它们。首次扫描无需额外设置 KEEL_HTTPX_BIN。

然后将 MCP 客户端指向 keel-pentest 可执行文件：

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+。不要执行 pip install keel——那是另一个项目。操作系统说明以及 pip/venv 说明：INSTALL.md。客户端配置形式：clients/README.md。

之后可选：使用 KEEL_APPROVAL_FILE 指定团队清单，以固定范围、模板 ID 和证明目标。默认模式为自我声明——begin_engagement 即为授权。速率限制、每个主机每波次一次、签名模板和已清理的证据仍然适用。

安全地证明影响

扫描器输出只是一个假设。Keel 使用一次性测试账号和唯一金丝雀来证明（或证伪）该假设。每个操作手册都只执行 GET 请求、设有预算限制，并会返回 curl 重放命令。重放命令就是报告产物：如果不修复，有普通账号的漏洞猎手就能做到这一点。

操作手册	证明内容	如何在不造成损害的情况下证明
cross_account_read	IDOR / BOLA	测试账号 A 读取其金丝雀；测试账号 B 对同一个归 A 所有的 URL 发起 GET 请求。金丝雀相同且状态码为 2xx = proven。401/403/404，或状态码为 2xx 但不含金丝雀 = protected（已证伪）。
reflected_marker	反射型 XSS / HTML 注入	注入唯一标记和无害的 <keel> 探针。反射内容未转义 = proven。反射内容经过 HTML 编码 = protected。控制 GET 请求中不得已包含该探针。
open_redirect_canary	开放重定向	将重定向参数指向 https://keel-proof.invalid/<marker>。若状态码为 3xx，且 Location 主机是该金丝雀，则为 proven。
unauth_access_probe	缺少授权校验	测试账号 A 的基线结果必须显示金丝雀；同一 URL 在不带凭据的情况下不得显示。未认证时状态码为 2xx 且包含金丝雀 = proven。
own_session_marker	仅证明可访问性	A 读取自己的金丝雀。这属于 corroborated，绝不能作为漏洞证明。

execute_proof 会保存状态码、金丝雀布尔值、截断标志、哈希、漏洞猎手影响说明和复现脚本。它不会持久化响应正文或机密信息。

在执行 cross_account_read / unauth_access_probe 前，请在测试账号拥有的对象中植入非机密金丝雀。反射型 XSS 和开放重定向会自行注入标记。

MCP 工具

工具	作用
begin_engagement	注册范围和流量上限
draft_waves	提出可达性 + 模板微波次；不产生流量
execute_wave	将一个后台任务加入队列
wave_status	查看阶段、进度和结果；省略 job_id 可列出任务
cancel_wave	停止已排队或正在运行的扫描器
query_cards	查看按优先级排序的语义卡片
second_look	仅重新运行最初使用的 Nuclei 模板
assess_exploitability	评估候选影响、缺失证据、负向控制和操作手册
state_impact	记录漏洞猎手的假设
draft_proof	创建允许列表中的证明计划；不产生流量
execute_proof	运行仅执行 GET 请求的操作手册
engagement_health	查看冷却时间、预算和待处理波次
engagement_audit	仅追加应用事件

begin_engagement 需要 engagement_id 和 scope_hosts（纯主机名，例如 target.example）。默认值：3 req/s、一次一个主机、每个波次 120 秒 / 120 个请求。allow_safe_proof=true 可启用证明。仅传入测试账号凭据的名称；请将机密信息放入 KEEL_CREDENTIALS_FILE。

示例提示词

Use only Keel MCP tools. Do not shell out to httpx, nuclei, curl, or exploit tools.

1. begin_engagement for bb-2026-01 with scope_hosts ["target.example"], 3 req/s.
   Set allow_safe_proof true if I will run proofs.
2. draft_waves for https://target.example.
3. execute_wave for each wave. Poll wave_status until completed, retryable_failed,
   terminal_failed, or cancelled.
4. query_cards (include_noise false), then assess_exploitability on candidates.
5. For a card with a safe playbook, draft_proof then execute_proof using tester
   credential names and the canary I planted. Treat protected as refuted.
6. Summarize duplicates, evidence state, hunter_impact, and the repro_script.
   Claim exploitable only when Keel reports proven.

流量控制

• 精确限定 draft、admit、ingest 和 proof 的范围及排除项
• 每台主机同时只运行一个 wave；同一主机上的任务需等待
• 共享全局和按主机划分的令牌桶
• 持久化请求预留；重试会消耗新的预留
• Nuclei：使用签名的 HTTP 模板，不使用 OAST，不跟随重定向，不重试，排除 dos/fuzz/bruteforce/intrusive
• 使用隔离的空扫描器配置；清除代理和 ProjectDiscovery-cloud 环境变量
• HTTP 429 会停止 wave 并遵从 Retry-After
• 限制响应读取量；保留证据但不保留原始正文

故障排除

keel-pentest doctor
keel-pentest setup    # if doctor reports missing httpx/nuclei

客户端重启后，begin_engagement 会恢复 SQLite engagement。如果更改了范围，请使用新的 engagement_id。

Proof 需要设置 allow_safe_proof=true；对于会话 playbook，还需要在 KEEL_CREDENTIALS_FILE 中将 tester-a 之类的名称映射到 Authorization 或 Cookie。

许可证

MIT。版权所有 (c) 2026 Lutfi Z.P.

PyPI：keel-pentest。MCP Registry：io.github.lutfizp/keel。源代码：github.com/lutfizp/keel。