Hookwarden — Webhook Integrity

首个实现 Webhook 签名验证的 MCP 服务。
本地运行。结果确定。零网络访问。JS / TS / Python / PHP / Go — 27 个提供商 — 三态判定。

功能

@hookwarden/mcp 将 hookwarden 的确定性 Webhook 验证引擎封装为 MCP 工具。AI 编码 Agent——Claude Desktop、Cursor、Continue，以及基于 Anthropic Agent SDK 构建的应用——可使用两个工具：

• scan_handler — 扫描粘贴的 Webhook 处理程序代码，并返回结构化结果（verified / not-verified / manual-review），支持 Stripe、GitHub、Shopify、Twilio 及其他 23 个提供商。
• verify_audit_chain — 离线验证 hookwarden 证据包的哈希链和由 KMS 签名的 Merkle 根（无需网络，无需身份验证），并返回 { valid, broken_at_row, signatures_verified }。

完全在客户端运行。MCP 进程不会向外发起任何网络请求。无需身份验证。使用与 hookwarden CLI 相同的引擎——相同的规则包、相同的内容哈希和端到端来源证明。

一条命令安装

npx @hookwarden/mcp init

该命令会检测已安装的 MCP 客户端（Claude Desktop / Cursor / Continue），打印各操作系统的摘要表，并为每个客户端写入规范配置。它会在每个修改过的配置文件旁生成 .bak 文件。重启相应客户端后，工具列表中就会出现 scan_handler 和 verify_audit_chain。

传入 --all 可用于非交互式操作，传入 --dry-run 可预览更改，传入 --force 可覆盖现有的 mcpServers.hookwarden 条目，或传入 --clients claude-desktop,cursor 可限制客户端范围。

手动配置

如果不想运行初始化辅助工具，也可以手动编写配置。

Claude Desktop

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "hookwarden": {
      "command": "npx",
      "args": ["-y", "@hookwarden/mcp"]
    }
  }
}

Cursor

~/.cursor/mcp.json — 格式与 Claude Desktop 相同：

{
  "mcpServers": {
    "hookwarden": {
      "command": "npx",
      "args": ["-y", "@hookwarden/mcp"]
    }
  }
}

Continue.dev

Continue 为每个服务使用单独的文件。写入 ~/.continue/mcpServers/hookwarden.yaml：

name: hookwarden
command: npx
args: [-y, "@hookwarden/mcp"]

Anthropic Agent SDK

Agent SDK 以编程方式使用——无需编辑配置文件。将以下内容添加到代码中：

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Audit this webhook handler for missing signature verification...",
  options: {
    mcpServers: {
      hookwarden: {
        command: "npx",
        args: ["-y", "@hookwarden/mcp"],
      },
    },
  },
})) {
  console.log(message);
}

初始化辅助工具不会在这里写入配置——SDK 集成通过代码实现，而非配置。

scan_handler 工具

输入

字段	类型	说明
code	string	单文件模式。默认为 TypeScript；可通过 language 覆盖。不能与 files 同时使用。
files	Record<string, string>	多文件模式。键为虚拟文件路径；语言根据扩展名推断。
language	"js" | "ts" | "python"	可选。"php" 会返回 language_not_in_preview——PHP 支持将在 v0.8.1 中提供。
provider	string	可选。不区分大小写（"stripe" = "Stripe"）。如果规则包中没有该提供商，则返回 unknown_provider。

输出

返回包含 structuredContent 一等字段的 Tool.result（MCP 规范 2025-06-18），并附带一个字符串化 JSON 文本块以保持向后兼容：

{
  "verdict_summary": { "verified": 0, "not_verified": 1, "manual_review": 0, "parse_error": 0 },
  "findings": [
    {
      "rule_id": "stripe/missing-signature-verification",
      "provider": "stripe",
      "severity": "critical",
      "verdict": "not-verified",
      "file": "__handler.ts",
      "line_start": 7,
      "line_end": 9,
      "message": "Webhook handler reads req.body without calling stripe.webhooks.constructEvent...",
      "provider_docs_url": "https://stripe.com/docs/webhooks",
      "references": [
        "https://www.svix.com/blog/common-failure-modes-for-webhook-signatures/",
        "https://hookdeck.com/webhooks/guides/webhook-security-vulnerabilities-guide"
      ],
      "rule_pack_version": "0.7.2"
    }
  ],
  "scan_metadata": {
    "engine_version": "0.7.2",
    "rule_pack_version": "0.7.2",
    "rule_pack_content_hash": "938f7565e29f19e0cbd34594731d1de2b0ffd40ee87aacaa8be2435fc1f47f32"
  }
}

