Parte dello StudioMeyer MCP Stack — Realizzato a Maiorca 🌴 · ⭐ se lo usi

mcp-stdio-shellguard

• Specifica MCP: 2025-06-18
• SDK: @modelcontextprotocol/sdk ^1.29.0
• Node: >= 20
• Licenza: MIT
• Autore: Matthias Meyer (StudioMeyer)

Installa

npm install mcp-stdio-shellguard

Oppure esegui la CLI di audit direttamente senza installare:

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

Cosa ti offre

Tre livelli, attivabili singolarmente:

1. API Libreria — guardExec / guardSpawn integrabili che chiami dal tuo server MCP. Lista consentita predefinita-negata, profili sandbox, finestra replay.
2. CLI di Audit — mcp-shellguard-audit scan <path> esamina l'AST, segnala 12 anti-pattern da BASSO (no timeout) a CRITICO (exec(\...${userInput}...`)`).
3. Server MCP di riferimento — mcp-stdio-shellguard-demo espone 8 strumenti così che MCP Inspector / Claude Desktop possano guidare direttamente il bundle.

Strumenti (server di riferimento)

Profili sandbox

Il chiamante può stringere tramite timeoutMs / fdBudget per chiamata. Il chiamante non può allargare oltre il profilo.

Livelli di fiducia

Solleva BASSO → CRITICO registrando lo strumento + impostando argsPatterns + eseguendo tramite guardExec/guardSpawn (che attivano sempre sandbox + replay).

Avvio rapido libreria

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 di Audit

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

Codici di uscita:

• 0 pulito (nessun risultato al livello o superiore)
• 1 risultati presenti
• 2 errori di parsing / IO

Raccolta anti-pattern (12 regole)

Lo scanner risolve i binding child_process rinominati prima di confrontarli, quindi le forme pericolose sotto vengono catturate anche quando la chiamata passa attraverso un alias piuttosto che un letterale 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(...)

Le varianti sincrone (spawnSync, execFileSync) condividono le loro regole asincrone, e shell_true_option si attiva anche su una shell stringa ({ shell: "/bin/sh" }) o un valore shell dinamico — non solo il letterale { shell: true }. Un promisify di una funzione non-child_process, una destrutturazione da un altro modulo, e { shell: false } rimangono puliti (nessun falso positivo).

Pragmi

• // shellguard:ignore-next-line — sopprime un risultato
• // shellguard:ignore-file — sopprime l'intero file (raro; preferire per riga)

Perché esiste

Ox-Security ha divulgato (2026-05) che oltre 200k server MCP stdio avvolgono child_process.exec con template literal che trasportano input utente direttamente dagli argomenti degli strumenti LLM. LiteLLM v1.83.6 era l'esempio canonico (CVE corretto in 1.83.7). Questo bundle è la controparte di sicurezza difensiva: un guard + scanner integrabile che chiude la classe. Ispirato da AWS Linux seccomp + livelli sandbox di Chromium.

Vedi anche

• HOOK_RECIPES.md — ricette hook di Claude Code che bloccano automaticamente chiamate pericolose agli strumenti
• CHANGELOG.md — cronologia delle versioni
• Ox-Security MCP audit: https://venturebeat.com/security/200000-mcp-stdio-servers/
• LiteLLM CVE-2026-XXXX: https://github.com/BerriAI/litellm/security/advisories

Licenza

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