MCP Agent Firewall

Ein deterministisches Sicherheits-Gateway für Model Context Protocol (MCP) 2026-07-28-Datenverkehr.

Es sitzt zwischen einem Agenten/MCP-Client und einem entfernten MCP-Server und erzwingt beide Seiten der Vertrauensgrenze:

• vor der Ausführung: Protokollintegrität, deterministische Richtlinie, gepinnte Tool-Schemas und signierte menschliche Genehmigung

• nach der Ausführung: Credential-DLP auf der Antwortseite, begrenzte Inspektion, explizite Kennzeichnung nicht vertrauenswürdiger Inhalte und datenschutzminimiertes Ausgabe-Audit

Das LLM besitzt niemals die Sicherheitsentscheidung.

Aktueller Meilenstein — v0.5.0

v0.5 fügt Ausgabe-Containment auf der Antwortseite hinzu.

Ein autorisierter Tool-Aufruf wird nicht länger als vertrauenswürdige Ausgabe vorausgesetzt. Jede Upstream-Antwort wird geprüft, bevor sie an den Aufrufer zurückgegeben wird. Geheimnis-/Credential-ähnliche Ausgaben werden blockiert, prompt-injection-artiger Text wird gekennzeichnet, und alle durchgereichten Upstream-Inhalte werden explizit als nicht vertrauenswürdig markiert.

agent / MCP client
        |
        v
MCP header/body integrity
        |
        v
deterministic policy
        |
        +--> DENY ------------------------------> stop
        |
        v
pinned tool catalog + JSON Schema
        |
        v
signed human approval when required
        |
        v
mcp.upstream.dispatch                   [CLIENT span]
        |
        v
upstream MCP server
        |
        |  UNTRUSTED OUTPUT
        v
mcp.output.inspect
        |
        +--> credential / secret -------------> BLOCK 502 / -32046
        |
        +--> malformed / binary / oversized --> BLOCK 502 / -32046
        |
        +--> prompt-injection signal ----------> FLAG + pass through
        |
        +--> clean ----------------------------> pass through
        |
        v
explicit untrusted-content headers
        |
        v
agent / MCP client

Parallel controls:
- privacy-minimized request + output SQLite audit
- low-cardinality OpenTelemetry metrics
- optional OTLP HTTP export

Related MCP server: guardrails-mcp-server

Ausgabe-Containment auf der Antwortseite

Credential-/Geheimnis-DLP

Der deterministische Ausgabe-Scanner blockiert erkanntes Credential-Material, einschließlich:

• strukturierte geheimnistragende Schlüssel wie access_token, refresh_token, api_key, private_key, authorization, password, secret und verwandte Varianten

• PEM-Private-Key-Material

• Bearer-Credentials

• AWS-Access-Key-IDs

• GitHub-artige Tokens

• OpenAI-artige sk--Credentials

• JWT-förmige Credential-Strings

Eine blockierte Upstream-Antwort wird durch einen firewall-generierten JSON-RPC-Fehler ersetzt:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32046,
    "message": "Upstream MCP response blocked by output containment",
    "data": {
      "action": "block",
      "signals": ["sensitive_key"],
      "untrusted": true
    }
  }
}

Der blockierte Antworttext wird nicht im Fehler wiedergegeben.

Prompt-Injection-Behandlung

Ausgabe-Prompt-Injection-Regexes sind Signale, keine Sicherheitsinstanz.

Beispielsweise darf Inhalt wie „ignore previous instructions“ durchgelassen werden, wenn er kein blockierendes Geheimnissignal enthält, aber der Aufrufer erhält:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: flagged
Mcp-Firewall-Output-Signals: prompt_injection_signal

Auch saubere Ausgaben erhalten:

Mcp-Firewall-Untrusted-Content: true
Mcp-Firewall-Output-Inspection: clean

Dies bewahrt die Unterscheidung zwischen von einem Tool zurückgegebenen Daten und vertrauenswürdigen Anweisungen.

