protect-mcp

Fail-closed Cedar Policy Gate plus signierte Belege für Tool-Aufrufe von KI-Agenten.

protect-mcp ist ein Gate, das vor den Tool-Aufrufen eines KI-Agenten sitzt. Es bewertet jeden Aufruf anhand einer Cedar-Policy (derselben Sprache, die AWS für IAM verwendet), blockiert, was die Regeln verletzt, bevor es ausgeführt wird, und signiert einen offline-verifizierbaren Ed25519-Beleg für jede Entscheidung. Es läuft lokal, sendet keine Telemetrie deiner Entscheidungen irgendwohin und ist MIT-lizenziert.

Warum es anders ist

• Standardmäßig fail-closed. Bei jedem Policy-Fehler, einer fehlenden Engine oder einem Auswertungsfehler lautet die Entscheidung DENY. Das Gate erlaubt niemals stillschweigend. Ein Observe-Modus existiert für Shadow-Rollout, aber selbst dort wird ein Aufruf, der blockiert würde, mit would_deny: true markiert, sodass ein Fehler niemals still bleibt.
• Es beweist seine eigene Zurückhaltung. serve --enforce und doctor führen einen Startup- Selbsttest aus und weigern sich, das Gate zu scharf zu stellen, es sei denn, sie können zeigen, dass eine bekannt-verbotene Aktion tatsächlich verweigert wird. Ein Gate, das nicht beweisen kann, dass es verweigert, startet nicht.
• Jede Entscheidung ist ein Beleg, den jeder verifizieren kann. Entscheidungen sind Ed25519-signiert und offline verifizierbar mit @veritasacta/verify. Kein Vendor-Vertrauen erforderlich: Die Mathematik kümmert sich nicht darum, wer sie ausführt.

Quickstart: von der Installation zum ersten nützlichen Beweis```bash

1. Generate an Ed25519 keypair, config template, and sample policy.

npx protect-mcp init

2. Wrap any MCP server in shadow mode. Nothing is blocked yet; calls are logged.

npx protect-mcp wrap -- node your-mcp-server.js

3. Inspect the local-only dashboard: tool inventory, risk, approvals, receipts.

npx protect-mcp dashboard --open

4. Draft a reviewable policy from observed calls.

npx protect-mcp recommend --write

5. When reviewed, restart the wrapper in enforce mode with that policy.

npx protect-mcp --policy protect-mcp.recommended.json --enforce -- node your-mcp-server.js

Für Claude Desktop führen Sie zuerst einen Dry-Run-Konfigurations-Patch aus und wenden ihn dann an:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

Das Dashboard bindet an 127.0.0.1, liest nur lokale Log-/Receipt-Dateien und lädt nichts hoch. Verwende npx protect-mcp connect nur, wenn du explizit ein gehostetes ScopeBlind-Dashboard möchtest.

Das Gate als MCP-Server

Wenn du das Gate lieber als Tools aufrufen möchtest, anstatt die Claude Code Hooks zu verdrahten, führe es als MCP-Server aus:```bash npx protect-mcp mcp

Es spricht MCP über stdio und stellt vier schreibgeschützte Tools bereit, den gesamten Ablauf:

- **`evaluate_action`**: entscheidet einen vorgeschlagenen Tool-Aufruf anhand einer Inline-Cedar-Richtlinie, fail-closed (jeder Richtlinienfehler ist DENY). Gibt `{ allowed, decision, reason, policy_digest }` zurück.
- **`sign_decision`**: verwandelt eine Entscheidung in eine Ed25519-signierte Quittung (eine Ablehnung signiert ein `gateway_restraint`, eine Genehmigung ein `decision_receipt`). Gibt die Quittung und ihren öffentlichen Schlüssel zurück; generiert einen ephemeren Schlüssel, wenn Sie keinen bereitstellen.
- **`verify_receipt`**: verifiziert eine signierte Quittung offline gegen einen öffentlichen Schlüssel. Gibt `{ valid, error, type, kid, issuer }` zurück.
- **`self_test`**: beweist es, ohne Eingaben. Eine bekanntermaßen verbotene Aktion wird abgelehnt, dann durchläuft eine signierte Quittung einen Round-Trip und eine manipulierte Kopie schlägt fehl.

