protect-mcp

Gate di policy Cedar a blocco di default con ricevute firmate per chiamate di strumenti di agenti AI.

protect-mcp è un gate che si posiziona davanti alle chiamate di strumenti di un agente AI. Valuta ogni chiamata rispetto a una policy Cedar (lo stesso linguaggio che AWS utilizza per IAM), blocca ciò che infrange le regole prima che venga eseguito e firma una ricevuta Ed25519 verificabile offline per ogni decisione. Funziona localmente, non invia alcuna telemetria delle decisioni e ha licenza MIT.

Perché è diverso

Blocco di default per progettazione. Su qualsiasi errore di policy, motore mancante o fallimento di valutazione, la decisione è DENY. Il gate non consente mai in silenzio. Esiste una modalità di osservazione per rollout ombra, ma anche lì una chiamata che verrebbe bloccata è contrassegnata con would_deny: true, quindi un fallimento non è mai silenzioso.
Prova la propria moderazione. serve --enforce e doctor eseguono un autotest all'avvio e rifiutano di armare il gate a meno che non possano dimostrare che un'azione nota come vietata è effettivamente negata. Un gate che non riesce a provare di negare non si avvia.
Ogni decisione è una ricevuta verificabile da chiunque. Le decisioni sono firmate con Ed25519 e verificabili offline con @veritasacta/verify. Nessuna fiducia nel fornitore richiesta: la matematica non si cura di chi la esegue.

Avvio rapido: installazione fino alla prima prova utile```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

Per Claude Desktop, esegui prima un dry-run config patch, poi applicalo:```bash
npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

Il dashboard si collega a 127.0.0.1, legge solo i file di log/ricevuta locali e non carica nulla. Usa npx protect-mcp connect solo se desideri esplicitamente un dashboard ScopeBlind ospitato.

Il gate come server MCP

Se preferisci chiamare il gate come strumenti invece di collegare i hook di Claude Code, eseguilo come server MCP:```bash npx protect-mcp mcp

Parla MCP tramite stdio ed espone quattro strumenti di sola lettura, l'intero ciclo:

- **`evaluate_action`**: decide una chiamata allo strumento proposta rispetto a una politica Cedar inline, fail-closed (qualsiasi errore di politica è DENY). Restituisce `{ allowed, decision, reason, policy_digest }`.
- **`sign_decision`**: trasforma una decisione in una ricevuta firmata Ed25519 (una negazione firma un `gateway_restraint`, un permesso un `decision_receipt`). Restituisce la ricevuta e la sua chiave pubblica; genera una chiave effimera se non ne fornisci una.
- **`verify_receipt`**: verifica una ricevuta firmata offline rispetto a una chiave pubblica. Restituisce `{ valid, error, type, kid, issuer }`.
- **`self_test`**: dimostralo, nessun input. Un'azione nota come proibita viene negata, poi una ricevuta firmata fa un round-trip e una copia manomessa fallisce.

Punta qualsiasi host MCP su di esso, ad esempio Claude Desktop:```json
{
  "mcpServers": {
    "protect-mcp": { "command": "npx", "args": ["-y", "protect-mcp", "mcp"] }
  }
}

I receipt sono byte-compatibili con quelli che il gate firma a runtime, quindi un receipt emesso qui viene verificato con @veritasacta/verify e il verificatore del browser allo stesso modo.

Local Action Dashboard

protect-mcp dashboard è la vista operatore per passare dalla visibilità all'applicazione:

