Stdio Shellguard

StudioMeyer MCP Stack の一部 — マヨルカ島で開発 🌴 · ご利用の際は ⭐ を付けてください

mcp-stdio-shellguard

MCP stdio サーバー向けの多層防御バンドルです。child_process.exec/spawn を許可リスト、サンドボックス、リプレイ検出でラップし、MCP サーバーのソース内にサニタイズされていないシェル呼び出しがないかをスキャンする AST 監査 CLI（mcp-shellguard-audit）も備えています。Ox-Security が開示した MCP stdio-RCE の脆弱性クラス（脆弱なサーバー 20 万件、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

提供する機能

必要なものを個別に選べる、オプトイン方式の 3 層構成です。

1. ライブラリ API — 独自の MCP サーバーから呼び出せる、ドロップインの guardExec / guardSpawn です。デフォルト拒否の許可リスト、サンドボックスプロファイル、リプレイウィンドウを備えています。
2. 監査 CLI — mcp-shellguard-audit scan <path> は AST を走査し、重大度 LOW（no timeout）から 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	変更可能	ツール名を実行ファイルおよび引数の正規表現とともに登録します。登録しない場合は、デフォルト拒否が適用されます。
audit_source	読み取り専用	TS/JS パスをスキャンし、シェルインジェクションのアンチパターンを検出します。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 s	1 MB	256 KB	32	yes (cpu/memory)
standard（デフォルト）	30 s	10 MB	1 MB	256	yes
permissive	5 min	100 MB	10 MB	1024	no

呼び出しごとに 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 エラー

scanPath または audit_source MCP ツールに渡すカスタム ignoreGlobs は、 最大 128 個の文字列を受け付けます。各文字列は、1024 UTF-16 コード単位、 エスケープされていない開きグループ文字（(、{、[）16 個までに制限されます。 これらの上限を超える入力は、マッチングの前に制御されたエラーを発生させます。

アンチパターンライブラリ（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

スキャナーはマッチングの前に、名前が変更された 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: true } だけでなく、 文字列のシェル（{ shell: "/bin/sh" }）や動的なシェル値でも検出されます。 child_process 以外の関数に対する promisify、別のモジュールからの 分割代入、{ shell: false } は問題なしと判定されます（誤検出なし）。

プラグマ

• // shellguard:ignore-next-line — 検出結果を 1 件抑制します
• // 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 フックのレシピ
• CHANGELOG.md — リリース履歴
• Ox-Security の MCP 監査：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)