** StudioMeyer MCP Stack 的一部分** — 在马略卡岛构建 🌴 · 如果使用请⭐

mcp-stdio-shellguard

针对 MCP stdio 服务器的深度防御捆绑包。使用白名单 + 沙箱 + 重放检测包装 child_process.exec/spawn，外加一个 AST 审计 CLI (mcp-shellguard-audit)，用于扫描 MCP 服务器源中未清理的 shell 调用。封堵了 Ox-Security MCP stdio-RCE 漏洞类别（200k 台易受攻击服务器，2026 年 5 月披露）。

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

安装

npm install mcp-stdio-shellguard

或者直接运行审计 CLI 而无需安装：

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

它为您提供了什么

三个层次，可逐层选择使用：

1. 库 API — 可直接使用的 guardExec / guardSpawn，您可以从自己的 MCP 服务器中调用。默认拒绝白名单、沙箱配置文件、重放窗口。
2. 审计 CLI — mcp-shellguard-audit scan <path> 遍历 AST，报告 12 种反模式，从 LOW（no timeout）到 CRITICAL（exec(\...${userInput}...`)`）。
3. 参考 MCP 服务器 — mcp-stdio-shellguard-demo 公开了 8 个工具，以便 MCP Inspector / Claude Desktop 可以直接驱动这个捆绑包。

工具（参考服务器）

沙箱配置文件

调用者可以通过每次调用的 timeoutMs / fdBudget 来收紧。调用者不能放宽超出配置文件的限制。

信任等级

通过注册工具 + 设置 argsPatterns + 通过 guardExec/guardSpawn 运行（始终激活沙箱 + 重放）来将 LOW 提升为 CRITICAL。

库快速入门

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

审计 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

退出代码：

• 0 干净（找不到达到或高于下限的问题）
• 1 存在问题
• 2 解析 / IO 错误

反模式库（12 条规则）

扫描器在匹配前解析了重命名的 child_process 绑定，因此即使调用通过别名而非字面量的 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(...)

同步变体（spawnSync、execFileSync）共享其异步规则，并且 shell_true_option 也会在字符串 shell（{ shell: "/bin/sh" }）或动态 shell 值上触发——而不仅仅是字面量 { shell: true }。对非 child_process 函数的 promisify、从其他模块解构、以及 { shell: false } 保持干净（无误报）。

编译指示

• // shellguard:ignore-next-line — 抑制一条结果
• // shellguard:ignore-file — 抑制整个文件（很少使用；建议逐行抑制）

为什么存在

Ox-Security 披露（2026 年 5 月）超过 20 万个 MCP stdio 服务器将 child_process.exec 与包含直接来自 LLM 工具参数的用户输入的模板字面量包装在一起。LiteLLM v1.83.6 是典型示例（CVE 在 1.83.7 中修补）。此捆绑包是防御安全对应物：一个可直接使用的防护 + 扫描器，封堵了该漏洞类别。灵感来自 AWS Linux seccomp + Chromium 沙箱等级。

另请参阅

• HOOK_RECIPES.md — Claude Code 钩子配方，自动阻止危险工具调用
• CHANGELOG.md — 发布历史
• Ox-Security MCP audit: https://venturebeat.com/security/200000-mcp-stdio-servers/
• LiteLLM CVE-2026-XXXX: https://github.com/BerriAI/litellm/security/advisories

许可证

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