mcp-stdio-shellguard

<!-- studiomeyer-mcp-stack-banner:start -->
> **Fait partie de la [StudioMeyer MCP Stack](https://studiomeyer.io)** — Conçu à Majorque 🌴 · ⭐ si vous l'utilisez
<!-- studiomeyer-mcp-stack-banner:end -->

# mcp-stdio-shellguard


<!-- badges -->
[![npm version](https://img.shields.io/npm/v/mcp-stdio-shellguard?style=flat-square&color=cb3837&logo=npm&label=npm)](https://www.npmjs.com/package/mcp-stdio-shellguard)
[![npm downloads](https://img.shields.io/npm/dm/mcp-stdio-shellguard?style=flat-square&color=cb3837&logo=npm&label=installs/mo)](https://www.npmjs.com/package/mcp-stdio-shellguard)
![License](https://img.shields.io/github/license/studiomeyer-io/mcp-stdio-shellguard?style=flat-square&color=22c55e&label=license)
![Last commit](https://img.shields.io/github/last-commit/studiomeyer-io/mcp-stdio-shellguard?style=flat-square&color=88c0d0&label=updated)
![GitHub stars](https://img.shields.io/github/stars/studiomeyer-io/mcp-stdio-shellguard?style=flat-square&color=ffd700&logo=github&label=stars)
<!-- /badges -->Bundle de défense en profondeur pour les serveurs MCP stdio. Enveloppe `child_process.exec/spawn`
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).

- **Spécification MCP** : 2025-06-18
- **SDK** : `@modelcontextprotocol/sdk` ^1.29.0
- **Node** : >= 20
- **Licence** : MIT
- **Auteur** : Matthias Meyer (StudioMeyer)

## Installation

```bash
npm install mcp-stdio-shellguard
```

Ou exécutez directement la CLI d'audit sans installation :

```bash
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
```

## Ce que cela vous apporte

Trois couches, activables individuellement :

1. **API de bibliothèque** — `guardExec` / `guardSpawn` prêts à l'emploi que vous appelez depuis votre
   propre serveur MCP. Liste d'autorisation par défaut en refus, profils de bac à sable, fenêtre de rejeu.
2. **CLI d'audit** — `mcp-shellguard-audit scan <path>` parcourt l'AST, signale
   12 anti-patterns allant de LOW (`no timeout`) à CRITICAL (`exec(\`...${userInput}...\`)`).
3. **Serveur MCP de référence** — `mcp-stdio-shellguard-demo` expose 8 outils
   afin que le MCP Inspector / Claude Desktop puissent piloter le bundle directement.

## Outils (serveur de référence)

| Outil | Type | Objectif |
|------|------|---------|
| `guard_exec` | destructif | `child_process.exec` protégé. Force le vecteur args[], liste d'autorisation + bac à sable + rejeu. Renvoie `stdout`, `stderr`, `exitCode`, `canonicalHash`, `isReplay`, `trustTier`. |
| `guard_spawn` | destructif | `child_process.spawn` protégé. Renvoie les hachages SHA-256 de stdout/stderr au lieu des corps complets. Rejette fermement `shell:true`. |
| `register_allowlist` | mutation | Enregistre un nom d'outil avec un exécutable + une regex d'arguments. 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 de shell. Renvoie `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 s'il figure déjà dans la fenêtre de rejeu. |
| `sandbox_status` | lecture seule | Indique le profil de bac à sable actif + les limites concrètes + l'indicateur d'activation cgroup-v2. |
| `trust_tier` | lecture seule | Déduit le niveau LOW/MEDIUM/HIGH/CRITICAL d'un outil enregistré ainsi que des conseils d'amélioration. |

## Profils de bac à sable

| Profil | Délai d'expiration | stdout max | stderr max | Budget de 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.

## Niveaux de confiance

| Niveau | Condition |
|------|-----------|
| LOW | outil non enregistré (refus par défaut) |
| MEDIUM | enregistré mais `argsPatterns` vide (tous les arguments autorisés) |
| HIGH | `argsPatterns` défini mais bac à sable ou traqueur de rejeu inactif |
| CRITICAL | argsPatterns + bac à sable + rejeu tous actifs |

Passez de LOW → CRITICAL en enregistrant l'outil + en définissant argsPatterns + en passant
par `guardExec`/`guardSpawn` (qui activent toujours le bac à sable + le rejeu).

## Démarrage rapide de la bibliothèque

```ts
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
```

## Audit CLI

```bash
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ésentes
- `2` erreurs d'analyse / d'E/S

Les `ignoreGlobs` personnalisés transmis à `scanPath` ou à l'outil MCP `audit_source` acceptent
au maximum 128 chaînes. Chaque chaîne est limitée à 1024 unités de code UTF-16 et à 16
caractères d'ouverture de groupe non échappés (`(`, `{`, `[`). Les entrées dépassant ces
budgets déclenchent une erreur contrôlée avant la mise en correspondance.

## Bibliothèque d'anti-patterns (12 règles)

| ID | Sévérité | Déclenché par |
|----|----------|-------------|
| `exec_template_literal_with_input` | CRITICAL | `child_process.exec(\`ls ${x}\`)` |
| `exec_dynamic_string` | CRITICAL | `child_process.exec(cmd)` |
| `exec_sync_dynamic_string` | CRITICAL | `child_process.execSync(cmd)` |
| `eval_near_child_process` | CRITICAL | `eval(...)` |
| `function_constructor_near_child_process` | CRITICAL | `new Function(...)` |
| `spawn_dynamic_file_args` | HIGH | `spawn(bin, userArgs)` |
| `exec_file_dynamic` | HIGH | `execFile(bin, ...)` |
| `shell_true_option` | HIGH | `{ shell: true }` |
| `os_system_equivalent` | HIGH | `Deno.run` / `Bun.spawn` |
| `spawn_literal_dynamic_args` | MEDIUM | `spawn('git', userArgs)` |
| `unbounded_buffer` | LOW | exec sans `maxBuffer` |
| `missing_timeout` | LOW | exec/spawn sans `timeout` |

Le scanner résout les liaisons `child_process` *renommées* avant la mise en correspondance,
de sorte que les formes dangereuses ci-dessous sont détectées même lorsque l'appel passe par un
alias plutôt que par un littéral `child_process.exec` :

- `const execAsync = promisify(exec); execAsync(`...${x}`)`
- `import cp from "node:child_process"; cp.exec(`...${x}`)`
- `const { exec: sh } = require("child_process"); sh(`...${x}`)`
- `import { exec as run } from "node:child_process"; run(...)`

Les variantes synchrones (`spawnSync`, `execFileSync`) partagent leurs règles asynchrones,
et `shell_true_option` se déclenche également sur un shell sous forme de chaîne (`{ shell: "/bin/sh" }`)
ou sur une valeur de shell dynamique — pas seulement sur le littéral `{ shell: true }`. Un
`promisify` d'une fonction non liée à child_process, une déstructuration depuis un autre
module, et `{ shell: false }` restent propres (aucun faux positif).

## Pragmas

- `// shellguard:ignore-next-line` — supprime une détection
- `// shellguard:ignore-file` — supprime tout le fichier (rare ; préférer le par-ligne)

## Raison d'être

Ox-Security a divulgué (2026-05) que plus de 200 000 serveurs MCP stdio enveloppent
`child_process.exec` avec des littéraux de gabarit transportant des entrées utilisateur directement depuis
les arguments d'outils LLM. LiteLLM v1.83.6 en était l'exemple canonique (CVE corrigée dans 1.83.7).
Ce bundle est la contrepartie défensive : un garde-fou + scanner prêt à l'emploi
qui ferme cette classe de vulnérabilités. Inspiré par les niveaux `seccomp` d'AWS Linux + le bac à sable de Chromium.

## Voir aussi

- `HOOK_RECIPES.md` — recettes de hooks Claude Code qui bloquent automatiquement les appels d'outils dangereux
- `CHANGELOG.md` — historique des versions
- Audit MCP d'Ox-Security : <https://venturebeat.com/security/200000-mcp-stdio-servers/>
- CVE-2026-XXXX de LiteLLM : <https://github.com/BerriAI/litellm/security/advisories>

## Licence

MIT — Copyright (c) 2026 Matthias Meyer (StudioMeyer)