Richten Sie einen beliebigen MCP-Host darauf aus, zum Beispiel Claude Desktop:```json
{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

Receipts sind byte-kompatibel mit denen, die das Gate zur Laufzeit signiert, sodass ein hier erzeugter Receipt mit @veritasacta/verify und dem Browser-Verifier gleichermaßen verifiziert wird.

Lokales Action-Dashboard

protect-mcp dashboard ist die Operator-Ansicht, um von der Sichtbarkeit zur Durchsetzung zu gelangen:

• Tool-Inventar: jedes beobachtete Tool, Aufrufanzahl, hohes/mittleres/niedriges Risiko und ob die aktive Policy eine exakte Regel, einen Wildcard-Fallback oder keine Regel hat.
• Policy-Abdeckung: lokale Policy-Bearbeitung mit einem Klick für Require approval, Block oder Observe. Starten Sie den Wrapper nach der Überprüfung der Änderungen neu.
• Exact-Action-Genehmigungswarteschlange: das exakte Tool, die Aktion, das Ziel, die redigierte Payload-Vorschau, der Payload-Hash, die Policy-Grundlage und die Begründungserfassung, bevor ein Mensch genehmigt, ablehnt, bearbeitet oder übernimmt.
• Receipt-Kette: Request-IDs korreliert mit signierten Receipt-Hashes, sodass ein Audit-Reviewer sehen kann, welche Entscheidungen kryptografischen Nachweis haben.
• Audit-Export: lädt das offline-verifizierbare Audit-Bundle herunter, wenn signierte Receipts existieren. Wenn nur unsignierte lokale Logs existieren, erklärt das Dashboard, dass die Signierung zuerst aktiviert werden muss.

Für Live-Desktop-Fallback-Genehmigungen starten Sie das Dashboard mit dem lokalen Gateway-Genehmigungsendpunkt und dem vom Wrapper ausgegebenen Nonce:```bash npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"

`Approve` leitet an das Live-Local-Gateway weiter, wenn diese Flags vorhanden sind.
`Deny`, `Edit` und `Take over` werden lokal als Approval-Resolution-Datensätze
aufgezeichnet; verwende sie als Operator-Anweisung und führe das Tool bei Bedarf erneut aus.

### Paid Boundary MVP: Digest-Anchoring, kein Daten-Upload

Lokale selbstsignierte Belege bleiben kostenlos und offline-verifizierbar. Die Paid Boundary ist
ein unabhängiger Nachweis, dass ScopeBlind einen Beleg-Digest zu einem Zeitpunkt unter einer Org-
Identität gesehen hat, ohne den rohen Prompt, die Tool-Payload, die Ausgabe, den privaten Schlüssel oder
den rohen Beleg zu erhalten.```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

Die lokale Vorschau ist bewusst als local-preview-not-independent gekennzeichnet. Der gehostete Modus verankert nur Receipt-Hashes, Request-IDs, öffentliche Organisationsschlüssel und Abrechnungsmetadaten. Er lädt keine rohen Receipts oder sensiblen Kontext hoch.

Killer-Demo: Shadow zu Policy zu Proof

protect-mcp killer-demo generiert ein komplettes dreiminütiges Sales-/Demo-Paket:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

Es erstellt ein Mock-Dateisystem, GitHub-, E-Mail- und PMS-Aktivität; zeigt riskante Aufrufe im
Shadow-Modus; wendet ein Policy-Paket an; erfordert eine Genehmigung für eine sensible PMS-Buchung;
führt die Ausführung über das Gateway durch; schreibt eine signierte Quittung; beweist, dass die
ursprüngliche Quittung verifiziert werden kann; beweist, dass eine manipulierte Quittung fehlschlägt;
und erstellt ein selektives Offenlegungspaket, das sensiblen Kontext verbirgt, während es den
minimalen Nachweis zeigt.

Öffne zuerst die generierte `DEMO-RUNBOOK.md`. Führe dann den ausgegebenen Dashboard-
Befehl aus, um einen Kunden durch die exakte Abfolge zu führen.

### Selective Disclosure v0

Quittungen im Commitment-Modus können ein `committed_fields_root` tragen, anstatt jedes Feld
im Klartext offenzulegen. Später kann der Inhaber nur ausgewählte Felder offenlegen:```bash
npx protect-mcp verify-disclosure \
  --receipt ./receipts/selective-disclosure.receipt.json \
  --disclosure ./receipts/selective-disclosure.tool-only.json

