From cc2be185152630bd45419415d80ca07db733fa5a Mon Sep 17 00:00:00 2001 From: tommylauren Date: Sun, 5 Apr 2026 06:52:05 -0400 Subject: [PATCH] Add agent-governance skill: signed receipts + Cedar policy enforcement Adds a skill for cryptographic audit trails on agent tool calls via protect-mcp (MIT, npmjs.com/package/protect-mcp). Covers: Ed25519 receipt signing, Cedar WASM policy evaluation, shadow/enforce modes, offline verification, audit bundle export. References: IETF draft-farley-acta-signed-receipts, Microsoft AGT PR #667. --- skills/agent-governance/LICENSE.txt | 21 ++++ skills/agent-governance/SKILL.md | 165 ++++++++++++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 skills/agent-governance/LICENSE.txt create mode 100644 skills/agent-governance/SKILL.md diff --git a/skills/agent-governance/LICENSE.txt b/skills/agent-governance/LICENSE.txt new file mode 100644 index 00000000..a5630b25 --- /dev/null +++ b/skills/agent-governance/LICENSE.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 ScopeBlind + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/skills/agent-governance/SKILL.md b/skills/agent-governance/SKILL.md new file mode 100644 index 00000000..21e4de2b --- /dev/null +++ b/skills/agent-governance/SKILL.md @@ -0,0 +1,165 @@ +--- +name: agent-governance +description: Add cryptographic audit trails and policy enforcement to AI agent tool calls. Use when you need signed receipts, Cedar policy evaluation, or tamper-evident proof of what an agent actually did. Works with Claude Code hooks, MCP servers, or any tool-calling agent. +license: Complete terms in LICENSE.txt +--- + +# Agent Governance — Signed Receipts and Policy Enforcement + +## Overview + +Add independently verifiable audit trails to agent tool calls. Every tool invocation produces an Ed25519-signed receipt that anyone can verify offline, without trusting the platform that created it. + +This skill uses [protect-mcp](https://www.npmjs.com/package/protect-mcp) (MIT, 2,300+ downloads/month) to wrap tool calls with Cedar policy enforcement and receipt signing. + +--- + +# Process + +## Quick Start + +### Step 1: Initialize hooks and start the governance server + +```bash +npx protect-mcp init-hooks +npx protect-mcp serve +``` + +This creates `.claude/settings.json` with PreToolUse and PostToolUse hooks that route every tool call through the governance server on port 9377. + +### Step 2: Work normally + +Every tool call now produces a signed receipt automatically. The governance server runs in shadow mode by default — it logs everything but blocks nothing. + +### Step 3: View and verify receipts + +```bash +# View recent receipts +npx protect-mcp receipts --last 10 + +# Verify the entire receipt chain offline +npx @veritasacta/verify .protect-mcp-receipts.jsonl +``` + +--- + +## Cedar Policy Configuration + +### Writing policies + +Cedar policies define what tools are allowed, denied, or rate-limited. Create policies in `policies/` directory: + +```cedar +// Allow read operations +permit(principal, action, resource) + when { resource.tool == "Read" || resource.tool == "Glob" || resource.tool == "Grep" }; + +// Allow code editing +permit(principal, action, resource) + when { resource.tool == "Edit" || resource.tool == "Write" }; + +// Block destructive shell commands +forbid(principal, action, resource) + when { + resource.tool == "Bash" && + (resource.command.contains("rm -rf") || + resource.command.contains("git push --force") || + resource.command.contains("DROP TABLE")) + }; +``` + +### Shadow mode vs enforce mode + +Start in shadow mode to observe what the agent does without blocking anything: + +```bash +npx protect-mcp serve # shadow mode (default) +npx protect-mcp serve --enforce # enforce mode (blocks denied calls) +``` + +Shadow mode logs every decision with the same receipt format. Review the receipts before switching to enforce mode. + +### Policy digest tracking + +Every receipt includes a `policy_digest` (SHA-256 of the active policy set). When receipts show a behavior change, diff the policy digests to determine whether it was a policy change (intentional) or an agent behavior change (potentially risky). + +--- + +## Receipt Verification + +### What a receipt proves + +| Property | Unsigned logs | Signed receipts | +|----------|--------------|-----------------| +| Tamper detection | None | Ed25519 signature breaks | +| Ordering proof | Timestamp (editable) | Hash-chained (tamper-evident) | +| Third-party audit | Requires trust in log operator | Offline verification by anyone | +| Policy binding | "A policy was configured" | "This specific policy was evaluated" | + +### Offline verification + +The verifier is MIT-licensed and works without any network access: + +```bash +npx @veritasacta/verify .protect-mcp-receipts.jsonl +``` + +This checks every Ed25519 signature against the JCS-canonicalized payload. Change one character and the signature invalidates. + +### Audit bundle export + +```bash +npx protect-mcp bundle --format audit +``` + +Produces a self-contained archive with receipts, policy snapshots, and verification instructions. + +--- + +## MCP Server Wrapping + +protect-mcp can also wrap any MCP server as a stdio proxy: + +```bash +# Wrap any server — receipts generated for every tool call +npx protect-mcp -- node my-server.js + +# With policy enforcement +npx protect-mcp --policy policy.json --enforce -- node my-server.js + +# With Cedar policies +npx protect-mcp --cedar ./policies/ --enforce -- node my-server.js +``` + +This works with Claude Desktop, Cursor, or any MCP client. + +--- + +## Dashboard (Optional) + +Connect to the ScopeBlind dashboard for real-time analytics: + +```bash +npx protect-mcp quickstart --connect +``` + +Free tier: 20,000 receipts/month. No credit card required. + +--- + +## Anti-Patterns + +- Do NOT hardcode policy rules in CLAUDE.md or system prompts — use Cedar files +- Do NOT skip shadow mode — always observe before enforcing +- Do NOT commit signing keys to version control +- Do NOT disable receipt signing — even in development, the audit trail has value + +--- + +## References + +- npm: https://www.npmjs.com/package/protect-mcp +- IETF Internet-Draft: https://datatracker.ietf.org/doc/draft-farley-acta-signed-receipts/ +- Microsoft Agent Governance Toolkit integration: https://github.com/microsoft/agent-governance-toolkit/pull/667 +- Working examples: https://github.com/ScopeBlind/examples +- Verification: https://www.npmjs.com/package/@veritasacta/verify