mcp-shark

Scanner de sécurité pour les outils d'agents d'IA — conçu pour les ingénieurs en sécurité et en plateforme travaillant avec MCP dans l'IDE.

Effectuez une analyse statique locale sur les configs IDE MCP et les métadonnées d'outils intégrées : 41 règles (dont la visibilité AAuth), heuristiques de flux toxique, et rapports SARIF / HTML / JSON. Il n'y a pas de backend d'analyse de config hébergé.

Ajoutez un proxy HTTP local optionnel avec un tableau de bord dans le navigateur pour que le trafic en direct, les résultats, les signaux AAuth et les vérifications du terrain de jeu restent au même endroit — sans envoyer vos configurations à un fournisseur.

Vous pouvez

• Utiliser Trafic pour la capture JSON-RPC en direct, les filtres, l'exportation et les badges de posture AAuth
• Exécuter Analyse locale pour des résultats de type OWASP sur le trafic capturé
• Exécuter Détection YARA pour des règles de schémas de trafic (moteur natif installé, sinon solution de repli regex)
• Ouvrir l'Explorateur AAuth pour un graphe des agents, missions, ressources et signaux de signature / accès
• Utiliser le Terrain de jeu MCP pour appeler des outils, des prompts et des ressources via le proxy
• Exécuter optionnellement l'Analyse intelligente (basée IA ; utilise votre jeton API lorsqu'il est activé)
• Utiliser la Configuration du serveur pour détecter les configs, convertir le format et router l'éditeur via le proxy

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.

Utilisez les résultats de mcp-shark comme entrée pour votre propre modèle de menace, et non comme un audit complet.

## Fonctionnalités

| Fonctionnalité | Description |
|---------|-------------|
| **41 security rules** | OWASP MCP Top 10 + Agentic Security Initiative + visibilité AAuth + vérifications générales |
| **Toxic flow analysis** | Détection de chemins d'attaque entre serveurs à partir d'heuristiques de capacités d'outils |
| **Attack walkthroughs** | Récits d'exploitation étape par étape à partir des résultats |
| **Shark Score** | Score de posture de sécurité transparent (0-100, A-F) |
| **Auto-fix** | `--fix` remplace les secrets codés en dur, corrige les permissions, avec sauvegarde/annulation |
| **Tool pinning** | `.mcp-shark.lock` commitable dans Git avec hachages SHA-256 |
| **15 IDE detection** | Cursor, Claude Desktop, VS Code, Windsurf, Codex, Amp, Kiro, et plus |
| **4 output formats** | Terminal, JSON, SARIF v2.1.0, HTML |
| **Health checks** | Commande `doctor` pour la validation de l'environnement |
| **Server inventory** | La commande `list` affiche tous les serveurs dans un tableau |
| **Watch mode** | Re-scan en direct lors des modifications de configuration |
| **HTML reports** | Rapports de sécurité hors ligne autonomes |
| **Downloadable rule packs** | [Registre de packs de règles](https://github.com/mcp-shark/rule-packs) (manifeste + JSON) ; `update-rules` synchronise les packs déclaratifs et les heuristiques de flux toxiques — zéro changement de code |
| **YAML rules** | Règles personnalisées par projet via `.mcp-shark/rules/` |
| **GitHub Action** | Intégration CI/CD avec téléchargement SARIF |
| **Interactive TUI** | Interface terminal de style lazygit pour l'analyse, la correction et la navigation des serveurs |
| **Browser dashboard** | Trafic en direct, analyse locale, règles YARA, AAuth Explorer, bac à sable, configuration et journaux |
| **Proxy toxic flows** | Panneau d'analyse locale + `GET/POST /api/security/traffic-toxic-flows*` déduit les paires entre serveurs à partir du trafic **tools/list** capturé (voir [docs/local-analysis.md](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/local-analysis.md)) |
| **YARA-style traffic rules** | Dans **Analyse locale → Détection YARA**, activez ou modifiez les règles de motif intégrées, ajoutez des règles personnalisées et inspectez l'état du moteur (YARA natif lorsque disponible, repli regex sinon) |
| **Local static scans** | Aucun backend d'analyse hébergé ; `update-rules` est HTTPS optionnel vers le registre |

## Démarrage rapide```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

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

Les packs téléchargés sont mis en cache dans `.mcp-shark/rule-packs/` et fusionnés avec les règles intégrées lors de chaque analyse.

<details>
<summary>Schéma JSON du pack de règles</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"
    }
  ]
}

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"