Der Verifier prüft den Parent-Receipt-Hash, die Ed25519-Signatur, die Commitment-Root und den Merkle-Beweis jedes offengelegten Feldes. Anschließend erklärt er, welche Felder offengelegt wurden und welche committeten Felder verborgen bleiben. Dies ist eine gesalzene Commitment-Offenlegung, nicht vollständiges Zero-Knowledge, aber sie macht die Datenschutzbehauptung konkret: Auditoren können ausgewählte Fakten verifizieren, ohne die vollständige Tool-Payload oder sensiblen Desk-Kontext zu erhalten.

Einen Claim über den Record beweisen (positionsblinde Attestierungen)

Du kannst einen CLAIM über deinen Record beweisen, ohne ihn offenzulegen. Prägen Sie eine signierte, positionsblinde Attestierung über den gesamten Record, die nur pro-Entscheidung-Kategorien offenlegt (einen Receipt-Digest, das Verdict, Capability-Tags), niemals Ihre Tool-Eingaben, -Ausgaben oder -Daten:```bash

"No action reached the network across the record":

npx protect-mcp claim --no net.egress

other predicates:

--only fs.read,fs.write all actions were confined to these capabilities

--no-verdict blocked no action was blocked

--count blocked how many were blocked

Jeder kann sie offline verifizieren und sieht dabei nur die Kategorien, niemals den Inhalt:```bash
npx protect-mcp verify-claim claim-<id>.json

Der Verifizierer berechnet eine Merkle-Wurzel über die offengelegte Menge neu und berechnet das Prädikat unabhängig neu, sodass der Aussteller bezüglich der Behauptung angesichts der Offenlegung nicht lügen kann. Fügen Sie --anchor hinzu, um den Digest der Behauptung im öffentlichen, nur anhängbaren ScopeBlind-Transparenzprotokoll aufzuzeichnen, sodass eine Gegenpartei, die Ihnen nicht vertraut, bestätigen kann, dass die offengelegte Menge vollständig ist und nicht stillschweigend neu zugeschnitten wurde (nur der Hash wird gesendet; der Datensatz bleibt lokal):```bash npx protect-mcp claim --no net.egress --anchor

Dies ist eine nachvollziehbare, positionsblinde Attestierung, kein vollständiges Zero-Knowledge: Sie
offenbart die Form, nicht den Inhalt.

## In 60 Sekunden ausprobieren (kein Agent erforderlich)

[![Den zweiminütigen Demo-Film ansehen](https://assets.kitploit.com/production/public/readmes/13151/01d856d6ca762bf76992ad56ab4c05824f272e9d98d62516a8f53bb90bce0db5.jpg)](https://legate.scopeblind.com/record)

Sehen Sie sich den zweiminütigen Film unter [legate.scopeblind.com/record](https://legate.scopeblind.com/record) an und spielen Sie ihn dann gegen Ihre eigene Kopie nach:```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

Lege die generierte demo-tampered.jsonl auf die Datensatzseite, um zu sehen, wie eine Bearbeitung nach der Signierung erkannt wird. sample weigert sich, einen vorhandenen Datensatz anzufassen, also führe es in einem leeren Ordner aus. Wenn du bereit für den Ernstfall bist, verdrahte das unten stehende Gate, und dieselben Befehle laufen gegen den eigenen Datensatz deines Agenten.

