mcp-shark

Analyse forensique à la Wireshark pour les communications du Model Context Protocol Capturez, inspectez et enquêtez sur toutes les requêtes et réponses HTTP entre votre IDE et les serveurs MCP

Confidentialité : les analyses statiques ne nécessitent aucun cloud et n'envoient aucune télémétrie. L'actualisation des catalogues de règles est une option HTTPS (update-rules).

Tableau de bord en un coup d'œil

Ces captures proviennent du tableau de bord en direct avec du trafic réel capturé (MCP factice ou vos propres amonts). Commencez avec npx @mcp-shark/mcp-shark serve --open. Analyse intelligente n'est pas montrée ci-dessous — elle dépend d'un jeton API distant optionnel. Le Terrain de jeu MCP apparaît dès que vous avez au moins un amont MCP configuré (la capture du Terrain de jeu utilise un serveur de démonstration avec des outils chargés).

Capture de trafic en direct

Chaque trame JSON-RPC entre votre IDE et chaque amont MCP est capturée avec les en-têtes, le corps, la temporisation et un badge de posture AAuth complets. Filtrez par méthode, statut, serveur, session, agent / mission / posture AAuth.

Terrain de jeu MCP

Choisissez un amont, chargez les outils, prompts et ressources de ce serveur, puis appelez des outils ou lisez des ressources via le proxy — utile pour valider le comportement avant qu'il n'atteigne votre IDE. La vue ci-dessous montre la liste des outils pour un MCP de démonstration configuré.

Explorateur AAuth

Graphe de connaissances orienté force de chaque agent / mission / ressource / algorithme de signature / mode d'accès observé dans le trafic capturé. Utilisez Générer des données d'exemple pour un graphe de démonstration rapide, ou capturez du trafic réel formaté AAuth via le proxy.

Analyse locale

Analyseur hors ligne basé sur des règles appliqué au trafic capturé. La carte Posture AAuth résume la distribution signée / consciente AAuth / porteur / sans authentification ; le panneau Flux toxiques (trafic proxy) infère les appariements entre serveurs à partir des réponses tools/list observées. Avec des paquets déjà dans la base de données, utilisez Rejouer depuis la BD (lorsqu'aucun MCP en direct n'est attaché) puis Analyser pour remplir les résultats — la vue ci-dessous est après cette exécution.

Détection YARA

Même onglet Analyse locale : passez à Détection YARA pour le moteur de règles de trafic — état du moteur, huit règles prédéfinies (activer, éditer, supprimer), et Nouvelle règle pour vos propres schémas. Lorsque le module natif yara n'est pas installé, les analyses s'exécutent malgré tout avec le repli regex intégré (voir docs/local-analysis.md).

Nouvelle règle ouvre l'éditeur avec un modèle de départ (meta, strings et condition). Modifiez le texte de la règle, puis Sauvegarder la règle pour l'ajouter comme schéma personnalisé aux côtés des règles intégrées.

Configuration du serveur

Détecte automatiquement les configs Cursor / Codex / Windsurf, les convertit au format mcp-shark et modifie l'IDE pour qu'il route via le proxy au démarrage.

Pourquoi mcp-shark ?

Les configurations MCP mélangent souvent secrets, accès étendu aux outils et plusieurs serveurs dans un même contexte d'agent ; les problèmes sont faciles à manquer sans vérifier les configs. Consultez le Top 10 OWASP MCP pour une vue structurée de ce qui peut mal tourner.

mcp-shark s'exécute sur votre machine — pas de clés API ni de backend d'analyse hébergé. Installez avec npx et examinez les résultats localement.

Analyse des flux toxiques

Le scanner modélise comment les serveurs MCP composent dans le contexte de l'agent et signale les appariements de capacités risqués (par exemple, accès aux secrets combiné avec sortie externe) :``` ▲ 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.

Commandes

Flags CLI

scan (commande par défaut)

Autres commandes

Comment scan fonctionne

La commande CLI scan est statique : elle lit les entrées MCP depuis vos fichiers de configuration IDE (voir IDEs pris en charge et le projet optionnel ./mcp.json) et analyse ce qui y est écrit. Elle ne se connecte pas aux serveurs MCP en cours d'exécution et n'appelle pas tools/list.

