Defense-in-depth bundle for MCP stdio servers: drop-in guardExec/guardSpawn wrappers, AST audit CLI, reference MCP server. Closes the Ox-Security 200k-server stdio-RCE class (LiteLLM CVE-2025-69256). MIT, TypeScript, Node >= 20.
Part of the StudioMeyer MCP Stack — Built in Mallorca 🌴 · ⭐ if you use it
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).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
Or run the audit CLI directly without installing:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
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.
Three layers, opt-in piecewise:
guardExec / guardSpawn you call from your
own MCP server. Default-deny allowlist, sandbox profiles, replay window.mcp-shellguard-audit scan <path> walks the AST, reports
12 anti-patterns from LOW (no timeout) to CRITICAL (exec(\...${userInput}...`)`).mcp-stdio-shellguard-demo exposes 8 tools
so the MCP Inspector / Claude Desktop can drive the bundle directly.| Tool | Type | Purpose |
|---|---|---|
guard_exec | destructive | Defended child_process.exec. Forces args[] vector, allowlist + sandbox + replay. Returns stdout, stderr, exitCode, canonicalHash, isReplay, trustTier. |
guard_spawn | destructive | Defended child_process.spawn. Returns SHA-256 hashes of stdout/stderr instead of full bodies. Hard-rejects shell:true. |
register_allowlist | mutating | Register a tool name with executable + args regex. Without registration the default-deny applies. |
audit_source | read-only | Scan a TS/JS path for shell-injection anti-patterns. Returns AuditFinding[] + summary. |
audit_report | read-only | Format an audit result as markdown / json / SARIF 2.1.0. |
replay_check | read-only | Compute canonical SHA-256 hash for an invocation and report whether it's already in the replay window. |
sandbox_status | read-only | Report active sandbox profile + concrete limits + cgroup-v2 active flag. |
trust_tier | read-only | Derive LOW/MEDIUM/HIGH/CRITICAL tier for a registered tool plus improvement hints. |
| Profile | Timeout | Max stdout | Max stderr | FD budget | cgroup-v2 |
|---|---|---|---|---|---|
strict | 5 s | 1 MB | 256 KB | 32 | yes (cpu/memory) |
standard (default) | 30 s | 10 MB | 1 MB | 256 | yes |
permissive | 5 min | 100 MB | 10 MB | 1024 | no |
Caller can tighten via timeoutMs / fdBudget per call. Caller cannot widen
beyond the profile.
| Tier | Condition |
|---|---|
| LOW | tool not registered (default-deny) |
| MEDIUM | registered but argsPatterns empty (any args allowed) |
| HIGH | argsPatterns set but sandbox or replay tracker inactive |
| CRITICAL | argsPatterns + sandbox + replay all active |
Lift LOW → CRITICAL by registering the tool + setting argsPatterns + running
through guardExec/guardSpawn (which always activate 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
Exit codes:
0 clean (no findings at-or-above floor)1 findings present2 parse / IO errorsCustom 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.
| ID | Severity | Triggers on |
|---|---|---|
exec_template_literal_with_input | CRITICAL | child_process.exec(\ls ${x}`)` |
exec_dynamic_string | CRITICAL | child_process.exec(cmd) |
exec_sync_dynamic_string | CRITICAL | child_process.execSync(cmd) |
eval_near_child_process | CRITICAL | eval(...) |
function_constructor_near_child_process | CRITICAL | new Function(...) |
spawn_dynamic_file_args | HIGH | spawn(bin, userArgs) |
exec_file_dynamic | HIGH | execFile(bin, ...) |
shell_true_option | HIGH | { shell: true } |
os_system_equivalent | HIGH | Deno.run / Bun.spawn |
spawn_literal_dynamic_args | MEDIUM | spawn('git', userArgs) |
unbounded_buffer | LOW | exec without maxBuffer |
missing_timeout | LOW | exec/spawn without timeout |