Claude Code Hook-Schnellstart```bash

Generate hook config and a sample Cedar policy.

npx protect-mcp init-hooks

Serve the Claude Code hook gate in enforce mode. It runs a restraint self-test

first and refuses to start if it cannot prove it denies a forbidden vector.

npx protect-mcp serve --enforce --cedar ./cedar

Einmalige Auswertung, so wie ein PreToolUse-Hook sie aufruft. Exit-Code 2 bedeutet Ablehnung
(das Tool wird blockiert); Exit-Code 0 bedeutet Erlauben:```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

Eine fehlende oder nicht ladbare Policy verweigert (Exit 2), es sei denn, du übergibst explizit --fail-on-missing-policy false.

Claude Code hooks

protect-mcp init-hooks schreibt eine .claude/settings.json für dich. Um das Gate manuell zu verdrahten, sind die beiden Verben, die du brauchst, evaluate (PreToolUse, blockiert bei Exit 2) und sign (PostToolUse, zeichnet eine Quittung auf). Pinne die Version, damit eine Claude-Code- Sitzung immer das Gate ausführt, das du getestet hast:```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" } ] } ] } }

### Die Richtlinienentscheidung selbst signieren

Ab 0.13.0 kann `sign` die Richtlinie auswerten und die tatsächliche Entscheidung im
Receipt aufzeichnen, anstatt einer bedingungslosen Erlaubnis. Übergeben Sie das Richtlinienverzeichnis und
dieselbe Eingabe und denselben Kontext, die der Hook an `evaluate` übergeben würde:```bash
npx [email protected] sign --cedar ./cedar --tool Bash \
  --input '{"command":"rm -rf /"}' --context '{"command_pattern":"rm -rf"}' \
  --receipts ./receipts --key ./keys/gateway.json

Die Receipt-Payload trägt dann decision (allow oder deny), reason (cedar_allow oder cedar_deny) und policy_digest (den acta-policy-digest-v1 Digest des Policy-Sets) und zitiert draft-farley-acta-signed-receipts-03. Der Befehl gibt die Entscheidung und den Digest auf stdout aus. Ein Deny wird ebenfalls signiert: Das Receipt ist die Aufzeichnung der Entscheidung, nicht die Erlaubnis fortzufahren.

Zwei Cedar-Aktionsmodelle werden unterstützt. Das Runtime-Gate evaluiert Action::"MCP::Tool::call" mit dem Tool als Ressource, was die Policies in cedar/ erwarten und was sign --cedar standardmäßig verwendet. Policies, die das Tool als Aktion benennen (action == Action::"Bash"), wie die veröffentlichte Konformitäts-Policy in agent-governance-testvectors, benötigen --action-model tool. evaluate akzeptiert dasselbe Flag.

evaluate beendet sich mit 2 bei Deny, sodass Claude Code den Tool-Aufruf blockiert, und mit 0 bei Allow. sign ist Best-Effort: Es hängt ein Ed25519-signiertes Receipt an, wenn ein Schlüssel konfiguriert ist, und wenn kein Signierer verfügbar ist, zeichnet es eine ehrliche unsignierte Zeile ("signed": false) auf, anstatt das Tool fehlschlagen zu lassen.

Verwenden Sie es in anderen Agents (Codex, Cursor, Gemini, Hermes)

Dasselbe fail-closed Gate läuft als Tool-Hook in jedem Agent, der diese unterstützt. Fügen Sie --format <host> hinzu, damit das Verb die Hook-Payload dieses Hosts von stdin liest und gemäß seinem Vertrag verweigert:```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

Paaren Sie jedes mit `sign --format <host>` beim Post-Tool-Event für Belege. Der wichtige Fall ist **Hermes**, der Hook-Exit-Codes ignoriert und das Urteil von stdout liest, sodass `--format hermes` über `{"decision":"block"}` verweigert statt über Exit 2 (ein roher Exit-2 würde dort stillschweigend offen fehlschlagen). Ohne `--format` lesen die Verben die Flags `--tool`/`--input` genau wie im obigen Claude-Code-Abschnitt.

## Eine Policy schreiben

Cedar-Policies liegen in einem Verzeichnis, auf das Sie mit `--cedar` zeigen. Eine `forbid`-Regel verweigert, eine `permit`-Regel erlaubt. Um gegen einen Wert in der Tool-Eingabe zu matchen, verwenden Sie das `.contains()`-Idiom:```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"
);

