⚠️ Dieses Repository wurde verschoben. Die aktive Entwicklung wird unter ScopeBlind/scopeblind-gateway fortgesetzt.

Dieser persönliche Fork könnte hinter dem kanonischen Repository zurück sein. Bitte nutzen Sie das Org-Repo für Issues, Pull-Requests und den aktuellsten Code.

protect-mcp

Sicherheits-Gateway für MCP-Server. Shadow-Modus protokolliert standardmäßig, pro-Tool-Richtlinien, optionale lokale Ed25519-Quittungen und verifizierungsfreundliche Audit-Ausgabe.

Aktueller CLI-Pfad: Umhüllen Sie jeden stdio MCP-Server als transparenten Proxy. Im Shadow-Modus protokolliert er jede tools/call-Anfrage und lässt alles durch. Fügen Sie eine Richtliniendatei hinzu, um Pro-Tool-Regeln durchzusetzen. Führen Sie protect-mcp init aus, um lokale Signierschlüssel und Konfiguration zu generieren, sodass das Gateway auch signierte Quittungen ausgeben kann.

Schnellstart

# 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

Was es tut

protect-mcp sitzt zwischen Ihrem MCP-Client und -Server als stdio-Proxy:

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

Es fängt tools/call JSON-RPC-Anfragen ab und:

• Shadow-Modus (Standard): protokolliert jeden Tool-Aufruf und lässt alles durch
• Erzwingungsmodus: wendet Pro-Tool-Richtlinienregeln wie block, rate_limit und min_tier an
• Optional lokales Signieren: wenn Signieren konfiguriert ist, wird eine Ed25519-signierte Quittung zusammen mit dem strukturierten Log ausgegeben

Alle anderen MCP-Nachrichten (initialize, tools/list, Benachrichtigungen) werden transparent durchgelassen.

Was heute ausgeliefert wird

• Pro-Tool-Richtlinien — blockieren Sie zerstörerische Tools, drosseln Sie teure und fügen Sie Mindeststufenanforderungen hinzu
• Strukturierte Entscheidungslogs — jede Entscheidung wird an stderr mit [PROTECT_MCP] ausgegeben
• Optionale lokale signierte Quittungen — werden generiert, wenn Sie mit einer Richtlinie laufen, die signing.key_path enthält, in .protect-mcp-receipts.jsonl gespeichert und unter http://127.0.0.1:9876/receipts bereitgestellt
• Offline-Verifizierung — verifizieren Sie Quittungen oder Pakete mit npx @veritasacta/verify
• Kein Konto erforderlich — lokale Schlüssel, lokale Richtlinie, lokaler Prozess

Aktuelle Fähigkeitsgrenzen

Diese sind wichtig, bevor Sie dies ausrollen oder mit Benutzern sprechen:

• Das Signieren erfolgt nicht automatisch auf dem reinen npx protect-mcp -- ...-Pfad. Dieser Pfad protokolliert Entscheidungen im Shadow-Modus. Für lokales Signieren führen Sie npx protect-mcp init aus und starten dann das Gateway mit der generierten Richtliniendatei.
• Stufenbewusste Richtlinienprüfungen sind live, aber die Manifestaufnahme ist nicht in den Standard-CLI/stdio-Pfad eingebunden. Die CLI setzt Sitzungen standardmäßig auf unknown, es sei denn, eine Host-Integration ruft die Admissions-API programmatisch auf.
• Die Anmeldeinformationskonfiguration validiert derzeit umgebungsgestützte Anmeldeinformationsreferenzen und zeichnet Anmeldeinformationsbezeichnungen in Logs/Quittungen auf. Die generische pro-Aufruf-Injektion in beliebige stdio-Tools ist adapterspezifisch und wird nicht vom Standard-Proxy-Pfad durchgeführt.
• Externe PDP-Adapter und Audit-Paket-Helfer existieren als exportierte Dienstprogramme. Sie sind noch nicht vollständig in den Standard-CLI-Pfad eingebunden.

Richtliniendatei

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

Richtlinienregeln

Tool-Namen stimmen exakt überein, mit "*" als Platzhalter-Fallback.

MCP-Client-Konfiguration

Claude Desktop

Fügen Sie zu claude_desktop_config.json hinzu:

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

Cursor / VS Code

Gleiches Muster — ersetzen Sie den Server-Befehl durch protect-mcp, der ihn umhüllt.

CLI-Optionen

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

Programmatische Hooks

Die Bibliothek stellt auch die Primitiven bereit, die noch nicht in den Standard-CLI-Pfad eingebunden sind:

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

Verwenden Sie diese, wenn Sie Folgendes hinzufügen möchten:

• Manifest-Aufnahme vor dem Start einer Sitzung
• einen externen PDP (OPA, Cerbos oder einen generischen HTTP-Webhook)
• benutzerdefinierte, durch Anmeldeinformationen vermittelte Integrationen
• Audit-Paket-Export um Ihren eigenen Quittungsspeicher herum

Entscheidungslogs und Quittungen

Jeder Tool-Aufruf gibt strukturiertes JSON an stderr aus:

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

Wenn das Signieren konfiguriert ist, folgt eine signierte Quittung:

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

Verifizieren Sie mit der CLI: npx @veritasacta/verify receipt.json Verifizieren Sie im Browser: scopeblind.com/verify

Audit-Pakete

Das Paket exportiert einen Helfer für eigenständige Audit-Pakete:

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

Verwenden Sie createAuditBundle() um Ihre eigenen gesammelten signierten Quittungen herum.

Philosophie

• Erst Shadow. Sehen Sie, was Agenten tun, bevor Sie etwas erzwingen.
• Quittungen schlagen Dashboard-only-Logs. Signierte Artefakte sollten unabhängig verifizierbar sein.
• Halten Sie die Behauptungen eng. Der Standard-CLI-Pfad macht noch nicht alles, was die langfristige Architektur unterstützen wird.
• Auf vorhandene Authentifizierung aufsetzen. Reißen Sie nicht Ihren gesamten Stack heraus, nur um Kontrolle und Nachweise hinzuzufügen.

Vorfallverankerte Richtlinienpakete

Wird mit protect-mcp ausgeliefert — jedes verhindert einen echten Angriff:

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

Vollständige OWASP Agentic Top 10 Zuordnung: scopeblind.com/docs/owasp

BYOPE: Externe Richtlinien-Engines

Unterstützt OPA, Cerbos, Cedar (AWS AgentCore) und generische HTTP-Endpunkte:

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

Standards & IP

• IETF Internet-Entwurf: draft-farley-acta-signed-receipts-00 — Signierte Entscheidungsquittungen für maschinen-zu-maschinen-Zugriffskontrolle
• Patentstatus: 4 australische vorläufige Patente angemeldet (2025-2026), die Entscheidungsquittungen mit konfigurierbarer Offenlegung, Tool-Calling-Gateway, Agenten-Manifeste und portable Identität abdecken
• Verifizierung: MIT-lizenziert — npx @veritasacta/verify --self-test

Lizenz

MIT — frei nutzbar, modifizierbar, verteilbar und ohne Einschränkungen darauf aufbauend.

scopeblind.com · npm · GitHub · IETF-Entwurf