Bundle de défense en profondeur pour serveurs MCP stdio : wrappers guardExec/guardSpawn prêts à l'emploi, CLI d'audit AST, serveur MCP de référence. Corrige la classe de vulnérabilité stdio-RCE Ox-Security 200k-server (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.
Fait partie de la StudioMeyer MCP Stack — Conçu à Majorque 🌴 · ⭐ si vous l'utilisez
avec allowlist + sandbox + détection de rejeu, plus une CLI d'audit AST (mcp-shellguard-audit)
qui analyse les sources des serveurs MCP à la recherche d'appels shell non assainis. Comble la classe
de RCE stdio MCP d'Ox-Security (200k serveurs vulnérables, divulgation de mai 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
Ou exécutez directement la CLI d'audit sans installation :
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
La version 0.1.3 inclut le bundle de dépendances décrit ci-dessous.
Le paquet embarque @typescript-eslint/typescript-estree ainsi que TypeScript et la fermeture des dépendances du parseur requises via bundledDependencies. Un override npm à la racine ne contraint pas l'arbre de dépendances d'un paquet installé ; la fermeture incluse transmet les versions vérifiées aux consommateurs. La préparation du bundle vérifie @typescript-eslint/typescript-estree 8.72.1 et minimatch 11.0.3, puis modifie uniquement la plage de dépendance du manifeste du parseur de minimatch ^10.2.2 à ^11.0.3. Les fichiers sources tiers et les numéros de version des paquets restent inchangés. L'audit AST appelle directement typescript-estree.parse, avec TypeScript inclus explicitement pour satisfaire l'arbre de dépendances du parseur ; aucun runtime ESLint n'est requis.
L'archive mesurée fait environ 4,92 Mo compressée et 26,04 Mo décompressée (Mo décimaux). Le bundling augmente le téléchargement et l'utilisation du disque ; une mise à jour de sécurité d'une dépendance incluse nécessite une archive de paquet mise à jour.
Pour la maintenance, exécutez npm ci et npm run test:consumer depuis le checkout du dépôt. npm pack exécute prepack automatiquement : il construit le paquet et prépare le bundle déclaré. La vérification consommateur effectue deux packs, vérifie l'identité des octets, installe l'archive réelle dans un projet neuf, contrôle npm ls et les deux audits de dépendances, et exerce la CLI ou le runtime installé. Examinez les mises à jour de dépendances conjointement avec le bundle verrouillé et les preuves de licence avant de distribuer une nouvelle archive. Le fichier dist/bundled-dependencies.json de l'archive enregistre le bundle et les ajustements du manifeste.
Trois couches, activables pièce par pièce :
guardExec / guardSpawn prêts à l'emploi que vous appelez depuis votre
propre serveur MCP. Liste d'autorisation par défaut en refus, profils de sandbox, fenêtre de rejeu.mcp-shellguard-audit scan <path> parcourt l'AST et signale
12 anti-patterns, de LOW (no timeout) à CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo expose 8 outils
afin que le MCP Inspector / Claude Desktop puissent piloter le bundle directement.| Outil | Type | Objectif |
|---|---|---|
guard_exec | destructif | child_process.exec protégé. Force le vecteur args[], liste d'autorisation + sandbox + rejeu. Retourne stdout, stderr, exitCode, canonicalHash, isReplay, trustTier. |
guard_spawn | destructif | child_process.spawn protégé. Retourne les hachages SHA-256 de stdout/stderr au lieu des corps complets. Rejette fermement shell:true. |
register_allowlist | mutant | Enregistre un nom d'outil avec un exécutable + une regex d'args. Sans enregistrement, le refus par défaut s'applique. |
audit_source | lecture seule | Analyse un chemin TS/JS à la recherche d'anti-patterns d'injection shell. Retourne AuditFinding[] + un résumé. |
audit_report | lecture seule | Formate un résultat d'audit en markdown / json / SARIF 2.1.0. |
replay_check | lecture seule | Calcule le hachage SHA-256 canonique d'une invocation et indique si elle est déjà dans la fenêtre de rejeu. |
sandbox_status | lecture seule | Signale le profil de sandbox actif + les limites concrètes + l'indicateur cgroup-v2 actif. |
trust_tier | lecture seule | Déduit le niveau LOW/MEDIUM/HIGH/CRITICAL d'un outil enregistré ainsi que des conseils d'amélioration. |
| Profil | Timeout | stdout max | stderr max | Budget FD | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 Mo | 256 Ko | 32 | oui (cpu/mémoire) |
standard (par défaut) | 30 s | 10 Mo | 1 Mo | 256 | oui |
permissive | 5 min | 100 Mo | 10 Mo | 1024 | non |
L'appelant peut resserrer via timeoutMs / fdBudget à chaque appel. L'appelant ne peut pas élargir
au-delà du profil.
| Niveau | Condition |
|---|---|
| LOW | outil non enregistré (refus par défaut) |
| MEDIUM | enregistré mais argsPatterns vide (tous les args autorisés) |
| HIGH | argsPatterns défini mais sandbox ou traqueur de rejeu inactif |
| CRITICAL | argsPatterns + sandbox + rejeu tous actifs |
élever le niveau de LOW → CRITICAL en enregistrant l'outil + en définissant argsPatterns + en exécutant
via guardExec/guardSpawn (qui activent toujours le sandbox + le replay).
import {
AllowlistRegistry,
ReplayWindow,
guardExec,
} from "mcp-stdio-shellguard";
const registry = new AllowlistRegistry();
const replay = new ReplayWindow();
registry.register({
toolName: "git-log",
executable: "/usr/bin/git",
argsPatterns: ["^log$", "^--oneline$", "^-n$", "^\\d+$"],
sandboxProfile: "strict",
});
const result = await guardExec(
{
toolName: "git-log",
command: "/usr/bin/git",
args: ["log", "--oneline", "-n", "10"],
},
{ registry, replay },
);
console.log(result.stdout); // → commit lines
console.log(result.trustTier); // → "CRITICAL"
console.log(result.canonicalHash); // → 64-char SHA-256
mcp-shellguard-audit scan ./src
mcp-shellguard-audit scan ./src --format sarif --output audit.sarif
mcp-shellguard-audit scan ./src --severity-floor HIGH # CI gate
Codes de sortie :
0 propre (aucune détection au niveau plancher ou au-dessus)1 détections présentes2 erreurs d'analyse / d'E/SLes ignoreGlobs personnalisés transmis à scanPath ou à l'outil MCP audit_source acceptent
au plus 128 chaînes. Chaque chaîne est limitée à 1024 unités de code UTF-16 et à 16
caractères ouvrants de regroupement non échappés ((, {, [). Les entrées dépassant ces
budgets déclenchent une erreur contrôlée avant la mise en correspondance.