protect-mcp 0.7.0 → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +7 -0
- package/README.md +135 -425
- package/SECURITY.md +48 -0
- package/package.json +3 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,12 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.7.1: documentation and security policy
|
|
4
|
+
|
|
5
|
+
No code change from 0.7.0. Rewrote the README to lead with the fail-closed and
|
|
6
|
+
self-test guarantees, and added a `SECURITY.md` disclosure policy (supported
|
|
7
|
+
versions, the affected 0.5.x/0.6.x range, the published advisory, and the
|
|
8
|
+
coordinated-disclosure process). The package now ships `SECURITY.md`.
|
|
9
|
+
|
|
3
10
|
## 0.7.0 (security release): the gate now fails closed and actually evaluates
|
|
4
11
|
|
|
5
12
|
This release fixes the way the Cedar policy gate behaves when anything goes
|
package/README.md
CHANGED
|
@@ -1,240 +1,122 @@
|
|
|
1
1
|
# protect-mcp
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[](https://www.npmjs.com/package/protect-mcp)
|
|
5
|
-
[](https://github.com/wshobson/agents/tree/main/plugins/protect-mcp)
|
|
6
|
-
[](./LICENSE)
|
|
7
|
-
|
|
8
|
-
> A policy check that sits between your AI agent and the tools it calls.
|
|
9
|
-
> Every tool call is evaluated against a rule you wrote. Every decision is signed.
|
|
10
|
-
|
|
11
|
-
> **Receipt format:** `protect-mcp` emits Veritas Acta receipts. Legacy
|
|
12
|
-
> ScopeBlind receipts remain verifiable, but Acta v0.1 is the canonical
|
|
13
|
-
> format going forward. Spec: [`@veritasacta/protocol`](https://www.npmjs.com/package/@veritasacta/protocol)
|
|
14
|
-
> · IETF: [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/).
|
|
15
|
-
|
|
16
|
-
## What it does, in plain English
|
|
17
|
-
|
|
18
|
-
When an AI agent (Claude Code, Cursor, a custom LangChain app, anything that
|
|
19
|
-
uses the Model Context Protocol) wants to run a command, edit a file, or call
|
|
20
|
-
an API, `protect-mcp` intercepts that request before it executes:
|
|
21
|
-
|
|
22
|
-
1. **Checks a policy.** You write rules in [Cedar](https://www.cedarpolicy.com/)
|
|
23
|
-
— the same policy language AWS uses for IAM. Rules like *"never allow
|
|
24
|
-
`rm -rf /`"*, *"only allow `Bash` during working hours"*, or *"require
|
|
25
|
-
human approval for anything touching production."*
|
|
26
|
-
2. **Returns a decision.** `allow`, `deny`, or `request_approval`. The agent
|
|
27
|
-
framework respects the decision — if it's `deny`, the tool call doesn't run.
|
|
28
|
-
3. **Signs a receipt.** An Ed25519-signed, hash-chained record of the decision,
|
|
29
|
-
written to `.receipts/`. Verifiable offline by anyone with the public key.
|
|
30
|
-
When your auditor asks *"what did that agent do on 2026-03-14?"* you have
|
|
31
|
-
cryptographic proof — not a log file you might have tampered with.
|
|
32
|
-
|
|
33
|
-
You install it once. Your agent keeps working the same way. The difference:
|
|
34
|
-
every action it takes is now policy-checked and audit-evidenced.
|
|
35
|
-
|
|
36
|
-
## Who this is for
|
|
37
|
-
|
|
38
|
-
- **Developers using Claude Code / Cursor / Cline** who want *"don't let the
|
|
39
|
-
agent delete my repo"* enforced rather than hoped for.
|
|
40
|
-
- **Security teams** shipping agents to engineering who need a portable
|
|
41
|
-
policy layer that travels across frameworks.
|
|
42
|
-
- **Compliance teams** who need tamper-evident evidence of what agents did,
|
|
43
|
-
verifiable without trusting the vendor.
|
|
44
|
-
|
|
45
|
-
## How it relates to `sb-runtime`
|
|
46
|
-
|
|
47
|
-
`protect-mcp` is a **library** — it sits inside your agent framework and
|
|
48
|
-
gates tool calls cooperatively. Right tool when you own the agent's code and
|
|
49
|
-
trust its framework to honour decisions.
|
|
50
|
-
|
|
51
|
-
[`sb-runtime`](https://github.com/ScopeBlind/sb-runtime) is the companion
|
|
52
|
-
**binary** that wraps the whole agent *process* in an OS-level sandbox
|
|
53
|
-
(Landlock + seccomp on Linux). It enforces decisions at the kernel layer —
|
|
54
|
-
the agent can't ignore them even if it tried. Use `sb-runtime` when you're
|
|
55
|
-
running an agent you didn't write, or when you want belt-and-braces defence
|
|
56
|
-
in depth:
|
|
57
|
-
|
|
58
|
-
```
|
|
59
|
-
┌─────────────────────────────────────────────────┐
|
|
60
|
-
│ sb-runtime ← OS refuses forbidden syscalls │
|
|
61
|
-
│ ┌───────────────────────────────────────────┐ │
|
|
62
|
-
│ │ agent process (Claude Code, Python, …) │ │
|
|
63
|
-
│ │ ┌─────────────────────────────────────┐ │ │
|
|
64
|
-
│ │ │ protect-mcp │ │ │
|
|
65
|
-
│ │ │ ← Cedar decides per tool call, │ │ │
|
|
66
|
-
│ │ │ receipts every decision │ │ │
|
|
67
|
-
│ │ └─────────────────────────────────────┘ │ │
|
|
68
|
-
│ └───────────────────────────────────────────┘ │
|
|
69
|
-
└─────────────────────────────────────────────────┘
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
**One-liner:** `protect-mcp` is the policy hook inside your agent.
|
|
73
|
-
`sb-runtime` is the OS sandbox around it. You want both.
|
|
74
|
-
|
|
75
|
-
---
|
|
76
|
-
|
|
77
|
-
## Quick Start — Claude Code
|
|
78
|
-
|
|
79
|
-
Two commands. Every tool call is receipted.
|
|
3
|
+
Fail-closed Cedar policy gate plus signed receipts for AI agent tool calls.
|
|
80
4
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
| `protect-mcp.json` | JSON policy with signing + rate limits |
|
|
107
|
-
| `.claude/skills/verify-receipt/SKILL.md` | `/verify-receipt` skill for Claude Code |
|
|
108
|
-
|
|
109
|
-
### Architecture
|
|
110
|
-
|
|
111
|
-
```
|
|
112
|
-
Claude Code → POST /hook → protect-mcp (Cedar + sign) → response
|
|
113
|
-
↓
|
|
114
|
-
.protect-mcp-log.jsonl
|
|
115
|
-
.protect-mcp-receipts.jsonl
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
- **PreToolUse**: synchronous Cedar policy check → deny blocks the tool
|
|
119
|
-
- **PostToolUse**: async receipt signing → zero latency impact
|
|
120
|
-
- **deny is architecturally final** — it cannot be overridden by the model or other hooks
|
|
121
|
-
|
|
122
|
-
### Endpoints
|
|
123
|
-
|
|
124
|
-
| Method | Path | Description |
|
|
125
|
-
|--------|------|-------------|
|
|
126
|
-
| POST | `/hook` | Claude Code hook endpoint |
|
|
127
|
-
| GET | `/health` | Server status, policy info, signer info |
|
|
128
|
-
| GET | `/receipts` | Recent signed receipts |
|
|
129
|
-
| GET | `/receipts/latest` | Most recent receipt |
|
|
130
|
-
| GET | `/suggestions` | Auto-generated Cedar policy fix suggestions |
|
|
131
|
-
| GET | `/alerts` | Config tamper detection alerts |
|
|
132
|
-
|
|
133
|
-
### Verify receipts
|
|
5
|
+
[](https://www.npmjs.com/package/protect-mcp)
|
|
6
|
+
[](https://www.npmjs.com/package/protect-mcp)
|
|
7
|
+
[](https://www.npmjs.com/package/protect-mcp)
|
|
8
|
+
[](https://www.npmjs.com/package/protect-mcp)
|
|
9
|
+
|
|
10
|
+
`protect-mcp` is a gate that sits in front of an AI agent's tool calls. It evaluates
|
|
11
|
+
each call against a [Cedar](https://www.cedarpolicy.com/) policy (the same language
|
|
12
|
+
AWS uses for IAM), blocks what breaks the rules before it runs, and signs an
|
|
13
|
+
offline-verifiable Ed25519 receipt of every decision. It runs locally, sends no
|
|
14
|
+
telemetry of your decisions anywhere, and is MIT licensed.
|
|
15
|
+
|
|
16
|
+
## Why it is different
|
|
17
|
+
|
|
18
|
+
- **Fail-closed by default.** On any policy error, a missing engine, or an
|
|
19
|
+
evaluation failure, the decision is DENY. The gate never silently allows. An
|
|
20
|
+
observe mode exists for shadow rollout, but even there a call that would be
|
|
21
|
+
blocked is flagged `would_deny: true`, so a failure is never silent.
|
|
22
|
+
- **It proves its own restraint.** `serve --enforce` and `doctor` run a startup
|
|
23
|
+
self-test and refuse to arm the gate unless they can show that a known-forbidden
|
|
24
|
+
action is actually denied. A gate that cannot prove it denies does not start.
|
|
25
|
+
- **Every decision is a receipt anyone can verify.** Decisions are Ed25519-signed
|
|
26
|
+
and verifiable offline with [`@veritasacta/verify`](https://www.npmjs.com/package/@veritasacta/verify).
|
|
27
|
+
No vendor trust required: the math does not care who runs it.
|
|
28
|
+
|
|
29
|
+
## Quickstart (30 seconds)
|
|
134
30
|
|
|
135
31
|
```bash
|
|
136
|
-
#
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
# From terminal:
|
|
140
|
-
curl http://127.0.0.1:9377/receipts/latest | jq .
|
|
141
|
-
npx protect-mcp receipts
|
|
32
|
+
# 1. Generate an Ed25519 keypair, a config template, and a sample policy.
|
|
33
|
+
npx protect-mcp init
|
|
142
34
|
|
|
143
|
-
#
|
|
144
|
-
|
|
35
|
+
# 2. Put a Cedar policy in ./cedar (see "Write a policy" below), then serve
|
|
36
|
+
# the Claude Code hook gate in enforce mode. It runs a restraint self-test
|
|
37
|
+
# first and refuses to start if it cannot prove it denies a forbidden vector.
|
|
38
|
+
npx protect-mcp serve --enforce --cedar ./cedar
|
|
145
39
|
```
|
|
146
40
|
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
Wrap any stdio MCP server as a transparent proxy:
|
|
41
|
+
One-shot evaluation, the way a PreToolUse hook calls it. Exit code 2 means deny
|
|
42
|
+
(the tool is blocked); exit 0 means allow:
|
|
150
43
|
|
|
151
44
|
```bash
|
|
152
|
-
|
|
153
|
-
|
|
45
|
+
npx protect-mcp evaluate --cedar ./cedar --tool Bash --input '{"command":"rm"}'
|
|
46
|
+
echo $? # 2 -> denied, fail-closed
|
|
154
47
|
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
# Generate keys + config template
|
|
159
|
-
npx protect-mcp init
|
|
48
|
+
npx protect-mcp evaluate --cedar ./cedar --tool Read --input '{"path":"README.md"}'
|
|
49
|
+
echo $? # 0 -> allowed
|
|
160
50
|
```
|
|
161
51
|
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
protect-mcp evaluates every tool call against a policy (JSON, Cedar, or external PDP), signs the decision as an Ed25519 receipt, and logs the result.
|
|
165
|
-
|
|
166
|
-
**Two integration modes:**
|
|
167
|
-
|
|
168
|
-
| Mode | Transport | Use Case |
|
|
169
|
-
|------|-----------|----------|
|
|
170
|
-
| Hook Server | HTTP (`npx protect-mcp serve`) | Claude Code, agent swarms |
|
|
171
|
-
| Stdio Proxy | stdin/stdout (`npx protect-mcp -- ...`) | Claude Desktop, Cursor, any MCP client |
|
|
172
|
-
|
|
173
|
-
**Three policy engines:**
|
|
52
|
+
A missing or unloadable policy denies (exit 2) unless you explicitly pass
|
|
53
|
+
`--fail-on-missing-policy false`.
|
|
174
54
|
|
|
175
|
-
|
|
176
|
-
|--------|--------|-------|
|
|
177
|
-
| JSON | `--policy policy.json` | Simple per-tool rules |
|
|
178
|
-
| Cedar | `--cedar ./policies/` | Local WASM evaluation via `@cedar-policy/cedar-wasm` |
|
|
179
|
-
| External PDP | `policy_engine: "external"` | OPA, Cerbos, or any HTTP PDP |
|
|
55
|
+
## Claude Code hooks
|
|
180
56
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
**11 hook events handled:**
|
|
186
|
-
|
|
187
|
-
| Event | Type | Description |
|
|
188
|
-
|-------|------|-------------|
|
|
189
|
-
| `PreToolUse` | Sync | Cedar/policy evaluation before tool execution |
|
|
190
|
-
| `PostToolUse` | Async | Receipt signing after tool execution |
|
|
191
|
-
| `SubagentStart` / `SubagentStop` | Lifecycle | Worker agent spawn/completion |
|
|
192
|
-
| `TaskCreated` / `TaskCompleted` | Lifecycle | Coordinator task assignment |
|
|
193
|
-
| `SessionStart` / `SessionEnd` | Lifecycle | Session lifecycle with sandbox detection |
|
|
194
|
-
| `TeammateIdle` | Lifecycle | Agent utilization monitoring |
|
|
195
|
-
| `ConfigChange` | Security | Tamper detection for `.claude/settings.json` |
|
|
196
|
-
| `Stop` | Lifecycle | Finalization + policy suggestion summary |
|
|
197
|
-
|
|
198
|
-
Each receipt includes:
|
|
199
|
-
- `swarm.agent_id`, `swarm.agent_type`, `swarm.team_name`
|
|
200
|
-
- `timing.tool_duration_ms`, `timing.hook_latency_ms`
|
|
201
|
-
- `payload_digest` (SHA-256 hash for payloads >1KB)
|
|
202
|
-
- `deny_iteration` (retry count after denial)
|
|
203
|
-
- `sandbox_state` (enabled/disabled/unavailable)
|
|
204
|
-
- OpenTelemetry `otel_trace_id` and `otel_span_id`
|
|
205
|
-
|
|
206
|
-
## Policy File
|
|
57
|
+
`protect-mcp init-hooks` writes a `.claude/settings.json` for you. To wire the
|
|
58
|
+
gate by hand, the two verbs you need are `evaluate` (PreToolUse, blocks on exit 2)
|
|
59
|
+
and `sign` (PostToolUse, records a receipt). Pin the version so a Claude Code
|
|
60
|
+
session always runs the gate you tested:
|
|
207
61
|
|
|
208
62
|
```json
|
|
209
63
|
{
|
|
210
|
-
"
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
64
|
+
"hooks": {
|
|
65
|
+
"PreToolUse": [
|
|
66
|
+
{
|
|
67
|
+
"matcher": "",
|
|
68
|
+
"hooks": [
|
|
69
|
+
{
|
|
70
|
+
"type": "command",
|
|
71
|
+
"command": "npx protect-mcp@0.7.0 evaluate --cedar ./cedar --tool \"$TOOL_NAME\" --input \"$TOOL_INPUT\""
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
],
|
|
76
|
+
"PostToolUse": [
|
|
77
|
+
{
|
|
78
|
+
"matcher": "",
|
|
79
|
+
"hooks": [
|
|
80
|
+
{
|
|
81
|
+
"type": "command",
|
|
82
|
+
"command": "npx protect-mcp@0.7.0 sign --tool \"$TOOL_NAME\" --receipts ./receipts --key ./keys/gateway.json"
|
|
83
|
+
}
|
|
84
|
+
]
|
|
85
|
+
}
|
|
86
|
+
]
|
|
221
87
|
}
|
|
222
88
|
}
|
|
223
89
|
```
|
|
224
90
|
|
|
225
|
-
|
|
91
|
+
`evaluate` exits 2 on deny so Claude Code blocks the tool call, and 0 on allow.
|
|
92
|
+
`sign` is best-effort: it appends an Ed25519-signed receipt when a key is
|
|
93
|
+
configured, and if no signer is available it records an honest unsigned line
|
|
94
|
+
(`"signed": false`) rather than failing the tool.
|
|
95
|
+
|
|
96
|
+
## Write a policy
|
|
226
97
|
|
|
227
|
-
Cedar
|
|
98
|
+
Cedar policies live in a directory you point at with `--cedar`. A `forbid` rule
|
|
99
|
+
denies, a `permit` rule allows. To match against a value in the tool input, use
|
|
100
|
+
the `.contains()` idiom:
|
|
228
101
|
|
|
229
102
|
```cedar
|
|
230
|
-
// Allow read-only tools
|
|
103
|
+
// Allow read-only tools.
|
|
231
104
|
permit(
|
|
232
105
|
principal,
|
|
233
106
|
action == Action::"MCP::Tool::call",
|
|
234
107
|
resource == Tool::"Read"
|
|
235
108
|
);
|
|
236
109
|
|
|
237
|
-
//
|
|
110
|
+
// Deny dangerous shell commands by matching the command against a list.
|
|
111
|
+
forbid(
|
|
112
|
+
principal,
|
|
113
|
+
action == Action::"MCP::Tool::call",
|
|
114
|
+
resource == Tool::"Bash"
|
|
115
|
+
) when {
|
|
116
|
+
["rm", "dd", "mkfs"].contains(context.command)
|
|
117
|
+
};
|
|
118
|
+
|
|
119
|
+
// Block destructive tools outright.
|
|
238
120
|
forbid(
|
|
239
121
|
principal,
|
|
240
122
|
action == Action::"MCP::Tool::call",
|
|
@@ -242,239 +124,67 @@ forbid(
|
|
|
242
124
|
);
|
|
243
125
|
```
|
|
244
126
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
| `clinejection.json` | CVE-2025-6514: MCP OAuth proxy hijack (437K environments) | A01, A03 |
|
|
254
|
-
| `terraform-destroy.json` | Autonomous Terraform agent destroys production | A05, A06 |
|
|
255
|
-
| `github-mcp-hijack.json` | Prompt injection via crafted GitHub issue | A01, A02, A03 |
|
|
256
|
-
| `data-exfiltration.json` | Agent data theft via outbound tool abuse | A02, A04 |
|
|
257
|
-
| `financial-safe.json` | Unauthorized financial transaction | A05, A06 |
|
|
258
|
-
|
|
259
|
-
Cedar equivalents available in `policies/cedar/`.
|
|
260
|
-
|
|
261
|
-
## MCP Client Configuration
|
|
262
|
-
|
|
263
|
-
### Claude Desktop
|
|
264
|
-
|
|
265
|
-
```json
|
|
266
|
-
{
|
|
267
|
-
"mcpServers": {
|
|
268
|
-
"my-protected-server": {
|
|
269
|
-
"command": "npx",
|
|
270
|
-
"args": [
|
|
271
|
-
"-y", "protect-mcp",
|
|
272
|
-
"--policy", "/path/to/protect-mcp.json",
|
|
273
|
-
"--enforce",
|
|
274
|
-
"--", "node", "my-server.js"
|
|
275
|
-
]
|
|
276
|
-
}
|
|
277
|
-
}
|
|
278
|
-
}
|
|
279
|
-
```
|
|
280
|
-
|
|
281
|
-
### Cursor / VS Code
|
|
282
|
-
|
|
283
|
-
Same pattern — replace the server command with `protect-mcp` wrapping it.
|
|
284
|
-
|
|
285
|
-
## CLI Commands
|
|
286
|
-
|
|
287
|
-
```
|
|
288
|
-
Commands:
|
|
289
|
-
serve Start HTTP hook server for Claude Code (port 9377)
|
|
290
|
-
init-hooks Generate Claude Code hook config + skill + sample Cedar policy
|
|
291
|
-
quickstart Zero-config onboarding: init + demo + show receipts
|
|
292
|
-
connect Link to ScopeBlind dashboard (creates sandbox if needed)
|
|
293
|
-
init Generate Ed25519 keypair + config template
|
|
294
|
-
demo Start a demo server wrapped with protect-mcp
|
|
295
|
-
doctor Check your setup: keys, policies, verifier, connectivity
|
|
296
|
-
trace <id> Visualize the receipt DAG from a given receipt_id
|
|
297
|
-
status Show tool call statistics from the decision log
|
|
298
|
-
digest Generate a human-readable summary of agent activity
|
|
299
|
-
receipts Show recent persisted signed receipts
|
|
300
|
-
bundle Export an offline-verifiable audit bundle
|
|
301
|
-
simulate Dry-run a policy against recorded tool calls
|
|
302
|
-
report Generate a compliance report from an audit bundle
|
|
303
|
-
|
|
304
|
-
Options:
|
|
305
|
-
--policy <path> Policy/config JSON file
|
|
306
|
-
--cedar <dir> Cedar policy directory
|
|
307
|
-
--enforce Enable enforcement mode (default: shadow)
|
|
308
|
-
--port <port> HTTP server port (default: 9377 for serve)
|
|
309
|
-
--verbose Enable debug logging
|
|
310
|
-
```
|
|
311
|
-
|
|
312
|
-
## Decision Logs
|
|
313
|
-
|
|
314
|
-
Every tool call emits structured JSON to `stderr`:
|
|
315
|
-
|
|
316
|
-
```json
|
|
317
|
-
[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"cedar_allow","policy_digest":"a1b2c3...","mode":"enforce","hook_event":"PreToolUse","timing":{"hook_latency_ms":1},"otel_trace_id":"..."}
|
|
318
|
-
```
|
|
319
|
-
|
|
320
|
-
When signing is configured, a signed receipt is persisted to `.protect-mcp-receipts.jsonl`.
|
|
321
|
-
|
|
322
|
-
## Audit Bundles
|
|
323
|
-
|
|
324
|
-
```bash
|
|
325
|
-
npx protect-mcp bundle --output audit.json
|
|
326
|
-
```
|
|
327
|
-
|
|
328
|
-
Self-contained offline-verifiable bundle with receipts + signing keys. Verify with `npx @veritasacta/verify`.
|
|
329
|
-
|
|
330
|
-
## Dashboard
|
|
331
|
-
|
|
332
|
-
protect-mcp works fully offline. Optionally connect to the ScopeBlind dashboard for:
|
|
333
|
-
|
|
334
|
-
- Real-time receipt visualization
|
|
335
|
-
- Abuse alerts and anomaly detection
|
|
336
|
-
- Compliance export and audit bundles
|
|
337
|
-
- Usage analytics
|
|
338
|
-
|
|
339
|
-
Free tier: 20,000 receipts/month. No credit card required.
|
|
340
|
-
|
|
341
|
-
[scopeblind.com/pricing](https://scopeblind.com/pricing)
|
|
342
|
-
|
|
343
|
-
### ScopeBlind tenant integration (Founding Plan)
|
|
344
|
-
|
|
345
|
-
If you have a ScopeBlind Founding Plan tenant, set your `SCOPEBLIND_TOKEN`
|
|
346
|
-
(from the welcome email) in the environment and protect-mcp forwards every
|
|
347
|
-
signed receipt to your dashboard at `https://scopeblind.com/console/<your-slug>`.
|
|
348
|
-
|
|
349
|
-
```bash
|
|
350
|
-
# Your protect-mcp install with cloud-synced receipts
|
|
351
|
-
SCOPEBLIND_TOKEN=scp_... \
|
|
352
|
-
npx protect-mcp init-hooks
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
How it works:
|
|
127
|
+
> **Hazard:** do NOT write `context.command in ["rm", "dd"]` to match a string
|
|
128
|
+
> against a list. `in` is for entity hierarchies, not string membership. Cedar
|
|
129
|
+
> treats the expression as a type error and silently discards the whole `forbid`
|
|
130
|
+
> rule, which (under a fail-open gate) leaves a residual `permit` standing. This
|
|
131
|
+
> is the exact defect behind the advisory below. Use `[...].contains(context.command)`
|
|
132
|
+
> instead. From 0.7.0 the gate denies on that error rather than permitting, and a
|
|
133
|
+
> CI tripwire test fails the build if the pattern is reintroduced into a shipped
|
|
134
|
+
> policy. See [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
|
|
356
135
|
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
2. Receipts are batched and POSTed to `/fn/console/<slug>/receipts` every 5
|
|
360
|
-
seconds (up to 128 per batch).
|
|
361
|
-
3. The local `.receipts/` chain remains authoritative regardless of forward
|
|
362
|
-
status. Network failures are retried; quota exhaustion is reported. No
|
|
363
|
-
crash, no blocking.
|
|
136
|
+
Ready-to-use Cedar packs ship in `policies/cedar/` (Clinejection / CVE-2025-6514,
|
|
137
|
+
Terraform destroy, secret-file exfiltration, spending authority).
|
|
364
138
|
|
|
365
|
-
|
|
366
|
-
above quota is rejected with a structured response; receipts stay safe in
|
|
367
|
-
`.receipts/` until you upgrade or until tomorrow.
|
|
139
|
+
## Verify a receipt
|
|
368
140
|
|
|
369
|
-
|
|
141
|
+
Receipts are signed and verifiable offline by anyone with the public key. No
|
|
142
|
+
network, no vendor, no trust in ScopeBlind:
|
|
370
143
|
|
|
371
144
|
```bash
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
npx @veritasacta/verify .receipts/0001.json
|
|
145
|
+
npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl
|
|
146
|
+
# Exit 0 = valid, non-zero = tampered or malformed
|
|
375
147
|
```
|
|
376
148
|
|
|
377
|
-
|
|
149
|
+
`npx protect-mcp bundle --output audit.json` exports a self-contained,
|
|
150
|
+
offline-verifiable audit bundle of your receipts plus the public signing key.
|
|
378
151
|
|
|
379
|
-
##
|
|
152
|
+
## Security
|
|
380
153
|
|
|
381
|
-
|
|
154
|
+
`protect-mcp` 0.7.0 fails closed by design. On any policy-evaluation error, a
|
|
155
|
+
missing engine, or a policy that errored at evaluation, the decision is DENY,
|
|
156
|
+
not allow. `serve --enforce` and `doctor` run a boot self-test that proves the
|
|
157
|
+
gate denies a known-forbidden vector before it is trusted, and refuse to arm if
|
|
158
|
+
it cannot.
|
|
382
159
|
|
|
383
|
-
|
|
384
|
-
|
|
385
|
-
|
|
386
|
-
| **2 IETF Internet-Drafts** | [draft-farley-acta-signed-receipts-01](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/), [draft-pidlisnyi-aps-00](https://datatracker.ietf.org/doc/draft-pidlisnyi-aps/) |
|
|
387
|
-
| **8 cross-engine receipts** | [Composition test](https://github.com/ScopeBlind/examples/tree/main/interop/composition-test): 2 engines, 1 verifier, all VALID |
|
|
388
|
-
| **PRs merged into microsoft/agent-governance-toolkit** | [#667](https://github.com/microsoft/agent-governance-toolkit/pull/667), [#1159](https://github.com/microsoft/agent-governance-toolkit/pull/1159), [#1168](https://github.com/microsoft/agent-governance-toolkit/pull/1168), [#1186](https://github.com/microsoft/agent-governance-toolkit/pull/1186), [#1197](https://github.com/microsoft/agent-governance-toolkit/pull/1197), [#1202](https://github.com/microsoft/agent-governance-toolkit/pull/1202), [#1203](https://github.com/microsoft/agent-governance-toolkit/pull/1203), [#1205](https://github.com/microsoft/agent-governance-toolkit/pull/1205) |
|
|
389
|
-
| **1 verifier, zero dependencies** | `npx @veritasacta/verify receipt.json --key <hex>` (Apache-2.0, offline) |
|
|
160
|
+
**Affected versions: 0.5.x and 0.6.x.** Those lines fail open (they return ALLOW
|
|
161
|
+
on evaluation error) and do not evaluate Cedar correctly against the pinned
|
|
162
|
+
engine, so a `forbid` rule could fail to block. **Upgrade to >= 0.7.0.**
|
|
390
163
|
|
|
391
|
-
|
|
164
|
+
Details and remediation: [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
|
|
165
|
+
To report a vulnerability, see [SECURITY.md](./SECURITY.md).
|
|
392
166
|
|
|
393
|
-
|
|
394
|
-
npx @veritasacta/verify receipt.json --key <public-key-hex>
|
|
395
|
-
# Exit 0 = valid, 1 = tampered, 2 = malformed
|
|
396
|
-
```
|
|
397
|
-
|
|
398
|
-
## Standards & IP
|
|
399
|
-
|
|
400
|
-
- **IETF Internet-Draft**: [draft-farley-acta-signed-receipts-01](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
|
|
401
|
-
- **Patent Status**: 4 Australian provisional patents pending (2025-2026)
|
|
402
|
-
- **Cedar WASM**: [PR #64](https://github.com/cedar-policy/cedar-for-agents/pull/64) merged + [PR #73](https://github.com/cedar-policy/cedar-for-agents/pull/73) (RequestGenerator, pending review)
|
|
403
|
-
|
|
404
|
-
## What's New in v0.7.0 (security release)
|
|
405
|
-
|
|
406
|
-
The gate now fails closed. On any policy-evaluation error, a missing engine, or a
|
|
407
|
-
policy that errored, the decision is DENY, not allow. Cedar is also evaluated
|
|
408
|
-
correctly against cedar-wasm 4.x (earlier versions passed the policy in a shape the
|
|
409
|
-
engine rejected, so evaluation errored and the old fail-open default allowed
|
|
410
|
-
everything). `serve --enforce` now runs a restraint self-test before arming and
|
|
411
|
-
refuses to start if it cannot prove it denies a forbidden vector, `doctor` reports
|
|
412
|
-
that self-test, and one-shot `evaluate` and `sign` verbs are available for hooks.
|
|
413
|
-
Upgrade from any 0.5.x or 0.6.x. See CHANGELOG.md.
|
|
414
|
-
|
|
415
|
-
## What's New in v0.5.3
|
|
416
|
-
|
|
417
|
-
- `quickstart --connect`: Auto-create dashboard sandbox and configure receipt upload
|
|
418
|
-
- `connect` subcommand: Link an existing setup to the ScopeBlind dashboard
|
|
419
|
-
- Anonymous install telemetry (opt-out: `PROTECT_MCP_TELEMETRY=off`)
|
|
420
|
-
- Improved Cedar WASM detection
|
|
421
|
-
|
|
422
|
-
## Cybersecurity: Vulnerability Disclosure Receipts
|
|
423
|
-
|
|
424
|
-
protect-mcp provides the infrastructure for receipt-signed vulnerability disclosure workflows. When AI security agents (Claude Code Security, Mythos, or similar) discover vulnerabilities, every step of the disclosure lifecycle can produce a signed, chain-linked receipt:
|
|
425
|
-
|
|
426
|
-
```
|
|
427
|
-
DISCOVER → DISCLOSE → PATCH → DEPLOY
|
|
428
|
-
(Each step: Ed25519-signed, chain-linked, Cedar policy-bound)
|
|
429
|
-
```
|
|
430
|
-
|
|
431
|
-
Cedar policies govern what the scanning agent is allowed to do:
|
|
432
|
-
- **CAN**: scan code, report findings internally
|
|
433
|
-
- **CANNOT**: disclose externally or deploy patches without human approval
|
|
434
|
-
- **MUST**: escalate critical findings to humans
|
|
435
|
-
|
|
436
|
-
See the [security vulnerability disclosure example](https://github.com/ScopeBlind/examples/tree/main/security-vulnerability-disclosure) for a complete working implementation with Cedar policies and example receipt chains.
|
|
167
|
+
## Commands
|
|
437
168
|
|
|
438
|
-
|
|
169
|
+
| Command | Description |
|
|
170
|
+
|---------|-------------|
|
|
171
|
+
| `serve` | Start the HTTP hook server for Claude Code (port 9377). `--enforce` runs the restraint self-test first; `--cedar <dir>` and `--policy <path>` select the policy. |
|
|
172
|
+
| `init` | Generate an Ed25519 keypair (`keys/gateway.json`), a config template, and a sample policy. |
|
|
173
|
+
| `evaluate` | Evaluate one tool call against a Cedar policy (PreToolUse gate). Exit 2 = deny (fail-closed), exit 0 = allow. |
|
|
174
|
+
| `sign` | Sign one tool call into a receipt (PostToolUse). Best-effort: records an honest unsigned line if no key. |
|
|
175
|
+
| `simulate` | Dry-run a policy against a recorded decision log to see what it would have blocked. |
|
|
176
|
+
| `demo` | Start a built-in demo server wrapped with the gate, to see receipts instantly. |
|
|
177
|
+
| `doctor` | Check your setup (keys, policies, Cedar engine, verifier) and run the restraint self-test. |
|
|
178
|
+
| `bundle` | Export an offline-verifiable audit bundle of receipts plus the public key. |
|
|
179
|
+
| `report` | Generate a compliance report (Markdown or JSON) from the decision log and receipts. |
|
|
439
180
|
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
See complete working examples at [github.com/ScopeBlind/examples](https://github.com/ScopeBlind/examples):
|
|
443
|
-
- [Claude Code hooks](https://github.com/ScopeBlind/examples/tree/main/claude-code-hooks) — receipt signing for every tool call
|
|
444
|
-
- [Security vulnerability disclosure](https://github.com/ScopeBlind/examples/tree/main/security-vulnerability-disclosure) — receipt-signed disclosure lifecycle with Cedar governance
|
|
445
|
-
- [MCP server signing](https://github.com/ScopeBlind/examples/tree/main/mcp-server-signing) — Cedar WASM policy engine with audit bundles
|
|
446
|
-
|
|
447
|
-
## ScopeBlind Dashboard
|
|
448
|
-
|
|
449
|
-
protect-mcp works fully offline, forever, for free. For teams that want visibility across agents, ScopeBlind offers a hosted dashboard:
|
|
450
|
-
|
|
451
|
-
```bash
|
|
452
|
-
npx protect-mcp connect
|
|
453
|
-
```
|
|
454
|
-
|
|
455
|
-
| | Free | Pro | Enterprise |
|
|
456
|
-
|---|---|---|---|
|
|
457
|
-
| Receipts/month | 20,000 | Pay-as-you-go | Annual commit |
|
|
458
|
-
| Price | $0 | $0.50 / 1K | $0.40 / 1K |
|
|
459
|
-
| Receipt explorer | Yes | Yes | Yes |
|
|
460
|
-
| Compliance reports | Yes | Yes | Yes |
|
|
461
|
-
| SSO / SAML | - | - | Yes |
|
|
462
|
-
| SLA | - | - | 99.9% |
|
|
463
|
-
|
|
464
|
-
No signup required for free tier. No card upfront.
|
|
465
|
-
|
|
466
|
-
[Dashboard](https://scopeblind.com) | [Docs](https://scopeblind.com/docs/protect-mcp) | [Pricing](https://scopeblind.com/pricing)
|
|
467
|
-
|
|
468
|
-
## Telemetry
|
|
469
|
-
|
|
470
|
-
protect-mcp sends a single anonymous install beacon on first run (package name, version, OS, Node version). No PII. Disable with:
|
|
471
|
-
|
|
472
|
-
```bash
|
|
473
|
-
PROTECT_MCP_TELEMETRY=off
|
|
474
|
-
```
|
|
181
|
+
Run `npx protect-mcp --help` for the full flag reference.
|
|
475
182
|
|
|
476
|
-
##
|
|
183
|
+
## Links
|
|
477
184
|
|
|
478
|
-
|
|
185
|
+
- Protocol (IETF): [draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)
|
|
186
|
+
- [CHANGELOG](./CHANGELOG.md)
|
|
187
|
+
- [npm](https://www.npmjs.com/package/protect-mcp)
|
|
188
|
+
- [scopeblind.com](https://scopeblind.com)
|
|
479
189
|
|
|
480
|
-
Built by [ScopeBlind](https://scopeblind.com)
|
|
190
|
+
MIT licensed. Built by [ScopeBlind](https://scopeblind.com).
|
package/SECURITY.md
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
# Security Policy
|
|
2
|
+
|
|
3
|
+
This policy covers the `protect-mcp` npm package.
|
|
4
|
+
|
|
5
|
+
## Supported versions
|
|
6
|
+
|
|
7
|
+
| Version | Supported |
|
|
8
|
+
|---------|-----------|
|
|
9
|
+
| >= 0.7.0 | Yes |
|
|
10
|
+
| 0.6.x | No, upgrade |
|
|
11
|
+
| 0.5.x | No, upgrade |
|
|
12
|
+
|
|
13
|
+
## Affected versions
|
|
14
|
+
|
|
15
|
+
The 0.5.x and 0.6.x lines have a fail-open gate: the Cedar policy was not
|
|
16
|
+
evaluated correctly against the pinned engine, and the evaluator returned ALLOW
|
|
17
|
+
on evaluation error. A `forbid` rule could therefore fail to block. This is fixed
|
|
18
|
+
in 0.7.0, which fails closed (denies) on any evaluation error, missing engine, or
|
|
19
|
+
errored policy. If you are on 0.5.x or 0.6.x, upgrade to >= 0.7.0.
|
|
20
|
+
|
|
21
|
+
Advisory: [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
|
|
22
|
+
|
|
23
|
+
## Design posture
|
|
24
|
+
|
|
25
|
+
The gate fails closed by default. On any policy error, a missing engine, or an
|
|
26
|
+
evaluation failure, the decision is DENY, never a silent ALLOW. Before arming an
|
|
27
|
+
enforcing gate, `serve --enforce` and `doctor` run a boot self-test that proves
|
|
28
|
+
the gate denies a known-forbidden vector, and refuse to start if it cannot. The
|
|
29
|
+
observe mode that allows on error is opt-in, and even then flags any call that
|
|
30
|
+
would be blocked as `would_deny: true`.
|
|
31
|
+
|
|
32
|
+
## Reporting a vulnerability
|
|
33
|
+
|
|
34
|
+
Please report security issues privately. Do not open a public issue for an
|
|
35
|
+
unpatched vulnerability.
|
|
36
|
+
|
|
37
|
+
- Email: security@scopeblind.com
|
|
38
|
+
- Or open a private advisory via [GitHub Security Advisories](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/new).
|
|
39
|
+
|
|
40
|
+
Include the affected version, a description, and (if possible) a minimal
|
|
41
|
+
reproduction. We aim to acknowledge reports within 3 business days and to ship a
|
|
42
|
+
fix or a clear remediation plan as quickly as the severity warrants.
|
|
43
|
+
|
|
44
|
+
## Disclosure and credit
|
|
45
|
+
|
|
46
|
+
We follow coordinated disclosure: we work with you on a fix and a timeline before
|
|
47
|
+
any public detail is released. Reporters who disclose responsibly are credited in
|
|
48
|
+
the advisory and the CHANGELOG unless they ask to remain anonymous.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "protect-mcp",
|
|
3
|
-
"version": "0.7.
|
|
3
|
+
"version": "0.7.1",
|
|
4
4
|
"mcpName": "com.scopeblind/protect-mcp",
|
|
5
5
|
"description": "Fail-closed Cedar policy gate + signed receipts for AI agent tool calls. Blocks what breaks the rules before it runs, denies on any policy error, and proves the gate is live with a startup self-test.",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -25,7 +25,8 @@
|
|
|
25
25
|
"dist",
|
|
26
26
|
"policies",
|
|
27
27
|
"README.md",
|
|
28
|
-
"CHANGELOG.md"
|
|
28
|
+
"CHANGELOG.md",
|
|
29
|
+
"SECURITY.md"
|
|
29
30
|
],
|
|
30
31
|
"keywords": [
|
|
31
32
|
"scopeblind",
|