Fail-closed-Antwortgrenzen

Die Ausgabeinspektion blockiert:

• deklariertes JSON, das nicht geparst werden kann

• Nicht-UTF-8-Binärausgaben

• Antworten größer als MAX_RESPONSE_BYTES (Standard 262.144 Bytes)

• JSON tiefer als 32 Ebenen

• JSON-Traversierungen über 10.000 Knoten

UTF-8-Ausgaben, die mit { oder [ beginnen, werden JSON-geparst, auch wenn der Upstream-Server einen irreführenden Nicht-JSON-Medientyp deklariert, wodurch eine einfache Content-Type-Umgehung des strukturierten Schlüssel-DLP verhindert wird.

Aktuelle Einschränkung: httpx puffert die Upstream-Antwort, bevor die Größenprüfung erfolgt. Das Limit begrenzt daher das Inspektions-/Rückgabeverhalten, ist aber noch keine Streaming-Netzwerkspeichergrenze.

Datenschutzminimiertes Ausgabe-Audit

GET /v1/audit/output ist durch dasselbe X-Operator-Token-Kontrollsystem geschützt wie der Request-Audit-Zugriff.

Ausgabe-Audit-Datensätze enthalten nur:

• Zeitstempel

• Methoden-/Toolname

• clean, flagged oder blocked-Ergebnis

• Signalnamen mit festem Vokabular

• Antwort-SHA-256

• Antwort-Byte-Länge

Rohe Upstream-Antworttexte werden niemals im Ausgabe-Audit gespeichert.

OpenTelemetry-Beobachtbarkeit

Sicherheitsfokussierte Spans umfassen:

• mcp.firewall.request

• mcp.policy.evaluate

• mcp.schema.validate

• mcp.approval.issue

• mcp.approval.verify

• mcp.approval.consume

• mcp.upstream.dispatch

• mcp.output.inspect

Metriken mit niedriger Kardinalität:

Toolnamen und Request-Hashes sind nur für Traces, nicht für Metrik-Dimensionen. Trace-Strings werden bereinigt und längenbegrenzt. Rohe Request-Argumente, Antworttexte, Genehmigungsbelege, Identitäten und Auth-Tokens sind von der Telemetrie ausgeschlossen.

Auf der Request-Seite beibehaltene Kontrollen aus v0.1–v0.4

• MCP-Protocol-Version, Mcp-Method und Mcp-Name-Integritätsprüfungen

• Default-Deny-deterministische Tool-Policy

• explizite Deny-Muster für Shell-/Befehls-/Credential-artige Tools

• menschliche Genehmigung für folgenreiche Senden/Erstellen/Aktualisieren/Löschen/Kaufen/Übertragen/Bereitstellen-Tools

• verschachtelte Secret-Schlüssel-, geschützte Pfad-, String-Größen- und numerische Request-Einschränkungen

• Prompt-Injection-Signale ohne Regex-Sicherheitsautorität

• SHA-256-gepinnte vertrauenswürdige Tool-Katalog

• JSON-Schema-2020-12-Argumentvalidierung

• vertrauenswürdige x-mcp-header / Mcp-Param-*-Body-Header-Verifizierung

• HMAC-SHA256-kurzlebige Einmal-Genehmigungsbelege

• Aufrufer-Autorisierung wird niemals an Upstream weitergeleitet

• Pro-Prozess-Rate-Limiting und begrenzte Request-Bodies

• W3C-TraceContext-Extraktion + generierte Upstream-Propagation

• optionaler OTLP-HTTP-Trace-/Metrik-Export

Konfigurieren

UPSTREAM_MCP_URL=https://your-mcp-server.example/mcp
MAX_BODY_BYTES=65536
MAX_RESPONSE_BYTES=262144

APPROVAL_SIGNING_KEY=<random-secret-at-least-32-bytes>
APPROVAL_ISSUER_TOKEN=<operator-only-token>
APPROVAL_DEFAULT_TTL_SECONDS=300
APPROVAL_MAX_TTL_SECONDS=900

TRUSTED_TOOL_CATALOG_PATH=./config/trusted_tools.example.json
TRUSTED_TOOL_CATALOG_SHA256=<canonical-catalog-sha256>

AUDIT_READ_TOKEN=<operator-only-token>

OTEL_ENABLED=false
OTEL_SERVICE_NAME=mcp-agent-firewall
OTEL_EXPORTER_OTLP_ENDPOINT=

Alle Gates ausführen

pip install -e ".[dev]"
ruff check app tests scripts
pytest -q
python scripts/run_benchmark.py --fail-on-unsafe
python scripts/run_approval_benchmark.py
python scripts/run_schema_benchmark.py
python scripts/run_observability_benchmark.py
python scripts/run_output_benchmark.py
docker build -t mcp-agent-firewall:test .

Verifizierte v0.5-Regressionsnachweise

Verifiziert auf GitHub Actions für die v0.5-Implementierung:

• 74 pytest-Tests bestanden

• Policy-Sicherheits-Benchmark: 32/32 exakte Entscheidungen

• Policy-Sicherheits-Benchmark: 0 unsichere False-Accepts, 0 False-Blocks

• Signierte Genehmigungs-Sicherheits-Benchmark: 11/11 bestanden

• Signierte Genehmigungs-Sicherheits-Benchmark: 0 unsichere False-Accepts

• Vertrauenswürdiges Schema / MCP-Header-Benchmark: 12/12 bestanden

• Vertrauenswürdiges Schema / MCP-Header-Benchmark: 0 unsichere False-Accepts, 0 False-Blocks

• Beobachtbarkeits-Datenschutz-/Propagations-Benchmark: 14/14 bestanden

• Beobachtbarkeits-Benchmark: 0 erkannte Telemetrie-Lecks

• Ausgabe-Containment-Benchmark: 11/11 bestanden

• Ausgabe-Containment-Benchmark: 0 unsichere False-Accepts

• Ruff: bestanden

• Docker-Build: bestanden

Der Ausgabe-Containment-Benchmark deckt sauberen Durchgang, strukturierte Secret-Schlüssel, PEM-Private-Keys, Bearer-Credentials, GitHub-artige Credentials, Prompt-Injection-Signalisierung, fehlerhaftes JSON, Binärausgabe, Antwortgrößenlimits, irreführende Content-Types und nicht-echoende öffentliche Inspektionsmetadaten ab.

Der Beobachtbarkeits-Benchmark übt echte FastAPI/MCP-Anfragen aus und prüft W3C-Elternkontext, Policy-/Schema-/Genehmigungs-/Ausgabe-Spiffe, begrenzte Metrik-Dimensionen, generierte Upstream-Trace-Propagation, Ausgabe-Unvertrauenswürdigkeits-Kennzeichnung und Abwesenheit eines injizierten Secret-Sentinels aus erfasster Telemetrie.

Dies sind synthetische Regressionstests, kein Anspruch auf universelle Produktionssicherheit oder vollständige Credential-/Prompt-Injection-Erkennung.

Siehe docs/THREAT_MODEL.md für Vertrauensgrenzen, Kontrollen und Restrisiken.

Nächste Meilensteine

1. Genehmigungs-Signaturschlüssel-Rotation mit Schlüssel-IDs und begrenzter Überlappung

2. Streaming-Antwortgrößen-Durchsetzung und optionale sichere Content-Type-Allowlists

3. gemeinsamer Replay-/Rate-Limit-Zustand für Multi-Replica-Bereitstellung

4. Live-Upstream-tools/list-Drift-Erkennung gegen den gepinnten Katalog

5. optionales OPA/Rego-Backend mit deterministischem lokalem Fallback

6. adversarielles Korpus aus echten MCP-Traces