Pacchetto di difesa in profondità per server MCP stdio: wrapper guardExec/guardSpawn sostitutivi, CLI di audit AST, server MCP di riferimento. Risolve la vulnerabilità di classe stdio-RCE che ha colpito 200k server (Ox-Security) (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.
Parte dello StudioMeyer MCP Stack — Realizzato a Maiorca 🌴 · ⭐ se lo usi
con allowlist + sandbox + rilevamento di replay, più una CLI di audit AST (mcp-shellguard-audit)
che analizza i sorgenti dei server MCP alla ricerca di chiamate shell non sanificate. Chiude la classe
di vulnerabilità MCP stdio-RCE di Ox-Security (200k server vulnerabili, divulgazione di maggio 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
Oppure esegui direttamente la CLI di audit senza installarla:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
La versione 0.1.3 include il bundle di dipendenze descritto di seguito.
Il pacchetto distribuisce @typescript-eslint/typescript-estree insieme a TypeScript e alla chiusura delle dipendenze del parser richiesta tramite bundledDependencies. Un override npm a livello root non vincola l'albero delle dipendenze di un pacchetto installato; la chiusura inclusa trasporta le versioni verificate ai consumatori. La preparazione del bundle verifica @typescript-eslint/typescript-estree 8.72.1 e minimatch 11.0.3, poi modifica solo l'intervallo di dipendenza del manifest del parser da minimatch ^10.2.2 a ^11.0.3. I file sorgente di terze parti e i numeri di versione dei pacchetti restano invariati. L'audit AST chiama direttamente typescript-estree.parse, con TypeScript incluso esplicitamente per soddisfare l'albero delle dipendenze del parser; non è richiesto alcun runtime ESLint.
L'archivio misurato è di circa 4,92 MB compresso e 26,04 MB decompresso (MB decimali). Il bundling aumenta il download e l'uso del disco; un aggiornamento di sicurezza di una dipendenza inclusa richiede un archivio del pacchetto aggiornato.
Per la manutenzione, eseguire npm ci e npm run test:consumer dal checkout del repository. npm pack esegue automaticamente prepack: compila il pacchetto e prepara il bundle dichiarato. Il controllo del consumatore esegue il pack due volte, verifica l'identità dei byte, installa l'archivio effettivo in un progetto pulito, controlla npm ls ed entrambi gli audit delle dipendenze, ed esercita la CLI o il runtime installato. Rivedere gli aggiornamenti delle dipendenze insieme al bundle bloccato e alle prove di licenza prima di distribuire un nuovo archivio. Il file dist/bundled-dependencies.json dell'archivio registra il bundle e le modifiche al manifest.
Tre livelli, attivabili singolarmente:
guardExec / guardSpawn drop-in che chiami dal tuo
server MCP. Allowlist con default-deny, profili sandbox, finestra di replay.mcp-shellguard-audit scan <path> percorre l'AST, segnala
12 anti-pattern da LOW (no timeout) a CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo espone 8 strumenti
così che MCP Inspector / Claude Desktop possano pilotare direttamente il bundle.| Strumento | Tipo | Scopo |
|---|---|---|
guard_exec | distruttivo | child_process.exec difeso. Impone il vettore args[], allowlist + sandbox + replay. Restituisce stdout, stderr, exitCode, canonicalHash, isReplay, trustTier. |
guard_spawn | distruttivo | child_process.spawn difeso. Restituisce hash SHA-256 di stdout/stderr invece dei corpi completi. Rifiuta categoricamente shell:true. |
register_allowlist | mutante | Registra un nome di strumento con eseguibile + regex degli args. Senza registrazione si applica il default-deny. |
audit_source | sola lettura | Analizza un percorso TS/JS alla ricerca di anti-pattern di shell-injection. Restituisce AuditFinding[] + riepilogo. |
audit_report | sola lettura | Formatta un risultato di audit come markdown / json / SARIF 2.1.0. |
replay_check | sola lettura | Calcola l'hash SHA-256 canonico per un'invocazione e segnala se è già nella finestra di replay. |
sandbox_status | sola lettura | Segnala il profilo sandbox attivo + i limiti concreti + il flag cgroup-v2 attivo. |
trust_tier | sola lettura | Deriva il livello LOW/MEDIUM/HIGH/CRITICAL per uno strumento registrato più suggerimenti di miglioramento. |
| Profilo | Timeout | Stdout max | Stderr max | Budget FD | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 MB | 256 KB | 32 | sì (cpu/memory) |
standard (predefinito) | 30 s | 10 MB | 1 MB | 256 | sì |
permissive | 5 min | 100 MB | 10 MB | 1024 | no |
Il chiamante può restringere tramite timeoutMs / fdBudget per chiamata. Il chiamante non può ampliare
oltre il profilo.
| Livello | Condizione |
|---|---|
| LOW | strumento non registrato (default-deny) |
| MEDIUM | registrato ma argsPatterns vuoto (qualsiasi arg consentito) |
| HIGH | argsPatterns impostato ma sandbox o tracker di replay inattivo |
| CRITICAL | argsPatterns + sandbox + replay tutti attivi |
Elevare da LOW a CRITICAL registrando lo strumento + impostando argsPatterns + eseguendo
tramite guardExec/guardSpawn (che attivano sempre 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
Codici di uscita:
0 pulito (nessun rilevamento pari o superiore alla soglia)1 rilevamenti presenti2 errori di parsing / IOI ignoreGlobs personalizzati passati a scanPath o allo strumento MCP audit_source accettano al massimo 128 stringhe. Ogni stringa è limitata a 1024 unità di codice UTF-16 e 16 caratteri di raggruppamento di apertura non escapati ((, {, [). Input che superano questi limiti generano un errore controllato prima del matching.