MCP Tool Security Inspector

Erklärbare, deterministische statische Analyse für Metadaten von Model Context Protocol-Tools.

Sicherheitshinweis: Der MCP Tool Security Inspector ist ein defensives Analysetool. Er identifiziert Indikatoren, die eine Überprüfung rechtfertigen können, stellt jedoch nicht fest, ob ein MCP-Tool oder -Server definitiv bösartig oder sicher ist.

Platzhalter für Screenshots

• screenshots/clean-scan.png — saubere Katalogzusammenfassung

• screenshots/suspicious-scan.png — Befundnachweise und Empfehlungen

• screenshots/drift-comparison.png — Baseline-Abweichungstabelle

Related MCP server: mcp-guardian

Das Problem

KI-Clients legen MCP-Toolnamen, -Beschreibungen, -Schemata und -Metadaten häufig einem Modell offen. Dieser Katalog ist eine Vertrauensgrenze: Irreführende Anweisungen, versteckte Fähigkeiten, unerwartete Anmeldefelder oder spätere Schemaänderungen verdienen eine Überprüfung, selbst wenn kein Tool ausgeführt wurde. mcpsec analysiert diese statische Oberfläche, ohne Tools aufzurufen oder Metadaten-URLs abzurufen.

Was sind MCP und MCP-Tools?

Das Model Context Protocol ist ein offenes Protokoll zum Verbinden von KI-Anwendungen mit Servern, die Kontext und Fähigkeiten bereitstellen. Ein Tool ist eine benannte aufrufbare Fähigkeit mit beschreibenden Metadaten und JSON-Schemata für Eingaben und optionale Ausgaben. Diese Version zielt auf die offizielle Spezifikation vom 2026-07-28 und das stabile offizielle Python-SDK v2 ab, toleriert jedoch ältere gängige Kataloghüllen.

Bedrohungsmodell und Tool-Vergiftung

Tool-Metadaten können sowohl die menschliche Genehmigung als auch die Modell-Toolauswahl beeinflussen. Ein bösartiger Herausgeber, ein kompromittierter Server, eine Abhängigkeit oder eine versehentliche Konfiguration könnte modellgesteuerte Anweisungen, Verschleierungstexte, privilegierte Felder oder Obfuskation hinzufügen. Siehe Bedrohungsmodell und Tool-Vergiftung.

Funktionen

• Laden von Einzeltools, Arrays, direkten tools-Objekten und JSON-RPC-tools/list-Antworten

• Erhaltung unbekannter Felder und Unicode-NFC-Normalisierung

• Stabiles UTF-8-kanonisches JSON und SHA-256-Voll-/Komponenten-Fingerabdrücke

• Datenschutzbewusste Baselines und Feldabweichungsklassifizierung

• Detektoren für Anweisungsüberschreibung, Verschleierung, sensible Daten, Schema, Abweichung, Obfuskation und Fähigkeiten

• Strenge reine Daten-YAML-Regeln mit sicherem Laden und begrenztem Literalabgleich

• Erklärbare, gedeckelte Risikobewertungen von 0–100

• Umfangreiche Terminal-, JSON-, CSV- und SARIF-2.1.0-Ausgabe

• Befund-Schwärzung und Abschwächung von Tabellenkalkulationsformel-Injection

• CI-Schweregradschwellen mit dokumentierten Exit-Codes

• Keine Telemetrie, Tool-Aufrufe, Symbol-Downloads, URL-Abrufe oder Metadatenausführung

Architektur

flowchart LR
  A["Hostile JSON catalog"] --> B["Bounded loader"]
  B --> C["Normalizer"]
  C --> D["Canonicalizer + SHA-256"]
  C --> E["Detectors + data-only rules"]
  E --> F["Capped risk engine"]
  D --> G["Baseline comparator"]
  F --> H["Terminal / JSON / CSV / SARIF"]
  G --> H

Die Implementierung sendet Kataloginhalte niemals an ein Modell und führt gescannte Werte niemals aus. Siehe Architektur.

Installation

python -m venv .venv
# Windows: .\.venv\Scripts\Activate.ps1
# Linux/macOS: source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
mcpsec --help

Siehe PREPARATION.md für die geprüfte Umgebung und Editor-Empfehlungen.

Schnellstart und Scans

mcpsec scan examples/clean_tools.json
mcpsec scan examples/suspicious_tools.json
mcpsec scan examples/mixed_tools.json --format json
mcpsec scan examples/suspicious_tools.json --format csv --output report.csv --redact
mcpsec scan examples/suspicious_tools.json --format sarif --output report.sarif
mcpsec scan examples/mixed_tools.json --rules rules/default_rules.yml --fail-on high

Strukturierte Berichte enthalten keine ANSI-Escape-Sequenzen. CSV-Felder, die mit Tabellenkalkulationsformelzeichen beginnen, werden mit einem Apostroph versehen.

Baseline- und Schema-Abweichungsworkflow

mcpsec baseline examples/clean_tools.json --output baseline.json
mcpsec compare examples/clean_tools.json --baseline baseline.json
mcpsec compare examples/changed_tools.json --baseline baseline.json --verbose
mcpsec fingerprint examples/clean_tools.json

