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

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

toolname --version

toolname [options] <target>

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

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

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

sudo toolname https://example.com

pip install -r requirements.txt

toolname -t 60 https://example.com

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

**قبل استخدام 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)

## كيف يعمل

-   يستخدم وحدة VM الداخلية لإنشاء سياق آمن.
-   يستخدم [الوكلاء (Proxies)](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Proxy) لمنع الهروب من بيئة العزل.
-   يتجاوز دالة require المدمجة للتحكم في الوصول إلى الوحدات.

للحصول على نظرة متعمقة على دواخل vm2، انظر [docs/ATTACKS.md](https://github.com/patriksimek/vm2/blob/main/docs/ATTACKS.md).

## ما الفرق بين vm الخاصة بـ Node وvm2؟

جرّبها بنفسك:```js
import { runInNewContext } from "node:vm";

runInNewContext('this.constructor.constructor("return process")().exit()');
console.log('Never gets executed.');

toolname --help

git clone https://github.com/example/toolname.git
cd toolname
pip install -r requirements.txt
python setup.py install

toolname scan --target example.com

toolname scan --target example.com --verbose --output report.json

toolname subdomain --target example.com --wordlist subdomains.txt

toolname portscan --target 192.168.1.1 --ports 1-1000

toolname vuln --target example.com --severity high

pip install --upgrade pip

## التوثيق

-   [VM](#vm)
-   [NodeVM](#nodevm)
-   [VMScript](#vmscript)
-   [معالجة الأخطاء](#error-handling)
-   [تصحيح أخطاء الكود المعزول](#debugging-a-sandboxed-code)
-   [الكائنات للقراءة فقط](#read-only-objects-experimental)
-   [الكائنات المحمية](#protected-objects-experimental)
-   [العلاقات بين العزلات](#cross-sandbox-relationships)
-   [واجهة سطر الأوامر](#cli)
-   [تغييرات 2.x إلى 3.x](https://github.com/patriksimek/vm2/wiki/2.x-to-3.x-changes)
-   [توثيق 1.x و 2.x](https://github.com/patriksimek/vm2/wiki/1.x-and-2.x-docs)
-   [المساهمة](https://github.com/patriksimek/vm2/wiki/Contributing)

## VM

VM هو عزل بسيط لتشغيل الكود غير الموثوق بشكل متزامن دون ميزة `require`. تتوفر فقط كائنات JavaScript المدمجة و`Buffer` الخاصة بـ Node. دوال الجدولة (`setInterval`, `setTimeout` و `setImmediate`) غير متوفرة افتراضيًا.

**الخيارات:**

-   `timeout` - مهلة البرنامج النصي بالمللي ثانية. **تحذير**: قد ترغب في استخدام هذا الخيار مع `allowAsync=false`. علاوة على ذلك، فإن التعامل مع الكائنات المُعادة من العزل يمكن أن يشغّل كودًا عشوائيًا ويتجاوز المهلة. يجب على المرء اختبار ما إذا كان الكائن المُعاد بدائيًا باستخدام `typeof` والتخلص منه تمامًا (قد يؤدي تسجيل الدخول أو إنشاء رسائل خطأ باستخدام مثل هذا الكائن أيضًا إلى تشغيل كود عشوائي مرة أخرى) في الحالة الأخرى.
-   `sandbox` - الكائن العام لـ VM.
-   `compiler` - `javascript` (الافتراضي)، `typescript`، `coffeescript` أو دالة مترجم مخصصة. تتوقع المكتبة أن يكون لديك المترجم مثبتًا مسبقًا إذا تم تعيين القيمة على `typescript` أو `coffeescript`. **يتطلب `typescript` إصدار `typescript@6` أو أحدث** — انظر [المترجمون](#compilers).
-   `eval` - إذا تم تعيينه على `false`، فإن أي استدعاءات لـ `eval` أو منشئات الدوال (`Function`, `GeneratorFunction`, إلخ) ستُطلق `EvalError` (الافتراضي: `true`).
-   `wasm` - إذا تم تعيينه على `false`، فإن أي محاولة لتجميع وحدة WebAssembly ستُطلق `WebAssembly.CompileError` (الافتراضي: `true`). ملاحظة: تتم إزالة `WebAssembly.JSTag` داخل العزل لأسباب أمنية، لذا لا يمكن لكود wasm التقاط استثناءات JavaScript.
-   `allowAsync` - إذا تم تعيينه على `false`، فإن أي محاولة لتشغيل كود باستخدام `async` ستُطلق `VMError` (الافتراضي: `true`).
-   `bufferAllocLimit` - الحد الأقصى للحجم بالبايت لطلب واحد من `Buffer.alloc` / `Buffer.allocUnsafe` / `Buffer.allocUnsafeSlow` / `Buffer(N)` / `new Buffer(N)` من داخل العزل. الطلبات التي تتجاوز هذا الحد تُطلق `RangeError` بشكل متزامن دون تنفيذ التخصيص على المضيف. الافتراضي: `Infinity` (بدون حد، متوافق تمامًا مع الإصدارات السابقة). يجب على المُضمّنين الذين يشغّلون كودًا غير موثوق في بيئات محدودة الذاكرة (Docker / Kubernetes / Lambda / serverless) اختيار حد محدود (مثل `32 * 1024 * 1024`) كجزء من الدفاع الطبقي ضد DoS، بنفس الطريقة التي يختارون بها `timeout`. انظر [توصيات التحصين](#hardening-recommendations) أدناه.

**مهم**: المهلة فعالة فقط على الكود المتزامن الذي تشغّله عبر `run`. المهلة **لا** تعمل على أي طريقة مُعادة من VM. هناك بعض الحالات التي لا تعمل فيها المهلة - انظر [#244](https://github.com/patriksimek/vm2/pull/244).```js
import { VM } from 'vm2';

const vm = new VM({
	timeout: 1000,
	allowAsync: false,
	sandbox: {},
});

vm.run('process.exit()'); // throws ReferenceError: process is not defined

**نصيحة**: راجع الاختبارات لمزيد من أمثلة الاستخدام.

## NodeVM

على عكس `VM`، يتيح لك `NodeVM` استيراد الوحدات بنفس الطريقة التي تستخدمها في سياق Node العادي.

**الخيارات:**

-   `console` - `inherit` لتمكين وحدة التحكم، `redirect` لإعادة التوجيه إلى الأحداث، `off` لتعطيل وحدة التحكم (الافتراضي: `inherit`).
-   `sandbox` - الكائن العام لـ VM.
-   `compiler` - `javascript` (الافتراضي)، `typescript`، `coffeescript` أو دالة مترجم مخصصة (تستقبل الكود ومسار ملفه). تتوقع المكتبة أن يكون لديك المترجم مثبتًا مسبقًا إذا تم تعيين القيمة إلى `typescript` أو `coffeescript`. **يتطلب `typescript` الإصدار `typescript@6` أو إصدارًا أقدم** — راجع [المترجمون](#compilers).
-   `eval` - إذا تم تعيينه إلى `false`، فإن أي استدعاء لـ `eval` أو منشئات الدوال (`Function`، `GeneratorFunction`، إلخ) سيؤدي إلى رمي خطأ `EvalError` (الافتراضي: `true`).
-   `wasm` - إذا تم تعيينه إلى `false`، فإن أي محاولة لتجميع وحدة WebAssembly ستؤدي إلى رمي خطأ `WebAssembly.CompileError` (الافتراضي: `true`). ملاحظة: تتم إزالة `WebAssembly.JSTag` داخل بيئة العزل لأسباب أمنية، لذا لا يمكن لرمز wasm التقاط استثناءات JavaScript.
-   `bufferAllocLimit` - نفس الدلالات كما في `VM` — الحد الأقصى للحجم بالبايت لطلب واحد من عائلة `Buffer.alloc` من داخل بيئة العزل. الافتراضي: `Infinity`. راجع [توصيات التقوية](#hardening-recommendations).
-   `sourceExtensions` - مصفوفة من امتدادات الملفات التي سيتم التعامل معها ككود مصدري (الافتراضي: `['js']`).
-   `require` - `true`، أو كائن، أو أداة حل (Resolver) لتمكين طريقة `require` (الافتراضي: `false`).
-   `require.external` - يمكن أن تكون القيم `true`، أو مصفوفة من الوحدات الخارجية المسموح بها، أو كائنًا (الافتراضي: `false`). يُسمح باستيراد جميع المسارات المطابقة لـ `/node_modules/${any_allowed_external_module}/(?!/node_modules/)`.
-   `require.external.modules` - مصفوفة من الوحدات الخارجية المسموح بها. تدعم أيضًا أحرف البدل، لذا فإن تحديد `['@scope/*-ver-??]`، على سبيل المثال، سيسمح باستخدام جميع الوحدات التي تحمل اسمًا بالشكل `@scope/something-ver-aa`، `@scope/other-ver-11`، إلخ. لا يطابق حرف البدل `*` فواصل المسارات.
-   `require.external.transitive` - قيمة منطقية تشير إلى ما إذا كانت التبعيات غير المباشرة للوحدات الخارجية مسموحًا بها (الافتراضي: `false`). **تحذير**: عندما يتم استيراد وحدة بشكل غير مباشر، يصبح بإمكان أي وحدة أخرى استيرادها بشكل طبيعي، حتى لو لم يكن ذلك ممكنًا قبل تحميلها.
-   `require.builtin` - مصفوفة من الوحدات المدمجة المسموح بها، تقبل `["\*"]` للجميع (الافتراضي: لا شيء). **تحذير**: يمكن أن يكون `"\*"` خطيرًا حيث يمكن إضافة وحدات مدمجة جديدة.
-   `require.root` - المسار (المسارات) المقيدة حيث يمكن استيراد الوحدات المحلية (الافتراضي: كل مسار).
-   `require.mock` - مجموعة من الوحدات الوهمية (سواء كانت خارجية أو مدمجة).
-   `require.context` - `host` (الافتراضي) لاستيراد الوحدات في المضيف وتمريرها عبر وكيل إلى بيئة العزل. `sandbox` لتحميل الوحدات وتجميعها واستيرادها داخل بيئة العزل. `callback(moduleFilename, ext)` لاختيار سياق ديناميكيًا لكل وحدة. سيكون الافتراضي هو بيئة العزل إذا لم يتم تحديد أي شيء. باستثناء `events`، يتم دائمًا استيراد الوحدات المدمجة في المضيف وتمريرها عبر وكيل إلى بيئة العزل.
-   `require.import` - مصفوفة من الوحدات التي سيتم تحميلها في NodeVM عند البدء.
-   `require.resolve` - دالة بحث إضافية في حال لم يتم العثور على وحدة في أحد مسارات البحث التقليدية في Node.
-   `require.customRequire` - يُستخدم بدلاً من دالة `require` لتحميل الوحدات من المضيف.
-   `require.strict` - `false` لعدم فرض الوضع الصارم على الوحدات المحملة بواسطة require (الافتراضي: `true`).
-   `require.fs` - تنفيذ مخصص لنظام الملفات.
-   `nesting` - **تحذير**: السماح بهذا يشكل خطرًا أمنيًا حيث يمكن للبرامج النصية إنشاء NodeVM يمكنه استيراد أي وحدة من المضيف. `true` لتمكين تداخل VMs (الافتراضي: `false`).
-   `wrapper` - `commonjs` (الافتراضي) لتغليف البرنامج النصي في غلاف CommonJS، `none` لاسترجاع القيمة التي يعيدها البرنامج النصي.
-   `argv` - مصفوفة يتم تمريرها إلى `process.argv`.
-   `env` - كائن يتم تمريره إلى `process.env`.
-   `strict` - `true` لتحميل الوحدات في الوضع الصارم (الافتراضي: `false`).

**مهم**: المهلة الزمنية غير فعالة مع NodeVM لذا فهو ليس محصنًا ضد `while (true) {}` أو ما شابه ذلك من الأكواد الضارة.

**تذكر**: كلما زادت الوحدات التي تسمح بها، زادت هشاشة بيئة العزل لديك.```js
import { NodeVM } from 'vm2';

const vm = new NodeVM({
	console: 'inherit',
	sandbox: {},
	require: {
		external: true,
		builtin: ['fs', 'path'],
		root: './',
		mock: {
			fs: {
				readFileSync: () => 'Nice try!',
			},
		},
	},
});

// Sync

let functionInSandbox = vm.run('module.exports = function(who) { console.log("hello "+ who); }');
functionInSandbox('world');

// Async

let functionWithCallbackInSandbox = vm.run('module.exports = function(who, callback) { callback("hello "+ who); }');
functionWithCallbackInSandbox('world', greeting => {
	console.log(greeting);
});

**نصيحة**: راجع الاختبارات لمزيد من أمثلة الاستخدام.

### تحميل الوحدات عبر مسار نسبي

لتحميل الوحدات عبر مسار نسبي، يجب عليك تمرير المسار الكامل للبرنامج النصي الذي تقوم بتشغيله كوسيط ثانٍ لطريقة `run` الخاصة بـ vm إذا كان البرنامج النصي عبارة عن سلسلة نصية. يتم بعد ذلك عرض اسم الملف في أي تتبعات مكدس (stack traces) يتم إنشاؤها بواسطة البرنامج النصي.```js
vm.run('require("foobar")', '/data/myvmscript.js');

### Resolver

يمكن إنشاء resolver عبر `makeResolverFromLegacyOptions` واستخدامه لعدة نسخ من `NodeVM` مما يسمح بمشاركة كود الوحدة المترجمة وربما تسريع أوقات التحميل. يمكن إعادة كتابة المثال الأول من `NodeVM` باستخدام `makeResolverFromLegacyOptions` على النحو التالي.```js
const resolver = makeResolverFromLegacyOptions({
	external: true,
	builtin: ['fs', 'path'],
	root: './',
	mock: {
		fs: {
			readFileSync: () => 'Nice try!',
		},
	},
});
const vm = new NodeVM({
	console: 'inherit',
	sandbox: {},
	require: resolver,
});

يعمل لكل من `VM` و `NodeVM`.```js
import { NodeVM, VMScript } from 'vm2';

const vm = new NodeVM();
const script = new VMScript('module.exports = Math.random()');
console.log(vm.run(script));
console.log(vm.run(script));

إما أن تثبّت `typescript@6`، أو وفّر المترجم الخاص بك — أي دالة تُرجع JavaScript تعمل، لذا فإن `tsc` الخاص بـ TypeScript 7، أو esbuild، أو swc، أو أداة إزالة الأنواع كلها صالحة:```js
import { VM, VMScript } from 'vm2';
import { transformSync } from 'esbuild';

const script = new VMScript('const x: number = 1; x', {
	compiler: (code, filename) => transformSync(code, { loader: 'ts', format: 'cjs' }).code,
});

new VM().run(script);

## تصحيح أخطاء الكود المعزول

يمكنك تصحيح أو فحص الكود الذي يعمل داخل العزل (sandbox) كما لو كان يعمل في عملية عادية.

-   يمكنك استخدام نقاط التوقف (breakpoints) (وهذا يتطلب منك تحديد اسم ملف السكربت)
-   يمكنك استخدام الكلمة المفتاحية `debugger`.
-   يمكنك استخدام خطوة-إلى-الداخل (step-in) للدخول داخل الكود الذي يعمل في العزل.

### مثال

/tmp/main.js:```js
import { VM, VMScript } from 'vm2';
import { readFileSync } from 'node:fs';

const file = `${__dirname}/sandbox.js`;

// By providing a file name as second argument you enable breakpoints
const script = new VMScript(readFileSync(file), file);

new VM().run(script);

## كائنات للقراءة فقط (تجريبي)

لمنع البرامج النصية المعزولة من إضافة أو تغيير أو حذف الخصائص من الكائنات المُوكَّلة (proxied)، يمكنك استخدام طرق `freeze` لجعل الكائن للقراءة فقط. هذا فعّال فقط داخل VM. الكائنات المجمَّدة تتأثر بعمق. لا يمكن تجميد الأنواع البدائية (Primitive types).

**مثال بدون استخدام `freeze`:**```js
const util = {
	add: (a, b) => a + b,
};

const vm = new VM({
	sandbox: { util },
});

vm.run('util.add = (a, b) => a - b');
console.log(util.add(1, 1)); // returns 0

**مهم:** لا يمكن تجميد الكائنات التي تم بالفعل تمريرها كوسيط (proxy) إلى الآلة الافتراضية.

## الكائنات المحمية (تجريبي)

على عكس `freeze`، تسمح هذه الطريقة للبرامج النصية المعزولة بإضافة أو تغيير أو حذف الخصائص على الكائنات، مع استثناء واحد - لا يمكن إرفاق الدوال. وبالتالي، لا تستطيع البرامج النصية المعزولة تعديل طرق مثل `toJSON` أو `toString` أو `inspect`.

**مهم:** لا يمكن حماية الكائنات التي تم بالفعل تمريرها كوسيط (proxy) إلى الآلة الافتراضية.

## العلاقات عبر العزل (Cross-sandbox)```js
const assert = require('assert');
const { VM } = require('vm2');

const sandbox = {
	object: new Object(),
	func: new Function(),
	buffer: new Buffer([0x01, 0x05]),
};

const vm = new VM({ sandbox });

assert.ok(vm.run(`object`) === sandbox.object);
assert.ok(vm.run(`object instanceof Object`));
assert.ok(vm.run(`object`) instanceof Object);
assert.ok(vm.run(`object.__proto__ === Object.prototype`));
assert.ok(vm.run(`object`).__proto__ === Object.prototype);

assert.ok(vm.run(`func`) === sandbox.func);
assert.ok(vm.run(`func instanceof Function`));
assert.ok(vm.run(`func`) instanceof Function);
assert.ok(vm.run(`func.__proto__ === Function.prototype`));
assert.ok(vm.run(`func`).__proto__ === Function.prototype);

assert.ok(vm.run(`new func() instanceof func`));
assert.ok(vm.run(`new func()`) instanceof sandbox.func);
assert.ok(vm.run(`new func().__proto__ === func.prototype`));
assert.ok(vm.run(`new func()`).__proto__ === sandbox.func.prototype);

assert.ok(vm.run(`buffer`) === sandbox.buffer);
assert.ok(vm.run(`buffer instanceof Buffer`));
assert.ok(vm.run(`buffer`) instanceof Buffer);
assert.ok(vm.run(`buffer.__proto__ === Buffer.prototype`));
assert.ok(vm.run(`buffer`).__proto__ === Buffer.prototype);
assert.ok(vm.run(`buffer.slice(0, 1) instanceof Buffer`));
assert.ok(vm.run(`buffer.slice(0, 1)`) instanceof Buffer);

## توصيات التقوية

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

### 1. تقييد تخصيص الذاكرة باستخدام `bufferAllocLimit`

استدعاء واحد لـ `Buffer.alloc(N)` مع `N` يتحكم فيه المهاجم يعمل كتخصيص واحد متزامن في C++ على المضيف لا يمكن لمهلة V8 (`timeout`) مقاطعته. في البيئات المقيّدة بالذاكرة، يمكن لحمولة صغيرة في بيئة الاختبار بحجم ~100 بايت أن ترفع استخدام ذاكرة المضيف (RSS) بأكثر من 100 ميجابايت وتُسقط عملية المضيف عبر نفاد الذاكرة (OOM). اضبط `bufferAllocLimit` (مثل `32 * 1024 * 1024`) لتقييد التخصيصات الفردية:```js
const vm = new VM({
	timeout: 1000,
	bufferAllocLimit: 32 * 1024 * 1024,
	allowAsync: false,
});

إذا لم يكن لتطبيقك أي مصدر آخر للرفض غير المعالج، فإن الابتلاع الشامل + التسجيل مقبول:```js
process.on('unhandledRejection', reason => {
	yourLogger.warn('swallowed sandbox rejection', reason);
});

إذا قمت بتعيين `nesting: true`، فأنت بذلك منحت الصندوق الرملي نفس مستوى الثقة الذي تتمتع به أنت. **لا تقم بتفعيل `nesting: true` للكود غير الموثوق.** استخدمه فقط عندما تثق بالكود داخل الصندوق الرملي نفسه ولكنك تريد دلالات تنفيذ بنمط VM (بيئة عامة جديدة، مهلات زمنية محكومة) لأسباب غير أمنية.

`nesting: true` **يتطلب كائن إعدادات `require` صريحًا** (مثل `require: { builtin: [] }` أو `require: {}`). أي شكل آخر — `require: false`، أو `require: undefined`، أو `require: null`، أو حذف `require` تمامًا — يرمي خطأ `VMError` عند الإنشاء (GHSA-m4wx-m65x-ghrr، يحل محل GHSA-8hg8-63c5-gwmx). جميع هذه الأشكال تنتج محللًا من نوع NESTING_OVERRIDE فقط: يمكن للصندوق الرملي استدعاء `require('vm2')` ولكن لا شيء آخر، وهو بدائية هروب خالصة لا فائدة مشروعة منها. لمنع جميع الاستدعاءات، قم بإزالة `nesting: true`. للسماح بـ VMs متداخلة، قم بتوفير إعداد `require` صريح بحيث يكون المقايض مرئيًا في موقع الاستدعاء.

## المشكلات المعروفة

-   ليس من الممكن تعريف فئة تمتد من فئة مُوكَّلة (proxied class). يتضمن ذلك استخدام فئة مُوكَّلة في `Object.create`.
-   التقييم المباشر (Direct eval) لا يعمل.
-   تسجيل مصفوفات الصندوق الرملي سيكرر جزء المصفوفة في الخصائص.
-   تحويلات الكود المصدري يمكن أن تؤدي إلى سلسلة مصدر مختلفة للدالة.
-   هناك طرق لتعطيل عملية node من داخل الصندوق الرملي. راجع [توصيات التقوية](#hardening-recommendations).
-   مترجم `typescript` المدمج لا يعمل مع TypeScript 7 أو أحدث، الذي أزال واجهة برمجة التطبيقات `transpileModule()` التي يستخدمها vm2. استخدم `typescript@6` أو مرر المترجم الخاص بك — راجع [المترجمون](#compilers).

[npm-image]: https://img.shields.io/npm/v/vm2.svg
[npm-url]: https://www.npmjs.com/package/vm2
[license-image]: https://img.shields.io/npm/l/vm2.svg
[license-url]: https://raw.githubusercontent.com/patriksimek/vm2/resurrection/LICENSE.md
[downloads-image]: https://img.shields.io/npm/dm/vm2.svg
[downloads-url]: https://www.npmjs.com/package/vm2
[snyk-image]: https://snyk.io/test/github/patriksimek/vm2/badge.svg
[snyk-url]: https://snyk.io/test/github/patriksimek/vm2