mcp-shark

Sicherheitsscanner für KI-Agententools — entwickelt für Sicherheits- und Plattformingenieure, die mit MCP in der IDE arbeiten.

Führen Sie einen lokalen statischen Scan über MCP-IDE-Konfigurationen und eingebettete Tool-Metadaten durch: 41 Regeln (einschließlich AAuth-Sichtbarkeit), Toxic-Flow-Heuristiken und SARIF / HTML / JSON-Berichte. Es gibt kein gehostetes Config-Scan-Backend.

Fügen Sie optional einen lokalen HTTP-Proxy mit einem Dashboard im Browser hinzu, sodass Live-Datenverkehr, Ergebnisse, AAuth-Signale und Playground-Prüfungen an einem Ort bleiben – ohne Ihre Konfigurationen an einen Anbieter zu senden.

Sie können

• Traffic für Live-JSON-RPC-Erfassung, Filter, Export und AAuth-Posture-Chips nutzen
• Local Analysis für OWASP-ähnliche Ergebnisse über erfassten Datenverkehr ausführen
• YARA Detection für Verkehrsmusterregeln (native Engine falls installiert, sonst Regex-Fallback)
• AAuth Explorer für einen Graphen von Agents, Missionen, Ressourcen und Signierungs-/Zugriffssignalen öffnen
• MCP Playground nutzen, um Tools, Prompts und Ressourcen durch den Proxy aufzurufen
• Optional Smart Scan ausführen (KI-gestützt; verwendet bei Aktivierung Ihren API-Token)
• Server-Setup nutzen, um Konfigurationen zu erkennen, das Format zu konvertieren und den Editor durch den Proxy zu leiten

Datenschutz: Statische Scans benötigen keine Cloud und senden keine Telemetrie. Das Aktualisieren von Regelkatalogen erfolgt per Opt-in über HTTPS (update-rules).

Dashboard auf einen Blick

Diese Aufnahmen stammen vom Live-Dashboard mit echtem erfassten Datenverkehr (Dummy-MCP oder eigene Upstreams). Starten Sie mit npx @mcp-shark/mcp-shark serve --open. Smart Scan wird unten nicht gezeigt – es hängt von einem optionalen Remote-API-Token ab. MCP Playground erscheint, sobald mindestens ein MCP-Upstream konfiguriert ist (die Playground-Aufnahme verwendet einen Demo-Server mit geladenen Tools).

Live-Datenverkehrserfassung

Jeder JSON-RPC-Frame zwischen Ihrer IDE und jedem MCP-Upstream wird mit vollständigen Headern, Body, Timing und einem AAuth-Posture-Chip erfasst. Filtern Sie nach Methode, Status, Server, Sitzung, AAuth-Agent / Mission / Posture.

MCP Playground

Wählen Sie einen Upstream aus, laden Sie Tools, Prompts und Ressourcen von diesem Server und rufen Sie dann Tools auf oder lesen Sie Ressourcen durch den Proxy – nützlich, um das Verhalten zu validieren, bevor es Ihre IDE erreicht. Die Ansicht unten zeigt die Tools-Liste für einen konfigurierten Demo-MCP.

AAuth Explorer

Kraftgerichteter Wissensgraph jedes Agents / jeder Mission / Ressource / jedes Signierungsalgorithmus / Zugriffsmodus, der im erfassten Datenverkehr beobachtet wurde. Verwenden Sie Generate sample data für einen schnellen Demo-Graphen oder erfassen Sie echten AAuth-förmigen Datenverkehr durch den Proxy.

Local Analysis

Offline-regelbasierter Scanner über erfassten Datenverkehr. Die Karte AAuth Posture fasst die Verteilung von signiert / aauth-aware / bearer / no-auth zusammen; das Panel Toxic flows (Proxy-Traffic) leitet serverübergreifende Paarungen aus beobachteten tools/list-Antworten ab. Mit bereits in der Datenbank befindlichen Paketen verwenden Sie Replay from DB (wenn kein Live-MCP angeschlossen ist) und dann Analyse, um Ergebnisse zu füllen – die Ansicht unten ist nach diesem Durchlauf.

YARA Detection

Gleicher Reiter Local Analysis: wechseln Sie zu YARA Detection für die Verkehrsregel-Engine – Engine-Status, acht vordefinierte Regeln (umschalten, bearbeiten, löschen) und New Rule für eigene Muster. Wenn das native yara-Modul nicht installiert ist, laufen Scans trotzdem mit dem integrierten Regex-Fallback (siehe docs/local-analysis.md).

