Skip to content

Commit b66dda5

Browse files
tomjwxfZeroXLauren
tomjwxf
and
ZeroXLauren
authored
feat(examples): protect-mcp governed example — Cedar policies + signed receipts (#1159)
Adds a governed example showing MCP tool calls with Cedar policy enforcement and Ed25519 signed receipts. Complements the scopeblind-protect-mcp integration merged in #667. Contents: - examples/protect-mcp-governed/getting_started.py: 8-scenario showcase (Cedar eval, authoritative deny, tamper detection, spending authority, chain integrity, trust tier mapping, offline verification, full pipeline) - examples/protect-mcp-governed/policies/mcp-tool-access.yaml: AGT policy file - examples/protect-mcp-governed/README.md: architecture diagram, scenario table - examples/quickstart/protect_mcp_governed.py: 30-line quickstart Runs standalone (zero dependencies) with inline signing fallback. Uses full scopeblind-protect-mcp adapter when installed. All scenarios produce signed, hash-chained receipts verifiable with: npx @veritasacta/verify Signed-off-by: Tom Farley <tomjwxf@gmail.com> Co-authored-by: tommylauren <tfarley@utexas.edu>
1 parent 3130880 commit b66dda5

4 files changed

Lines changed: 677 additions & 0 deletions

File tree

‎examples/protect-mcp-governed/README.md‎

Lines changed: 191 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# protect-mcp + Governance Toolkit — Governed MCP with Signed Receipts
2+
3+
> MCP tool calls governed by **Cedar policies** with **Ed25519 signed receipts**.
4+
> Every allow/deny decision produces a cryptographic receipt that can be verified
5+
> independently, offline, forever. Integrates AGT policy evaluation, trust
6+
> scoring, and tamper-proof audit alongside ScopeBlind's receipt signing layer.
7+
8+
## Quick Start (< 2 minutes)
9+
10+
```bash
11+
pip install agent-governance-toolkit[full]
12+
python examples/protect-mcp-governed/getting_started.py
13+
```
14+
15+
`getting_started.py` is a **~180-line** copy-paste-friendly example showing
16+
the core integration pattern:
17+
18+
```python
19+
from agent_os.policies.evaluator import PolicyEvaluator
20+
from agentmesh.governance.audit import AuditLog
21+
22+
# ScopeBlind protect-mcp integration
23+
from scopeblind_protect_mcp.adapter import (
24+
CedarPolicyBridge,
25+
CedarDecision,
26+
ReceiptVerifier,
27+
SpendingGate,
28+
scopeblind_context,
29+
)
30+
31+
# 1. Load YAML policies + set up Cedar bridge
32+
evaluator = PolicyEvaluator()
33+
evaluator.load_policies(Path("./policies"))
34+
cedar_bridge = CedarPolicyBridge()
35+
receipt_verifier = ReceiptVerifier()
36+
spending_gate = SpendingGate(max_amount=1000.0)
37+
audit_log = AuditLog()
38+
39+
# 2. Evaluate a tool call with Cedar + AGT policies
40+
decision = CedarDecision(
41+
decision="allow",
42+
policy_id="autoresearch-safe",
43+
tool_name="file_system:read_file",
44+
trust_tier="evidenced",
45+
)
46+
47+
# 3. Bridge Cedar decision into AGT scoring
48+
agt_result = cedar_bridge.evaluate(decision, agent_id="research-bot")
49+
# Cedar deny is authoritative — overrides any trust score
50+
51+
# 4. Verify the signed receipt
52+
receipt = decision.to_receipt() # Ed25519 signed
53+
is_valid = receipt_verifier.validate(receipt)
54+
# True = signature valid, structure intact, not replayed
55+
56+
# 5. Check spending authority
57+
spending_ok = spending_gate.check(amount=50.0, category="compute")
58+
59+
# 6. Build AGT-compatible context for audit
60+
ctx = scopeblind_context(decision, receipt, spending_gate)
61+
audit_log.append(ctx)
62+
63+
# 7. Verify the tamper-proof audit trail
64+
valid, err = audit_log.verify_integrity()
65+
```
66+
67+
For the full **8-scenario showcase**, run:
68+
69+
```bash
70+
python examples/protect-mcp-governed/protect_mcp_governance_demo.py
71+
```
72+
73+
## What This Shows
74+
75+
| Scenario | Governance Layer | What Happens |
76+
|----------|-----------------|--------------|
77+
| **1. Cedar Policy Evaluation** | `CedarPolicyBridge` | Tool calls evaluated against Cedar policies (principal/action/resource/context). Cedar deny is authoritative and overrides trust scores. |
78+
| **2. Receipt Signing & Verification** | `ReceiptVerifier` | Every decision produces an Ed25519 signed receipt. Tampered receipts are detected. Replayed receipts are rejected within the bounded window. |
79+
| **3. Spending Authority** | `SpendingGate` | Tool calls with financial impact checked against amount limits, category blocks, and utilization bands. High-value actions require receipts. |
80+
| **4. Trust Tier Mapping** | `CedarPolicyBridge` | Cedar trust tiers (anonymous/attested/evidenced/institutional) map to AGT trust score bonuses (0/+10/+20/+30). |
81+
| **5. Receipt Chain Integrity** | `ReceiptVerifier` + `AuditLog` | Receipts are hash-chained (each references previous receipt hash). Chain verification detects insertions, deletions, and modifications. |
82+
| **6. Concurrent Access Safety** | `CedarPolicyBridge` + `SpendingGate` | Thread-safe evaluation under concurrent tool calls. Trust updates and spending checks are atomic. |
83+
| **7. Cedar + AGT Composition** | All layers | Cedar policy deny overrides AGT trust=999. AGT rate limiting composes with Cedar spending authority. Both produce audit entries. |
84+
| **8. Offline Verification** | `ReceiptVerifier` | Receipts verified without any network call. Ed25519 signature check + JCS canonical form. Works air-gapped. |
85+
86+
## Architecture
87+
88+
```
89+
┌─────────────────────────────────────────────────────────────────────┐
90+
│ MCP Tool Call │
91+
│ (file_system:read_file) │
92+
└────────────────────────────┬────────────────────────────────────────┘
93+
│
94+
▼
95+
┌─────────────────────────────────────────────────────────────────────┐
96+
│ AGT Policy Evaluator │
97+
│ (YAML policies, rate limits, │
98+
│ content filters, allow-lists) │
99+
└────────────────────────────┬────────────────────────────────────────┘
100+
│
101+
▼
102+
┌─────────────────────────────────────────────────────────────────────┐
103+
│ Cedar Policy Bridge │
104+
│ (principal / action / resource / context) │
105+
│ │
106+
│ Cedar DENY is authoritative — overrides trust scores. │
107+
│ Cedar ALLOW earns trust bonus based on trust tier. │
108+
│ Every evaluation produces a signed receipt. │
109+
└────────────────────────────┬────────────────────────────────────────┘
110+
│
111+
▼
112+
┌─────────────────────────────────────────────────────────────────────┐
113+
│ Spending Gate │
114+
│ (amount limits, category blocks, │
115+
│ utilization bands, receipt requirements) │
116+
└────────────────────────────┬────────────────────────────────────────┘
117+
│
118+
▼
119+
┌─────────────────────────────────────────────────────────────────────┐
120+
│ Ed25519 Receipt Signing │
121+
│ │
122+
│ JCS canonicalization (RFC 8785) → SHA-256 → Ed25519 signature │
123+
│ Receipt is hash-chained to previous receipt │
124+
│ Verifiable offline with: npx @veritasacta/verify receipt.json │
125+
└────────────────────────────┬────────────────────────────────────────┘
126+
│
127+
▼
128+
┌─────────────────────────────────────────────────────────────────────┐
129+
│ Tamper-Proof Audit Log │
130+
│ (Merkle-chained entries + receipt chain) │
131+
│ │
132+
│ Two independent integrity guarantees: │
133+
│ 1. AGT AuditLog Merkle chain (operator-side) │
134+
│ 2. Ed25519 receipt chain (independently verifiable) │
135+
└─────────────────────────────────────────────────────────────────────┘
136+
```
137+
138+
## Key Differentiator: Two Integrity Layers
139+
140+
AGT's `AuditLog` provides a Merkle-chained audit trail maintained by the
141+
operator. This is excellent for internal governance but is only as trustworthy
142+
as the operator.
143+
144+
protect-mcp adds a second layer: Ed25519 signed receipts that are
145+
independently verifiable by any party without trusting the operator. The
146+
receipt chain is verifiable offline using open-source tools:
147+
148+
```bash
149+
npx @veritasacta/verify receipt.json
150+
# exit 0 = valid, exit 1 = tampered, exit 2 = malformed
151+
```
152+
153+
Both layers are needed:
154+
- **AuditLog** catches internal process failures (missed evaluations, dropped entries)
155+
- **Receipt chain** provides external accountability (third-party audit, regulatory evidence)
156+
157+
## Cedar Policy Example
158+
159+
```cedar
160+
// Allow read-only tools for evidenced-tier agents
161+
permit(
162+
principal,
163+
action in [Action::"file_system:read_file", Action::"web_search"],
164+
resource
165+
) when {
166+
context.trust_tier == "evidenced"
167+
};
168+
169+
// Block destructive tools unless institutional tier
170+
forbid(
171+
principal,
172+
action in [Action::"shell_exec", Action::"delete_file"],
173+
resource
174+
) unless {
175+
context.trust_tier == "institutional"
176+
};
177+
```
178+
179+
## Standards
180+
181+
- **Ed25519** (RFC 8032) for receipt signatures
182+
- **JCS** (RFC 8785) for deterministic canonicalization before signing
183+
- **Cedar** (AWS) for declarative, formally verifiable policy evaluation
184+
- **IETF Internet-Draft** ([draft-farley-acta-signed-receipts](https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/)) for receipt format
185+
186+
## Related
187+
188+
- [protect-mcp](https://www.npmjs.com/package/protect-mcp) — MCP gateway with Cedar policies + receipt signing
189+
- [@veritasacta/verify](https://www.npmjs.com/package/@veritasacta/verify) — Offline receipt verification CLI
190+
- [cedar-policy/cedar-for-agents](https://github.com/cedar-policy/cedar-for-agents) — WASM bindings for Cedar MCP schema generation
191+
- [Veritas Acta](https://veritasacta.com) — Open protocol for verifiable machine decisions

0 commit comments

Comments
 (0)