MCP stdio ShellGuard

Part of the [StudioMeyer MCP Stack](https://studiomeyer.io) — Built in Mallorca 🌴 · ⭐ if you use it

mcp-stdio-shellguard

Defense-in-depth bundle for MCP stdio servers. Wraps child_process.exec/spawn with allowlist + sandbox + replay-detection, plus an AST audit CLI (mcp-shellguard-audit) that scans MCP server sources for unsanitized shell calls. Closes the Ox-Security MCP stdio-RCE class (200k vulnerable servers, May 2026 disclosure).

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

Install

npm install mcp-stdio-shellguard

Or run the audit CLI directly without installing:

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

Package contents and maintenance

Version 0.1.3 includes the dependency bundle described below.

The package ships @typescript-eslint/typescript-estree plus TypeScript and the required parser dependency closure through bundledDependencies. A root-only npm override does not constrain an installed package's dependency tree; the included closure carries the checked versions to consumers. The bundle preparation checks @typescript-eslint/typescript-estree 8.72.1 and minimatch 11.0.3, then changes only the parser manifest dependency range from minimatch ^10.2.2 to ^11.0.3. Third-party source files and package version numbers are unchanged. The AST audit calls typescript-estree.parse directly, with TypeScript included explicitly to satisfy the parser dependency tree; no ESLint runtime is required.

The measured archive is approximately 4.92 MB compressed and 26.04 MB unpacked (decimal MB). Bundling increases download and disk use; a security update to an included dependency requires an updated package archive.

For maintenance, run npm ci and npm run test:consumer from the repository checkout. npm pack runs prepack automatically: it builds the package and prepares the declared bundle. The consumer check packs twice, verifies identical bytes, installs the actual archive in a fresh project, checks npm ls and both dependency audits, and exercises the installed CLI or runtime. Review dependency updates together with the locked bundle and license proofs before distributing a new archive. The archive's dist/bundled-dependencies.json records the bundle and manifest adjustments.

What it gives you

Three layers, opt-in piecewise:

1. Library API — drop-in guardExec / guardSpawn you call from your own MCP server. Default-deny allowlist, sandbox profiles, replay window.
2. Audit CLI — mcp-shellguard-audit scan walks the AST, reports 12 anti-patterns from LOW (no timeout) to CRITICAL (exec(\...${userInput}...\)).
3. Reference MCP server — mcp-stdio-shellguard-demo exposes 8 tools so the MCP Inspector / Claude Desktop can drive the bundle directly.

Tools (reference server)

Sandbox profiles

Caller can tighten via timeoutMs / fdBudget per call. Caller cannot widen beyond the profile.

Trust tiers

Lift LOW → CRITICAL by registering the tool + setting argsPatterns + running through guardExec/guardSpawn (which always activate sandbox + replay).

Library quickstart

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 clean (no findings at-or-above floor)
• 1 findings present
• 2 parse / IO errors

Custom ignoreGlobs passed to scanPath or the audit_source MCP tool accept at most 128 strings. Each string is limited to 1024 UTF-16 code units and 16 unescaped opening grouping characters ((, {, [). Inputs above these budgets raise a controlled error before matching.

Anti-pattern library (12 rules)

The scanner resolves *renamed* child_process bindings before matching, so the dangerous shapes below are caught even when the call goes through an alias rather than a literal 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(...)

Synchronous variants (spawnSync, execFileSync) share their async rules, and shell_true_option also fires on a string shell ({ shell: "/bin/sh" }) or a dynamic shell value — not just the literal { shell: true }. A promisify of a non-child_process function, a destructure off another module, and { shell: false } stay clean (no false positives).

Pragmas

• // shellguard:ignore-next-line — suppress one finding
• // shellguard:ignore-file — suppress whole file (rare; prefer per-line)

Why this exists

Ox-Security disclosed (2026-05) that 200k+ MCP stdio servers wrap child_process.exec with template literals carrying user input straight from LLM tool args. LiteLLM v1.83.6 was the canonical example (CVE patched in 1.83.7). This bundle is the defensive-security counterpart: a drop-in guard + scanner that closes the class. Inspired by AWS Linux seccomp + Chromium sandbox tiers.

See also

• HOOK_RECIPES.md — Claude Code hook recipes that auto-block dangerous tool calls
• CHANGELOG.md — release history
• Ox-Security MCP audit: https://venturebeat.com/security/200000-mcp-stdio-servers/
• LiteLLM CVE-2026-XXXX: https://github.com/BerriAI/litellm/security/advisories

License

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

Bundled dependencies retain their complete upstream license texts in the archive. The package license applies to this project's own code; bundled third-party packages retain their respective terms. The consumer check verifies each approved package version's full license file, or its complete README license section, against pinned content hashes from integrity-verified official npm artifacts. Whitespace and line-ending differences are accepted; missing, empty or partial legal text is rejected.