⚠️ Questo repository è stato spostato. Lo sviluppo attivo continua su ScopeBlind/scopeblind-gateway.

Questo fork personale potrebbe essere in ritardo rispetto al repository canonico. Si prega di utilizzare il repository dell'organizzazione per problemi, pull request e il codice più recente.

protect-mcp

Gateway di sicurezza per server MCP. Registrazione in modalità ombra per impostazione predefinita, politiche per strumento, ricevute Ed25519 locali opzionali e output di audit facilmente verificabile.

Percorso attuale da riga di comando: avvolgi qualsiasi server MCP stdio come proxy trasparente. In modalità ombra registra ogni richiesta tools/call e permette tutto. Aggiungi un file di policy per applicare regole per strumento. Esegui protect-mcp init per generare chiavi di firma locali e configurazione in modo che il gateway possa anche emettere ricevute firmate.

Quick Start

# Wrap an existing OpenClaw / MCP config into a usable pack
npx @scopeblind/passport wrap --runtime openclaw --config ./openclaw.json --policy email-safe

# Shadow mode — log every tool call, enforce nothing
npx protect-mcp -- node my-server.js

# Generate keys + config template for local signing
npx protect-mcp init

# Shadow mode with local signing enabled
npx protect-mcp --policy protect-mcp.json -- node my-server.js

# Enforce mode
npx protect-mcp --policy protect-mcp.json --enforce -- node my-server.js

# Export an offline-verifiable audit bundle
npx protect-mcp bundle --output audit.json

Cosa Fa

protect-mcp si posiziona tra il tuo client e server MCP come proxy stdio:

MCP Client ←stdin/stdout→ protect-mcp ←stdin/stdout→ your MCP server

Intercetta le richieste JSON-RPC tools/call e:

• Modalità ombra (predefinita): registra ogni chiamata di strumento e permette tutto
• Modalità di applicazione: applica regole di policy per strumento come block, rate_limit e min_tier
• Firma locale opzionale: quando la firma è configurata, emette una ricevuta firmata Ed25519 insieme al log strutturato

Tutti gli altri messaggi MCP (initialize, tools/list, notifiche) passano in modo trasparente.

Cosa include oggi

• Politiche per strumento — blocca strumenti distruttivi, limita il tasso di quelli costosi e allega requisiti di livello minimo
• Log delle decisioni strutturati — ogni decisione viene emessa su stderr con [PROTECT_MCP]
• Ricevute firmate locali opzionali — generate quando esegui con una policy contenente signing.key_path, archiviate in .protect-mcp-receipts.jsonl e esposte su http://127.0.0.1:9876/receipts
• Verifica offline — verifica ricevute o bundle con npx @veritasacta/verify
• Nessun account richiesto — chiavi locali, policy locale, processo locale

Limiti attuali delle funzionalità

Questi sono importanti prima di implementarlo o parlarne agli utenti:

• La firma non è automatica sul percorso semplice npx protect-mcp -- .... Quel percorso registra le decisioni in modalità ombra. Per la firma locale, esegui npx protect-mcp init e poi avvia il gateway con il file di policy generato.
• I controlli di policy basati sul livello sono attivi, ma l'ammissione del manifesto non è integrata nel percorso predefinito da CLI/stdio. La CLI imposta le sessioni predefinite su unknown a meno che un'integrazione host non chiami programmaticamente l'API di ammissione.
• La configurazione delle credenziali attualmente convalida i riferimenti alle credenziali basate su env e registra le etichette delle credenziali nei log/ricevute. L'iniezione generica per chiamata in strumenti stdio arbitrari è specifica dell'adattatore e non viene eseguita dal percorso proxy predefinito.
• Gli adattatori PDP esterni e gli helper per i bundle di audit esistono come utility esportate. Non sono ancora completamente integrati nel percorso CLI predefinito.

File di Policy

{
  "default_tier": "unknown",
  "tools": {
    "dangerous_tool": { "block": true },
    "admin_tool": { "min_tier": "signed-known", "rate_limit": "5/hour" },
    "read_tool": { "require": "any", "rate_limit": "100/hour" },
    "*": { "rate_limit": "500/hour" }
  },
  "signing": {
    "key_path": "./keys/gateway.json",
    "issuer": "protect-mcp",
    "enabled": true
  },
  "credentials": {
    "internal_api": {
      "inject": "env",
      "name": "INTERNAL_API_KEY",
      "value_env": "INTERNAL_API_KEY"
    }
  }
}

Regole della Policy

I nomi degli strumenti corrispondono esattamente, con "*" come fallback wildcard.

Configurazione del client MCP

Claude Desktop

Aggiungi a claude_desktop_config.json:

