结合Cedar策略门控（默认拒绝）与签名收据，用于AI智能体工具调用。
protect-mcp 是一个位于AI智能体工具调用前的门控。它针对每个调用根据 Cedar 策略（AWS用于IAM的同一语言）进行评估，在执行前阻止违反规则的行为，并为每个决策签署可离线验证的Ed25519收据。它在本地运行，不将任何决策遥测数据发送到任何地方，并采用MIT许可证。
would_deny: true，因此失败绝不会无声无息。serve --enforce 和 doctor 运行启动自检，除非它们能证明已知被禁止的操作确实被拒绝，否则拒绝启用门控。无法证明它拒绝的门控不会启动。@veritasacta/verify 离线验证。无需信任供应商：数学不在乎谁运行它。npx protect-mcp init
npx protect-mcp wrap -- node your-mcp-server.js
npx protect-mcp dashboard --open
npx protect-mcp recommend --write
npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js
对于Claude Desktop，先运行一次试运行配置补丁，然后再应用它：```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open
仪表盘绑定到 127.0.0.1，仅读取本地日志/收据文件，不会上传任何内容。仅当您明确想要托管的 ScopeBlind 仪表盘时，才使用 npx protect-mcp connect。
如果您更愿意将 gate 作为工具调用，而不是连接 Claude Code 钩子，则将其作为 MCP 服务器运行：```bash npx protect-mcp mcp
由于该分块展示了 MCP 的四个只读工具（整个循环），与之前的分块没有直接衔接问题，以下是对该分块的忠实翻译：
它通过 stdio 进行 MCP 通信，并暴露四个只读工具，整条链如下：
- **`evaluate_action`**：根据内联 Cedar 策略决定提议的工具调用，采用失败关闭原则（任何策略错误均视为 DENY）。返回 `{ allowed, decision, reason, policy_digest }`。
- **`sign_decision`**：将决策转换为 Ed25519 签名收据（拒绝对应 `gateway_restraint`，允许对应 `decision_receipt`）。返回收据及公钥；若未提供密钥，则生成临时密钥。
- **`verify_receipt`**：离线根据公钥验证已签名的收据。返回 `{ valid, error, type, kid, issuer }`。
- **`self_test`**：自证明，无输入。已知被禁止的操作将被拒绝，随后执行签名收据的往返验证，篡改版本校验则失败。
将任意 MCP 主机指向该服务，例如 Claude Desktop：```json
{
"mcpServers": {
"protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
}
}
Receipts are byte-compatible with the ones the gate signs at runtime, so a
receipt minted here verifies with @veritasacta/verify
and the browser verifier just the same.
protect-mcp dashboard 是操作员从可见性转向执行控制的视图：
Require approval、Block 或 Observe。在审核更改后重新启动包装器。对于实时桌面后备审批，使用包装器打印的本地网关审批端点和随机数启动控制面板：```bash
npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"
`Approve` 在这些标志存在时转发到实时本地网关。
`Deny`、`Edit` 和 `Take over` 作为批准决议记录本地保存；将其用作操作员指令，并在需要时重新运行该工具。
### 付费边界 MVP：摘要锚定，而非数据上传
本地的自签名收据保持免费且可离线验证。付费边界是独立的证据，表明 ScopeBlind 在某个时间点、在某个组织身份下看到了收据摘要，但并未接收原始提示、工具载荷、输出、私钥或原始收据。```bash
# Create or refresh a local org identity and public-key directory.
npx protect-mcp registry init --org "Meridian Global Macro" --billing-account acct_meridian
# Local preview: writes a digest registry and shareable static verifier page.
npx protect-mcp registry anchor
# Hosted mode: uploads receipt digests only for independent anchoring.
SCOPEBLIND_TOKEN=... npx protect-mcp registry anchor \
--hosted \
--endpoint https://api.scopeblind.com \
--verifier-base https://legate.scopeblind.com
本地预览被特意标记为 local-preview-not-independent。
托管模式仅锚定收据哈希、请求ID、组织公钥和账单元数据。
它不上传原始收据或敏感上下文。
protect-mcp killer-demo 生成一个完整的三分钟销售/演示包：```bash
npx protect-mcp killer-demo --dir ./scopeblind-demo
它创建模拟的文件系统、GitHub、电子邮件和PMS活动；在影子模式下显示风险调用；应用策略包；要求批准敏感PMS预订；通过网关执行；写入签名收据；证明原始收据验证通过；证明被篡改的收据失败；并创建选择性披露包，该包隐藏敏感上下文同时显示最小证明。
首先打开生成的`DEMO-RUNBOOK.md`。然后运行打印的仪表板命令，引导客户完成确切的序列。
### 选择性披露 v0
承诺模式收据可以携带`committed_fields_root`，而不是以明文形式暴露每个字段。之后，持有者可以仅披露选定的字段：```bash
npx protect-mcp verify-disclosure \
--receipt ./receipts/selective-disclosure.receipt.json \
--disclosure ./receipts/selective-disclosure.tool-only.json
验证者检查父收据哈希值、Ed25519签名、承诺根以及每个已披露字段的Merkle证明。然后它解释哪些字段被披露，哪些已承诺字段保持隐藏。这是加盐承诺披露，不是完全零知识，但它使隐私声明具体化：审计者可以在不接收完整工具载荷或敏感桌面上下文的情况下验证选定的事实。
你可以对记录提出声明而不透露记录本身。铸造一个签名的、位置盲化的证明，覆盖整个记录，仅披露每个决策类别（收据摘要、裁决、能力标签），而绝不透露你的工具输入、输出或数据：```bash
npx protect-mcp claim --no net.egress
任何人离线验证它，只能看到类别，而看不到内容：```bash
npx protect-mcp verify-claim claim-<id>.json
验证者会重新计算已披露集合上的Merkle根，并独立重新计算谓词，因此基于该披露，签发者无法对声明进行作假。添加 --anchor 可以将声明的摘要记录在公共的、仅可追加的ScopeBlind透明度日志中，从而让不信任您的对方可以确认已披露的集合是完整的且未被悄悄重新切割（仅发送哈希值；记录保留在本地）：```bash
npx protect-mcp claim --no net.egress --anchor
这是一种可问责、位置盲的证明，并非完全的零知识：它揭示了形状，而非内容。
## 60秒内尝试（无需代理）
[](https://legate.scopeblind.com/record)
在 [legate.scopeblind.com/record](https://legate.scopeblind.com/record) 观看两分钟短片，然后针对你自己的副本进行重放：```bash
npx protect-mcp sample # seed a labeled sample record (8 decisions: 1 blocked, 2 payments)
npx protect-mcp record # open it: signatures verified in your browser
npx protect-mcp claim --payment-under 100 --anchor --output payments-under-100.json
npx protect-mcp verify-claim payments-under-100.json
npx protect-mcp anchor-record
将生成的 demo-tampered.jsonl 拖入记录页面，即可看到签名后的编辑被捕获。sample 拒绝触碰已有记录，因此请在一个空文件夹中运行。当你准备好实际操作时，接入下面的门控，同样的命令将对你的代理自身记录运行。
npx protect-mcp init-hooks
npx protect-mcp serve --enforce --cedar ./cedar
一次性评估，就像 PreToolUse 钩子调用它的方式那样。退出码 2 表示拒绝（工具被阻止）；退出码 0 表示允许：```bash
npx protect-mcp evaluate --cedar ./cedar --tool Bash --input '{"command":"rm"}'
echo $? # 2 -> denied, fail-closed
npx protect-mcp evaluate --cedar ./cedar --tool Read --input '{"path":"README.md"}'
echo $? # 0 -> allowed
缺失或无法加载的策略会拒绝（exit 2），除非你显式传递 --fail-on-missing-policy false。
protect-mcp init-hooks 为你写入一个 .claude/settings.json 文件。要手动连接网关，你需要两个动词：evaluate (PreToolUse, 在 exit 2 时阻塞) 和 sign (PostToolUse, 记录收据)。固定版本，以确保 Claude Code 会话始终运行你测试过的网关：```json
{
"hooks": {
"PreToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "npx [email protected] evaluate --cedar ./cedar --tool "$TOOL_NAME" --input "$TOOL_INPUT""
}
]
}
],
"PostToolUse": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "npx [email protected] sign --tool "$TOOL_NAME" --receipts ./receipts --key ./keys/gateway.json"
}
]
}
]
}
}
`evaluate` 在拒绝时退出码为 2，因此 Claude Code 会阻止工具调用，允许时退出码为 0。
`sign` 是尽力而为的：当配置了密钥时，它会附加一个 Ed25519 签名的收据，如果没有签名器可用，它会记录一条诚实的未签名行（`"signed": false`）而不是让工具失败。
## 在其他代理中使用（Codex, Cursor, Gemini, Hermes）
相同的失败封闭门控作为工具钩子在支持它们的任何代理中运行。添加 `--format <host>` 以便动词从标准输入读取该主机的钩子负载并在其契约中拒绝：```bash
# the PreToolUse / before-tool command for each host
npx -y protect-mcp@latest evaluate --format codex --cedar ./cedar # OpenAI Codex
npx -y protect-mcp@latest evaluate --format gemini --cedar ./cedar # Gemini CLI BeforeTool
npx -y protect-mcp@latest evaluate --format cursor --cedar ./cedar # Cursor beforeShellExecution
npx -y protect-mcp@latest evaluate --format hermes --cedar ./cedar # Hermes pre_tool_call
在工具后事件中，将每个与 sign --format <host> 配对以获取收据。重要的情况是 Hermes，它忽略钩子退出代码并从标准输出读取裁决，因此 --format hermes 通过 {"decision":"block"} 拒绝，而不是退出码2（原始退出码2在那里会静默失败开放）。没有 --format 时，动词读取 --tool/--input 标志，完全与上面的 Claude Code 部分相同。
Cedar 策略存放在你用 --cedar 参数指向的目录中。forbid 规则拒绝，permit 规则允许。要匹配工具输入中的某个值，使用 .contains() 惯用法：```cedar
// Allow read-only tools.
permit(
principal,
action == Action::"MCP::Tool::call",
resource == Tool::"Read"
);
// Deny dangerous shell commands by matching the command against a list. forbid( principal, action == Action::"MCP::Tool::call", resource == Tool::"Bash" ) when { ["rm", "dd", "mkfs"].contains(context.command) };
// Block destructive tools outright. forbid( principal, action == Action::"MCP::Tool::call", resource == Tool::"delete_file" );
> **危险：** 请勿编写 `context.command in ["rm", "dd"]` 以匹配字符串与列表。`in` 用于实体层级关系，而非字符串成员关系。Cedar 将该表达式视为类型错误，并静默丢弃整个 `forbid` 规则，这（在默认允许的网关下）会留下一个残留的 `permit`。这正是以下安全公告所描述的确切缺陷。请改用 `[...].contains(context.command)`。从 0.7.0 版本开始，网关遇到该错误时会拒绝而非允许，并且如果该模式重新出现在已发布策略中，CI 触发测试将导致构建失败。参见 [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9)。
### 入门策略包
大多数团队不应从零开始编写 Cedar 策略。安装一个入门包，以影子模式运行，检查执行记录，然后收紧或强制执行：```bash
npx protect-mcp policy-packs list
npx protect-mcp policy-packs show secrets-safe
npx protect-mcp policy-packs install filesystem-safe --dir ./cedar
npx protect-mcp policy-packs install all --dir ./cedar
npx protect-mcp serve --cedar ./cedar
内置包：
filesystem-safe：破坏性文件操作和类似机密路径读取。git-safe：强制推送、硬重置、破坏性清理、仓库删除。email-safe：允许草稿，阻止无人值守发送。database-safe：面向读取的数据库姿态，阻止写入/管理SQL。cloud-spend-safe：明显的云开销创建和基础设施销毁。secrets-safe：常见的文件、环境变量、Shell和云机密外泄。finance-mandate-safe：预订流程中的受限清单和集中度违规。收据经过签名，任何持有公钥的人都可以离线验证。无需网络、无需供应商、无需信任ScopeBlind：```bash npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl
`npx protect-mcp bundle --output audit.json` 导出一个独立、可离线验证的审计包，包含您的收据和公共签名密钥。
## 安全性
`protect-mcp` 0.7.0 设计上默认为拒绝。在任何策略评估错误、缺失引擎或策略评估出错时，决策为 DENY，而不是允许。`serve --enforce` 和 `doctor` 会运行启动自检，证明网关在受信任前会拒绝已知的禁用向量，如果无法通过则拒绝启用。
**受影响版本：0.5.x 和 0.6.x。** 这些版本默认为允许（在评估错误时返回 ALLOW），并且未正确针对固定引擎评估 Cedar，因此 `forbid` 规则可能无法阻止。**请升级至 >= 0.7.0。**
详细信息和补救措施：[GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9)。
要报告漏洞，请参见 [SECURITY.md](https://github.com/scopeblind/scopeblind-gateway/blob/HEAD/SECURITY.md)。
## 命令
| 命令 | 描述 |
|---------|-------------|
| `serve` | 启动 Claude Code 的 HTTP 钩子服务器（端口 9377）。`--enforce` 首先运行约束自检；`--cedar <目录>` 和 `--policy <路径>` 选择策略。 |
| `init` | 生成 Ed25519 密钥对（`keys/gateway.json`）、配置模板和示例策略。 |
| `sample` | 种子一个清晰标记的示例记录（8个决策：一个被阻止的调用，两个支付；kid `sample-demo`）以及一个被篡改的副本，以便在接入代理之前从头重放 `record`、`claim`、`verify-claim` 和 `anchor-record`。拒绝触碰现有记录；`--force` 覆盖。 |
| `policy` | 从终端查看和更改 Cedar 策略：`policy list`（每个工具的允许/禁止/默认拒绝，以及网关允许或拒绝的频率）、`policy show`、`policy allow <tool>`、`policy deny <tool>`、`policy path`。运行中的 `serve` 会热重载更改。 |
| `wrap` | 打印受保护的 MCP 命令或补丁 Claude Desktop MCP 服务器。默认干运行；使用 `--write` 更新 Claude Desktop 配置。 |
| `dashboard` | 在 `127.0.0.1` 上启动仅限本地的仪表板，显示工具清单、风险、策略覆盖范围、精确操作批准、收据链和审计导出。 |
| `recommend` | 根据观察到的本地调用草拟可审阅的 JSON 策略。默认干运行；使用 `--write` 创建 `protect-mcp.recommended.json`。 |
| `registry` | 创建组织身份，锚定收据摘要，并编写静态验证器页面。托管模式仅上传摘要。 |
| `record` | 打开一个本地、可搜索的收据查看器（`--live` 在代理运行时流式传输）：在浏览器中根据您的网关密钥验证 Ed25519 签名，包含能力标签、来源树和一键签名导出。全部本地，不上传任何内容。 |
| `claim` | 生成一个签名的、位置无关的记录谓词证明（`--no <cap>` 包括 `--no payment`、`--only <c1,c2>`、`--no-verdict <verdict>`、`--count <verdict>`、`--payment-under <cap>`），仅透露决策类别。添加 `--anchor` 将声明摘要记录到公共透明日志中；注册密钥作为命名组织锚定。 |
| `anchor-record` | 将记录的 Merkle 根 + 计数 + 时间范围检查点到公共日志（心跳友好：无变化时跳过）。后续声明如果其承诺与已锚定的检查点匹配，则可证明是在该检查点时的完整记录。 |
| `verify-claim` | 离线验证声明包：签名、重新计算的 Merkle 根、独立重新计算的谓词以及存在的锚定 sidecar（将锚定信封绑定到此确切声明，然后确认公共日志持有它）。`--check-anchor` 需要锚定；`--offline` 跳过日志跳转。 |
| `killer-demo` | 生成一个从影子模式到策略到批准到签名收据的完整演示包。 |
| `verify-disclosure` | 验证 `scopeblind.selective_disclosure.v0` 包并解释公开字段与隐藏字段。 |
| `policy-packs` | 列出、检查和安装入门级 Cedar 策略包。 |
| `evaluate` | 针对 Cedar 策略评估一个工具调用（PreToolUse 网关）。退出码 2 = 拒绝（安全关闭），退出码 0 = 允许。 |
| `sign` | 将一次工具调用签入收据（PostToolUse）。尽力而为：如果没有密钥，则记录一个诚实的未签名行。 |
| `simulate` | 针对记录的决策日志干运行策略，以查看它会阻止什么。 |
| `demo` | 启动一个内置的演示服务器，包裹了网关，以立即查看收据。 |
| `doctor` | 检查您的设置（密钥、策略、Cedar 引擎、验证器）并运行约束自检。 |
| `bundle` | 导出可离线验证的收据审计包以及公钥。 |
| `report` | 从决策日志和收据生成合规报告（Markdown 或 JSON）。 |
运行 `npx protect-mcp --help` 查看完整标志参考。
## 链接
- 协议（IETF）：[draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
- [CHANGELOG](https://github.com/scopeblind/scopeblind-gateway/blob/HEAD/CHANGELOG.md)
- [npm](https://www.npmjs.com/package/protect-mcp)
- [scopeblind.com](https://scopeblind.com)
MIT 许可。由 [ScopeBlind](https://scopeblind.com) 构建。