• Toujours scanné : command, args, env, url de chaque bloc serveur, et les champs associés (secrets dans env, motifs de lancement dangereux, URL HTTP, etc.).
• Règles au niveau des outils (packs déclaratifs, heuristiques d'injection de commandes, classification de flux toxique à partir des noms d'outils, etc.) ne s'exécutent que lorsque l'entrée du serveur inclut un tableau tools intégré (nom, description, schémas). Si tools est omis—typique pour les configurations uniquement command/stdio—le scan peut signaler 0 outils vérifiés même si Cursor exécute le serveur correctement.

Pour obtenir une couverture complète des règles en CI ou dans les dépôts de test, soit intégrez les métadonnées des outils dans le même JSON que votre scanner lit, soit utilisez un harnais mcp.json local au projet (voir --ide Project).

Ce qu'il couvre

mcp-shark est conçu pour la configuration et les métadonnées que vous avez déjà sur le disque (plus une surveillance locale optionnelle). Il aide à détecter les erreurs de configuration courantes et les combinaisons risquées ; considérez la sortie comme une entrée pour votre propre révision, pas comme une garantie qu'il n'y a rien d'anormal.

Extensibilité des règles

Packs de règles téléchargeables (JSON)

Le registre canonique (manifeste, fichiers de packs, CI de validation et notes de schéma) se trouve dans mcp-shark/rule-packs. Le package npm intègre des copies ; update-rules récupère les mêmes artefacts dans .mcp-shark/rule-packs/.

mcp-shark est livré avec 30 règles déclaratives sous forme de packs JSON (OWASP MCP, Agentic Security Initiative, General Security, AAuth Visibility), plus un pack toxic-flow-heuristics (toxic_flow_rules pour la composition inter-serveurs). De nouveaux catalogues de vulnérabilités peuvent être ajoutés sous forme de fichiers .json — pas de JavaScript, pas de modifications de code.```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

Règles YAML personnalisées (par projet)

Créez .mcp-shark/rules/ dans votre projet pour ajouter des règles personnalisées légères:```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"

IDE pris en charge

Règles de sécurité (41)

Tableau de bord navigateur

MCP Shark embarque un tableau de bord dans le navigateur sur le proxy local pour le trafic MCP en temps réel, l'analyse et l'exploration :```bash npx @mcp-shark/mcp-shark serve --open

Le tableau de bord fournit :

• Agrégation multi-serveur et capture de trafic en temps réel (filtres, export, badges de posture AAuth)
• MCP Playground — appeler des outils, des prompts et des ressources via le proxy vers un upstream sélectionné
• Local Analysis — scan statique de style OWASP sur le trafic capturé ; YARA Detection pour les règles de motifs de trafic (moteur natif si installé, sinon regex comme fallback)
• AAuth Explorer — graphe des signaux Agent / Mission / Resource / signature / accès observés dans le trafic
• Smart Scan — scan optionnel basé sur l'IA (nécessite un jeton API configuré)
• Documentation API intégrée, configuration du serveur, journaux et arrêt en douceur

Premier démarrage sans intervention

Le tableau de bord s'initialise automatiquement la première fois que vous le lancez sur une nouvelle machine — aucun clic d'assistant de configuration requis :

1. Si ~/.mcp-shark/mcps.json déclare déjà des upstreams (par exemple d'une exécution précédente, modification manuelle, ou testbed:up), le proxy démarre directement avec cette configuration.
2. Sinon, sur une installation toute neuve (pas de ~/.mcp-shark du tout), MCP Shark recherche une configuration MCP d'éditeur réelle (~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.codex/config.toml). Si une est trouvée avec des upstreams réels, il les importe automatiquement, écrit ~/.mcp-shark/mcps.json, démarre le proxy, et modifie la configuration de l'éditeur pour que l'éditeur route via le proxy.
3. Si aucun des chemins ne s'applique, l'interface démarre en mode surveillance uniquement et le panneau de configuration reste disponible pour une configuration manuelle.

Pour réinitialiser le comportement de premier démarrage sur une machine, supprimez ~/.mcp-shark/ et redémarrez l'interface.

Architecture```

┌────────────────────────────────────────────────────┐ │ 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) │ └────────────────────────────────────────────────────┘

Assistance

• Problèmes : GitHub Issues
• Site Web : mcpshark.sh