Zurück zu den Updates
New releaseAug 21, 2026

mcp-stdio-shellguard v0.1.2

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.

Teilen

Teil des StudioMeyer MCP Stack — Gebaut auf Mallorca 🌴 · ⭐ wenn du es nutzt

mcp-stdio-shellguard

npm version npm downloads License Last commit GitHub stars

Defense-in-depth-Bundle für MCP-stdio-Server. Umschließt `child_process.exec/spawn`

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

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

Installation

npm 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

Paketinhalt und Wartung

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.

Was es Ihnen bietet

Drei Ebenen, stückweise optional:

  1. Bibliotheks-API — Drop-in guardExec / guardSpawn, die Sie aus Ihrem eigenen MCP-Server aufrufen. Default-Deny-Allowlist, Sandbox-Profile, Replay-Fenster.
  2. Audit-CLI — mcp-shellguard-audit scan <path> durchläuft den AST und meldet 12 Anti-Patterns von LOW (no timeout) bis CRITICAL (exec(\...${userInput}...`)`).
  3. Referenz-MCP-Server — mcp-stdio-shellguard-demo stellt 8 Tools bereit, sodass der MCP Inspector / Claude Desktop das Bündel direkt steuern kann.

Tools (Referenzserver)

ToolTypZweck
guard_execdestruktivAbgesichertes child_process.exec. Erzwingt args[]-Vektor, Allowlist + Sandbox + Replay. Gibt stdout, stderr, exitCode, canonicalHash, isReplay, trustTier zurück.
guard_spawndestruktivAbgesichertes child_process.spawn. Gibt SHA-256-Hashes von stdout/stderr statt vollständiger Inhalte zurück. Lehnt shell:true strikt ab.
register_allowlistmutierendRegistriert einen Tool-Namen mit Executable + Args-Regex. Ohne Registrierung gilt Default-Deny.
audit_sourceschreibgeschütztDurchsucht einen TS/JS-Pfad nach Shell-Injection-Anti-Patterns. Gibt AuditFinding[] + Zusammenfassung zurück.
audit_reportschreibgeschütztFormatiert ein Audit-Ergebnis als markdown / json / SARIF 2.1.0.
replay_checkschreibgeschütztBerechnet den kanonischen SHA-256-Hash für einen Aufruf und meldet, ob er bereits im Replay-Fenster liegt.
sandbox_statusschreibgeschütztMeldet aktives Sandbox-Profil + konkrete Limits + cgroup-v2-Aktiv-Flag.
trust_tierschreibgeschütztLeitet die Stufe LOW/MEDIUM/HIGH/CRITICAL für ein registriertes Tool ab, plus Verbesserungshinweise.

Sandbox-Profile

ProfilTimeoutMax. stdoutMax. stderrFD-Budgetcgroup-v2
strict5 s1 MB256 KB32ja (cpu/memory)
standard (Standard)30 s10 MB1 MB256ja
permissive5 min100 MB10 MB1024nein

Der Aufrufer kann pro Aufruf über timeoutMs / fdBudget verschärfen. Der Aufrufer kann nicht über das Profil hinaus erweitern.

Vertrauensstufen

StufeBedingung
LOWTool nicht registriert (Default-Deny)
MEDIUMregistriert, aber argsPatterns leer (beliebige Args erlaubt)
HIGHargsPatterns gesetzt, aber Sandbox oder Replay-Tracker inaktiv
CRITICALargsPatterns + Sandbox + Replay alle aktiv

Lift LOW → CRITICAL durch Registrieren des Tools + Setzen von argsPatterns + Ausführen über guardExec/guardSpawn (die immer Sandbox + Replay aktivieren).

Library-Schnellstart

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

Audit-CLI

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 vorhanden
  • 2 Parse-/IO-Fehler

Benutzerdefinierte 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.

Anti-Pattern-Bibliothek (12 Regeln)

Kategorien