
关于
MCP 工具调用的代理治理技能——Cedar 策略编写、影子模式到强制执行的渐进部署,以及 Ed25519 回执验证。
name: protect-mcp-governance description: "MCP 工具调用的代理治理技能——Cedar 策略编写、影子模式到强制执行的渐进部署,以及 Ed25519 收据验证。" risk: safe source: community source_repo: scopeblind/scopeblind-gateway source_type: official date_added: "2026-04-05"
使用 protect-mcp 的 MCP 代理治理
概述
使用 Cedar 策略和 Ed25519 签名收据治理 AI 代理工具调用的指南。此技能教授如何为 MCP 服务器编写访问控制策略、在影子模式下运行以进行观察,以及验证加密审计跟踪。
何时使用此技能
- 需要控制代理可以调用哪些 MCP 工具以及在什么条件下调用时
- 需要代理工具执行的防篡改审计跟踪时
- 渐进式部署治理策略时(先影子模式,再强制执行)
- 为 MCP 工具访问控制编写 Cedar 策略时
- 验证收据或审计包未被篡改时
何时不使用此技能
- 需要通用应用安全审计时(使用
@security-auditor) - 需要扫描代码漏洞时(使用
@security-audit) - 需要不涉及代理特定治理的合规框架指导时
工作原理
protect-mcp 拦截 MCP 工具调用,根据 Cedar 策略(与 AWS Verified Permissions 使用的相同策略引擎)进行评估,并将每个决策签名为 Ed25519 收据。收据是加密证明,证明特定策略在特定时间对特定工具调用进行了评估。
Agent → protect-mcp → Cedar 策略评估 → MCP Server
↓
Ed25519 签名收据
三种运行模式:
- 影子模式(默认)— 记录决策但不阻止。用于在强制执行前观察策略效果。
- 强制模式 — 阻止违反策略的工具调用。在影子模式验证后使用。
- 钩子模式 — 与 Claude Code 钩子集成,实现工具调用前/后治理。
核心概念
Cedar 策略
Cedar 是为授权设计的策略语言。策略通过 WASM 在本地评估——无需网络调用。
// Allow read-only file operations
permit(
principal,
action == Action::"call_tool",
resource
) when {
resource.tool_name in ["read_file", "list_directory", "search_files"]
};
// Deny destructive operations
forbid(
principal,
action == Action::"call_tool",
resource
) when {
resource.tool_name in ["execute_command", "delete_file", "write_file"]
&& resource has args
&& resource.args.contains("rm -rf")
};
签名收据
每个策略决策产生一个签名收据:
{
"payload": {
"type": "protectmcp:decision",
"tool_name": "read_file",
"decision": "allow",
"policy_digest": "sha256:9d0fd4c9e72c1d5d",
"issued_at": "2026-04-05T14:32:04.102Z",
"issuer_id": "sb:issuer:de073ae64e43"
},
"signature": {
"alg": "EdDSA",
"kid": "sb:issuer:de073ae64e43",
"sig": "2a3b5022..."
}
}
收据格式遵循 IETF Internet-Draft draft-farley-acta-signed-receipts。
分步指南
1. 为项目初始化治理
# Install and initialize hooks (Claude Code integration)
npx protect-mcp init-hooks
# Or run as a standalone MCP gateway
npx protect-mcp serve
这会在项目根目录创建 protect-mcp.config.json 和一个入门 Cedar 策略。
2. 编写你的第一个策略
在项目中创建 policy.cedar:
// Start permissive — allow everything in shadow mode
permit(
principal,
action == Action::"call_tool",
resource
);
3. 在影子模式下运行(先观察)
# Shadow mode is the default — logs decisions without blocking
npx protect-mcp --policy policy.cedar -- node your-mcp-server.js
在编写限制性策略之前,审查影子日志以了解代理的行为。
4. 收紧并强制执行
了解工具调用模式后,编写具体策略:
// Allow file reads, deny writes outside src/
permit(
principal,
action == Action::"call_tool",
resource
) when {
resource.tool_name == "read_file"
};
permit(
principal,
action == Action::"call_tool",
resource
) when {
resource.tool_name == "write_file"
&& resource has args
&& resource.args.path like "src/*"
};
// Deny everything else
forbid(
principal,
action == Action::"call_tool",
resource
);
切换到强制模式:
npx protect-mcp --policy policy.cedar --enforce -- node your-mcp-server.js
5. 验证收据
# Verify a single receipt
npx @veritasacta/verify receipt.json --key <public-key-hex>
# Verify an audit bundle (multiple receipts + keys)
npx @veritasacta/verify bundle.json --bundle
# Self-test the verifier (proves it works offline)
npx @veritasacta/verify --self-test
兼容工具
Claude CodeCursor
标签
安全
