mcpsafetywarden

MCP safety warden est un serveur proxy qui encapsule n'importe quel serveur MCP et ajoute à ses outils du profilage comportemental, de l'analyse de sécurité, du filtrage de risque et une exécution sécurisée.

Sommaire

• Aperçu
• Prérequis
• Installation
• Configuration
• Intégration MCP
• Référence CLI
• Intégrations aux outils de sécurité auxiliaires
• Développement
• Tests
• Pour aller plus loin

[!IMPORTANT] La sécurité de MCP est un domaine de recherche actif. Des études récentes cataloguent de nombreuses catégories de menaces spécifiques au protocole, incluant l'empoisonnement d'outils, l'injection de prompt, les attaques de type rug-pull, les compromissions de chaîne d'approvisionnement, l'exfiltration d'identifiants et les attaques par composition tout au long du cycle de vie du serveur. Voir Securing the MCP (OpenReview), Landscape & Threats (arXiv), When MCP Servers Attack (arXiv) et MCP-38 Taxonomy (arXiv).

Aperçu

Utilisez-le comme proxy pour ajouter un filtrage de sécurité à n'importe quel serveur MCP, ou pointez-le vers un serveur dont vous n'êtes pas propriétaire et effectuez un audit de sécurité complet sans faire un seul appel d'outil.

Fig 1. Deux modes de fonctionnement : proxy et audit

Profilage comportemental : Classe d'effet, sécurité de reprise, destructivité. Assisté par LLM (Anthropic, OpenAI, Gemini, Ollama) avec repli basé sur des règles. Statistiques observées (latence p50/p95, taux d'échec, taille de sortie) mises à jour après chaque appel proxy.

Analyse de sécurité : Pipeline mcpsafety+ en cinq étapes (Recon, Planner, Hacker, Auditor, Supervisor). Cisco AI Defense (AST/YARA). Snyk (analyse de métadonnées). Les intégrations Kali et Burp Suite enrichissent le pipeline avec des données réseau réelles et des sondes au niveau HTTP. Analyse du code source depuis GitHub avec détection d'entropie, AST, flux de taint et détection de rug-pull.

Fig 2. Pipeline mcpsafety+ en cinq étapes, déclenché lorsque vous exécutez un audit de sécurité complet sur un serveur MCP

Exécution sécurisée : Analyse des arguments (20+ catégories d'attaques, deuxième passe LLM). Analyse d'injection de sortie à deux couches. Filtrage de risque avec alternatives et politiques par outil. Détection de dérive sur chaque appel et vérification autonome.

Fig 3. Pipeline d'exécution sécurisée : les cinq vérifications que chaque appel d'outil proxy traverse

CLI : 24 sous-commandes, menu de risque interactif, option --json sur chaque commande, --yes pour l'IC.

Ce qu'il détecte

• Injection de prompt : sorties d'outils tentant de détourner l'agent : détournement de rôle, jailbreaks, fausses invites système, remplacement d'instructions. Détecte 11 techniques d'obfuscation, y compris les homoglyphes Unicode, les caractères de largeur nulle et les charges utiles encodées en base64.
• Métadonnées d'outil malveillantes : descriptions contenant des chaînes d'injection, secrets codés en dur, URL de téléchargement suspectes, usurpation d'outil (shadowing), exécution financière directe, modification de services système et dépendances externes non fiables. Soutenu par 19 vérifications Snyk.
• Injection d'arguments : 20+ catégories d'attaques vérifiées sur chaque appel d'outil avant que l'appel ne soit transmis : SSRF vers les points de terminaison de métadonnées cloud (AWS, GCP, Azure, Alibaba), traversée de chemin, accès aux fichiers d'identifiants (.aws, .ssh, .kube, .env), injection de commandes, injection SQL/NoSQL/LDAP/XPath, XXE, injection de template (SSTI), CRLF, octet nul, charges utiles de désérialisation (Java, Python pickle, PHP, .NET), attaques Windows UNC/ADS, et variantes obfusquées en base64 de tout ce qui précède.
• Risques de code source : récupère le code source GitHub du serveur et exécute 6 couches d'analyse : analyse d'entropie pour les secrets codés en dur, suivi de flux de taint AST (paramètre vers puits dangereux), décalage description vs implémentation, SAST Bandit et Semgrep, et raisonnement inter-fonctions LLM. Prend en charge Python et TypeScript/JavaScript.
• Rug-pull et dérive : stocke un hachage SHA-256 du code source du serveur lors de la première analyse et alerte s'il change. Détecte les échanges de description, les changements de schéma et la suppression d'outils en direct sur chaque appel via une garde de dérive par appel.
• Anomalies comportementales : classe chaque outil par classe d'effet, destructivité et 7 étiquettes de risque : exposition d'identifiants, exécution arbitraire, exfiltration de données, accès au système de fichiers, mouvement latéral, élévation de privilèges et surface d'injection de prompt.
• Attaques par composition : analyse les ensembles d'outils pour les risques de chaînage : chaînes IDOR, paires lecture-écriture, exploitation de flux d'authentification, séquences écriture-puis-exécution et chemins d'accumulation de données + exfiltration sur plusieurs outils.
• Risques réseau et hôte : lorsque Kali Linux MCP est enregistré : ports ouverts, services en cours d'exécution, empreinte OS via nmap. Lorsque Burp Suite MCP est enregistré : sondes actives au niveau HTTP et SSRF aveugle via rappels hors bande.
• Exposition d'identifiants dans les sorties : masque les secrets des réponses d'outils avant le stockage. Les réponses signalées comme injectées sont mises en quarantaine et jamais renvoyées à l'agent appelant – stockées sous un ID de run pour examen forensique.

Prérequis

• Python 3.10 ou ultérieur
• Au moins un serveur MCP encapsulé à proxifier (stdio, SSE ou streamable_http)
• Recommandé : une clé API LLM (Anthropic, OpenAI ou Gemini)

Sans clé, le wrapper fonctionne uniquement en mode basé sur des règles : classification d'outils moins fiable, analyse d'injection par expressions régulières uniquement, pas d'alternatives dans le filtrage de risque, pas de pipeline mcpsafety+. Pour une configuration entièrement locale, exécutez Ollama, définissez OLLAMA_MODEL et passez --provider ollama explicitement (Ollama n'est pas détecté automatiquement).

