حزمة دفاع متعدد الطبقات لخوادم MCP stdio: أغلفة guardExec/guardSpawn جاهزة للتبديل المباشر (drop-in)، وأداة CLI لتدقيق AST، وخادم MCP مرجعي. تسد فئة ثغرة stdio-RCE الخاصة بـ Ox-Security التي تمس 200 ألف خادم (LiteLLM CVE-2025-69256). MIT، TypeScript، Node >= 20.
جزء من StudioMeyer MCP Stack — صُنع في مايوركا 🌴 · ⭐ إذا استخدمته
بقائمة سماح + صندوق رمل + كشف إعادة التشغيل، إضافةً إلى أداة تدقيق AST عبر سطر الأوامر (mcp-shellguard-audit)
تفحص مصادر خادم MCP بحثًا عن استدعاءات shell غير المعقَّمة. تُغلق فئة Ox-Security
MCP stdio-RCE (200 ألف خادم معرَّض للخطر، إفصاح مايو 2026).
@modelcontextprotocol/sdk ^1.29.0npm install mcp-stdio-shellguard
أو شغّل واجهة سطر أوامر التدقيق مباشرةً دون تثبيت:
npx -y -p mcp-stdio-shellguard mcp-shellguard-audit scan ./src
يتضمن الإصدار 0.1.3 حزمة التبعيات الموضحة أدناه.
تشحن الحزمة @typescript-eslint/typescript-estree بالإضافة إلى TypeScript وإغلاق تبعيات المحلل المطلوبة عبر bundledDependencies. لا يقيّد تجاوز npm على مستوى الجذر شجرة تبعيات الحزمة المثبّتة؛ بل يحمل الإغلاق المضمّن الإصدارات المفحوصة إلى المستهلكين. تتحقق عملية تحضير الحزمة من @typescript-eslint/typescript-estree 8.72.1 وminimatch 11.0.3، ثم تغيّر فقط نطاق تبعية بيان المحلل من minimatch ^10.2.2 إلى ^11.0.3. تبقى ملفات المصدر الخاصة بالجهات الخارجية وأرقام إصدارات الحزم دون تغيير. يستدعي تدقيق AST الدالة typescript-estree.parse مباشرةً، مع تضمين TypeScript صراحةً لتلبية شجرة تبعيات المحلل؛ ولا حاجة إلى بيئة تشغيل ESLint.
يبلغ حجم الأرشيف المقاس حوالي 4.92 ميغابايت مضغوطًا و26.04 ميغابايت غير مضغوط (بالميغابايت العشري). يزيد التضمين من التنزيل واستخدام القرص؛ ويتطلب تحديث أمني لأحد التبعيات المضمّنة أرشيف حزمة محدّثًا.
للصيانة، شغّل npm ci وnpm run test:consumer من نسخة المستودع المحلية. يشغّل npm pack الأمر prepack تلقائيًا: إذ يبني الحزمة ويحضّر الحزمة المعلنة. يفحص فحص المستهلك الحزمة مرتين، ويتحقق من تطابق البايتات، ويثبّت الأرشيف الفعلي في مشروع جديد، ويفحص npm ls وكلا تدقيقي التبعيات، ويجرّب واجهة سطر الأوامر أو بيئة التشغيل المثبّتة. راجع تحديثات التبعيات مع الحزمة المقفلة وإثباتات الترخيص قبل توزيع أرشيف جديد. يسجّل الملف dist/bundled-dependencies.json داخل الأرشيف الحزمة وتعديلات البيان.
ثلاث طبقات، اختيارية بشكل تدريجي:
guardExec / guardSpawn جاهزة للاستخدام تستدعيها من
خادم MCP الخاص بك. قائمة سماح بالرفض الافتراضي، وملفات تعريف العزل، ونافذة إعادة التشغيل.mcp-shellguard-audit scan <path> يتجول في AST، ويبلّغ
عن 12 نمطًا مضادًا من LOW (no timeout) إلى CRITICAL (exec(\...${userInput}...`)`).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 محمية. تعيد تجزئات SHA-256 لـ stdout/stderr بدلًا من المحتوى الكامل. ترفض 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 ثوانٍ | 1 ميغابايت | 256 كيلوبايت | 32 | نعم (cpu/memory) |
standard (افتراضي) | 30 ثانية | 10 ميغابايت | 1 ميغابايت | 256 | نعم |
permissive | 5 دقائق | 100 ميغابايت | 10 ميغابايت | 1024 | لا |
يمكن للمستدعي التشديد عبر timeoutMs / fdBudget لكل استدعاء. لا يمكن للمستدعي التوسيع
بما يتجاوز الملف التعريفي.
| الفئة | الشرط |
|---|---|
| LOW | الأداة غير مسجّلة (الرفض الافتراضي) |
| MEDIUM | مسجّلة لكن argsPatterns فارغة (أي وسائط مسموحة) |
| HIGH | argsPatterns محددة لكن العزل أو متتبع إعادة التشغيل غير نشط |
| CRITICAL | argsPatterns + العزل + إعادة التشغيل كلها نشطة |
رفع من LOW ← CRITICAL عبر تسجيل الأداة + تعيين argsPatterns + التشغيل
عبر guardExec/guardSpawn (التي تُفعّل دائمًا 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
رموز الخروج:
0 نظيف (لا توجد نتائج عند الحد الأدنى أو أعلى)1 توجد نتائج2 أخطاء تحليل / إدخال وإخراجتقبل ignoreGlobs المخصصة التي تُمرَّر إلى scanPath أو أداة MCP audit_source
128 سلسلة نصية كحد أقصى. كل سلسلة محدودة بـ 1024 وحدة رمز UTF-16 و16
حرف تجميع افتتاحي غير مُهرَّب ((, {, [). المدخلات التي تتجاوز هذه
الميزانيات تُطلق خطأً مُتحكَّمًا به قبل المطابقة.
| المعرّف | الخطورة | يُفعَّل عند |
|---|---|---|
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 |