Parte del StudioMeyer MCP Stack — Hecho en Mallorca 🌴 · ⭐ si lo usas

mcp-stdio-shellguard

Paquete de defensa en profundidad para servidores MCP stdio. Envuelve child_process.exec/spawn con lista blanca + sandbox + detección de replay, además de una CLI de auditoría AST (mcp-shellguard-audit) que escanea el código fuente de servidores MCP en busca de llamadas shell sin sanitizar. Cierra la clase de vulnerabilidad MCP stdio-RCE señalada por Ox-Security (200k servidores vulnerables, divulgación de mayo de 2026).

• Especificación MCP: 2025-06-18
• SDK: @modelcontextprotocol/sdk ^1.29.0
• Node: >= 20
• Licencia: MIT
• Autor: Matthias Meyer (StudioMeyer)

Instalación

npm install mcp-stdio-shellguard

O ejecuta la CLI de auditoría directamente sin instalar:

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

Qué te ofrece

Tres capas, opt-in por piezas:

1. API de librería — guardExec / guardSpawn como reemplazo directo que puedes invocar desde tu propio servidor MCP. Lista blanca de denegación por defecto, perfiles de sandbox y ventana de replay.
2. CLI de auditoría — mcp-shellguard-audit scan <path> recorre el AST e informa de 12 antipatrones, desde LOW (sin timeout) hasta CRITICAL (exec(\...${userInput}...`)`).
3. Servidor MCP de referencia — mcp-stdio-shellguard-demo expone 8 herramientas para que MCP Inspector / Claude Desktop puedan manejar el paquete directamente.

Herramientas (servidor de referencia)

Perfiles de sandbox

Quien llama puede ajustar a la baja mediante timeoutMs / fdBudget por llamada, pero no puede ampliar los límites más allá del perfil.

Niveles de confianza

Sube de LOW → CRITICAL registrando la herramienta, definiendo argsPatterns y ejecutándola a través de guardExec/guardSpawn (que siempre activan sandbox + replay).

Inicio rápido con la librería

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

CLI de auditoría

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

Códigos de salida:

• 0 limpio (sin hallazgos en o por encima del umbral)
• 1 hay hallazgos
• 2 errores de análisis / E/S

Biblioteca de antipatrones (12 reglas)

El escáner resuelve los enlaces renombrados de child_process antes de comparar, por lo que las formas peligrosas siguientes se detectan incluso cuando la llamada pasa por un alias en lugar de un child_process.exec literal:

• 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(...)

Las variantes síncronas (spawnSync, execFileSync) comparten sus reglas asíncronas, y shell_true_option también se activa con un shell en forma de cadena ({ shell: "/bin/sh" }) o con un valor de shell dinámico — no solo con el literal { shell: true }. Un promisify de una función que no sea de child_process, una desestructuración de otro módulo y { shell: false } permanecen limpios (sin falsos positivos).

Pragmas

• // shellguard:ignore-next-line — suprime un hallazgo
• // shellguard:ignore-file — suprime el archivo completo (poco habitual; prefiere la opción por línea)

Por qué existe

Ox-Security reveló (2026-05) que más de 200k servidores MCP stdio envuelven child_process.exec con template literals que llevan entrada del usuario directamente desde los argumentos de las herramientas del LLM. LiteLLM v1.83.6 fue el ejemplo canónico (CVE parcheado en 1.83.7). Este paquete es la contrapartida de seguridad defensiva: un guardián de sustitución directa + escáner que cierra esta clase de vulnerabilidad. Inspirado en seccomp de AWS Linux y en los niveles de sandbox de Chromium.

Ver también

• HOOK_RECIPES.md — recetas de hooks para Claude Code que bloquean automáticamente llamadas peligrosas a herramientas
• CHANGELOG.md — historial de versiones
• Auditoría MCP de Ox-Security: https://venturebeat.com/security/200000-mcp-stdio-servers/
• CVE-2026-XXXX de LiteLLM: https://github.com/BerriAI/litellm/security/advisories

Licencia

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