MCPGuard-Lab

Ein Sicherheits-Experimentierprojekt für MCP-Toolaufrufe basierend auf dem echten mcp==2.0.0 SDK. Es ist nicht auf externe große Modelle oder API-Schlüssel angewiesen, sondern realisiert über deterministische Strategien eine Tool-Whitelist, Parametervalidierung, Dateigrenzen, SSRF-Schutz, Bestätigung sensibler Operationen, Ausgabebereinigung, Erkennung von Tool-Beschreibungsvergiftungen und JSONL-Protokollierung. Regressionstests stellen sicher, dass der Schutz durch spätere Änderungen nicht beeinträchtigt wird.

Verwendungszweck: Dieses Projekt ist ausschließlich für lokale Experimente, autorisierte Tests und Sicherheitsforschung gedacht und enthält keine Angriffsfunktionen gegen nicht autorisierte Ziele.

Implementierte Fähigkeiten

• Roundtrip-Tests zwischen MCP 2.0 stdio-Server und echtem Client.

• Sechs Demo-Tools: Sicheres Rechnen, Dateilesen innerhalb des Stammverzeichnisses, Notizabfrage, öffentliche URL-Anfragen, Tool-Metadatenprüfung, Notiz schreiben nach Bestätigung.

• Tool-Whitelist und strikte JSON-Schema-Validierung, Ablehnung zusätzlicher Parameter.

• Normalisierung von Dateipfaden, Ablehnung von absoluten Pfaden, Verzeichnisquerungen und Ausbrechen aus dem Stammverzeichnis.

• Prüfung von URL-Protokoll, Benutzerinformationen, Ports und DNS-Auflösungsergebnissen; Ablehnung von Loopback-, privaten, link-lokalen und anderen nicht-öffentlichen Adressen.

• Schreibzugriff nur mit confirmed=true-Türsteuerung.

• Explizite Kennzeichnung von Ausgaben aus nicht vertrauenswürdigen Tools; rekursive Bereinigung von Passwörtern, Tokens, API-Schlüsseln und Bearer-Anmeldeinformationen.

• Erkennung von Hinweisen auf Prompt-Injektion in Tool-Namen/Beschreibungen mit hohem Risiko.

• Jede Entscheidung wird in JSONL protokolliert: Anfrage-ID, Zeit, Tool, Parameter, Erlaubnis/Ablehnung, Grund und Ergebnis.

• pytest-Unit-/Integrationstests und reproduzierbare Angriffsregressionsberichte.

Related MCP server: meok-mcp-injection-scan-mcp

Architektur

MCP Client
   │ stdio / MCP 2.0
   ▼
MCP Server ──► GuardedGateway ──► PolicyEngine
                      │                 ├─ allowlist + schema
                      │                 ├─ path boundary
                      │                 ├─ URL / SSRF
                      │                 └─ confirmation
                      ├─ Tool handler
                      ├─ untrusted labeling + redaction
                      └─ JSONL audit

Das Kernprinzip lautet: „Zuerst entscheiden, dann ausführen, dann Ausgabe bereinigen, alles protokollieren“. Prompt-Texte erhalten nicht direkt zusätzliche Berechtigungen; die Berechtigungen basieren auf der Whitelist und den Richtlinien im Code.

Schnellstart (Windows)

py -3.10 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe -m mcpguard.regression

Sie können auch direkt ausführen:

powershell -ExecutionPolicy Bypass -File .\scripts\verify.ps1

Der Bericht wird erstellt in:

• reports/regression-report.md* reports/regression-report.json* reports/regression-audit.jsonl

Beispielkonfiguration für MCP-Client

Zunächst pip install -e . ausführen, dann die folgende Struktur durch den aktuellen absoluten Pfad des Repositorys ersetzen:

{
  "mcpServers": {
    "mcpguard-lab": {
      "command": "D:/path/to/mcpguard-lab/.venv/Scripts/python.exe",
      "args": ["-m", "mcpguard.server"],
      "env": {
        "MCPGUARD_WORKSPACE": "D:/path/to/mcpguard-lab/fixtures/workspace",
        "MCPGUARD_NOTES": "D:/path/to/mcpguard-lab/fixtures/workspace/notes",
        "MCPGUARD_AUDIT": "D:/path/to/mcpguard-lab/reports/audit.jsonl"
      }
    }
  }
}

Reale Grenzen

• Die Tool-Beschreibungsvergiftungserkennung ist eine Regel mit hoher Signalstärke und kann manuelle Überprüfungen und feste Whitelists nicht ersetzen.

• confirmed=true ist eine explizite Bestätigungstür in lokalen Experimenten; in der Produktion sollten Bestätigungsnachweise verwendet werden, die vom Host-UI/Identitätssystem ausgestellt werden und nicht vom Modell selbst gefälscht werden können.

• Das URL-Tool deaktiviert derzeit Weiterleitungen, um zu vermeiden, dass nach dem ersten Prüfungsdurchlauf ins interne Netz gesprungen wird; die Produktionsversion sollte auch Antwortgröße, Inhaltstyp und ausgehendes Netzwerk einschränken.

• Die Kennzeichnung nicht vertrauenswürdiger Inhalte kann das Risiko verringern, dass „Daten als Anweisungen“ behandelt werden, aber der endgültige Host-Agent muss weiterhin die Vertrauensgrenzen einhalten.

• Regressionsdaten repräsentieren nur festgelegte Anwendungsfälle innerhalb des Repositorys und bedeuten nicht, dass alle Prompt-Injektionen oder alle MCP-Risiken blockiert werden können.

Inhaltsverzeichnis

src/mcpguard/       核心实现
tests/              单元测试与真实 MCP stdio 集成测试
fixtures/           可公开的本地测试数据
reports/            自动生成的测试和审计证据
scripts/verify.ps1  一键验证入口

Referenzen

• Model Context Protocol Python SDK

• AgentDojo