Gefahr: Schreiben Sie NICHT context.command in ["rm", "dd"], um einen String mit einer Liste abzugleichen. in ist für Entitätshierarchien gedacht, nicht für String-Zugehörigkeit. Cedar behandelt den Ausdruck als Typfehler und verwirft stillschweigend die gesamte forbid-Regel, was (unter einem Fail-Open-Gate) ein verbleibendes permit bestehen lässt. Dies ist genau der Defekt hinter dem untenstehenden Advisory. Verwenden Sie stattdessen [...].contains(context.command). Ab 0.7.0 verweigert das Gate bei diesem Fehler, anstatt zu erlauben, und ein CI-Tripwire-Test lässt den Build fehlschlagen, wenn das Muster wieder in eine ausgelieferte Policy eingeführt wird. Siehe GHSA-hm46-7j72-rpv9.

Starter-Policy-Pakete

Die meisten Teams sollten Cedar nicht am ersten Tag von Grund auf neu schreiben. Installieren Sie ein Starter-Paket, führen Sie es im Shadow-Modus aus, prüfen Sie die Belege und verschärfen oder erzwingen Sie es dann:```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

Eingebaute Pakete:

- `filesystem-safe`: destruktive Dateiaktionen und Lesezugriffe auf pfadähnliche Secrets.
- `git-safe`: Force-Pushes, Hard-Resets, destruktive Bereinigungen, Löschen von Repositories.
- `email-safe`: Entwerfen erlauben, unbeaufsichtigtes Senden blockieren.
- `database-safe`: leseorientierte DB-Haltung, Schreib-/Admin-SQL blockieren.
- `cloud-spend-safe`: offensichtliche Erzeugung von Cloud-Ausgaben und Zerstörung von Infrastruktur.
- `secrets-safe`: gängige Exfiltration von Datei-, Env-, Shell- und Cloud-Secrets.
- `finance-mandate-safe`: Verstöße gegen Restricted-Listen und Konzentrationsgrenzen in Buchungsabläufen.

## Einen Beleg verifizieren

Belege sind signiert und offline von jedem mit dem öffentlichen Schlüssel verifizierbar. Kein
Netzwerk, kein Anbieter, kein Vertrauen in ScopeBlind:```bash
npx @veritasacta/verify ./receipts/receipts.jsonl --format jsonl
# Exit 0 = valid, non-zero = tampered or malformed

npx protect-mcp bundle --output audit.json exportiert ein eigenständiges, offline-verifizierbares Audit-Bundle deiner Belege plus den öffentlichen Signaturschlüssel.

Sicherheit

protect-mcp 0.7.0 schlägt konstruktionsbedingt geschlossen fehl (fail closed). Bei jedem Fehler bei der Richtlinienauswertung, einer fehlenden Engine oder einer Richtlinie, die bei der Auswertung einen Fehler geworfen hat, lautet die Entscheidung DENY, nicht allow. serve --enforce und doctor führen einen Boot-Selbsttest aus, der beweist, dass das Gate einen bekannten verbotenen Vektor ablehnt, bevor ihm vertraut wird, und verweigern die Aktivierung, wenn dies nicht möglich ist.

Betroffene Versionen: 0.5.x und 0.6.x. Diese Versionslinien schlagen offen fehl (sie geben bei Auswertungsfehlern ALLOW zurück) und werten Cedar nicht korrekt gegen die gepinnte Engine aus, sodass eine forbid-Regel möglicherweise nicht blockiert. Upgrade auf >= 0.7.0.

Details und Behebung: GHSA-hm46-7j72-rpv9. Um eine Schwachstelle zu melden, siehe SECURITY.md.

Befehle

Führe npx protect-mcp --help für die vollständige Flag-Referenz aus.

Links

• Protokoll (IETF): draft-farley-acta-signed-receipts
• CHANGELOG
• npm
• scopeblind.com

MIT-lizenziert. Erstellt von ScopeBlind.