New Rule öffnet den Editor mit einer Vorlage (meta, strings und condition). Bearbeiten Sie den Regeltext und klicken Sie dann auf Save Rule, um sie als benutzerdefiniertes Muster neben den integrierten hinzuzufügen.

Server-Setup

Erkennt automatisch Cursor-/Codex-/Windsurf-Konfigurationen, konvertiert sie in das mcp-shark-Format und patcht die IDE, um beim Start durch den Proxy zu leiten.

Warum mcp-shark?

MCP-Setups mischen häufig Geheimnisse, breiten Tool-Zugriff und mehrere Server in einem Agent-Kontext; Probleme sind leicht zu übersehen, ohne die Konfigurationen zu prüfen. Siehe die OWASP MCP Top 10 für eine strukturierte Übersicht über mögliche Fehler.

mcp-shark läuft auf Ihrem Rechner – keine API-Schlüssel oder gehostetes Scan-Backend. Installieren Sie es mit npx und überprüfen Sie die Ergebnisse lokal.

Toxic-Flow-Analyse

Der Scanner modelliert, wie MCP-Server im Agent-Kontext zusammenspielen, und kennzeichnet riskante Fähigkeitskombinationen (z. B. Geheimniszugriff kombiniert mit externem Datenabfluss):``` ▲ HIGH notify-server → repo-server Untrusted content in one tool’s channel could lead the agent to take a destructive action in another (e.g. push code).

▲ MEDIUM browser-server → filesystem-server Web-sourced context could be chained into local file operations.

Verwenden Sie die Ergebnisse von mcp-shark als Eingabe für Ihr eigenes Bedrohungsmodell, nicht als vollständige Prüfung.

## Funktionen

| Funktion | Beschreibung |
|---------|-------------|
| **41 Sicherheitsregeln** | OWASP MCP Top 10 + Agentic Security Initiative + AAuth-Sichtbarkeit + allgemeine Prüfungen |
| **Toxische Flussanalyse** | Erkennung von serverübergreifenden Angriffspfaden basierend auf Tool-Fähigkeitsheuristiken |
| **Angriffsdurchläufe** | Schritt-für-Schritt-Exploit-Beschreibungen aus den Ergebnissen |
| **Shark Score** | Transparenter Sicherheitsbewertungspunkt (0-100, A-F) |
| **Auto-Fix** | `--fix` ersetzt hartcodierte Geheimnisse, korrigiert Berechtigungen, mit Backup/Rückgängig |
| **Tool-Pinning** | Git-committierbare `.mcp-shark.lock` mit SHA-256-Hashes |
| **15 IDE-Erkennung** | Cursor, Claude Desktop, VS Code, Windsurf, Codex, Amp, Kiro und weitere |
| **4 Ausgabeformate** | Terminal, JSON, SARIF v2.1.0, HTML |
| **Gesundheitschecks** | `doctor`-Befehl zur Umgebungsvalidierung |
| **Server-Inventar** | `list`-Befehl zeigt alle Server in einer Tabelle an |
| **Überwachungsmodus** | Live-Neu-Scan bei Konfigurationsänderungen |
| **HTML-Berichte** | In sich geschlossene Offline-Sicherheitsberichte |
| **Herunterladbare Regelpakete** | [Rule pack registry](https://github.com/mcp-shark/rule-packs) (Manifest + JSON); `update-rules` synchronisiert deklarative Pakete und Toxic-Flow-Heuristiken — null Codeänderungen |
| **YAML-Regeln** | Projektbezogene benutzerdefinierte Regeln über `.mcp-shark/rules/` |
| **GitHub-Aktion** | CI/CD-Integration mit SARIF-Upload |
| **Interaktive TUI** | Terminal-Benutzeroberfläche im lazygit-Stil für Scan, Fix und Server-Durchsuchen |
| **Browser-Dashboard** | Live-Datenverkehr, Lokale Analyse, YARA-Regeln, AAuth Explorer, Spielwiese, Einrichtung und Protokolle |
| **Proxy toxische Flüsse** | Lokales Analysepanel + `GET/POST /api/security/traffic-toxic-flows*` leitet serverübergreifende Paare aus erfasstem **tools/list**-Verkehr ab (siehe [docs/local-analysis.md](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/local-analysis.md)) |
| **YARA-ähnliche Verkehrsregeln** | In **Lokale Analyse → YARA-Erkennung** aktivieren oder bearbeiten Sie eingebaute Musterregeln, fügen Sie benutzerdefinierte Regeln hinzu und prüfen Sie den Motorstatus (natives YARA falls verfügbar, sonst Regex-Fallback) |
| **Lokale statische Scans** | Kein gehostetes Scan-Backend; `update-rules` ist opt-in HTTPS zur Registry |

## Schnellstart```bash
# Scan your MCP setup (default command)
npx @mcp-shark/mcp-shark

