vm2 [![NPM Version][npm-image]][npm-url] [![NPM Downloads][downloads-image]][downloads-url] [![License][license-image]][license-url] [![Known Vulnerabilities][snyk-image]][snyk-url]

vm2 هو صندوق رمل يمكنه تشغيل كود غير موثوق به مع وحدات Node.js المدمجة المدرجة في القائمة البيضاء.

التثبيت```sh

npm install vm2

## أمثلة سريعة```js
import { VM } from 'vm2';

const vm = new VM();
vm.run(`process.exit()`); // TypeError: process.exit is not a function

بعد اكتمال التثبيت، يمكنك التحقق من التثبيت عن طريق تشغيل الأمر التالي:

toolname --version

يجب أن يظهر إصدار الأداة في الإخراج. إذا واجهت أي أخطاء، تأكد من تثبيت جميع المتطلبات الأساسية بشكل صحيح.

الاستخدام

لاستخدام الأداة، اتبع الخطوات التالية:

1. افتح الطرفية (Terminal) أو موجه الأوامر (Command Prompt).
2. انتقل إلى الدليل الذي تم تثبيت الأداة فيه.
3. قم بتشغيل الأمر التالي:

toolname [options] <target>

الخيارات المتاحة

الخيار	الوصف
-h, --help	عرض رسالة المساعدة والخروج
-v, --verbose	تفعيل وضع الإخراج المفصل
-o, --output <file>	حفظ النتائج في ملف محدد
-t, --timeout <seconds>	تعيين مهلة زمنية للطلبات (الافتراضي: 30)

أمثلة

فيما يلي بعض الأمثلة على الاستخدام الشائع:

# فحص هدف أساسي
toolname https://example.com

# فحص مع إخراج مفصل
toolname -v https://example.com

# حفظ النتائج في ملف
toolname -o results.txt https://example.com

استكشاف الأخطاء وإصلاحها

إذا واجهت مشاكل أثناء استخدام الأداة، راجع الأقسام التالية:

خطأ: "Permission denied"

يحدث هذا الخطأ عادةً عندما لا تملك صلاحيات كافية لتنفيذ الأداة. حاول تشغيل الأمر مع sudo على أنظمة Linux أو macOS:

sudo toolname https://example.com

خطأ: "Module not found"

تأكد من تثبيت جميع التبعيات المطلوبة. يمكنك إعادة تثبيتها باستخدام:

pip install -r requirements.txt

خطأ: "Connection timeout"

قد يكون الهدف غير متاح أو أن الشبكة بطيئة. حاول زيادة المهلة الزمنية باستخدام الخيار -t:

toolname -t 60 https://example.com

المساهمة

نرحب بالمساهمات من المجتمع! إذا كنت ترغب في المساهمة في تطوير هذه الأداة، يرجى اتباع الخطوات التالية:

1. قم بعمل Fork للمستودع.
2. أنشئ فرعًا جديدًا لميزتك أو إصلاحك.
3. قم بإجراء التغييرات اللازمة.
4. تأكد من اجتياز جميع الاختبارات.
5. أرسل طلب سحب (Pull Request) مع وصف واضح للتغييرات.

الترخيص

هذه الأداة مرخصة بموجب رخصة MIT. راجع ملف LICENSE للحصول على التفاصيل الكاملة.

الإخلاء القانوني

