Hookwarden — Webhook Integrity

Webhook 署名検証を行う初の MCP サーバーです。
ローカルで動作。決定論的。ネットワーク通信ゼロ。JS / TS / Python / PHP / Go — 27 のプロバイダー — 3 状態の判定。

概要

@hookwarden/mcp は hookwarden の決定論的な webhook 検証エンジンを MCP ツールとして公開します。Claude Desktop、Cursor、Continue、Anthropic Agent SDK で構築されたアプリなどの AI コーディングエージェントは、次の 2 つのツールを利用できます。

• scan_handler — 貼り付けた webhook ハンドラーコードをスキャンし、Stripe、GitHub、Shopify、Twilio、およびその他 23 のプロバイダーについて、構造化された検出結果（verified / not-verified / manual-review）を返します。
• verify_audit_chain — hookwarden の証拠パックのハッシュチェーンと KMS 署名付き Merkle ルートをオフラインで検証し（ネットワークも認証も不要）、{ valid, broken_at_row, signatures_verified } を返します。

処理はすべてクライアント側で実行されます。MCP プロセスからのネットワーク通信はゼロです。認証も不要です。hookwarden CLI と同じエンジンを搭載しています。同じルールパック、同じコンテンツハッシュ、エンドツーエンドの来歴情報を使用します。

1 つのコマンドでインストール

npx @hookwarden/mcp init

このコマンドは、インストール済みの MCP クライアント（Claude Desktop / Cursor / Continue）を検出し、OS ごとの概要表を表示して、各クライアントに標準設定を書き込みます。変更する設定ファイルの隣には .bak ファイルが作成されます。該当するクライアントを再起動すると、ツール一覧に scan_handler と verify_audit_chain が表示されます。

対話なしで実行するには --all、プレビューするには --dry-run、既存の mcpServers.hookwarden エントリーを上書きするには --force、対象を限定するには --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	起動時または呼び出し時のドリフトです。ドリフト検出を参照してください。

解析エラーでトランスポートがクラッシュすることはありません。これらは重大度 high の rule_id: "engine/parse-error" の検出結果として出力され、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 に合格します。これは、HTTP クライアント（node:http、axios、undici など）のソースファイルからのインポートと、文書化された許可リストに含まれない直接依存を拒否する、構造的な CI ゲートです。
• ドリフト検出 — scan_handler を呼び出すたびに、実行時に解決されたエンジンとルールパックのハッシュを、ビルド時の dist/build-manifest.json と照合します。不一致の場合は、構造化された engine_drift / rules_drift ペイロードとともに isError: true を返します。環境変数による無効化はできません。ドリフト検出をご覧ください。v0.8.0 におけるエンジン内容ハッシュの制限についても説明しています。
• テレメトリーなし — tarball の dependencies に分析またはトラッキング用 SDK（@datadog/*、@segment/*、@sentry/* など）は宣言されておらず、ソースファイルからのインポートを介した間接的な依存もありません。
• オープンソース — Hookwarden/hookwarden/packages/mcp/ で Apache-2.0 ライセンスのもと公開されています。エンジンとルールパックは同じモノレポに含まれ、同じライセンスで提供されます。

リンク

• ドキュメント — はじめに、ツールのリファレンス、ドリフト検出
• npm パッケージ
• GitHub リポジトリ
• Apache-2.0 ライセンス

---

Copyright 2026 Hookwarden contributors. Apache License 2.0.