AI Agent 治理工具包MCP 工具调用的离线可验证决策收据mcp-receipt-governed实战指南【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit本文基于 agent-governance-toolkit 仓库中的 Tutorial 33《Offline-Verifiable Decision Receipts》编写围绕mcp-receipt-governed适配器展开。该组件为每一个 MCPModel Context Protocol工具调用生成带签名的治理收据governance receipt将 Cedar 策略决策、工具参数哈希与 Agent 身份 DID 绑定在一起并支持在完全离线的环境下验证整条收据链的完整性与真实性。读完本文你将掌握如何安装适配器、如何用 Ed25519 对 RFC 8785 规范化载荷签名、如何通过哈希链检测收据的插入/删除/篡改、如何用 CLI 离线验链以及如何将收据输出为 SLSA v1.0 provenance 供供应链验证工具消费。背景为什么每个工具调用都需要一张可离线验证的收据在 AI Agent 治理场景中一次 MCP 工具调用读文件、删文件、发邮件……往往发生在多云、多租户、跨组织的分布式环境里。仅仅当时做了策略判断是不够的——事后审计、合规取证、供应链安全验证都需要一份独立于原始基础设施的、第三方可以自行验证的证据。mcp-receipt-governed的目标正是如此把Cedar 策略决策 MCP 工具名与参数 Agent DID打包成一份结构化的GovernanceReceipt用 Ed25519 私钥签名后写入哈希链。任何第三方拿到导出的 JSON无需访问 AGT 基础设施、无需联网即可验证每条收据的签名是否真实Ed25519 / RFC 8032收据内容是否被篡改签名 载荷哈希收据链是否连续有没有被插入或删除伪造记录。该模块位于 agent-governance-python/agentmesh-integrations/mcp-receipt-governed/包名为agentmesh_mcp_receipts见 pyproject.toml要求 Python 3.11底层加密依赖cryptography。一、安装核心适配器与 Ed25519 加密扩展安装分两种场景# 核心适配器无加密——verify_receipt() 恒返回 False pip install -e agent-governance-python/agentmesh-integrations/mcp-receipt-governed # 带 Ed25519 签名与验证推荐 pip install -e agent-governance-python/agentmesh-integrations/mcp-receipt-governed[crypto]两条命令的区别对应 pyproject.toml 中的可选依赖声明依赖组内容用途默认dependencies空适配器核心逻辑策略评估、收据构造、哈希链[crypto]cryptography46.0.7,48.0Ed25519 私钥签名、公钥验证需要注意不带[crypto]时收据仍然会生成但没有签名verify_receipt()因缺少签名直接返回False。在需要证据效力non-repudiation的生产环境中务必安装[crypto]并使用安全的 32 字节十六进制种子作为签名密钥。仓库中的 demo.py 在cryptography缺失时会打印告警并以未签名模式降级运行这正是该前提的实际体现。二、快速开始从 Cedar 策略到第一条签名收据2.1 创建适配器并治理工具调用以下代码来自教程正文完整可运行from mcp_receipt_governed import McpReceiptAdapter, verify_receipt # 1. 定义 Cedar 策略并创建适配器 adapter McpReceiptAdapter( cedar_policy permit(principal, action Action::ReadData, resource); forbid(principal, action Action::DeleteFile, resource); , cedar_policy_idpolicy:mcp-tools:v1, signing_key_hexa * 64, # 生产环境请使用安全的 32 字节十六进制种子 ) # 2. 治理工具调用——每次调用都会产出一张签名收据 r1 adapter.govern_tool_call(did:mesh:agent-1, ReadData, {path: /data/1.csv}) r2 adapter.govern_tool_call(did:mesh:agent-1, ReadData, {path: /data/2.csv}) r3 adapter.govern_tool_call(did:mesh:agent-1, DeleteFile, {path: /secret}) # 3. 检查结果 for r in adapter.get_receipts(): icon ✅ if r.cedar_decision allow else print(f {icon} {r.tool_name}: {r.cedar_decision} (receipt: {r.receipt_id[:8]}...)) # 4. 验证签名收据 print(f Signature valid: {verify_receipt(r1)})2.2 参数与底层语义源码级McpReceiptAdapter构造参数在 adapter.py 中定义参数默认值说明cedar_policyCedar 策略文本。空策略时所有调用默认deny默认拒绝cedar_policy_iddefault策略标识会写入每张收据便于溯源到具体策略版本signing_key_hexNone32 字节 Ed25519 私钥种子十六进制。为None时不签名storeNone自定义ReceiptStore不传则新建内存存储可用于多适配器共享审计链session_id自动生成 UUID会话标识会进入收据的规范化载荷并影响哈希每次govern_tool_call()的完整流程adapter.py调用CedarPolicyEvaluator评估工具名对应的动作取当前链尾收据的payload_hash()作为新收据的parent_receipt_hash链首为None构造GovernanceReceipt含args_hash 工具参数的 SHA-256若配置了签名密钥执行sign_receipt()签名失败抛出ReceiptSigningErrorfail-closed绝不静默放行写入ReceiptStore重复receipt_id会抛ValueError防重放。策略评估有一个实用的降级设计CedarPolicyEvaluatoradapter.py优先尝试导入agentmesh.governance.cedar.CedarEvaluator若未安装 agentmesh则回退到内联的正则解析识别permit(... Action::X ...)与forbid(... Action::X ...)语句并支持permit(principal, action, resource);全量放行。这意味着核心测试可以在没有任何外部 SDK 的情况下独立运行这一点在 tests/test_adapter.py 的模块注释中明确说明。2.3 治理并执行govern_and_execute如果希望策略判断 收据 实际执行一步完成可以使用govern_and_execute()adapter.py只有决策为allow时才调用真实工具函数被deny的工具绝不会被执行tests/test_adapter.py 中的test_denied_tool_not_executed断言call_count 0若工具执行抛异常异常信息会写入收据的error字段格式为execution_failed: exc执行记录仍然留痕。三、哈希链插入、删除、篡改一网打尽3.1 链式结构收据通过parent_receipt_hash相互链接每条收据包含上一条收据的规范化载荷的 SHA-256 哈希。由此得到三重防护插入伪造收据下一条收据的parent_receipt_hash与插入收据的哈希对不上链立即断裂删除收据后续收据的parent_receipt_hash指向一条已不存在的记录链同样断裂修改任何收据既破坏该收据自身的 Ed25519 签名又破坏下一条收据的哈希链接。┌─────────┐ ┌─────────┐ ┌─────────┐ │Receipt 1│◀───│Receipt 2│◀───│Receipt 3│ │ (root) │ │parentH1│ │parentH2│ └─────────┘ └─────────┘ └─────────┘链首收据的parent_receipt_hash None且该字段为None时不会出现在规范化载荷中见 receipt.py 的canonical_payload()。3.2 规范化载荷与哈希RFC 8785 (JCS) 细节canonical_payload()是实现确定性哈希的关键其序列化规则receipt.pysort_keysTrue键按字典序排序保证键序无关separators(,, :)紧凑无空白消除空白差异ensure_asciiFalse按 RFC 8785 §3.2.2.2 要求输出原始 UTF-8而不是\uXXXX转义——这一点对包含中文、emoji 等 Unicode 工具名尤其重要tests/test_receipt.py 的test_unicode_raw_utf8_not_escaped用读取数据、قراءة等用例专门验证了该行为签名相关字段signature、signer_public_key被排除在外——它们签名覆盖的正是这份载荷本身。payload_hash()即对该规范化字符串做sha256(...).hexdigest()。同理工具参数args_hash也是对参数做排序后的紧凑 JSON 再取 SHA-256hash_tool_argsreceipt.pyNone与{}产生相同哈希参数键序不影响哈希不同参数必然产生不同哈希。3.3 编程方式验链from mcp_receipt_governed import verify_receipt_chain receipts adapter.get_receipts() errors verify_receipt_chain(receipts) if errors: for e in errors: print(f ❌ {e}) else: print( ✅ Chain is contiguous and signatures are valid)verify_receipt_chain()receipt.py返回错误字符串列表空列表即链完全有效。它逐一检查链首约束第一条收据不得携带parent_receipt_hash链连续性第 i 条收据的parent_receipt_hash必须等于第 i-1 条的payload_hash()防重放receipt_id重复立即标记possible replay attack签名有效性每条收据必须带合法 Ed25519 签名公钥必须为 64 位十六进制可信签名者可选参数trusted_keys传入公钥白名单时签名者不在名单内的收据直接拒绝。这些检查在 tests/test_receipt.py 中都有对应的独立测试用例test_inserted_receipt_detected插入伪造收据被检出、test_deleted_receipt_detected删除中间收据被检出、test_tampered_signed_receipt_detected篡改后签名失效、test_untrusted_key_rejected不可信签名者被拒。四、离线验证导出 JSON命令行验链零网络依赖这是本文档的核心场景验证方不需要运行任何 AGT 基础设施也不需要联网只要拿到导出的 JSON 文件和可选签名者公钥即可完成全部验证。4.1 导出收据链import json with open(receipts.json, w) as f: json.dump(adapter.store.export(), f, indent2)ReceiptStore.export()receipt.py基于线程安全的ReceiptStore内部用threading.Lock保护可被多个适配器共享把每条收据的to_dict()完整导出包含receipt_id、tool_name、agent_did、cedar_policy_id、cedar_decision、args_hash、timestamp、session_id、parent_receipt_hash、payload_hash、signature、signer_public_key、error等全部字段。4.2 运行 CLI 验证器cd agent-governance-python/agentmesh-integrations/mcp-receipt-governed python scripts/verify_receipts.py receipts.json预期输出与教程一致╔══════════════════════════════════════════════════════╗ ║ MCP Receipt Chain — Offline Verification ║ ╚══════════════════════════════════════════════════════╝ Loaded 3 receipt(s) from receipts.json [0] Receipt 9f5b54c7-036… (tool: ReadData) ✅ Hash chain contiguous ✅ Payload hash verified ✅ Ed25519 signature valid [1] Receipt f31c719a-d97… (tool: ReadData) ✅ Hash chain contiguous ✅ Payload hash verified ✅ Ed25519 signature valid [2] Receipt 87e5cd86-780… (tool: DeleteFile) ✅ Hash chain contiguous ✅ Payload hash verified ✅ Ed25519 signature valid Verification passed — chain is contiguous and signatures are valid.如果某条收据被改动、删除或插入验证器会精确标记链断裂的位置如Hash chain broken — expected …、Payload hash mismatch、Ed25519 signature verification failed。4.3 验证器实现要点与 CI 集成scripts/verify_receipts.py 的实现有两个值得注意的细节逐条滚动校验verify_chain()用变量expected_parent记录上一条的payload_hash()与当前条目的parent_receipt_hash比对同时把导出的payload_hash字段与重算值比对防止 JSON 文件本身被静默改写。--json结构化输出验证器提供--json参数输出{file: ..., total_receipts: ..., passed: ..., exit_code: ..., receipts: [...]}可直接接入 CI/CD 流水线。退出码约定0 全部通过1 链存在完整性错误2 文件加载失败。4.4 内存审计存储的查询能力除了导出ReceiptStore还提供按agent_did、tool_name、cedar_decision组合过滤的query()以及get_stats()审计摘要总数、allow/deny 数、唯一 Agent 数、唯一工具数。demo.py 在运行结束后即用get_stats()打印审计摘要并将第一条allow收据的完整字段展示出来是观察收据结构的快速途径。五、SLSA Provenance让收据进入供应链验证体系收据可以输出为SLSA v1.0 provenance predicate即标准的 in-toto Statement / SLSA Provenance 格式从而被slsa-verifier、in-toto等标准供应链验证工具直接消费——把一次 Agent 工具调用建模成供应链中的一次构建/执行事件。import json slsa r1.to_slsa_provenance() print(json.dumps(slsa, indent2))输出遵循 SLSA v1.0 schema教程示例{ _type: https://in-toto.io/Statement/v1, subject: [ { name: pkg:agentmesh/tool/ReadData, digest: { sha256: ... } } ], predicateType: https://slsa.dev/provenance/v1, predicate: { buildDefinition: { buildType: https://agent-governance.org/schema/mcp-tool-call/v1, externalParameters: { agent_did: did:mesh:agent-1, cedar_policy_id: policy:mcp-tools:v1, cedar_decision: allow } } } }从源码看receipt.pyto_slsa_provenance()还做了两件教程示例之外的事subject digest 复用args_hashsubject 的digest.sha256即工具参数哈希把这次调用用了什么参数锚定进供应链证据resolvedDependencies 携带父收据哈希非链首收据会把parent_receipt_hash作为依赖项pkg:agentmesh/receipt/parent的摘要列出从而把哈希链原样映射进 SLSA 依赖图链首则为空列表另外runDetails.metadata.startedOn以 UTC 时间Z结尾输出。to_slsa_provenance()的结构正确性在 tests/test_receipt.py 的TestSLSAProvenance中逐字段断言_type、predicateType、subject 名称、父依赖、builder ID 域名、startedOn时区等。六、标准对齐一览本文档所述能力对应的标准与用途如下标准在本模块中的用途RFC 8032Ed25519收据签名与验证sign_receipt/verify_receiptRFC 8785JCS哈希前的规范化 JSON 序列化canonical_payloadSLSA Provenance v1可选的 provenance predicate 输出to_slsa_provenancein-toto Statement v1SLSA 输出的外层 Statement 信封_type字段IETF draft-farley-acta签名收据信封signed receipt envelope设计参考对应实现证据receipt.py 中的canonical_payload()RFC 8785、sign_receipt()/verify_receipt()RFC 8032基于cryptography的Ed25519PrivateKey/PublicKey、to_slsa_provenance()SLSA v1 in-toto v1。七、完整演示与下一步仓库提供了一个开箱即用的端到端演示pip install -e agent-governance-python/agentmesh-integrations/mcp-receipt-governed[crypto] python examples/mcp-receipt-governed/demo.pydemo.py 从 policies/mcp-tools.cedar 加载策略允许ReadData/ListFiles/SearchData禁止DeleteFile/DropTable/SendEmail模拟两名 Agentdid:mesh:researcher、did:mesh:analyst发起 7 次工具调用逐条打印决策、签名状态与验证结果最后给出审计摘要和一条完整收据样例。该 cedar 策略文件本身也是理解哪些调用会被记录为 deny的直观示例。继续深入可参考完整演示examples/mcp-receipt-governed/demo.pyAgent 身份与信任docs/tutorials/02-trust-and-identity.mdCedar 策略引擎docs/tutorials/01-policy-engine.mdMCP 信任代理另一条治理路径agent-governance-python/agentmesh-integrations/mcp-trust-proxy/模块测试策略评估、哈希链、签名、SLSA 输出的完整用例tests/test_adapter.py 与 tests/test_receipt.py生产实践建议生产环境务必使用持久化、来自密钥保管库vault的 32 字节 Ed25519 种子而不是教程示例中的占位密钥将签名失败视为 fail-closed 事件定期把ReceiptStore.export()的 JSON 归档并用verify_receipts.py --json接入 CI让每一次 Agent 工具调用都成为可独立举证、可离线审计、可对接供应链标准的治理证据。【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考