protect-mcp

Gate di policy Cedar fail-closed con ricevute firmate per le chiamate agli strumenti degli agenti AI.

protect-mcp è un gate che si frappone tra le chiamate agli strumenti di un agente AI. Valuta ogni chiamata rispetto a una policy Cedar, blocca ciò che viola le regole prima che venga eseguito, e firma una ricevuta Ed25519 verificabile offline di ogni decisione. Il gateway configurato viene eseguito localmente e non invia telemetria sulle decisioni. L' adattatore di coordinamento separato si connette al servizio di collaborazione ospitato di ScopeBlind; le sue richieste e i record restituiti hanno il percorso dati descritto di seguito. Entrambi sono con licenza MIT.

Per il lavoro su repository condivisi, usa i progetti client: le persone concordano il brief e i limiti, gli agenti preparano le revisioni, ed entrambe le persone approvano una versione esatta prima che il receiver del proprietario possa modificare il repository. Il flusso di lavoro sul repository di seguito include la configurazione e i cinque strumenti agent delimitati.

Perché è diverso

• Fail-closed per impostazione predefinita. In caso di qualsiasi errore di policy, engine mancante, o fallimento di valutazione, la decisione è DENY. Il gate non consente mai silenziosamente. Esiste una modalità observe per il rollout in shadow, ma anche lì una chiamata che verrebbe bloccata è contrassegnata con would_deny: true, così un fallimento non è mai silenzioso.
• Dimostra la propria moderazione. serve --enforce e doctor eseguono un self-test all'avvio e rifiutano di armare il gate a meno che non possano dimostrare che un'azione nota come proibita venga effettivamente negata. Un gate che non può dimostrare di negare non si avvia.
• Ogni decisione è una ricevuta che chiunque può verificare. Le decisioni sono firmate con Ed25519 e verificabili offline con @veritasacta/verify. La verifica della firma non richiede alcuna ricerca in rete. Le affermazioni sull'esecuzione dipendono comunque dall'operatore del gate identificato.

Quickstart: dall'installazione alla prima prova utile

# 1. Generate an Ed25519 keypair, config template, and sample policy.
npx protect-mcp init

# 2. Print a shadow-mode client configuration, then apply it in your MCP host.
#    This command prints configuration and exits; it does not launch the server.
npx protect-mcp wrap -- node your-mcp-server.js

# 3. Reopen the host and use its tools, then inspect the local-only dashboard.
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 una patch di configurazione dry-run, poi applicala:

npx protect-mcp wrap --claude-desktop
npx protect-mcp wrap --claude-desktop --write
npx protect-mcp dashboard --open

La dashboard si associa a 127.0.0.1, legge solo file di log/ricevute locali e non carica nulla. Usa npx protect-mcp connect solo se desideri esplicitamente una dashboard ScopeBlind ospitata.

Il gate come server MCP

Se preferisci chiamare il gate come strumenti anziché configurare gli hook di Claude Code, eseguilo come server MCP:

npx protect-mcp mcp

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

• evaluate_action: valuta una chiamata a strumento proposta rispetto a una policy Cedar inline, fail-closed (qualsiasi errore di policy è DENY). Restituisce { allowed, decision, reason, policy_digest }.
• sign_decision: trasforma una decisione in una ricevuta firmata Ed25519 (un diniego firma un gateway_restraint, un'autorizzazione 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: lo dimostra, senza input. Un'azione nota come vietata viene negata, poi una ricevuta firmata completa il ciclo e una copia manomessa fallisce.

Punta qualsiasi host MCP verso di esso, ad esempio Claude Desktop:

{
  "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 generato qui utilizza lo stesso envelope Acta. Le capacità di verifica e la compatibilità di canonicalizzazione dipendono dalla versione del verificatore; usa l'API verifyReceipt del gateway per il comportamento di conformità descritto di seguito.

Compatibilità di canonicalizzazione dei receipt

Questo albero dei sorgenti corregge il difetto di ordinamento delle chiavi intere presente fino alla 0.14.0: le firme e gli hash della catena ora utilizzano l'emissione diretta dei membri JCS, mantenendo il profilo delle chiavi oggetto ASCII del gateway. Le chiavi dall'aspetto numerico come "10" precedono "2", anche all'interno di oggetti annidati. I valori non JSON e l'Unicode non valido vengono rifiutati.

I receipt JSON ordinari le cui codifiche sono invariate continuano a verificarsi. I receipt storici firmati con il vecchio ordine di chiavi numeriche vengono segnalati come legacy_non_jcs_signature; la verifica rigorosa non li considera JCS validi. Per un controllo esplicito di compatibilità storica, usa verifyReceipt(receipt, publicKey, { allowLegacyNumericKeys: true }) e ispeziona i campi canonicalization e warning. Il suo hash è quindi l'hash storico originale. Conserva i receipt originali e i collegamenti della catena: ricalcolare un vecchio receipt con chiavi numeriche con receiptHash ora produce il suo hash JCS e può rompere la catena storica. Queste modifiche sono incluse nella 0.15.0.

Inizia con il tuo agente, poi autorizza ogni attività

La versione 0.25.0 include un profilo agente riutilizzabile. Apri Start through your agent per il comando di configurazione con la chiave di autorità mostrata dal servizio. Verifica quella chiave rispetto a una fonte attendibile prima di connetterti. Ad esempio:

npx --yes [email protected] coordination agent setup \
  --client claude-code \
  --profile ~/.scopeblind/agent.json \
  --endpoint https://scopeblind.com/api/coordination \
  --authority-key PINNED_64_HEX_AUTHORITY_KEY

Usa --client codex o --client json per quelle istruzioni di registrazione. La configurazione stampa la configurazione; applicala nel tuo client, poi riapri quel client. Il profilo privato contiene una chiave agente e connessioni con ambito separato, con permessi file 600. La configurazione non concede permessi di attività e non copia alcuna chiave browser umana. Il server registrato esegue coordination agent --profile FILE.

Chiedi al tuo agente di preparare un'attività fattura condivisa per la tua revisione. Il flusso dello strumento è: