studiomeyer-io/mcp-stdio-shellguard

# mcp-stdio-shellguard [](https://www.npmjs.com/package/mcp-stdio-shellguard) [](https://www.npmjs.com/package/mcp-stdio-shellguard)    MCP stdio 服务器的深度防御捆绑包。使用允许列表 + 沙箱 + 重放检测封装 `child_process.exec/spawn`，外加一个 AST 审计 CLI (`mcp-shellguard-audit`)，可扫描 MCP 服务器源代码中未经处理的 shell 调用。解决了 Ox-Security 披露的 MCP stdio-RCE 漏洞类别（20 万个脆弱服务器，2026 年 5 月披露）。 - **MCP 规范**: 2025-06-18 - **SDK**: `@modelcontextprotocol/sdk` ^1.29.0 - **Node**: >= 20 - **许可证**: MIT - **作者**: Matthias Meyer (StudioMeyer) ## 安装 ``` npm install mcp-stdio-shellguard ``` 或者无需安装直接运行审计 CLI： ``` npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src ``` ## 功能特性 三层防护，可按需逐层选择启用： 1. **库 API** — 可直接插入您自己的 MCP 服务器调用的 `guardExec` / `guardSpawn`。支持默认拒绝的允许列表、沙箱配置文件和重放窗口。 2. **审计 CLI** — `mcp-shellguard-audit scan ` 遍历 AST，报告从 LOW（`无超时`）到 CRITICAL（`exec(\`...${userInput}...\`)`）的 12 种反模式。 3. **参考 MCP 服务器** — `mcp-stdio-shellguard-demo` 暴露了 8 个工具，以便 MCP Inspector / Claude Desktop 可以直接驱动该捆绑包。 ## 工具 (参考服务器) | 工具 | 类型 | 用途 | |------|------|---------| | `guard_exec` | 破坏性 | 受防御的 `child_process.exec`。强制使用 args[] 向量、允许列表 + 沙箱 + 重放。返回 `stdout`、`stderr`、`exitCode`、`canonicalHash`、`isReplay`、`trustTier`。 | | `guard_spawn` | 破坏性 | 受防御的 `child_process.spawn`。返回 stdout/stderr 的 SHA-256 哈希值而非完整主体。硬性拒绝 `shell:true`。 | | `register_allowlist` | 修改性 | 注册一个工具名称及其可执行文件 + args 正则表达式。如果不注册，则应用默认拒绝规则。 | | `audit_source` | 只读 | 扫描 TS/JS 路径以查找 shell 注入反模式。返回 `AuditFinding[]` 及摘要。 | | `audit_report` | 只读 | 将审计结果格式化为 markdown / json / SARIF 2.1.0。 | | `replay_check` | 只读 | 计算调用的规范 SHA-256 哈希值，并报告它是否已处于重放窗口中。 | | `sandbox_status` | 只读 | 报告活动的沙箱配置文件 + 具体限制 + cgroup-v2 活动标志。 | | `trust_tier` | 只读 | 推断已注册工具的 LOW/MEDIUM/HIGH/CRITICAL 级别并提供改进提示。 | ## 沙箱配置文件 | 配置文件 | 超时时间 | 最大 stdout | 最大 stderr | FD 预算 | cgroup-v2 | |---------|---------|-----------|-----------|-----------|-----------| | `strict` | 5 秒 | 1 MB | 256 KB | 32 | 是 (CPU/内存) | | `standard` (默认) | 30 秒 | 10 MB | 1 MB | 256 | 是 | | `permissive` | 5 分钟 | 100 MB | 10 MB | 1024 | 否 | 调用方可以在每次调用时通过 `timeoutMs` / `fdBudget` 进行收紧。调用方不能扩展超出配置文件的范围。 ## 信任等级 | 等级 | 条件 | |------|-----------| | LOW | 工具未注册 (默认拒绝) | | MEDIUM | 已注册但 `argsPatterns` 为空 (允许任何参数) | | HIGH | 设置了 `argsPatterns`，但沙箱或重放跟踪器未激活 | | CRITICAL | argsPatterns + 沙箱 + 重放均已激活 | 通过注册工具 + 设置 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 条规则) | ID | 严重程度 | 触发条件 | |----|----------|-------------| | `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 | 没有 `maxBuffer` 的 exec | | `missing_timeout` | LOW | 没有 `timeout` 的 exec/spawn | ## 编译指示 - `// shellguard:ignore-next-line` — 抑制一个发现 - `// shellguard:ignore-file` — 抑制整个文件 (极少使用；建议按行抑制) ## 存在的原因 Ox-Security 披露 (2026-05) 有超过 20 万个 MCP stdio 服务器在使用带有直接来自 LLM 工具参数的用户输入的模板字符串来封装 `child_process.exec`。LiteLLM v1.83.6 就是典型的例子 (CVE 已在 1.83.7 版本中修补)。 本捆绑包是防御性安全的对应方案：一个即插即用的防护器和扫描器，从根本上解决了这一类问题。灵感来自 AWS Linux `seccomp` + Chromium 沙箱层。 ## 另请参见 - `HOOK_RECIPES.md` — Claude Code hook 配方，可自动拦截危险的工具调用 - `CHANGELOG.md` — 发布历史 - Ox-Security MCP 审计: - LiteLLM CVE-2026-XXXX: ## 许可证 MIT — 版权所有 (c) 2026 Matthias Meyer (StudioMeyer)

标签：AI安全, AST静态分析, Chat Copilot, CISA项目, CVE-2025-69256, GNU通用公共许可证, Go语言工具, LLM服务器安全, MCP协议, MITM代理, Node.js, npm包, stdio安全, TypeScript, 命令注入, 大模型安全, 安全审计CLI, 安全插件, 暗色界面, 模型上下文协议, 沙盒执行, 深度防御, 漏洞修复, 白名单, 网络安全, 网络安全培训, 自动化攻击, 进程执行控制, 远程代码执行(RCE), 隐私保护