Tool inventory: ogni strumento osservato, conteggio chiamate, rischio alto/medio/basso, e se la policy attiva ha una regola esatta, un fallback wildcard, o nessuna regola.
Policy coverage: modifiche locali della policy con un clic per Require approval, Block o Observe. Riavvia il wrapper dopo aver rivisto le modifiche.
Exact-action approval queue: lo strumento esatto, azione, destinazione, anteprima del payload oscurata, hash del payload, base della policy e cattura del motivo prima che un umano approvi, neghi, modifichi o subentri.
Receipt chain: ID richiesta correlati con hash di receipt firmati, così un revisore dell'audit può vedere quali decisioni hanno prova crittografica.
Audit export: scarica il bundle di audit verificabile offline quando esistono receipt firmati. Se esistono solo log locali non firmati, la dashboard spiega che la firma deve essere abilitata prima.

Per approvazioni di fallback live desktop, avvia la dashboard con l'endpoint di approvazione del gateway locale e il nonce stampato dal wrapper:```bash npx protect-mcp dashboard --open
--approval-endpoint http://127.0.0.1:9876
--approval-nonce "$PROTECT_MCP_APPROVAL_NONCE"

`Approve` si inoltra al gateway locale live quando quei flag sono presenti.
`Deny`, `Edit` e `Take over` sono registrati localmente come record di risoluzione delle approvazioni; usali come istruzioni per l'operatore e riesegui lo strumento quando necessario.

### Paid Boundary MVP: digest anchoring, not data upload

Le ricevute autofirmate locali rimangono gratuite e verificabili offline. Il confine a pagamento è una prova indipendente che ScopeBlind ha visto un digest di ricevuta in un determinato momento, sotto un'identità organizzativa, senza ricevere il prompt grezzo, il payload dello strumento, l'output, la chiave privata o la ricevuta grezza.```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

L'anteprima locale è deliberatamente etichettata local-preview-not-independent. La modalità ospitata ancora solo hash di ricevute, ID di richiesta, chiavi pubbliche dell'organizzazione e metadati di fatturazione. Non carica ricevute grezze o contesto sensibile.

Killer Demo: da shadow a policy a proof

protect-mcp killer-demo genera un pacchetto completo di vendita/demo di tre minuti:```bash npx protect-mcp killer-demo --dir ./scopeblind-demo

Crea attività simulate per filesystem, GitHub, email e PMS; mostra chiamate rischiose in
modalità shadow; applica un pacchetto di policy; richiede approvazione per una prenotazione PMS sensibile;
esegue attraverso il gateway; scrive una ricevuta firmata; dimostra che la ricevuta
originale viene verificata; dimostra che una ricevuta manomessa fallisce; e crea un
pacchetto di divulgazione selettiva che nasconde il contesto sensibile mostrando la prova minima.

Apri prima il `DEMO-RUNBOOK.md` generato. Poi esegui il comando del dashboard stampato
per guidare un cliente attraverso la sequenza esatta.

### Divulgazione Selettiva v0

Le ricevute in modalità commitment possono trasportare una `committed_fields_root` invece di esporre
ogni campo in chiaro. Successivamente, il detentore può divulgare solo i campi selezionati:```bash
npx protect-mcp verify-disclosure \
  --receipt ./receipts/selective-disclosure.receipt.json \
  --disclosure ./receipts/selective-disclosure.tool-only.json

Il verificatore controlla l'hash della ricevuta padre, la firma Ed25519, la radice dell'impegno e la prova Merkle di ogni campo divulgato. Spiega quindi quali campi sono stati divulgati e quali campi impegnati rimangono nascosti. Si tratta di divulgazione di impegno con sale, non di conoscenza zero completa, ma rende concreta l'affermazione sulla privacy: i revisori possono verificare fatti selezionati senza ricevere l'intero payload dello strumento o il contesto sensibile della scrivania.

Prova di un'affermazione sul record (attestazioni cieche alla posizione)

Puoi provare un'AFFERMAZIONE sul tuo record senza rivelarlo. Conia un'attestazione firmata e cieca alla posizione sull'intero record che divulga solo categorie per decisione (un digest del ricevuta, il verdetto, tag di capacità), mai i tuoi input, output o dati dello strumento:```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

