Claude Code ツール呼び出しの署名付き監査証跡

Claude Code のすべてのツール呼び出しに暗号署名されたレシートを付与するクックブック風のウォークスルーです。これは教育用スキルです。ランタイム実装については、protect-mcp プラグインをインストールしてください。

このパターンで得られるもの

すべてのツール呼び出し（Bash、Edit、Write、WebFetch）が以下を備えます：

1. 実行前に Cedar ポリシーに対して評価されます。ポリシーが呼び出しを拒否した場合、ツールは実行されません。
2. 実行後に Ed25519 レシートとして署名されます。レシートは JCS 正規形式で、ハッシュチェーンされており、公開鍵を持つ誰もがオフラインで検証可能です。

監査人、規制当局、または相手方は、後で単一の CLI コマンド（npx @veritasacta/verify receipts/*.json）でチェーン全体を検証できます。ネットワーク呼び出しなし、ベンダーの調査なし、オペレータの信頼なし。

パターンの使用時期

• 規制環境（金融、医療、重要なインフラストラクチャ）では、エージェントの動作の改ざん耐性のある証拠が必要な場合
• CI/CD パイプラインでは、自動化されたビルドステップごとにポリシーゲートが保持されたことを証明したい場合
• マルチパーティコラボレーションでは、相手方がオペレータを信頼することなくエージェントの動作を検証したい場合
• コンプライアンスコンテキスト（EU AI Act Article 12、エージェントが構築したソフトウェアの SLSA 由来）では、標準的なログでは不十分な場合

ステップ 1: フック設定をインストールする

プロジェクトのルートに .claude/settings.json を作成します：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hook": {
          "type": "command",
          "command": "npx protect-mcp@latest evaluate --policy ./protect.cedar --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\" --fail-on-missing-policy false"
        }
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hook": {
          "type": "command",
          "command": "npx protect-mcp@latest sign --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\" --output \"$TOOL_OUTPUT\" --receipts ./receipts/ --key ./protect-mcp.key"
        }
      }
    ]
  }
}

protect-mcp sign の最初の実行により、./protect-mcp.key（Ed25519 秘密鍵）が存在しない場合は生成されます。公開鍵フィンガープリント（任意のレシートの public_key フィールドに表示される）をコミットします。秘密鍵はコミットしないでください。

秘密鍵とレシートディレクトリを .gitignore に追加します：

echo "./protect-mcp.key" >> .gitignore
echo "./receipts/" >> .gitignore

ステップ 2: Cedar ポリシーを作成する

./protect.cedar を作成します：

// Allow all read-oriented tools by default.
permit (
    principal,
    action in [Action::"Read", Action::"Glob", Action::"Grep", Action::"WebSearch"],
    resource
);

// Allow Bash commands from a safe list only.
permit (
    principal,
    action == Action::"Bash",
    resource
) when {
    context.command_pattern in [
        "git", "npm", "pnpm", "yarn", "ls", "cat", "pwd",
        "echo", "test", "node", "python", "make"
    ]
};

// Explicit deny on destructive commands. Cedar deny is authoritative.
forbid (
    principal,
    action == Action::"Bash",
    resource
) when {
    context.command_pattern in ["rm -rf", "dd", "mkfs", "shred"]
};

// Restrict writes to the project directory.
permit (
    principal,
    action in [Action::"Write", Action::"Edit"],
    resource
) when {
    context.path_starts_with == "./"
};

4 つのルール：

• 読み取り指向のツールは常に許可
• Bash は安全なコマンドパターン（git、npm など）で許可
• Bash rm -rf および同様の破壊的なコマンドは明示的に拒否
• 書き込みはプロジェクト内（./ プレフィックス）のみで許可

Cedar forbid ルールは permit ルールより優先されるため、破壊的なコマンドは後続の許可的なルールでバイパスできません。

ステップ 3: Claude Code を通常通り使用する

Claude Code を開始します。すべてのツール呼び出しは両方のフックを通過します：

You: Please read the README and summarize it.

Claude: I will read README.md.
  [PreToolUse: Read ./README.md -> allow]
  [Tool: Read executes]
  [PostToolUse: receipt rcpt-a8f3c9d2 signed to ./receipts/]

... summary of README ...

20 個のツール呼び出しのセッションは、各レシートが先行レシートにハッシュチェーンされた 20 個のレシートを生成します。

ステップ 4: レシートを検査する

cat ./receipts/$(ls -t ./receipts/ | head -1)

{
  "receipt_id": "rcpt-a8f3c9d2",
  "receipt_version": "1.0",
  "issuer_id": "claude-code-protect-mcp",
  "event_time": "2026-04-17T12:34:56.123Z",
  "tool_name": "Read",
  "input_hash": "sha256:a3f8c9d2e1b7465f...",
  "decision": "allow",
  "policy_id": "protect.cedar",
  "policy_digest": "sha256:b7e2f4a6c8d0e1f3...",
  "parent_receipt_id": "rcpt-3d1ab7c2",
  "public_key": "4437ca56815c0516...",
  "signature": "4cde814b7889e987..."
}

signature と public_key を除くすべてのフィールドが Ed25519 署名でカバーされます。署名後にフィールドを変更すると、署名が無効化されます。

ステップ 5: レシートチェーンを検証する

npx @veritasacta/verify ./receipts/*.json

終了コード：

コード	意味
0	すべてのレシートが検証済み。チェーンは完全
1	レシートが署名検証に失敗（改ざんまたは間違ったキー）
2	レシートが不正な形式

ステップ 6: 改ざん検出のデモンストレーション

任意のレシートの decision フィールドを allow から deny に変更します：

python3 -c "
import json, os
path = './receipts/' + sorted(os.listdir('./receipts'))[-1]
r = json.loads(open(path).read())
r['decision'] = 'deny'
open(path, 'w').write(json.dumps(r))
"

npx @veritasacta/verify ./receipts/*.json

検証ツールは終了コード 1 で終了し、どのレシートが失敗したかを報告します。Ed25519 署名は改ざんされたペイロードの JCS 正規形式バイトと一致しなくなります。

フィールドを復元すると、検証は再度パスします。

暗号化の仕組み

3 つの不変量により、レシートは準拠する任意の実装全体でオフライン検証可能になります：

1. **JCS 正規化（RFC 8785）**は署名前に実施されます。キーをソート、空白を最小化、文字列を NFC 正規化します。同じレシート内容に対して、2 つの独立した実装はバイト同一の署名ペイロードを生成します。
2. **Ed25519 署名（RFC 8032）**は正規バイトに対して実施されます。決定論的、固定サイズ、ノンスの依存性なし。
3. ハッシュチェーンリンケージ。各レシートの parent_receipt_hash は先行レシートの正規形式の SHA-256 です。挿入、削除、並び替えは後続レシートを破壊します。

正式なワイヤフォーマットについては、draft-farley-acta-signed-receipts を参照してください。

クロス実装の相互運用性

レシートフォーマットには現在、4 つの独立した実装があります：

実装	言語	ユースケース
protect-mcp	TypeScript	Claude Code、Cursor、MCP ホスト
protect-mcp-adk	Python	Google Agent Development Kit
sb-runtime	Rust	OS レベルサンドボックス（Landlock + seccomp）
APS governance hook	Python	CrewAI、LangChain

いずれかによって生成されたレシートは、@veritasacta/verify に対して検証されます。監査人はオペレータのツール選択を信頼する必要はありません。フォーマットが契約です。

CI/CD 統合

マージを受信チェーン検証でゲートすると、破損した証拠チェーンでのビルドはランディングしません：

# .github/workflows/verify-receipts.yml
name: Verify Decision Receipts
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - name: Run governed agent
        run: python scripts/run_agent.py > receipts.jsonl
      - name: Verify receipt chain
        run: npx @veritasacta/verify receipts.jsonl

レシートをアーティファクトとしてアーカイブし、チェーンがジョブ実行を超えて存続するようにします：

      - name: Upload receipts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: decision-receipts
          path: receipts/

エージェント構築ソフトウェア向けの SLSA 由来との構成

Claude Code がソフトウェアを構築・リリースするとき（npm install、npm build、npm publish をツール呼び出しとして実行）、レシートチェーンはステップごとのビルドログです。SLSA Provenance v1 にはこのための拡張ポイント（byproducts フィールド）があり、構築アテステーションと共にレシートチェーンを参照できます。

agent-commit ビルドタイプは ResourceDescriptor 形状を使用するパターンを文書化しています：

{
  "name": "decision-receipts",
  "digest": { "sha256": "..." },
  "uri": "oci://registry/org/build-xyz/receipts:sha256-...",
  "annotations": {
    "predicateType": "https://veritasacta.com/attestation/decision-receipt/v0.1",
    "signerRole": "supervisor-hook"
  }
}

SLSA 由来はビルダーアイデンティティで署名されます。レシートアテステーションは supervisor-hook アイデンティティで署名されます。2 つのトラストドメイン、副産物層でクロス参照されます。構成についての議論は slsa-framework/slsa#1594 を参照してください。

よくある落とし穴

バージョン管理に秘密鍵がある。生成された ./protect-mcp.key はコミットしてはいけません。上記の例は .gitignore に追加しています。鍵が誤ってコミットされた場合、直ちにローテーション（鍵ファイルを削除し、次回実行時にフックが再生成するようにする）してください。

フックコマンドのクォート。フックは $TOOL_NAME と $TOOL_INPUT を環境変数として受け取ります。スペースや特殊文字を含む入力が正しく渡されるように、クォート "$TOOL_INPUT" を保持してください。

CI でのレシートディレクトリ。Claude Code が CI で実行される場合、ジョブの最後にアーティファクトとしてレシートをアップロードするか、チェーンはジョブ終了時に失われます。

ポリシーが見つからない。例の PreToolUse フックは --fail-on-missing-policy false を使用するため、欠落した ./protect.cedar が Claude Code を壊しません。本番環境ではこのフラグを削除し、欠落したポリシーがハードエラーとして扱われるようにしてください。

このマーケットプレイスの関連項目

• protect-mcp — ランタイムフック実装（本番環境ではこのプラグインを使用）
• review-agent-governance — レビュー表面アクション前に人間の承認が必要。protect-mcp と構成可能

参考資料

• draft-farley-acta-signed-receipts — IETF ドラフト、レシートワイヤフォーマット
• RFC 8032 — Ed25519
• RFC 8785 — JCS
• Cedar ポリシー言語
• npm の protect-mcp
• npm の @veritasacta/verify
• in-toto/attestation#549 — Decision Receipt predicate 提案
• agent-commit ビルドタイプ — エージェント生成コミットの SLSA 由来
• Microsoft Agent Governance Toolkit（examples/protect-mcp-governed/）
• AWS Cedar for Agents