⚠️ Ce dépôt a été déplacé. Le développement actif continue sur ScopeBlind/scopeblind-gateway.

Ce fork personnel peut être en retard par rapport au dépôt canonique. Veuillez utiliser le dépôt de l'organisation pour les problèmes, les pull requests et le code le plus récent.

protect-mcp

Passerelle de sécurité pour les serveurs MCP. Enregistrements en mode shadow par défaut, politiques par outil, reçus Ed25519 locaux optionnels et sortie d'audit adaptée à la vérification.

Chemin CLI actuel : enveloppez n'importe quel serveur MCP stdio en tant que proxy transparent. En mode shadow, il enregistre chaque requête tools/call et autorise tout. Ajoutez un fichier de politique pour appliquer des règles par outil. Exécutez protect-mcp init pour générer des clés de signature locales et une configuration afin que la passerelle puisse également émettre des reçus signés.

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

Ce qu'il fait

protect-mcp se situe entre votre client MCP et votre serveur en tant que proxy stdio :

Client MCP ←stdin/stdout→ protect-mcp ←stdin/stdout→ votre serveur MCP

Il intercepte les requêtes JSON-RPC tools/call et :

• Mode shadow (par défaut) : enregistre chaque appel d'outil et autorise tout
• Mode enforcement : applique les règles de politique par outil telles que block, rate_limit et min_tier
• Signature locale optionnelle : lorsque la signature est configurée, émet un reçu signé Ed25519 en parallèle du journal structuré

Tous les autres messages MCP (initialize, tools/list, notifications) transitent de manière transparente.

Ce qui est livré aujourd'hui

• Politiques par outil — bloquer les outils destructeurs, limiter le débit des outils coûteux et attacher des exigences de niveau minimum
• Journaux de décision structurés — chaque décision est émise sur stderr avec [PROTECT_MCP]
• Reçus signés locaux optionnels — générés lorsque vous exécutez avec une politique contenant signing.key_path, persistés dans .protect-mcp-receipts.jsonl et exposés sur http://127.0.0.1:9876/receipts
• Vérification hors ligne — vérifiez les reçus ou les bundles avec npx @veritasacta/verify
• Aucun compte requis — clés locales, politique locale, processus local

Limites actuelles des capacités

Ce sont des points importants avant de déployer ou d'en parler aux utilisateurs :

• La signature n'est pas automatique sur le chemin nu npx protect-mcp -- .... Ce chemin enregistre les décisions en mode shadow. Pour la signature locale, exécutez npx protect-mcp init puis démarrez la passerelle avec le fichier de politique généré.
• Les contrôles de politique basés sur les niveaux sont actifs, mais l'admission des manifests n'est pas câblée dans le chemin CLI/stdio par défaut. Le CLI par défaut définit les sessions sur unknown sauf si une intégration hôte appelle l'API d'admission de manière programmatique.
• La configuration des credentials valide actuellement les références de credentials soutenues par des variables d'environnement et enregistre les étiquettes de credentials dans les logs/reçus. L'injection générique par appel dans des outils stdio arbitraires est spécifique à l'adaptateur et n'est pas effectuée par le chemin proxy par défaut.
• Les adaptateurs PDP externes et les assistants de bundle d'audit existent en tant qu'utilitaires exportés. Ils ne sont pas encore complètement câblés dans le chemin CLI par défaut.

Fichier de politique

{
  "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"
    }
  }
}

Règles de politique

Les noms d'outils correspondent exactement, avec "*" comme joker de repli.

Configuration du client MCP

Claude Desktop

Ajoutez à 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

Même motif — remplacez la commande du serveur par protect-mcp qui l'enveloppe.

Options 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

Hooks programmatiques

La bibliothèque expose également les primitives qui ne sont pas encore câblées dans le chemin CLI par défaut :

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

Utilisez-les si vous souhaitez ajouter :

• une admission de manifest avant le début d'une session
• un PDP externe (OPA, Cerbos, ou un webhook HTTP générique)
• des intégrations personnalisées avec courtage de credentials
• une exportation de bundle d'audit autour de votre propre magasin de reçus

Journaux de décision et reçus

Chaque appel d'outil émet du JSON structuré sur stderr :

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

Lorsque la signature est configurée, un reçu signé suit :

[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":"..."}

Vérifiez avec le CLI : npx @veritasacta/verify receipt.json Vérifiez dans le navigateur : scopeblind.com/verify

Bundles d'audit

Le paquet exporte un assistant pour les bundles d'audit autonomes :

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

Utilisez createAuditBundle() autour de vos propres reçus signés collectés.

Philosophie

• Shadow d'abord. Voyez ce que font les agents avant d'appliquer quoi que ce soit.
• Les reçus battent les journaux de tableau de bord seuls. Les artefacts signés doivent être vérifiables indépendamment.
• Gardez les revendications serrées. Le chemin CLI par défaut ne fait pas encore tout ce que l'architecture à long terme supportera.
• Superposez-vous à l'auth existante. Ne démontez pas votre pile juste pour ajouter du contrôle et des preuves.

Packs de politiques ancrés sur des incidents

Livrés avec protect-mcp — chacun empêche une attaque réelle :

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

Mapping complet OWASP Agentic Top 10 : scopeblind.com/docs/owasp

BYOPE : Moteurs de politique externes

Prend en charge OPA, Cerbos, Cedar (AWS AgentCore) et les points de terminaison HTTP génériques :

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

Normes et PI

• Projet de norme IETF : draft-farley-acta-signed-receipts-00 — Reçus de décision signés pour le contrôle d'accès machine à machine
• Statut des brevets : 4 demandes de brevet provisoires australiennes en attente (2025-2026) couvrant les reçus de décision avec divulgation configurable, la passerelle d'appel d'outils, les manifests d'agent et l'identité portable
• Vérification : sous licence MIT — npx @veritasacta/verify --self-test

Licence

MIT — libre d'utilisation, de modification, de distribution et de construction sans restriction.

scopeblind.com · npm · GitHub · IETF Draft