判定结果词汇

判定结果	含义
verified	引擎证明处理程序通过提供方文档所述的 SDK 调用验证签名。
not-verified	引擎证明处理程序未验证签名（或在产生副作用后才验证）。
manual-review	引擎有结构层面的证据，但无法在没有人工检查的情况下作出判断——请检查代码片段。

与 CLI 使用相同的 3 种状态词汇。MCP 层不会进行映射。

错误负载（isError: true）

错误	触发条件
empty_input	未提供 code 或 files。
exclusive_input_modes	同时提供了 code 和 files——请选择其中一种。
language_not_in_preview	language: "php"——PHP 将在 v0.8.1 中发布。建议：npx hookwarden scan。
unsupported_language	language 不在已知集合中。
unknown_provider	provider 不在规则包中。响应会包含排序后的已知列表。
engine_drift / rules_drift	启动时或调用时发生偏差——请参阅 drift-detection。

解析失败不会导致传输崩溃——而是以 rule_id: "engine/parse-error"、严重性为 high 的发现项形式输出，并递增 verdict_summary.parse_error。

verify_audit_chain 工具

离线验证 hookwarden 证据包的完整性——无需网络、AWS 或凭据。“无需信任 hookwarden 即可验证证据链。”该工具会遍历逐行哈希链，往返验证清单哈希，并针对嵌入签名 CMK 的 SPKI 公钥的 v1.1 证据包，使用 node:crypto 验证 ECDSA-P256（MessageType:DIGEST）Merkle 根和清单签名。

输入

字段	类型	说明
evidence_pack_json	string	完整的证据包 JSON（由 hookwarden 证据导出功能生成的文件）。支持 v1.0 和 v1.1 证据包。

输出

{
  "valid": true,
  "broken_at_row": null,
  "signatures_verified": 2
}

字段	含义
valid	仅当哈希链完整、清单哈希往返验证通过，且所有可离线验证的签名均验证通过时，值为 true。
broken_at_row	链哈希不匹配的首行的 seq，若哈希链完整则为 null。签名有效性独立于链完整性。
signatures_verified	离线验证通过的签名数量：N 个 Merkle 根签名 + 1 个清单签名（N+1）。v1.0 证据包（未嵌入公钥）为 0——工具会输出 signatures not verifiable offline (v1.0 pack) 提示，而不会失败。

信任模型

v1.1 证据包自带 SPKI 公钥。该签名证明证据包在签名后未被持有该密钥的一方篡改——这是一种首次使用即信任的模型。若要通过带外方式将信任固定到特定签名者，审计人员可以将 signature.signing_cmk_arn 与 AWS KMS GetPublicKey 的结果交叉核对，并确认嵌入的 SPKI 密钥匹配。格式错误的证据包 JSON 会返回 isError: true（error: "invalid_pack_json"）——该工具绝不会让异常越过其边界。

该工具仅导入 @hookwarden/canonical-json（共享的 RFC 8785 字节相等性基准）和 node:crypto。它不会加载引擎或规则包，也不会运行偏差检测。

完整性声明

• 零出站 TCP — 已发布的 tarball 通过 pnpm inspect-bundle 检查。这是一项结构性 CI 门禁，会拒绝任何导入 HTTP 客户端（node:http、axios、undici 等）的源文件，以及任何不在文档所列允许清单中的直接依赖。
• 漂移检测 — 每次调用 scan_handler 时，都会将运行时解析出的引擎和规则包哈希值与构建时的 dist/build-manifest.json 交叉核对。不匹配时会返回 isError: true，并附带结构化的 engine_drift / rules_drift 负载。无法通过环境变量禁用。请参阅 漂移检测，其中也介绍了 v0.8.0 的引擎内容哈希限制。
• 无遥测 — tarball 的 dependencies 中及源文件的传递导入中均未声明分析或跟踪 SDK（@datadog/*、@segment/*、@sentry/* 等）。
• 开源 — Hookwarden/hookwarden/packages/mcp/ 下的代码采用 Apache-2.0 许可。引擎和规则包位于同一个单体仓库中，并采用相同的许可证发布。

链接

• 文档 — 入门指南、工具接口参考、漂移检测
• npm 包
• GitHub 仓库
• Apache-2.0 许可证

---

版权所有 2026 Hookwarden 贡献者。Apache License 2.0。