# Auto-fix issues (with interactive confirmation)
npx @mcp-shark/mcp-shark scan --fix

# See full attack chain narratives
npx @mcp-shark/mcp-shark scan --walkthrough

# Pin tool definitions (lockfile) to spot unexpected changes
npx @mcp-shark/mcp-shark lock

# Check environment health
npx @mcp-shark/mcp-shark doctor

# Show all detected servers
npx @mcp-shark/mcp-shark list

# Download latest rule packs (OWASP, Agentic Security)
npx @mcp-shark/mcp-shark update-rules

# Watch for config changes
npx @mcp-shark/mcp-shark watch

# Interactive terminal UI
npx @mcp-shark/mcp-shark tui

# Generate HTML report
npx @mcp-shark/mcp-shark scan --format html --output report.html

# CI mode (exits 1 on critical/high)
npx @mcp-shark/mcp-shark scan --ci --format sarif

Befehle

CLI-Flags

scan (Standardbefehl)

Andere Befehle

Wie scan funktioniert

Der CLI-Befehl scan ist statisch: Er liest MCP-Einträge aus Ihren IDE-Konfigurationsdateien (siehe Unterstützte IDEs und optionales Projekt ./mcp.json) und analysiert was dort geschrieben steht. Er verbindet sich nicht mit laufenden MCP-Servern oder ruft tools/list auf.

• Immer gescannt: Die command-, args-, env-, url-Felder jedes Server-Blocks und zugehörige Felder (Geheimnisse in env, unsichere Spawn-Muster, HTTP-URLs, usw.)
• Tool-Ebene-Regeln (deklarative Pakete, Befehlsinjektionsheuristiken, toxische Flussklassifizierung anhand von Tool-Namen, usw.) werden nur ausgeführt, wenn der Server-Eintrag ein eingebettetes tools-Array enthält (Name, Beschreibung, Schemas). Wenn tools weggelassen wird—typisch für reine command/stdio-Konfigurationen—kann der Scan 0 geprüfte Tools melden, obwohl Cursor den Server ordnungsgemäß ausführt.

Um eine vollständige Regelabdeckung in CI- oder Test-Repos zu erreichen, betten Sie entweder Tool-Metadaten in das gleiche JSON ein, das Ihr Scanner liest, oder verwenden Sie ein projektspezifisches mcp.json-Harness (siehe --ide Project).

Was es abdeckt

mcp-shark zielt auf Konfiguration und Metadaten, die Sie bereits auf der Festplatte haben (plus optionales lokales Monitoring). Es hilft, häufige Fehlkonfigurationen und riskante Kombinationen zu erkennen; betrachten Sie die Ausgabe als Input für Ihre eigene Überprüfung, nicht als Garantie, dass nichts falsch ist.

Erweiterbarkeit der Regeln

Herunterladbare Regelpakete (JSON)

Die kanonische Registry (Manifest, Paketdateien, Validierungs-CI und Schema-Notizen) befindet sich in mcp-shark/rule-packs. Das npm-Paket enthält Kopien; update-rules holt dieselben Artefakte nach .mcp-shark/rule-packs/.

mcp-shark wird mit 30 deklarativen Regeln als JSON-Pakete ausgeliefert (OWASP MCP, Agentic Security Initiative, General Security, AAuth Visibility), plus einem toxic-flow-heuristics-Paket (toxic_flow_rules für serverübergreifende Komposition). Neue Schwachstellenkataloge können als .json-Dateien hinzugefügt werden — kein JavaScript, keine Codeänderungen.```bash

Fetch latest rule packs from the registry

npx @mcp-shark/mcp-shark update-rules

Use a custom/enterprise registry

npx @mcp-shark/mcp-shark update-rules --source https://internal.corp/rules/manifest.json

Heruntergeladene Pakete werden in `.mcp-shark/rule-packs/` zwischengespeichert und bei jedem Scan mit den integrierten Regeln zusammengeführt.

<details>
<summary>JSON-Schema für Regelpakete</summary>```json
{
  "id": "owasp-mcp-2027",
  "name": "OWASP MCP Top 10 (2027)",
  "version": "1.0.0",
  "rules": [
    {
      "id": "MCP01-token-mismanagement",
      "name": "Token Mismanagement",
      "severity": "critical",
      "framework": "OWASP-MCP",
      "description": "Detects hardcoded tokens in MCP configs",
      "patterns": [
        { "regex": "(api[_-]?key|token)\\s*[:=]", "flags": "i", "label": "API key pattern" }
      ],
      "scope": ["tool", "prompt", "resource", "packet"],
      "exclude_patterns": [{ "regex": "\\$\\{|process\\.env" }],
      "match_mode": "any"
    }
  ]
}

