基于 Cedar 策略的 Claude Code 工具调用治理protect-mcp policy-enforcer 实战指南【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents本文以 plugins/protect-mcp/agents/policy-enforcer.md 为绝对主体深入讲解如何在 Claude Code 项目中以 AWS 开源授权引擎 Cedar 编写、审计并验证 AI Agent 工具调用的访问控制策略。你将掌握 permit/forbid 的语义差异、context 属性的实战用法、三档风险画像的策略模板只读研究项目 / 常规开发项目 / 生产部署项目以及结合 protect-mcp 插件PreToolUse 钩子 Ed25519 签名回执形成策略执行 密码学审计完整闭环的可落地方案。一、Policy Enforcer 在 protect-mcp 中的定位在 protect-mcp 插件体系中policy-enforcer 是一个面向 Claude Code 的 Cedar 策略编写与审计 Agent。它与同目录下的 receipt-verifier负责 Ed25519 签名回执与哈希链的离线验证构成先授权、后留痕的两段式治理链路policy-enforcer本文主角负责产出声明式、可形式化验证的 Cedar 策略回答这个 Agent 在项目里能做什么、不能做什么receipt-verifier负责验证每一次决策产生的签名回执回答当时到底发生了什么、有没有被篡改。protect-mcp 的核心机制是每次工具调用前PreToolUse 钩子调用 Cedar 求值器对调用做授权判定每次工具调用后PostToolUse 钩子为本次决策生成 Ed25519 签名回执回执按parent_receipt_id形成哈希链可离线验证。二、Cedar 授权模型的核心知识policy-enforcer 的知识底座是对 CedarAWS 开源授权引擎的深入理解这四块构成任何一条好策略的理论前提1. 语法核心permit / forbid 四元组每条规则围绕四个维度展开principal主体即 Agent、action动作即工具、resource资源即目标对象、context上下文即求值时可用的动态属性。permit ( principal, action Action::Bash, resource ) when { context.command_pattern in [git, npm, ls] };2. 类型系统Cedar 具备实体类型entity types、记录records、集合sets与扩展extensions。策略中通过Action::...、Tool::...等命名空间引用实体通过context.xxx访问上下文属性。3. 求值语义最关键的一条deny 是权威的只要有任何一条forbid规则匹配无论存在多少条匹配的permit最终结果都是拒绝permit 必须全部匹配一个动作只有在某条 permit 规则的条件下匹配且没有任何 forbid 规则拦截时才被允许。这意味着策略编写应以最小权限为默认值显式放行显式拦截高危操作。4. Schema 定义与校验如果项目配有 Cedar schema策略应通过cedar validate做类型检查确保context属性、实体引用与 schema 声明一致再部署生效。三、Claude Code 工具面与 protect-mcp 的集成方式policy-enforcer 需要同时理解三层内容工具本身、工具入参形状、以及求值期可用的上下文。Claude Code 工具面核心工具包括Bash、Edit、Write、Read、Glob、Grep、WebFetch、WebSearch。每条工具的输入形状各不相同——命令字符串Bash、文件路径Edit/Write/Read、URLWebFetch、通配模式Glob/Grep。求值期上下文Cedar 策略通过context检查工具输入Bash用context.command_pattern匹配命令族git、npm、docker、rm 等Edit/Write用context.path_starts_with限定文件系统范围。protect-mcp 的运行时行为从 hooks/hooks.json 可以看到插件的真实钩子配置{ hooks: { PreToolUse: [ { matcher: .*, hooks: [ { type: command, command: npx protect-mcp0.7.4 evaluate --policy \${PROTECT_MCP_POLICY:-./protect.cedar}\ --tool \$TOOL_NAME\ --input \$TOOL_INPUT\ --fail-on-missing-policy false } ] } ], PostToolUse: [ { matcher: .*, hooks: [ { type: command, command: npx protect-mcp0.7.4 sign --tool \$TOOL_NAME\ --input \$TOOL_INPUT\ --output \$TOOL_OUTPUT\ --receipts \${PROTECT_MCP_RECEIPTS:-./receipts/}\ --key \${PROTECT_MCP_KEY:-./protect-mcp.key}\ } ] } ] } }三个关键机制PreToolUse 钩子在每次工具调用前触发对$TOOL_NAME与$TOOL_INPUT执行 Cedar 求值。matcher: .*表示对所有工具生效Cedardeny使钩子以退出码 2 结束Claude Code 据此整体拦截该工具调用permit则放行工具执行PostToolUse 钩子为每次决策生成回执包含工具名、输入哈希、输出哈希、决策结果、策略 ID 与策略摘要、父回执 ID链式链接、公钥与签名写入./receipts/timestamp.json路径可通过PROTECT_MCP_RECEIPTS环境变量覆盖签名密钥通过PROTECT_MCP_KEY覆盖策略文件通过PROTECT_MCP_POLICY覆盖默认均为项目根目录下./开头的相对路径。四、策略编写工作流六步法policy-enforcer 在收到编写一条 Cedar 策略的请求时遵循以下六步方法论这也是任何项目落地策略时应复制的流程先问清项目的风险画像。这是只读即可安全的研究项目还是命令会改动生产的部署流水线还是存在审计要求的受监管环境金融、医疗、受监管研究合适的策略完全取决于上下文从安全默认值出发。优先 allow-list白名单而非 deny-list黑名单先给出完成任务所需的最少工具集合随着需求被证明再逐步增加善用 context 属性。策略通过context检视工具输入——Bash用context.command_pattern匹配命令族Edit/Write用context.path_starts_with限定文件系统范围为高风险操作写配对规则。对危险动作同时写一条带具体条件的permit和一条覆盖明显坏例的forbid——因为 Cedar 的forbid一旦匹配即为权威逐条解释每条规则。Cedar 策略是安全关键资产每条规则都需要注释说明其意图与所对抗的威胁模型对照 schema 校验。若项目有 Cedar schema确保策略通过类型检查部署前运行cedar validate。五、三档风险画像的完整策略模板policy-enforcer 提供了三种场景的完整示例下面全量继承并逐条批注可直接复制改造。5.1 研究项目只读、安全// Allow all read-oriented tools permit ( principal, action in [Action::Read, Action::Glob, Action::Grep], resource ); // Web searches are fine, no fetch permit ( principal, action Action::WebSearch, resource ); // No writes, no shell forbid ( principal, action in [Action::Write, Action::Edit, Action::Bash, Action::WebFetch], resource );设计要点读类工具Read/Glob/Grep整体放行WebSearch单独放行但WebFetch被禁用搜索可以、抓取不行末尾一条兜底forbid封死写入与 Shell与文档开头研究项目只读安全的风险画像一致。5.2 开发项目限定写入、禁止破坏性命令// Reads are free permit ( principal, action in [Action::Read, Action::Glob, Action::Grep], resource ); // Writes only within the project directory permit ( principal, action in [Action::Write, Action::Edit], resource ) when { context.path_starts_with ./ }; // Safe shell commands only permit ( principal, action Action::Bash, resource ) when { context.command_pattern in [ git, npm, pnpm, yarn, ls, cat, pwd, echo, test, node, python, make ] }; // Never destructive forbid ( principal, action Action::Bash, resource ) when { context.command_pattern in [rm -rf, dd, mkfs, shred] };设计要点写入被when { context.path_starts_with ./ }限定在项目目录内Shell 采用命令族白名单git/npm/pnpm/yarn/ls/cat/pwd/echo/test/node/python/make对rm -rf、dd、mkfs、shred等破坏性命令显式forbid。注意这里配对规则的体现Bash既被 permit 白名单约束又被 forbid 黑名单兜底双重保险。5.3 生产部署严格、逐动作显式放行// Reads require evidenced trust tier permit ( principal, action in [Action::Read, Action::Grep], resource ) when { context.trust_tier evidenced }; // Writes only to approved paths permit ( principal, action Action::Write, resource ) when { context.trust_tier institutional context.path_starts_with in [./deployments/, ./config/] }; // Shell only for explicit deployment commands permit ( principal, action Action::Bash, resource ) when { context.trust_tier institutional context.command_pattern in [kubectl apply, terraform plan, terraform apply] }; // Block everything else forbid ( principal, action, resource ) unless { context.trust_tier in [evidenced, institutional] };设计要点引入context.trust_tier信任层级evidenced/institutional作为放行前提——读取需evidenced写入仅限./deployments/、./config/且需institutionalShell 仅放行kubectl apply、terraform plan、terraform apply等显式部署命令最后一条forbid ... unless是默认拒绝的兜底闸门凡 trust_tier 不在此列者一律拦截。这是三类模板中约束最严的一种适合受监管环境。六、从文档到仓库源码策略的真实求值形状文档中的示例为了可读性采用Action::Read这种抽象写法。而仓库测试夹具揭示了 protect-mcp≥ 0.7.0实际求值的实体形状见 test/fixtures/test-policy.cedar 的头部注释protect-mcp 0.7.0 实际求值的形状为principalAgent::idactionAction::MCP::Tool::callresourceTool::toolName工具输入位于context.input。对应的测试策略片段// Allow read-oriented tools. permit ( principal, action Action::MCP::Tool::call, resource ) when { resource Tool::Read || resource Tool::Glob || resource Tool::Grep || resource Tool::WebSearch }; // Allow Bash only for safe command prefixes. permit ( principal, action Action::MCP::Tool::call, resource Tool::Bash ) when { context has input context.input has command (context.input.command like git* || context.input.command like npm* || context.input.command like ls* || context.input.command like cat* || context.input.command like echo* || context.input.command like pwd* || context.input.command like node*) };从源码结构可以推断两条重要实现事实动作统一为Action::MCP::Tool::call资源才是具体的工具名Tool::Bash、Tool::Read等这与文档示例的动作即工具抽象一一对应上下文携带原始工具输入context.input.command是 Bash 的命令字符串策略用like前缀匹配做安全命令白名单用*rm -rf*、dd *、*mkfs*、*shred*等模式做破坏性命令拦截。测试夹具同时给出了策略求值的端到端证据pretool-allow-read.jsonRead读取./README.md期望permit退出码 0pretool-allow-bash-safe.jsonBash执行git status期望permit退出码 0pretool-deny-bash-destructive.jsonBash执行rm -rf /期望forbid退出码 2pretool-deny-write.jsonWrite写入./secrets.env期望forbid退出码 2。七、审计既有策略五步检查清单policy-enforcer 在审核用户已写好的策略时执行如下五步检查这也是团队代码评审时可以套用的模板检查危险操作是否缺少forbid规则——已知高危动作递归删除、磁盘格式化、密码擦除等必须有显式拦截确认 context 属性已对照 schema 校验——context.command_pattern、context.path_starts_with、context.trust_tier等字段必须在 schema 中有声明否则求值行为不可预期排查过宽的permit规则——没有when子句的 permit 是典型反模式等于无条件放行检查逻辑缺口——例如Edit被允许但Write被禁止会导致绕过写入限制的路径验证策略通过cedar validate——部署前的最后一道类型与语法闸门。八、策略执行的完整验证闭环策略生效后的正确性验证在仓库中由 test/README.md 描述的 8 项端到端测试兜底覆盖求值 → 签名 → 验证全链路#场景期望退出码1PreToolUse作用于Read0permit2PreToolUse作用于Bash git status0permit3PreToolUse作用于Bash rm -rf /2forbid4PreToolUse作用于Write2forbid5PostToolUse签名生成回执文件0成功6生成的回执符合 schema0有效7veritasacta/verify接受该回执0有效8被篡改的回执被拒绝1tampered第 8 项是关键的回归防线翻转签名回执中的decision字段必须使 Ed25519 签名失效验证器必须返回 1 而非 0。而 expected/receipt-schema.json 定义了回执的 JSON Schema每个回执必须包含receipt_id、receipt_version、issuer_id、event_time、tool_name、input_hash、decision、policy_id、policy_digest、parent_receipt_id、public_key、signature等字段。离线验证命令由veritasacta/verify提供# 验证单条回执退出码 0有效1被篡改2格式错误 npx veritasacta/verify receipts/2026-04-15T10-30-00Z.json # 验证整条哈希链 npx veritasacta/verify receipts/*.json在 Claude Code 内还可使用插件自带的斜杠命令/verify-receipt path验证单条回执/audit-chain [--last N]回溯验证./receipts/中的回执链。完整安装与配置流程claude plugin install wshobson/agents/protect-mcp、npx protect-mcplatest serve --enforce启动本地签名服务、.claude/settings.json挂载钩子见 skills/protect-mcp-setup/SKILL.md。九、总结声明式治理 密码学留痕policy-enforcer 的价值在于把Agent 能做什么从隐式的模型行为转变为显式、声明式、可形式化验证的 Cedar 策略并与 protect-mcp 的 Ed25519 签名回执体系结合形成事前授权、事后留痕、随时可证的完整闭环事前PreToolUse 钩子按 Cedar 策略逐次求值deny即拦截退出码 2事后PostToolUse 钩子为每次决策签发 Ed25519 回执RFC 8032 签名 RFC 8785 JCS 规范化经parent_receipt_id哈希链接续成链随时任何第三方可用veritasacta/verify离线验证单条回执或整条链无需信任运营商、无需联网。编写策略时记住 policy-enforcer 的核心纪律先问风险画像、从白名单默认值起步、用 context 属性收窄作用域、为高危操作写 permit/forbid 配对规则、逐条注释威胁模型、部署前过cedar validate。这样产出的策略既是开发期的安全护栏也是合规审计期可直接呈堂的正式证据。【免费下载链接】agentsMulti-harness agentic plugin marketplace for Claude Code, Codex, Cursor, OpenCode, GitHub Copilot, and Google Antigravity项目地址: https://gitcode.com/GitHub_Trending/agents24/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考