{
  "mcpServers": {
    "my-protected-server": {
      "command": "npx",
      "args": [
        "-y", "protect-mcp",
        "--policy", "/path/to/protect-mcp.json",
        "--enforce",
        "--", "node", "my-server.js"
      ]
    }
  }
}

Cursor / VS Code

Stesso schema — sostituisci il comando del server con protect-mcp che lo avvolge.

Opzioni della CLI

protect-mcp [options] -- <command> [args...]
protect-mcp init

Commands:
  init              Generate Ed25519 keypair + config template
  status            Show decision stats and local passport identity
  digest            Generate a local human-readable summary
  receipts          Show recent persisted signed receipts
  bundle            Export an offline-verifiable audit bundle

Options:
  --policy <path>   Policy/config JSON file
  --slug <slug>     Service identifier for logs/receipts
  --enforce         Enable enforcement mode (default: shadow)
  --verbose         Enable debug logging
  --help            Show help

Hook programmatici

La libreria espone anche i primitivi che non sono ancora integrati nel percorso CLI predefinito:

import {
  ProtectGateway,
  loadPolicy,
  evaluateTier,
  meetsMinTier,
  resolveCredential,
  initSigning,
  signDecision,
  queryExternalPDP,
  buildDecisionContext,
  createAuditBundle,
} from 'protect-mcp';

Usali se vuoi aggiungere:

• ammissione del manifesto prima dell'avvio di una sessione
• un PDP esterno (OPA, Cerbos o un webhook HTTP generico)
• integrazioni personalizzate con intermediazione di credenziali
• esportazione di bundle di audit dal tuo archivio di ricevute

Log delle decisioni e ricevute

Ogni chiamata di strumento emette JSON strutturato su stderr:

[PROTECT_MCP] {"v":2,"tool":"read_file","decision":"allow","reason_code":"observe_mode","policy_digest":"none","mode":"shadow","timestamp":1710000000}

Quando la firma è configurata, una ricevuta firmata segue:

[PROTECT_MCP_RECEIPT] {"v":2,"type":"decision_receipt","algorithm":"ed25519","kid":"...","issuer":"protect-mcp","issued_at":"2026-03-22T00:00:00Z","payload":{"tool":"read_file","decision":"allow","policy_digest":"...","mode":"shadow","request_id":"..."},"signature":"..."}

Verifica con la CLI: npx @veritasacta/verify receipt.json Verifica nel browser: scopeblind.com/verify

Bundle di audit

Il pacchetto esporta un helper per bundle di audit autonomi:

{
  "format": "scopeblind:audit-bundle",
  "version": 1,
  "tenant": "my-service",
  "receipts": ["..."],
  "verification": {
    "algorithm": "ed25519",
    "signing_keys": ["..."]
  }
}

Utilizza createAuditBundle() intorno alle tue ricevute firmate raccolte.

Filosofia

• Prima l'ombra. Vedi cosa fanno gli agenti prima di applicare qualsiasi cosa.
• Le ricevute battono i log solo di dashboard. Gli artefatti firmati dovrebbero essere verificabili indipendentemente.
• Mantieni le rivendicazioni strette. Il percorso CLI predefinito non fa ancora tutto ciò che l'architettura a lungo termine supporterà.
• Mettiti sopra l'autenticazione esistente. Non strappare il tuo stack solo per aggiungere controllo e prove.

Pacchetti di policy ancorati a incidenti

Inclusi con protect-mcp — ognuno previene un attacco reale:

npx protect-mcp --policy node_modules/protect-mcp/policies/clinejection.json -- node server.js

Mappatura completa OWASP Agentic Top 10: scopeblind.com/docs/owasp

BYOPE: Motori di policy esterni

Supporta OPA, Cerbos, Cedar (AWS AgentCore) e endpoint HTTP generici:

{
  "policy_engine": "hybrid",
  "external": {
    "endpoint": "http://localhost:8181/v1/data/mcp/allow",
    "format": "cedar",
    "timeout_ms": 200,
    "fallback": "deny"
  }
}

Standard e proprietà intellettuale

• Bozza Internet IETF: draft-farley-acta-signed-receipts-00 — Ricevute di decisioni firmate per controllo accessi macchina-macchina
• Stato dei brevetti: 4 domande di brevetto provvisorio australiane in sospeso (2025-2026) che coprono ricevute di decisioni con divulgazione configurabile, gateway di chiamata di strumenti, manifesti di agenti e identità portatile
• Verifica: con licenza MIT — npx @veritasacta/verify --self-test

Licenza

MIT — libero da usare, modificare, distribuire e su cui costruire senza restrizioni.

scopeblind.com · npm · GitHub · IETF Draft