Benutzerdefinierte YAML-Regeln (pro Projekt)

Erstelle .mcp-shark/rules/ in deinem Projekt, um leichte benutzerdefinierte Regeln hinzuzufügen:```yaml

.mcp-shark/rules/no-production-keys.yaml

id: custom-no-prod-keys name: No Production Keys severity: critical description: Detects production API keys in MCP configs match: env_pattern: "^(PROD_|PRODUCTION_)" value_pattern: "^sk-live|^pk-live" message: "Production key detected in {key} — use staging keys for development"

Sowohl YAML-Regeln als auch JSON-Pakete werden beim Scannen automatisch geladen. Teilen Sie sie mit Ihrem Team, indem Sie den Ordner committen.

### Benutzerüberschreibbare Daten (`.mcp-shark/`)

Jede integrierte Datenquelle kann durch YAML-Dateien in Ihrem Projektstammverzeichnis erweitert oder überschrieben werden:

| Datei | Überschreibungen | Format |
|------|-----------|--------|
| `.mcp-shark/secrets.yaml` | Muster zur Erkennung von Geheimnissen | Liste von `{ name, regex }` |
| `.mcp-shark/classifications.yaml` | Tags für Server-/Tool-Fähigkeiten | Verschachtelte Map `server: { capability: true }` |
| `.mcp-shark/flows.yaml` | Regeln für toxische Abläufe | Liste von `{ source_cap, target_cap, risk, ... }` |
| `.mcp-shark/rules/*.yaml` | Benutzerdefinierte projektspezifische Regeln | Siehe YAML-Regeln oben |
| `.mcp-shark/rule-packs/*.json` | Überschreiben oder Hinzufügen deklarativer Pakete | Siehe JSON-Pakete oben |

Benutzerdaten werden beim Scannen mit den integrierten Daten zusammengeführt. Kein Neubau erforderlich.

## GitHub-Aktion```yaml
# .github/workflows/mcp-security.yml
name: MCP Security Scan
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: mcp-shark/scan-action@v1
        with:
          format: sarif
          fail-on: high
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: mcp-shark-results.sarif

Unterstützte IDEs

Sicherheitsregeln (41)

Browser-Dashboard

MCP Shark enthält ein In-Browser-Dashboard auf dem lokalen Proxy für Echtzeit-MCP-Datenverkehr, Analyse und Erkundung:```bash npx @mcp-shark/mcp-shark serve --open

Gleiche wie die ältere Verknüpfung (kein `serve`-Unterbefehl):```bash
npx @mcp-shark/mcp-shark --open

Das Dashboard bietet:

• Multi-Server-Aggregation und Echtzeit-Datenverkehrserfassung (Filter, Export, AAuth-Posture-Chips)
• MCP Playground — Aufruf von Tools, Prompts und Ressourcen über den Proxy gegen einen ausgewählten Upstream
• Lokale Analyse — OWASP-artiger statischer Scan des erfassten Datenverkehrs; YARA-Erkennung für Datenverkehrsmusterregeln (native Engine, sofern installiert, andernfalls Regex-Fallback)
• AAuth Explorer — Graph der im Datenverkehr beobachteten Agent-/Mission-/Ressourcen-/Signier-/Zugriffssignale
• Smart Scan — optionaler KI-gestützter Scan (erfordert ein konfiguriertes API-Token)
• API-Dokumentation in der App, Server-Setup, Logs und sauberes Herunterfahren

Zero-Touch-Erststart

Das Dashboard bootet sich beim ersten Start auf einem neuen Rechner selbst — kein Setup-Assistent nötig:

1. Wenn ~/.mcp-shark/mcps.json bereits Upstreams deklariert (z. B. von einem vorherigen Lauf, manueller Bearbeitung oder testbed:up), startet der Proxy direkt mit dieser Konfiguration.
2. Andernfalls, bei einer brandneuen Installation (kein ~/.mcp-shark vorhanden), sucht MCP Shark nach einer echten Editor-MCP-Konfiguration (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.codex/config.toml). Wird eine mit tatsächlichen Upstreams gefunden, importiert es diese automatisch, schreibt ~/.mcp-shark/mcps.json, startet den Proxy und patcht die Editor-Konfiguration, sodass der Editor über den Proxy routet.
3. Trifft keiner der Fälle zu, startet die UI im reinen Überwachungsmodus, und das Setup-Panel steht weiterhin für die manuelle Konfiguration zur Verfügung.

Um das Erststartverhalten auf einem Rechner erneut auszulösen, entfernen Sie ~/.mcp-shark/ und starten Sie die UI neu.

Architektur```

┌────────────────────────────────────────────────────┐ │ CLI (Commander.js) │ │ scan · lock · diff · doctor · list · watch · tui │ │ update-rules · serve │ ├──────────────┬──────────────┬──────────────────────┤ │ ConfigScanner│ ScanService │ StaticRulesService │ │ 15 IDEs │ orchestrator │ 41 rules │ ├──────────────┴──────────────┴──────────────────────┤ │ Data layer (JSON + user YAML/JSON overrides) │ │ ┌────────────┬──────────────┬───────────────────┐ │ │ │ rule-packs │ secret- │ tool- │ │ │ │ (30 rules) │ patterns.json│ classifications │ │ │ ├────────────┼──────────────┼───────────────────┤ │ │ │ toxic-flow │ rule- │ .mcp-shark/*.yaml │ │ │ │ rules.json │ sources.json │ (user overrides) │ │ │ └────────────┴──────────────┴───────────────────┘ │ ├────────────────────────────────────────────────────┤ │ JS plugins (11 rules needing algorithmic logic) │ │ + DeclarativeRuleEngine (30 pattern-based rules) │ └────────────────────────────────────────────────────┘

**Designprinzipien:**
- **Daten-orientiert** — Deklarative Regeln, Geheimnis-Muster, Werkzeugklassifikationen und Standardwerte für toxische Flüsse werden als JSON ausgeliefert; **30** von **41** Regeln sind Musterpakete, die Sie erweitern oder überschreiben können, ohne diese Definitionen zu forken.
- **Benutzerüberschreibbar** — Integrierte Daten können über `.mcp-shark/*.yaml` (und JSON-Paket-Ablagen) wie oben dokumentiert erweitert werden.
- **Hybride Regelmaschine** — Die anderen **11** Regeln sind JS-Plugins, bei denen Heuristiken Code benötigen. Beide Quellen werden zur Scan-Zeit zusammengeführt.
- **Null-Konfigurations-Scan** — `npx` und go. Erkennt automatisch die unten aufgeführten IDE-Pfade plus projektspezifische `mcp.json`-Varianten.

## Dokumentation

- [Regelpaket-Verzeichnis](https://github.com/mcp-shark/rule-packs) — Offizielle `manifest.json` und JSON-Pakete, die von `update-rules` konsumiert werden
- [Erste Schritte](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/getting-started.md) — Installation & Einrichtung
- [Funktionen](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/features.md) — Detaillierte Funktionsdokumentation
- [Benutzerhandbuch](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/user-guide.md) — Vollständige Nutzungsanleitung
- [Konfiguration](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/configuration.md) — Konfigurationsdateien & Umgebungsvariablen
- [Lokale Analyse](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/local-analysis.md) — Statische Sicherheitsanalyse & YARA-Verkehrsregeln
- [AAuth-Sichtbarkeit](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/aauth-visibility.md) — RFC 9421 / AAuth-Beobachtbarkeit
- [Architektur](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/architecture.md) — Systemdesign
- [Datenbankarchitektur](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/database-architecture.md) — SQLite-Schema-Referenz
- [API-Referenz](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/api-reference.md) — API-Endpunkte
- [Fehlerbehebung](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/troubleshooting.md) — Häufige Probleme & Lösungen
- [Entwicklung](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/development.md) — Beiträge & Projektkonventionen
- [Paketprüfung](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/package-inspection.md) — npm-Paketstruktur

## Anforderungen

- **Node.js**: 20.0.0 oder höher
- **Betriebssystem**: macOS, Windows oder Linux

## Lizenz

Quellverfügbare nicht-kommerzielle Lizenz

- ✅ Ansehen, forken, modifizieren, ausführen für persönliche, bildungsbezogene oder interne Unternehmensnutzung
- ❌ Verkaufen, weiterverkaufen oder in kostenpflichtige Produkte/Dienste integrieren ohne schriftliche Genehmigung

Siehe [LICENSE](https://github.com/mcp-shark/mcp-shark/blob/HEAD/LICENSE) für die vollständigen Bedingungen.

## CLI-Demo

Gleicher Einzeiler wie **[Schnellstart](#quick-start)** (Standard `scan`). Terminalausgabe hängt von Ihrer Konfiguration ab:```bash
npx @mcp-shark/mcp-shark

Support

• Issues: GitHub Issues
• Website: mcpshark.sh