Defense-in-depth-Bundle für MCP-stdio-Server: Drop-in-Wrapper für guardExec/guardSpawn, AST-Audit-CLI, Referenz-MCP-Server. Schließt die von Ox-Security identifizierte stdio-RCE-Klasse, von der 200.000 Server betroffen sind (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.
Teil des StudioMeyer MCP Stack — Gebaut auf Mallorca 🌴 · ⭐ wenn du es nutzt
mit Allowlist + Sandbox + Replay-Erkennung, plus eine AST-Audit-CLI (mcp-shellguard-audit),
die MCP-Server-Quellen nach unbereinigten Shell-Aufrufen durchsucht. Schließt die Ox-Security
MCP-stdio-RCE-Klasse (200k anfällige Server, Offenlegung Mai 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
Oder führen Sie die Audit-CLI direkt ohne Installation aus:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
Version 0.1.3 enthält das unten beschriebene Abhängigkeitsbündel.
Das Paket liefert @typescript-eslint/typescript-estree sowie TypeScript und den erforderlichen Parser-Abhängigkeitsabschluss über bundledDependencies aus. Ein npm-Override nur auf Root-Ebene schränkt den Abhängigkeitsbaum eines installierten Pakets nicht ein; der enthaltene Abschluss trägt die geprüften Versionen zu den Konsumenten. Die Bündelvorbereitung prüft @typescript-eslint/typescript-estree 8.72.1 und minimatch 11.0.3 und ändert dann nur den Abhängigkeitsbereich des Parser-Manifests von minimatch ^10.2.2 auf ^11.0.3. Quelldateien von Drittanbietern und Paketversionsnummern bleiben unverändert. Das AST-Audit ruft typescript-estree.parse direkt auf, wobei TypeScript explizit eingebunden wird, um den Parser-Abhängigkeitsbaum zu erfüllen; keine ESLint-Laufzeit ist erforderlich.
Das gemessene Archiv umfasst etwa 4,92 MB komprimiert und 26,04 MB entpackt (dezimales MB). Das Bündeln erhöht Download- und Speicherplatzbedarf; ein Sicherheitsupdate einer enthaltenen Abhängigkeit erfordert ein aktualisiertes Paketarchiv.
Für die Wartung führen Sie npm ci und npm run test:consumer aus dem Repository-Checkout aus. npm pack führt prepack automatisch aus: Es baut das Paket und bereitet das deklarierte Bündel vor. Die Konsumentenprüfung packt zweimal, verifiziert identische Bytes, installiert das tatsächliche Archiv in einem frischen Projekt, prüft npm ls und beide Abhängigkeitsaudits und testet die installierte CLI bzw. Laufzeit. Prüfen Sie Abhängigkeitsaktualisierungen zusammen mit dem gesperrten Bündel und den Lizenznachweisen, bevor Sie ein neues Archiv verteilen. Die Datei dist/bundled-dependencies.json des Archivs zeichnet das Bündel und die Manifest-Anpassungen auf.
Drei Ebenen, stückweise optional:
guardExec / guardSpawn, die Sie aus Ihrem
eigenen MCP-Server aufrufen. Default-Deny-Allowlist, Sandbox-Profile, Replay-Fenster.mcp-shellguard-audit scan <path> durchläuft den AST und meldet
12 Anti-Patterns von LOW (no timeout) bis CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo stellt 8 Tools bereit,
sodass der MCP Inspector / Claude Desktop das Bündel direkt steuern kann.| Tool | Typ | Zweck |
|---|---|---|
guard_exec | destruktiv | Abgesichertes child_process.exec. Erzwingt args[]-Vektor, Allowlist + Sandbox + Replay. Gibt stdout, stderr, exitCode, canonicalHash, isReplay, trustTier zurück. |
guard_spawn | destruktiv | Abgesichertes child_process.spawn. Gibt SHA-256-Hashes von stdout/stderr statt vollständiger Inhalte zurück. Lehnt shell:true strikt ab. |
register_allowlist | mutierend | Registriert einen Tool-Namen mit Executable + Args-Regex. Ohne Registrierung gilt Default-Deny. |
audit_source | schreibgeschützt | Durchsucht einen TS/JS-Pfad nach Shell-Injection-Anti-Patterns. Gibt AuditFinding[] + Zusammenfassung zurück. |
audit_report | schreibgeschützt | Formatiert ein Audit-Ergebnis als markdown / json / SARIF 2.1.0. |
replay_check | schreibgeschützt | Berechnet den kanonischen SHA-256-Hash für einen Aufruf und meldet, ob er bereits im Replay-Fenster liegt. |
sandbox_status | schreibgeschützt | Meldet aktives Sandbox-Profil + konkrete Limits + cgroup-v2-Aktiv-Flag. |
trust_tier | schreibgeschützt | Leitet die Stufe LOW/MEDIUM/HIGH/CRITICAL für ein registriertes Tool ab, plus Verbesserungshinweise. |
| Profil | Timeout | Max. stdout | Max. stderr | FD-Budget | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 MB | 256 KB | 32 | ja (cpu/memory) |
standard (Standard) | 30 s | 10 MB | 1 MB | 256 | ja |
permissive | 5 min | 100 MB | 10 MB | 1024 | nein |
Der Aufrufer kann pro Aufruf über timeoutMs / fdBudget verschärfen. Der Aufrufer kann nicht
über das Profil hinaus erweitern.
| Stufe | Bedingung |
|---|---|
| LOW | Tool nicht registriert (Default-Deny) |
| MEDIUM | registriert, aber argsPatterns leer (beliebige Args erlaubt) |
| HIGH | argsPatterns gesetzt, aber Sandbox oder Replay-Tracker inaktiv |
| CRITICAL | argsPatterns + Sandbox + Replay alle aktiv |
Lift LOW → CRITICAL durch Registrieren des Tools + Setzen von argsPatterns + Ausführen
über guardExec/guardSpawn (die immer Sandbox + Replay aktivieren).
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
Exit-Codes:
0 sauber (keine Befunde auf oder über der Schwelle)1 Befunde vorhanden2 Parse-/IO-FehlerBenutzerdefinierte ignoreGlobs, die an scanPath oder das MCP-Tool audit_source übergeben werden, akzeptieren höchstens 128 Strings. Jeder String ist auf 1024 UTF-16-Codeeinheiten und 16 nicht-escapte öffnende Gruppierungszeichen ((, {, [) begrenzt. Eingaben über diesen Budgets lösen vor dem Matching einen kontrollierten Fehler aus.