
Paquete de defensa en profundidad para servidores MCP stdio: wrappers guardExec/guardSpawn de sustitución directa, CLI de auditoría AST, servidor MCP de referencia. Cierra la clase stdio-RCE de los 200 000 servidores de Ox-Security (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.
Parte del StudioMeyer MCP Stack — Creado en Mallorca 🌴 · ⭐ si lo usas
con lista de permitidos + 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 a shell sin sanear. Cierra la clase de RCE
por stdio en MCP de Ox-Security (200k servidores vulnerables, divulgación de mayo de 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
O ejecute la CLI de auditoría directamente sin instalarlo:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
La versión 0.1.3 incluye el paquete de dependencias descrito a continuación.
El paquete incluye @typescript-eslint/typescript-estree junto con TypeScript y el cierre de dependencias del parser requerido mediante bundledDependencies. Una anulación de npm solo a nivel raíz no restringe el árbol de dependencias de un paquete instalado; el cierre incluido traslada las versiones verificadas a los consumidores. La preparación del paquete verifica @typescript-eslint/typescript-estree 8.72.1 y minimatch 11.0.3, y luego cambia únicamente el rango de dependencia del manifiesto del parser de minimatch ^10.2.2 a ^11.0.3. Los archivos fuente de terceros y los números de versión de los paquetes no se modifican. La auditoría del AST llama directamente a typescript-estree.parse, con TypeScript incluido explícitamente para satisfacer el árbol de dependencias del parser; no se requiere un entorno de ejecución de ESLint.
El archivo medido es de aproximadamente 4,92 MB comprimido y 26,04 MB descomprimido (MB decimales). El empaquetado aumenta la descarga y el uso de disco; una actualización de seguridad de una dependencia incluida requiere un archivo de paquete actualizado.
Para el mantenimiento, ejecute npm ci y npm run test:consumer desde el checkout del repositorio. npm pack ejecuta prepack automáticamente: compila el paquete y prepara el bundle declarado. La comprobación del consumidor empaqueta dos veces, verifica que los bytes sean idénticos, instala el archivo real en un proyecto nuevo, comprueba npm ls y ambas auditorías de dependencias, y ejercita la CLI o el entorno de ejecución instalados. Revise las actualizaciones de dependencias junto con el bundle bloqueado y las pruebas de licencia antes de distribuir un nuevo archivo. El archivo dist/bundled-dependencies.json del paquete registra el bundle y los ajustes del manifiesto.
Tres capas, opcionales por partes:
guardExec / guardSpawn listos para usar que usted llama desde su
propio servidor MCP. Lista de permitidos con denegación por defecto, perfiles de sandbox, ventana de replay.mcp-shellguard-audit scan <path> recorre el AST e informa
12 antipatrones desde LOW (no timeout) hasta CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo expone 8 herramientas
para que MCP Inspector / Claude Desktop puedan controlar el bundle directamente.| Herramienta | Tipo | Propósito |
|---|---|---|
guard_exec | destructiva | child_process.exec protegido. Fuerza el vector args[], lista de permitidos + sandbox + replay. Devuelve stdout, stderr, exitCode, canonicalHash, isReplay, trustTier. |
guard_spawn | destructiva | child_process.spawn protegido. Devuelve hashes SHA-256 de stdout/stderr en lugar de los cuerpos completos. Rechaza de forma estricta shell:true. |
register_allowlist | mutante | Registra un nombre de herramienta con ejecutable + regex de args. Sin registro se aplica la denegación por defecto. |
audit_source | solo lectura | Escanea una ruta TS/JS en busca de antipatrones de inyección de shell. Devuelve AuditFinding[] + resumen. |
audit_report | solo lectura | Formatea un resultado de auditoría como markdown / json / SARIF 2.1.0. |
replay_check | solo lectura | Calcula el hash SHA-256 canónico de una invocación e informa si ya está en la ventana de replay. |
sandbox_status | solo lectura | Informa el perfil de sandbox activo + límites concretos + indicador de cgroup-v2 activo. |
trust_tier | solo lectura | Deriva el nivel LOW/MEDIUM/HIGH/CRITICAL para una herramienta registrada, junto con sugerencias de mejora. |
| Perfil | Tiempo de espera | stdout máx. | stderr máx. | Presupuesto de FD | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 MB | 256 KB | 32 | sí (cpu/memory) |
standard (predeterminado) | 30 s | 10 MB | 1 MB | 256 | sí |
permissive | 5 min | 100 MB | 10 MB | 1024 | no |
El llamador puede restringir mediante timeoutMs / fdBudget por llamada. El llamador no puede ampliar
más allá del perfil.
| Nivel | Condición |
|---|---|
| LOW | herramienta no registrada (denegación por defecto) |
| MEDIUM | registrada pero argsPatterns vacío (se permite cualquier argumento) |
| HIGH | argsPatterns definido pero sandbox o rastreador de replay inactivos |
| CRITICAL | argsPatterns + sandbox + replay todos activos |
Elevar de BAJO → CRÍTICO registrando la herramienta + configurando argsPatterns + ejecutando
a través de guardExec/guardSpawn (que siempre activan sandbox + 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
Códigos de salida:
0 limpio (sin hallazgos en o por encima del umbral)1 hallazgos presentes2 errores de análisis / E/SDescubre las herramientas más usadas por nuestra comunidad.
Sin datos de popularidad aún.