هذه الأداة مخصصة للأغراض التعليمية والاختبارات الأمنية المشروعة فقط. لا يجوز استخدامها لأي أنشطة غير قانونية أو ضارة. المستخدم مسؤول بالكامل عن أي استخدام غير مناسب لهذه الأداة.```js import { NodeVM } from 'vm2';

const vm = new NodeVM({ require: { external: true, root: './', }, });

vm.run( var request = require('request'); request('http://www.google.com', function (error, response, body) { console.error(error); if (!error && response.statusCode == 200) { console.log(body); // Show the HTML for the Google homepage. } });, 'vm.js', );

## إخلاء مسؤولية أمني مهم

**قبل استخدام vm2، يجب أن تفهم كيف يعمل وقيوده.**

يحاول vm2 عزل كود JavaScript غير الموثوق **داخل نفس عملية Node.js** الخاصة بتطبيقك. يفعل ذلك من خلال شبكة معقدة من [الوكلاء (Proxies)](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) التي تعترض وتتوسط كل تفاعل بين بيئة العزل وبيئة المضيف.

### التحدي الأساسي

JavaScript لغة ديناميكية بشكل استثنائي. يمكن الوصول إلى الكائنات من خلال سلاسل النماذج الأولية (prototype chains)، ويمكن الوصول إلى المُنشئات عبر كائنات الأخطاء، وتوفر الرموز (symbols) خطافات بروتوكول، وينشئ التنفيذ غير المتزامن نوافذ توقيت. العدد الهائل من الطرق للتنقل من كائن إلى آخر في JavaScript يجعل بناء عزل آمن داخل العملية أمرًا صعبًا للغاية.

**نحن صادقون بشأن هذه الحقيقة:** على الرغم من جهودنا القصوى، يكتشف الباحثون ومتخصصو الأمن باستمرار طرقًا جديدة للهروب من عزل vm2. نقوم بنشط هذه الثغرات الأمنية فور الإبلاغ عنها، لكن طبيعة لعبة القط والفأر في العزل داخل العملية تعني أن:

1. **من المرجح اكتشاف تجاوزات جديدة في المستقبل.** تحقق من [التنبيهات الأمنية](https://github.com/patriksimek/vm2/security/advisories) الخاصة بنا للثغرات المعروفة.
2. **يجب عليك إبقاء vm2 محدثًا** للاستفادة من أحدث الإصلاحات الأمنية. اشترك في التنبيهات الأمنية وحدّث فورًا.
3. **لا ينبغي أن يكون vm2 خط دفاعك الوحيد.** الدفاع المتعمق (Defense in depth) ضروري عند تشغيل كود غير موثوق.

### بدائل أكثر قوة

إذا كنت بحاجة إلى ضمانات عزل أقوى، ففكر في هذه البدائل التي توفر **عزلًا حقيقيًا على مستوى العملية أو مستوى الأجهزة**:

| الحل | النهج | الأداء | المقايضات |
|----------|----------|-------------|------------|
| **[isolated-vm](https://github.com/laverdet/isolated-vm)** | عوازل V8 منفصلة (كومة V8 مختلفة) | سريع | في وضع الصيانة؛ يتطلب تحديثات V8 يدوية |
| **عملية منفصلة / Worker** | `child_process` أو Worker threads بصلاحيات محدودة | متوسط | حمل IPC أعلى؛ يجب تسلسل البيانات |
| **الحاويات / الأجهزة الافتراضية** | Docker، gVisor، Firecracker | بطيء | حمل بدء التشغيل؛ كثيف الموارد |
| **الخدمات المُدارة** | تنفيذ الكود المستند إلى السحابة (مثل AWS Lambda، Cloudflare Workers) | متغير | زمن استجابة الشبكة؛ اعتماد خارجي |

### متى قد يظل vm2 مناسبًا

يمكن أن يكون vm2 مناسبًا عندما:
- تحتاج إلى تكامل وثيق مع كائنات المضيف وتواصل متزامن سريع
- يأتي الكود غير الموثوق من مصدر موثوق نسبيًا (مثل الأدوات الداخلية، أنظمة الإضافات مع مؤلفين معتمدين)
- تجمع بين vm2 وطبقات أمنية أخرى (عزل الشبكة، قيود نظام الملفات، حدود الموارد)
- تقبل المخاطر وتراقب بنشاط التحديثات الأمنية

**إذا كنت تشغّل كودًا من مصادر غير موثوقة تمامًا (مثل إرسالات المستخدمين العشوائية)، فنوصي بشدة باستخدام حل بضمانات عزل أقوى.**

## بيئات التشغيل (Runtimes)

| بيئة التشغيل | الحالة |
|---------|--------|
| Node.js | مدعومة. بيئة العزل هي حدود أمنية. |
| Bun | **تجريبي.** توافق وظيفي جزئي — **ليست** حدودًا أمنية. |

ينطبق قيدان منفصلان على Bun، ولا يعني أحدهما الآخر.

**إنها ليست حدودًا أمنية.** نموذج التهديد الخاص بـ vm2، وكتالوج الهجمات في
[`docs/ATTACKS.md`](https://github.com/patriksimek/vm2/blob/main/docs/ATTACKS.md)، وكل اختبار انحدار في `test/ghsa/`
مشتقة من دواخل V8. JavaScriptCore، الذي يستخدمه Bun، له
ما يعادله الخاص، ولم يتم تدقيق أي منها مقابل جسر vm2. نجاح المجموعة
تحت Bun يُظهر التوافق، وليس أن العزل يصمد هناك. **لا
تستخدم vm2 على Bun لعزل كود غير موثوق.**

**التوافق جزئي، وليس تكافؤًا.** تشغيل Bun الأخضر يغطي فقط الاختبارات
التي تُنفَّذ فعليًا هناك. يسرد `test/bun-skips.js` ما هو مستبعد ولماذا،
وتشمل الفجوات السلوكية المعروفة ما يلي:

- `Buffer.from(arrayLike)` يُرجع مخزنًا مؤقتًا بطول صفري
- بيانات `VMScript` الوصفية `filename` / `lineOffset` / `columnOffset` غير
  قابلة للملاحظة، لأن كائنات CallSite الخاصة بـ JSC لا تحمل أي طرق
- `Object.freeze` على كائن مضيف مجمّد مع مُوصِّل غير قابل للتهيئة
  يرمي خطأ `TypeError` بانتهاك قيد الوكيل حيث لا يفعل V8 ذلك
- بعض عمليات `Buffer` عبر حدود بيئة العزل أبطأ بشكل كبير —
  يستغرق `allocUnsafe` بحجم 64 ميجابايت أكثر من 400 ثانية مقابل 1.7 على Node، بطيء بما يكفي
  ليُقرأ كتعليق

تعامل مع دعم Bun كتوافق بأفضل جهد ممكن للكود الموثوق، وتحقق من
قائمة التخطي قبل الاعتماد على أي سلوك معين.

## الميزات

-   تشغيل كود غير موثوق بأمان في عملية واحدة مع كودك جنبًا إلى جنب
-   تحكم كامل في مخرجات وحدة التحكم الخاصة ببيئة العزل
-   تتمتع بيئة العزل بوصول محدود إلى طرق العملية
-   من الممكن استدعاء الوحدات (المدمجة والخارجية) من بيئة العزل
-   يمكنك تقييد الوصول إلى وحدات مدمجة معينة (أو كلها)
-   يمكنك استدعاء الطرق وتبادل البيانات والاستدعاءات الرجعية (callbacks) بين بيئات العزل بأمان
-   صيانة نشطة مع تصحيحات لطرق الهروب المعروفة (انظر [إخلاء المسؤولية الأمني](#important-security-disclaimer))
-   دعم المُحوِّل (Transpiler)

## كيف يعمل