AOI-Future/agent-webhook-check

# webhook-check **一个免费的单文件审计工具，用于审计 webhook 签名验证器 —— 这是 AI agent 工具回调中最常见的真实漏洞。** webhook 是一种回调机制，允许外部系统触发 agent 的操作：退款、部署、发送消息、转移资金。如果检查 webhook 签名的验证器能被伪造的签名欺骗，攻击者就能控制 agent 的双手。该工具会审计验证器，排查其常见的四种失效方式。 它是从完整的 **AI-Agent Security Verification Kit** 中提取的一个免费用例。无依赖、无网络，仅使用标准库。运行它、阅读它、分享它。 ## 快速开始 无需任何设置，即可查看它如何发现真实漏洞： ``` python3 webhook_check.py --demo ``` 这会运行两个内置的参考验证器 —— 一个故意留有缺陷，另一个完全正确 —— 这样你就可以并排查看 PASS 和 FAIL 的结果。 就地审计你自己的验证器： ``` python3 webhook_check.py --verifier yourmodule:verify ``` `yourmodule:verify` 是任何具有以下签名的可调用对象： ``` def verify(secret: bytes, body: bytes, header: str) -> bool: """Return True iff `header` is a valid signature of `body` under `secret`. Must NOT raise on malformed input; must return False.""" ``` 如果所有检查都通过，退出代码为 `0`；如果有任何失败，则为 `1` —— 因此你可以将其直接接入 CI。 尝试运行 `examples/` 中的实战示例： ``` python3 webhook_check.py --verifier examples.vulnerable_verifier:verify # fails python3 webhook_check.py --verifier examples.fixed_verifier:verify # passes ``` ## 检查内容 | ID | 检查项 | 能够捕获的漏洞 | |----|-------|--------------------| | VT-D-050 | 接受有效签名 | 验证器过于严格，导致拒绝合法流量（失效的控件并不安全）。 | | VT-D-051 | 拒绝被篡改的 body | 旧的签名被用于接受被篡改的 payload —— 这意味着签名实际上并未与 body 绑定。 | | VT-D-052 | 对伪造的短签名具有长度安全性 | 过短的签名会导致手动编写的循环越界并引发 `IndexError`：伪造的 header 会导致 **handler 崩溃**（拒绝服务）。 | | VT-D-053 | 常数时间比较 | `==` 或字节循环会通过响应**时间差**泄露合法的 HMAC —— 攻击者可以逐字节恢复出签名。 | 这两个真实缺陷的修复方法只需一行代码：**`hmac.compare_digest`**，并加上 `startswith("sha256=")` / 长度校验保护。详见 `examples/fixed_verifier.py`。 请注意，这两个示例漏洞截然不同：对 digest 使用 `==`（`vulnerable_verifier.py`）具有长度安全性，但*不是*常数时间的，因此它只会使 VT-D-053 失败；而手动编写的索引循环（内置的 `--demo` 参考示例）则*同时*无法通过 VT-D-052 和 VT-D-053。真实的代码中这两种情况都存在。 ## 该工具不涉及的内容 —— 以及其余功能的去向 这个免费工具仅针对单一用例告诉你 **PASS 或 FAIL**。完整的 **AI-Agent Security Verification Kit** 能做到它不具备的两件事： 1. **覆盖整个攻击面** —— agent 身份与授权委托、工具和操作安全、不受信任的内容和记忆、MCP 供应链，以及企业托管授权 (EMA) —— 只需一条命令即可针对你的配置运行。 2. **生成足以经得起辩护的证据。** 每次运行都会封装成一个单一工件 —— 机器可读的 JSON 加上人类可读的 PDF —— 其哈希值由 [RFC 3161](https://www.rfc-editor.org/rfc/rfc3161) 时间戳权威机构进行会签。它能证明你测试了*什么*以及*何时*测试的，并且**没有任何 secret 会离开你的机器** —— 只有哈希值和 nonce 会发送到时间戳服务器。 - **书籍 —— _AI Agent Security_（Leanpub 会员免费 / 随心付费）** —— 涵盖了在 agent 攻击面中应该验证什么以及为什么。**现已上线** —— 。 - **验证套件** —— 包含所有检查项以及带有时间戳的证据工件。**现已发售** —— 。 - **获取下一个免费用例**，并在标准发生变动时提前获知 —— [加入 Security 邮件列表](https://dispatch.aoifuture.com/s/security)。 CLI 打印出的三个 URL 也可以通过环境变量（`AGENTKIT_BOOK_URL`、`AGENTKIT_KIT_URL`、`AGENTKIT_LIST_URL`）进行设置，无需修改源代码。 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。此免费工具特意采用宽松的许可协议，以便于广泛传播。付费套件有独立的许可协议。

标签：AI Agent安全, Python, Webhook审计, 无后门, 签名验证, 逆向工具