Both YAML rules and JSON packs are loaded automatically on scan. Share them with your team by committing the folder.

### User-Overridable Data (`.mcp-shark/`)

Every built-in data source can be extended or overridden through YAML files in your project root:

| File | Overrides | Format |
|------|-----------|--------|
| `.mcp-shark/secrets.yaml` | Secret detection patterns | List of `{ name, regex }` |
| `.mcp-shark/classifications.yaml` | Server/tool capability tags | Nested map `server: { capability: true }` |
| `.mcp-shark/flows.yaml` | Toxic flow rules | List of `{ source_cap, target_cap, risk, ... }` |
| `.mcp-shark/rules/*.yaml` | Custom per-project rules | See YAML Rules above |
| `.mcp-shark/rule-packs/*.json` | Override or add declarative packs | See JSON Packs above |

User data is merged with built-in data at scan time. No rebuild required.

## GitHub Action```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

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

Identique au raccourci plus ancien (pas de sous-commande `serve`) :```bash
npx @mcp-shark/mcp-shark --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) │ └────────────────────────────────────────────────────┘

**Principes de conception :**
- **Priorité aux données** — Les règles déclaratives, les motifs de secrets, les classifications d'outils et les valeurs par défaut des flux toxiques sont fournis en JSON ; **30** des **41** règles sont des packs de motifs que vous pouvez étendre ou remplacer sans dupliquer ces définitions.
- **Surchargeable par l'utilisateur** — Les données intégrées peuvent être étendues via `.mcp-shark/*.yaml` (et les packs JSON) comme documenté ci-dessus.
- **Moteur de règles hybride** — Les autres **11** règles sont des plugins JS où des heuristiques nécessitent du code. Les deux sources sont fusionnées au moment de l'analyse.
- **Analyse sans configuration** — `npx` et go. Détecte automatiquement les chemins IDE ci-dessous ainsi que les variantes locales `mcp.json`.

## Documentation

- **[Registre des packs de règles](https://github.com/mcp-shark/rule-packs)** — `manifest.json` officiel et packs JSON consommés par `update-rules`
- **[Démarrer](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/getting-started.md)** — Installation et configuration
- **[Fonctionnalités](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/features.md)** — Documentation détaillée des fonctionnalités
- **[Guide utilisateur](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/user-guide.md)** — Guide d'utilisation complet
- **[Configuration](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/configuration.md)** — Fichiers de configuration et variables d'environnement
- **[Analyse locale](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/local-analysis.md)** — Analyse de sécurité statique et règles de trafic YARA
- **[Visibilité AAuth](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/aauth-visibility.md)** — Observabilité RFC 9421 / AAuth
- **[Architecture](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/architecture.md)** — Conception du système
- **[Architecture de la base de données](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/database-architecture.md)** — Référence du schéma SQLite
- **[Référence API](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/api-reference.md)** — Points d'extrémité API
- **[Dépannage](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/troubleshooting.md)** — Problèmes courants et correctifs
- **[Développement](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/development.md)** — Contribution et conventions du projet
- **[Inspection des packages](https://github.com/mcp-shark/mcp-shark/blob/HEAD/docs/package-inspection.md)** — Disposition des packages npm

## Prérequis

- **Node.js** : 20.0.0 ou supérieur
- **OS** : macOS, Windows ou Linux

## Licence

Licence source disponible non commerciale

- ✅ Consulter, forker, modifier, exécuter pour un usage personnel, éducatif ou interne à l'entreprise
- ❌ Vendre, revendre ou intégrer dans des produits/services payants sans autorisation écrite

Voir [LICENSE](https://github.com/mcp-shark/mcp-shark/blob/HEAD/LICENSE) pour les conditions complètes.

## Démo CLI

Même commande one-liner que **[Démarrage rapide](#quick-start)** (par défaut `scan`). La sortie du terminal dépend de votre configuration :```bash
npx @mcp-shark/mcp-shark

Assistance

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