[!NOTE] Serveurs stdio nécessitant une configuration locale (serveurs stdio nécessitant une configuration locale avant de démarrer – fichiers de configuration manquants, identifiants, répertoires de données ou dépendances spécifiques au système d'exploitation) ne peuvent pas être inspectés par le wrapper – la découverte d'outils échouera et 0 outil sera stocké. Vous pouvez toujours exécuter une analyse de sécurité complète du code source sans lancer le serveur en passant --github-url à scan / onboard, ou le paramètre github_url à security_scan_server. Le pipeline mcpsafety+ récupérera et analysera le code source directement depuis GitHub. Les serveurs sse et streamable_http ne sont pas affectés.

Installation

pip install mcpsafetywarden

Avec tous les extras optionnels :

pip install "mcpsafetywarden[all]"

Ou des extras spécifiques :

pip install "mcpsafetywarden[anthropic,snyk]"

Depuis les sources :

git clone https://github.com/gautamvarmadatla/mcpsafetywarden
cd mcpsafetywarden
pip install .

La base de données SQLite est créée automatiquement lors du premier lancement dans le répertoire de données utilisateur de la plateforme (~/.local/share/mcpsafetywarden/ sur Linux, ~/Library/Application Support/mcpsafetywarden/ sur macOS, %APPDATA%\mcpsafetywarden\ sur Windows). Surchargez avec MCP_DB_PATH.

Protection des identifiants (automatique, aucune action requise)

Les valeurs secrètes passées à register_server ou onboard_server (jetons Bearer, clés API dans headers ou env) sont automatiquement détectées et remplacées par des identifiants opaques cref_ avant que quoi que ce soit n'atteigne le contexte du modèle. Le véritable identifiant est stocké chiffré dans la base de données et résolu silencieusement au moment de la connexion. Le modèle, l'historique de conversation et les journaux ne voient jamais que cref_<id>.

Optionnel : chiffrement au repos des identifiants stockés

pip install cryptography
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Définissez la clé imprimée comme MCP_DB_ENCRYPTION_KEY avant de démarrer le serveur. Cela chiffre à la fois les identifiants du serveur et les valeurs cref_ au repos.

Configuration

Toute la configuration se fait via des variables d'environnement.

Note de sécurité : Ne jamais commiter les clés API ou la clé de chiffrement. Le wrapper supprime ses propres secrets des environnements des processus enfants avant de lancer les serveurs stdio.

Intégration MCP

Connexion avec Claude Desktop

Ajoutez le wrapper à claude_desktop_config.json :

{
  "mcpServers": {
    "mcpsafetywarden": {
      "command": "mcpsafetywarden-server",
      "args": [],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-...",
        "MCP_DB_ENCRYPTION_KEY": "<generated_fernet_key>"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]
    }
  }
}

Enregistrez chaque serveur auprès du wrapper avant utilisation :

mcpsafetywarden register filesystem --transport stdio \
  --command npx \
  --args '["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/Documents"]'

Pour une configuration de passerelle obligatoire où tous les appels d'outils doivent passer par le wrapper, voir docs/DEPLOYMENT.md.

Outils MCP disponibles

Voir docs/TOOLS.md pour la référence complète des outils.

Référence CLI

24 sous-commandes couvrant les 25 outils MCP. Chaque commande prend en charge --json pour une sortie lisible par machine et --yes / -y pour ignorer les invites de confirmation.

Voir docs/CLI.md pour la référence complète avec les drapeaux et exemples.

Intégrations aux outils de sécurité auxiliaires

Kali Linux MCP, Burp Suite MCP et Snyk s'intègrent automatiquement une fois enregistrés. Kali enrichit l'étape Recon et ping_server avec des données nmap/traceroute réelles. Burp ajoute des sondes HTTP brutes, des rappels hors bande et des preuves de proxy. Snyk analyse les métadonnées des outils pour détecter les chaînes d'injection, l'usurpation d'outil, les secrets codés en dur et 16 autres vérifications.

Voir docs/INTEGRATIONS.md pour les instructions de configuration.

Développement

Installez en mode éditable :

pip install -e ".[all]"

Lancez le serveur et observez les journaux :

mcpsafetywarden-server 2>server.log

Chaque module utilise logging.getLogger(__name__). Le serveur n'appelle pas logging.basicConfig lui-même – configurez la journalisation dans votre point d'entrée avant d'importer.

Tests

pytest tests/ -v

Définissez une clé API LLM pour inclure les tests assistés par LLM ; sans elle, ils sont automatiquement ignorés. Voir docs/TESTING.md pour une vérification étape par étape de la classification, de l'analyse d'injection, du filtrage de risque et de l'application des politiques.

Pour aller plus loin

Contribution

Voir CONTRIBUTING.md pour les normes de code et les directives pour les demandes de tirage.

Licence

Licence Apache 2.0. Voir LICENSE pour plus de détails.