Die geänderte Fixture modifiziert die Rechner-Beschreibung und das Eingabeschema und fügt unit_converter hinzu. Baselines speichern Hashes und strukturelle Zusammenfassungen, nicht vollständige Beschreibungen, Standardwerte oder Beispielgeheimnisse. Siehe Schema-Abweichung.

Risikobewertung

Der konfigurierte Beitrag jedes Befunds wird mit der Konfidenz multipliziert. Beiträge werden gruppiert und auf 35 pro Kategorie gedeckelt; Kategorierisiken werden mit 100 × (1 − Π(1 − Kategorie/100)) kombiniert. Zwei dokumentierte Korrelationen fügen begrenzte Synergien hinzu: Anweisungsüberschreibung + Verschleierung addiert 10, und Verschleierung + Sprache sensibler Daten addiert 7. Der Endwert wird gerundet und auf 100 gedeckelt.

Bänder: 0–19 informativ, 20–39 niedrig, 40–59 mittel, 60–79 hoch, 80–100 kritisch. Eine Bewertung priorisiert die Überprüfung; sie ist keine Wahrscheinlichkeit oder ein Urteil.

Regeln und Erklärbarkeit

mcpsec rules list
mcpsec rules validate rules/default_rules.yml
mcpsec explain SEC-001

Benutzerdefinierte Regeln ermöglichen ID, Name, Kategorie, Felder, Literalmuster, Schweregrad, Konfidenz, Bewertung, Empfehlung, Begründung, legitime Nutzung und aktivierten Zustand. Sie dürfen keine Python-Ausdrücke, Shell-Befehle, Importe, Vorlagen oder ausführbare reguläre Ausdrücke enthalten. Siehe Erkennungsregeln.

Ausgabeformate

Die Terminaltabelle fasst Tool-Anzahlen, saubere/betroffene Gesamtwerte, Schweregrad, Risiko, Regel-IDs, Nachweise und Empfehlungen zusammen. JSON bewahrt typisierte Befunde; CSV ist analysefreundlich; SARIF bietet eine mit GitHub-Code-Scanning kompatible Struktur für zukünftige Integration.

CI-Nutzung

Exit-Codes sind 0 für keine überschrittene konfigurierte Schwelle, 1 für einen abgeschlossenen Scan, der --fail-on überschreitet, 2 für ungültige Benutzereingaben und 3 für einen internen Fehler.

mcpsec scan catalog.json --fail-on medium

Der enthaltene GitHub-Actions-Workflow installiert Python, führt Ruff-Lint-/Format-Prüfungen, mypy und pytest mit Abdeckung aus. Er benötigt keine Geheimnisse, verbindet sich nicht mit Servern und veröffentlicht nichts.

Tests

ruff check .
ruff format --check .
mypy src
python -m pytest --cov=mcpsec --cov-report=term-missing --cov-report=html

Unter Windows führt scripts\test.ps1 -q den korrekten Interpreter der virtuellen Umgebung aus, selbst wenn die Umgebung nicht aktiviert ist. Verwenden Sie scripts\dev-inspector.ps1 für den lokalen Demonstrationsserver; siehe den Beispielserver-Leitfaden. Die vom Inspector gedruckte /sandbox-Adresse ist ein interner Iframe-Endpunkt, nicht die Hauptbenutzeroberfläche.

Tests decken Eingabeformen, Unicode, Kanonisierung, Hashes, Baselines, Abweichungen, Detektoren, Risikogrenzen, Regelvalidierung, sicheres YAML, strukturierte Berichte, CSV-Neutralisierung und CLI-Exit-Codes ab.

Sicherheitsmodell und falsch-positive Ergebnisse

Alle Eingaben sind nicht vertrauenswürdige Daten. Dateien sind größenbegrenzt; Zeichenfolgen sind längenbegrenzt; YAML verwendet safe_load; Schema-Inhalte werden validiert, aber niemals ausgewertet; benutzerdefinierter Abgleich ist literal und begrenzt; Terminal-Escape-Bytes werden neutralisiert; Reporter rendern kein HTML. Ein Befund besagt „verdächtig“ oder „erfordert Überprüfung“, behauptet niemals eine Kompromittierung. Jede integrierte Regel dokumentiert ihre Begründung, legitime Auslöser und Anleitung über mcpsec explain.

Siehe SECURITY.md, Erkennungsregeln und Einschränkungen.

Einschränkungen

Ein sauberer Scan begründet kein Vertrauen; ein verdächtiger Scan beweist keine bösartige Absicht. Statische Metadaten können von der Laufzeitimplementierung abweichen. Heuristiken können nicht jede Sprache, jeden Geschäftskontext, jede Schema-Referenz oder jede Prompt-Injection-Variation verstehen. Menschliche Überprüfung und Laufzeitkontrollen bleiben notwendig.

Roadmap

• v0.2: Opt-in, auf die Whitelist gesetzter lokaler Katalogabruf nur über SDK-tools/list

• Umfangreichere MCP-2026-07-28-x-mcp-header-Validierung

• Signierte Baseline-Hüllen und Baseline-Richtlinienprofile

• Regelpaket-Versionierung, Unterdrückungen mit Begründung und Delta-SARIF

• Zusätzliche sprachbewusste Heuristiken und korpusgesteuerte Messung falsch-positiver Ergebnisse

Mitwirken und Lizenz

Siehe CONTRIBUTING.md. Sicherheitsmeldungen folgen SECURITY.md. Lizenziert unter der MIT-Lizenz.