Chiunque lo verifica offline, vedendo solo le categorie, mai il contenuto:```bash
npx protect-mcp verify-claim claim-<id>.json

The verifier ricalcola una radice Merkle sull'insieme divulgato e ricalcola il predicato indipendentemente, quindi l'emittente non può mentire riguardo alla rivendicazione data la divulgazione. Aggiungi --anchor per registrare il digest della rivendicazione nel log di trasparenza pubblico e append-only ScopeBlind, in modo che una controparte che non si fida di te possa confermare che l'insieme divulgato è completo e non è stato tagliato silenziosamente (viene inviato solo l'hash; il record rimane locale):```bash npx protect-mcp claim --no net.egress --anchor

Questa è un'attestazione responsabile e indipendente dalla posizione, non a conoscenza zero completa: rivela la forma, non il contenuto.

## Provalo in 60 secondi (nessun agente richiesto)

[![Guarda il filmato dimostrativo di due minuti](https://assets.kitploit.com/production/public/readmes/13151/01d856d6ca762bf76992ad56ab4c05824f272e9d98d62516a8f53bb90bce0db5.jpg)](https://legate.scopeblind.com/record)

Guarda il filmato di due minuti su [legate.scopeblind.com/record](https://legate.scopeblind.com/record), poi riproducilo sulla tua copia:```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

Butta il demo-tampered.jsonl generato nella pagina del record per osservare una modifica post-firma essere rilevata. sample rifiuta di toccare un record esistente, quindi eseguilo in una cartella vuota. Quando sei pronto per la cosa vera, collega il gate sottostante e gli stessi comandi eseguiti contro il record del tuo agente.

Claude Code hook Guida rapida```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

Valutazione one-shot, il modo in cui un hook PreToolUse lo chiama. Il codice di uscita 2 significa negazione (lo strumento è bloccato); il codice di uscita 0 significa consenti:```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

Una politica mancante o non caricabile nega (exit 2) a meno che non si passi esplicitamente --fail-on-missing-policy false.

Claude Code hooks

protect-mcp init-hooks scrive un .claude/settings.json per te. Per collegare il gate manualmente, i due verbi di cui hai bisogno sono evaluate (PreToolUse, si blocca su exit 2) e sign (PostToolUse, registra una ricevuta). Blocca la versione in modo che una sessione di Claude Code esegua sempre il gate che hai testato:```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` esce con codice 2 in caso di negazione, così Claude Code blocca la chiamata allo strumento, e con 0 in caso di autorizzazione.
`sign` è best-effort: aggiunge una ricevuta firmata con Ed25519 quando una chiave è configurata, e se non è disponibile un firmatario registra una riga onesta non firmata (`"signed": false`) anziché far fallire lo strumento.

## Usalo in altri agenti (Codex, Cursor, Gemini, Hermes)

Lo stesso gate fail-closed viene eseguito come hook di strumento in qualsiasi agente che li supporti. Aggiungi `--format <host>` in modo che il comando legga il payload dell'hook di quell'host da stdin e neghi nel suo contratto:```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

Abbina ciascuno con sign --format <host> sul post-tool event per i ricevuti. Il caso importante è Hermes, che ignora i codici di uscita dell'hook e legge il verdetto da stdout, quindi --format hermes nega tramite {"decision":"block"} anziché exit 2 (un exit-2 grezzo fallirebbe silenziosamente in aperto lì). Senza --format, i verbi leggono i flag --tool/--input esattamente come nella sezione Claude Code sopra.

Scrivere una policy

Le policy Cedar risiedono in una directory che punti con --cedar. Una regola forbid nega, una regola permit permette. Per confrontare un valore nell'input dello strumento, usa l'idioma .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" );

> **Pericolo:** NON scrivere `context.command in ["rm", "dd"]` per confrontare una stringa
> con un elenco. `in` è per gerarchie di entità, non per appartenenza a stringhe. Cedar
> tratta l'espressione come un errore di tipo e scarta silenziosamente l'intera regola `forbid`,
> che (sotto un gate fail-open) lascia un `permit` residuo attivo. Questo
> è il difetto esatto alla base dell'avviso sottostante. Usa invece `[...].contains(context.command)`.
> Dalla versione 0.7.0 il gate nega su quell'errore anziché permettere, e un
> test CI tripwire fallisce la build se il pattern viene reintrodotto in una policy pubblicata.
> Vedi [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).

### Pacchetti di policy per iniziare

La maggior parte dei team non dovrebbe scrivere Cedar da zero il primo giorno. Installa un pacchetto
iniziale, esegui in modalità shadow, ispeziona i ricevimenti, poi restringi o applica:```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

Pacchetti integrati:

filesystem-safe: azioni distruttive sui file e letture di percorsi simili a segreti.
git-safe: push forzati, reset duri, pulizia distruttiva, eliminazione del repository.
email-safe: consenti bozze, blocca invii non presidiati.
database-safe: postura DB orientata alla lettura, blocca scrittura/SQL amministrativo.
cloud-spend-safe: creazione evidente di spesa cloud e distruzione dell'infrastruttura.
secrets-safe: esfiltrazione comune di segreti da file, env, shell e cloud.
finance-mandate-safe: violazioni di liste ristrette e concentrazione nei flussi di prenotazione.

Verifica una ricevuta

Le ricevute sono firmate e verificabili offline da chiunque possieda la chiave pubblica. Nessuna rete, nessun fornitore, nessuna fiducia 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` esporta un bundle di audit autonomo e verificabile offline delle tue ricevute più la chiave di firma pubblica.

## Sicurezza

`protect-mcp` 0.7.0 fallisce in chiusura per progettazione. In caso di errore di valutazione della policy, motore mancante o policy che ha generato errore durante la valutazione, la decisione è DENY, non allow. `serve --enforce` e `doctor` eseguono un autotest di avvio che dimostra che il gate nega un vettore notoriamente vietato prima di essere considerato affidabile, e rifiutano di armarsi se non può.

**Versioni interessate: 0.5.x e 0.6.x.** Queste versioni falliscono in apertura (restituiscono ALLOW in caso di errore di valutazione) e non valutano Cedar correttamente rispetto al motore fissato, quindi una regola `forbid` potrebbe non riuscire a bloccare. **Aggiorna a >= 0.7.0.**

Dettagli e correzione: [GHSA-hm46-7j72-rpv9](https://github.com/ScopeBlind/scopeblind-gateway/security/advisories/GHSA-hm46-7j72-rpv9).
Per segnalare una vulnerabilità, vedere [SECURITY.md](https://github.com/scopeblind/scopeblind-gateway/blob/HEAD/SECURITY.md).

## Comandi

| Comando | Descrizione |
|---------|-------------|
| `serve` | Avvia il server HTTP hook per Claude Code (porta 9377). `--enforce` esegue prima l'autotest di moderazione; `--cedar <dir>` e `--policy <path>` selezionano la policy. |
| `init` | Genera una coppia di chiavi Ed25519 (`keys/gateway.json`), un modello di configurazione e una policy di esempio. |
| `sample` | Inserisce un record di esempio chiaramente etichettato (8 decisioni: una chiamata bloccata, due pagamenti; kid `sample-demo`) più una copia manomessa, in modo che `record`, `claim`, `verify-claim` e `anchor-record` siano ripetibili da zero prima di collegare un agente. Rifiuta di toccare un record esistente; `--force` lo sovrascrive. |
| `policy` | Visualizza e modifica la policy Cedar dal terminale: `policy list` (permit / forbid / default-deny per strumento, con quante volte il gate lo ha permesso o negato), `policy show`, `policy allow <tool>`, `policy deny <tool>`, `policy path`. Un `serve` in esecuzione ricarica automaticamente al cambiamento. |
| `wrap` | Stampa un comando MCP protetto o modifica i server MCP di Claude Desktop. Esecuzione di prova per impostazione predefinita; usa `--write` per aggiornare la configurazione di Claude Desktop. |
| `dashboard` | Avvia una dashboard solo locale su `127.0.0.1` che mostra inventario strumenti, rischio, copertura delle policy, approvazioni di azioni esatte, catene di ricevute ed esportazione audit. |
| `recommend` | Prepara una bozza di policy JSON revisionabile dalle chiamate locali osservate. Esecuzione di prova per impostazione predefinita; usa `--write` per creare `protect-mcp.recommended.json`. |
| `registry` | Crea un'identità organizzativa, ancora i digest delle ricevute e scrive una pagina di verifica statica. La modalità ospitata carica solo i digest. |
| `record` | Apre un visualizzatore locale e ricercabile delle tue ricevute (`--live` trasmette in streaming mentre l'agente è in esecuzione): firme Ed25519 verificate nel tuo browser con la tua chiave gateway, tag di capacità, un albero di provenienza ed esportazione firmata con un clic. Tutto locale, nulla caricato. |
| `claim` | Crea un'attestazione firmata e indipendente dalla posizione di un predicato sul record (`--no <cap>` incl. `--no payment`, `--only <c1,c2>`, `--no-verdict <verdict>`, `--count <verdict>`, `--payment-under <cap>`), rivelando solo le categorie di decisione. Aggiungi `--anchor` per registrare il digest del reclamo nel registro di trasparenza pubblico; le chiavi registrate si ancorano come un'organizzazione nominata. |
| `anchor-record` | Crea un checkpoint della radice Merkle del record + conteggio + intervallo di tempo nel registro pubblico (adatto per heartbeat: salta se invariato). Un reclamo successivo il cui impegno corrisponde a un checkpoint ancorato è provabilmente sull'intero record a partire da quel checkpoint. |
| `verify-claim` | Verifica un pacchetto di reclamo offline: firma, radice Merkle ricalcolata, predicato ricalcolato indipendentemente e l'ancora laterale quando presente (lega l'involucro ancorato a questo preciso reclamo, quindi conferma che il registro pubblico lo contiene). `--check-anchor` richiede l'ancora; `--offline` salta il salto del registro. |
| `killer-demo` | Genera un pacchetto demo completo da modalità ombra a policy ad approvazione a ricevuta firmata. |
| `verify-disclosure` | Verifica un pacchetto `scopeblind.selective_disclosure.v0` e spiega i campi divulgati rispetto a quelli nascosti. |
| `policy-packs` | Elenca, ispeziona e installa pacchetti di policy Cedar iniziali. |
| `evaluate` | Valuta una chiamata di strumento rispetto a una policy Cedar (gate PreToolUse). Uscita 2 = nega (fail-closed), uscita 0 = permette. |
| `sign` | Firma una chiamata di strumento in una ricevuta (PostToolUse). Best-effort: registra una riga onesta non firmata se non c'è chiave. |
| `simulate` | Esegue una simulazione di una policy contro un registro di decisioni registrato per vedere cosa avrebbe bloccato. |
| `demo` | Avvia un server demo integrato avvolto con il gate, per vedere le ricevute istantaneamente. |
| `doctor` | Controlla la tua configurazione (chiavi, policy, motore Cedar, verificatore) ed esegue l'autotest di moderazione. |
| `bundle` | Esporta un bundle di audit verificabile offline di ricevute più la chiave pubblica. |
| `report` | Genera un report di conformità (Markdown o JSON) dal registro delle decisioni e dalle ricevute. |

Esegui `npx protect-mcp --help` per il riferimento completo ai flag.

## Link

- Protocollo (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)

Concesso in licenza MIT. Realizzato da [ScopeBlind](https://scopeblind.com).

scopeblind-gateway

Più Popolari