جزء من حزمة StudioMeyer MCP — صُنعت في مايوركا 🌴 · ⭐ إذا كنت تستخدمها

mcp-stdio-shellguard

License Last commit

حزمة دفاع متعدد الطبقات لخوادم MCP stdio. تغلّف `child_process.exec/spawn` بقائمة سماح + صندوق رمل + كشف إعادة التشغيل، بالإضافة إلى واجهة سطر أوامر للتدقيق عبر AST (`mcp-shellguard-audit`) تفحص مصادر خوادم MCP بحثًا عن استدعاءات صدفة غير معقّمة. تسدّ فئة Ox-Security MCP stdio-RCE (200 ألف خادم معرّض للخطر، إفصاح مايو 2026).

مواصفة MCP: 2025-06-18
SDK: @modelcontextprotocol/sdk ^1.29.0
Node: >= 20
الترخيص: MIT
المؤلف: Matthias Meyer (StudioMeyer)

التثبيت

npm install mcp-stdio-shellguard

أو شغّل واجهة التدقيق مباشرة دون تثبيت:

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

ماذا يوفّر لك

ثلاث طبقات، تُفعَّل اختياريًا كلٌّ على حدة:

مكتبة برمجية — guardExec / guardSpawn جاهزة للاستبدال المباشر تستدعيها من خادم MCP الخاص بك. قائمة سماح ترفض افتراضيًا، ملفات تعريف صندوق رمل، نافذة إعادة تشغيل.
واجهة سطر أوامر للتدقيق — mcp-shellguard-audit scan <path> تجتاز AST وتبلّغ عن 12 نمطًا مضادًا تتراوح من LOW (بدون مهلة) حتى CRITICAL (exec(\...${userInput}...`)`).
خادم MCP مرجعي — mcp-stdio-shellguard-demo يعرض 8 أدوات بحيث يمكن لمفتّش MCP / Claude Desktop قيادة الحزمة مباشرة.

الأدوات (الخادم المرجعي)

الأداة	النوع	الغرض
`guard_exec`	مدمِّر	`child_process.exec` مُحصَّن. يفرض متجه args[]، قائمة سماح + صندوق رمل + إعادة تشغيل. يُرجع `stdout` و`stderr` و`exitCode` و`canonicalHash` و`isReplay` و`trustTier`.
`guard_spawn`	مدمِّر	`child_process.spawn` مُحصَّن. يُرجع تجزئات SHA-256 لـ stdout/stderr بدل النصوص الكاملة. يرفض `shell:true` رفضًا قاطعًا.
`register_allowlist`	مُعدِّل	تسجيل اسم أداة مع الملف التنفيذي + regex للوسائط. بدون تسجيل يُطبَّق الرفض الافتراضي.
`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	نعم (cpu/memory)
`standard` (افتراضي)	30 s	10 MB	1 MB	256	نعم
`permissive`	5 min	100 MB	10 MB	1024	لا

يمكن للمستدعي التضييق عبر timeoutMs / fdBudget لكل استدعاء. لا يمكن للمستدعي التوسيع بما يتجاوز ملف التعريف.

مستويات الثقة

المستوى	الشرط
LOW	الأداة غير مسجَّلة (رفض افتراضي)
MEDIUM	مسجَّلة لكن `argsPatterns` فارغة (أي وسائط مسموحة)
HIGH	`argsPatterns` مضبوطة لكن صندوق الرمل أو متتبِّع إعادة التشغيل غير نشط
CRITICAL	argsPatterns + صندوق الرمل + إعادة التشغيل جميعها نشطة

ارفع من LOW إلى CRITICAL بتسجيل الأداة + ضبط argsPatterns + التشغيل عبر guardExec/guardSpawn (اللذَين يفعّلان دائمًا صندوق الرمل وإعادة التشغيل).

بدء سريع مع المكتبة

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

رموز الخروج:

0 نظيف (لا توجد نتائج عند الحد الأدنى أو فوقه)
1 توجد نتائج
2 أخطاء تحليل / إدخال-إخراج

مكتبة الأنماط المضادة (12 قاعدة)

المعرّف	الخطورة	يُفعَّل عند
`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 بدون `maxBuffer`
`missing_timeout`	LOW	exec/spawn بدون `timeout`

يحلّ الماسح روابط 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: "/bin/sh" }) أو قيمة صدفة ديناميكية — وليس فقط حرفي { shell: true }. تبقى promisify لدالة ليست من child_process، وتفكيك من وحدة أخرى، و{ shell: false } نظيفة (بدون نتائج إيجابية خاطئة).

التوجيهات (Pragmas)

// shellguard:ignore-next-line — كتم نتيجة واحدة
// shellguard:ignore-file — كتم الملف بالكامل (نادر؛ يُفضَّل لكل سطر)

لماذا يوجد هذا

أفصحت Ox-Security (2026-05) عن أن أكثر من 200 ألف خادم MCP stdio يغلّفون child_process.exec بسلاسل قالب تحمل مدخلات مستخدم مباشرة من وسائط أدوات LLM. كان LiteLLM v1.83.6 المثال المعياري (تم تصحيح CVE في 1.83.7). هذه الحزمة هي النظير الأمني الدفاعي: حارس جاهز للاستبدال + ماسح يسدّ هذه الفئة. مستوحاة من مستويات seccomp في AWS Linux + صندوق رمل 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

الترخيص

اقرأ المزيد

mcp-stdio-shellguard v0.1.2

الفئات