العودة إلى التحديثات
New releaseAug 8, 2026

sandbox-runtime v0.0.71

أداة عزل (sandboxing) خفيفة الوزن لفرض قيود على نظام الملفات والشبكة على أي عملية على مستوى نظام التشغيل، دون الحاجة إلى حاوية (container).

مشاركة

Anthropic Sandbox Runtime (srt)

أداة عزل خفيفة الوزن لفرض قيود على نظام الملفات والشبكة على أي عمليات على مستوى نظام التشغيل، دون الحاجة إلى حاوية.

srt يستخدم بدائيات عزل نظام التشغيل الأصلية (sandbox-exec على macOS، وbubblewrap على Linux) وتصفية الشبكة القائمة على الوكيل. يمكن استخدامه لعزل سلوك الوكلاء وخوادم MCP المحلية وأوامر bash وأي عمليات.

معاينة بحثية (Beta)

إن Sandbox Runtime هي معاينة بحثية طُوّرت لصالح Claude Code لتمكين وكلاء ذكاء اصطناعي أكثر أمانًا. وهي متاحة الآن كمعاينة مبكرة مفتوحة المصدر للمساعدة في تمكين النظام البيئي الأوسع من بناء أنظمة وكيلية أكثر أمانًا. وبما أن هذه معاينة بحثية مبكرة، فإن واجهات برمجة التطبيقات (APIs) وصيغ التكوين قد تتطور. نرحب بالملاحظات والمساهمات لجعل وكلاء الذكاء الاصطناعي أكثر أمانًا افتراضيًا!

التثبيت```bash

npm install -g @anthropic-ai/sandbox-runtime

## الاستخدام الأساسي```bash
# Network restrictions
$ srt "curl anthropic.com"
Running: curl anthropic.com
<html>...</html>  # Request succeeds

$ srt "curl example.com"
Running: curl example.com
Connection blocked by network allowlist  # Request blocked

# Filesystem restrictions
$ srt "cat README.md"
Running: cat README.md
# Anthropic Sandb...  # Current directory access allowed

$ srt "cat ~/.ssh/id_rsa"
Running: cat ~/.ssh/id_rsa
cat: /Users/ollie/.ssh/id_rsa: Operation not permitted  # Specific file blocked

نظرة عامة

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

القدرات الرئيسية:

  • قيود الشبكة: التحكم في المضيفات/النطاقات التي يمكن الوصول إليها عبر HTTP/HTTPS والبروتوكولات الأخرى
  • قيود نظام الملفات: التحكم في الملفات/الدلائل التي يمكن قراءتها/كتابتها
  • قيود مقابس يونكس (Unix sockets): التحكم في الوصول إلى مقابس IPC المحلية
  • مراقبة الانتهاكات: على macOS، يمكنك الوصول إلى مخزن سجلات انتهاكات الصندوق الرملي في النظام للحصول على تنبيهات فورية

حالة استخدام مثال: عزل خوادم MCP

من حالات الاستخدام الرئيسية عزل خوادم بروتوكول سياق النموذج (Model Context Protocol - MCP) لتقييد قدراتها. على سبيل المثال، لعزل خادم MCP الخاص بنظام الملفات:

بدون عزل (.mcp.json):```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem"] } } }

**مع العزل** (`.mcp.json`):```json
{
  "mcpServers": {
    "filesystem": {
      "command": "srt",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem"]
    }
  }
}

ثم قم بتكوين القيود في ~/.srt-settings.json:```json { "filesystem": { "denyRead": [], "allowWrite": ["."], "denyWrite": ["~/sensitive-folder"] }, "network": { "allowedDomains": [], "deniedDomains": [] } }

الآن سيتم حظر خادم MCP من الكتابة إلى المسار المرفوض:```
> Write a file to ~/sensitive-folder
✗ Error: EPERM: operation not permitted, open '/Users/ollie/sensitive-folder/test.txt'

كيف يعمل

يستخدم الـ sandbox بدائيات على مستوى نظام التشغيل لفرض قيود تنطبق على شجرة العمليات بأكملها:

  • macOS: يستخدم sandbox-exec مع ملفات تعريف Seatbelt مولّدة ديناميكيًا
  • Linux: يستخدم bubblewrap للحاويات مع عزل مساحات أسماء الشبكة
  • Windows: يشغّل العملية المعزولة تحت حساب مستخدم محلي مخصص srt-sandbox، مع سياج للاتصالات الصادرة قائم على Windows Filtering Platform مرتبط بـ SID الخاص بهذا الحساب، وACEs صريحة لكل جلسة على شجرة العمل

0d1c612947c798aef48e6ab4beb7e8544da9d41a-4096x2305

نموذج العزل المزدوج

يتطلب العزل الفعال وجود عزل لنظام الملفات وعزل للشبكة معًا. فبدون عزل الملفات، قد تَسرّب عملية مخترَقة مفاتيح SSH أو ملفات حساسة أخرى. وبدون عزل الشبكة، قد تخرج عملية من بيئة العزل وتحصل على وصول شبكي غير مقيد.

عزل نظام الملفات يفرض قيود القراءة والكتابة:

  • القراءة (نمط المنع ثم السماح): افتراضيًا، يُسمح بالقراءة في كل مكان. يمكنك منع مناطق واسعة (مثل /Users) ثم إعادة السماح بمسارات محددة داخلها (مثل .). allowRead له أولوية على denyRead — عكس الكتابة، حيث denyWrite له أولوية على allowWrite.
  • الكتابة (نمط السماح فقط): افتراضيًا، يُمنع الوصول للكتابة في كل مكان. يجب عليك السماح صراحةً بمسارات (مثل ., /tmp). قائمة السماح الفارغة تعني عدم وجود وصول للكتابة.

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

  • Linux: يتم توجيه الطلبات عبر نظام الملفات باستخدام Unix domain socket. تتم إزالة مساحة اسم الشبكة الخاصة بالعملية المعزولة بالكامل، لذا يجب أن تمر كل حركة مرور الشبكة عبر البروكسيات التي تعمل على المضيف (التي تستمع على Unix sockets مثبّتة داخل بيئة العزل عبر bind mount)

  • macOS: يسمح ملف تعريف Seatbelt بالاتصال بمنفذ localhost محدد فقط. تستمع البروكسيات على هذا المنفذ، مما ينشئ قناة خاضعة للتحكم لكل الوصول إلى الشبكة

  • Windows: مجموعة عوامل تصفية WFP على مستوى الجهاز تمنع كل الاتصالات الصادرة التي تنشأ من حساب srt-sandbox باستثناء الاتصالات الحلقية (loopback) إلى نطاق منافذ البروكسي. تستمع البروكسيات داخل هذا النطاق، مما ينشئ قناة خاضعة للتحكم لكل الوصول إلى الشبكة

يتم توسط كل من حركة HTTP/HTTPS (عبر بروكسي HTTP) وحركة TCP الأخرى (عبر بروكسي SOCKS5) بواسطة هذه البروكسيات، التي تفرض قوائم السماح والمنع للنطاقات الخاصة بك.

لمزيد من التفاصيل حول العزل (sandboxing) في Claude Code، انظر:

البنية المعمارية```

src/ ├── index.ts # Library exports ├── cli.ts # CLI entrypoint (srt command) ├── utils/ # Shared utilities │ ├── debug.ts # Debug logging │ ├── settings.ts # Settings reader (permissions + sandbox config) │ ├── platform.ts # Platform detection │ └── exec.ts # Command execution utilities └── sandbox/ # Sandbox implementation ├── sandbox-manager.ts # Main sandbox manager ├── sandbox-schemas.ts # Zod schemas for validation ├── sandbox-violation-store.ts # Violation tracking ├── sandbox-utils.ts # Shared sandbox utilities ├── http-proxy.ts # HTTP/HTTPS proxy for network filtering ├── socks-proxy.ts # SOCKS5 proxy for network filtering ├── linux-sandbox-utils.ts # Linux bubblewrap sandboxing ├── macos-sandbox-utils.ts # macOS sandbox-exec sandboxing └── windows-sandbox-utils.ts # Windows srt-win sandboxing

## الاستخدام

### كأداة CLI

أمر `srt` (Anthropic Sandbox Runtime) يغلّف أي أمر بحدود أمنية:```bash
# Run a command in the sandbox
srt echo "hello world"

# With debug logging
srt --debug curl https://example.com

# Specify custom settings file
srt --settings /path/to/srt-settings.json npm install

كمكتبة```typescript

import { SandboxManager, type SandboxRuntimeConfig, } from '@anthropic-ai/sandbox-runtime' import { spawn } from 'child_process'

// Define your sandbox configuration const config: SandboxRuntimeConfig = { network: { allowedDomains: ['example.com', 'api.github.com'], deniedDomains: [], }, filesystem: { denyRead: ['~/.ssh'], allowWrite: ['.', '/tmp'], denyWrite: ['.env'], }, }

// Initialize the sandbox (starts proxy servers, etc.) await SandboxManager.initialize(config)

// Wrap a command with sandbox restrictions const sandboxedCommand = await SandboxManager.wrapWithSandbox( 'curl https://example.com', )

// Execute the sandboxed command const child = spawn(sandboxedCommand, { shell: true, stdio: 'inherit' })

// Handle exit and cleanup after child process completes child.on('exit', async code => { console.log(Command exited with code ${code}) // Cleanup when done (optional, happens automatically on process exit) await SandboxManager.reset() })

**إسناد الانتهاكات (`commandId` / `commandText`).** تُخزَّن الانتهاكات التي تُرصد أثناء تشغيل أمر مُغلَّف (أسطر سجل seatbelt، أحداث seccomp، رفض الوكيل) تحت مفتاح إسناد، وتقوم `annotateStderrWithSandboxFailures(key, stderr)` / `getViolationsForCommand(key)` بالبحث عنها باستخدام المفتاح نفسه. افتراضيًا، يكون المفتاح هو السلسلة المُغلَّفة نفسها. مرِّر `commandId` معتمًا خاصًا بكل استدعاء (مثل معرّف استخدام أداة) للربط به بدلًا من ذلك — وهو أمر موصى به: إذ تُقارَن المفاتيح على أساس أول 100 حرف منها، لذا فإن الأوامر الطويلة التي تتشارك بادئة قد تُنسب أحداثها بالخطأ إلى بعضها البعض، وإعادة تنفيذ النص نفسه قد ترث أحداث التشغيل السابق. إذا كانت السلسلة التي *تنفّذها* ليست الأمر الذي *يمثّله* الاستدعاء (مثلًا، إذا غلّفت أمرًا مُجمَّعًا كـ `source <snapshot> && eval '<cmd>'`)، مرِّر أيضًا `commandText: '<cmd>'`: فهو ما تُطابِق أنماط أوامر `ignoreViolations` ضده، وهو ما يُبلَّغ عنه كل انتهاك بصفته `command` الخاص به.```typescript
const wrapped = await SandboxManager.wrapWithSandbox(
  assembledCommand, // what actually runs
  undefined,
  undefined,
  undefined,
  { commandId: invocationId, commandText: rawCommand },
)
// ... run it ...
const annotated = SandboxManager.annotateStderrWithSandboxFailures(invocationId, stderr)

الصادرات المتاحة```typescript

// Main sandbox manager export { SandboxManager } from '@anthropic-ai/sandbox-runtime'

// Violation tracking export { SandboxViolationStore } from '@anthropic-ai/sandbox-runtime'

// TypeScript types export type { SandboxRuntimeConfig, NetworkConfig, FilesystemConfig, IgnoreViolationsConfig, SandboxAskCallback, FsReadRestrictionConfig, FsWriteRestrictionConfig, NetworkRestrictionConfig, } from '@anthropic-ai/sandbox-runtime'

## الإعدادات

### موقع ملف الإعدادات

بشكل افتراضي، يبحث مشغّل الصندوق الرملي عن الإعدادات في `~/.srt-settings.json`. يمكنك تحديد مسار مخصص باستخدام علامة `--settings`:```bash
srt --settings /path/to/srt-settings.json <command>

مثال تكوين كامل```json

{ "network": { "allowedDomains": [ "github.com", ".github.com", "lfs.github.com", "api.github.com", "npmjs.org", ".npmjs.org" ], "deniedDomains": ["malicious.com"], "allowUnixSockets": ["/var/run/docker.sock"], "allowLocalBinding": false }, "filesystem": { "denyRead": ["~/.ssh"], "allowRead": [], "allowWrite": [".", "src/", "test/", "/tmp"], "denyWrite": [".env", "config/production.json"] }, "ignoreViolations": { "*": ["/usr/bin", "/System"], "git push": ["/usr/bin/nc"], "npm": ["/private/tmp"] }, "enableWeakerNestedSandbox": false, "enableWeakerNetworkIsolation": false, "allowAppleEvents": false }

### خيارات التكوين

#### تكوين الشبكة

يستخدم نمط **السماح فقط** - جميع الوصول إلى الشبكة مرفوض افتراضيًا.

- `network.allowedDomains` - مصفوفة من النطاقات المسموح بها (تدعم أحرف البدل مثل `*.example.com`). المصفوفة الفارغة = لا وصول إلى الشبكة. لاحقة `:port` الاختيارية (`api.example.com:443`, `*.example.com:8443`) تقيّد الإدخال بمنفذ الوجهة ذلك؛ الإدخالات بدون منفذ تطابق أي منفذ.
  - يجب وضع عناوين IPv6 بين قوسين مربعين، بأسلوب RFC 3986: `[::1]`, `[2001:db8::1]:443`. يُرفض الإدخال متعدد النقطتين غير المقوّس باعتباره غامضًا (`2001:db8::1:443` بحد ذاته عنوان صالح).
- `network.deniedDomains` - مصفوفة من النطاقات المرفوضة (تُفحص أولاً، ولها أولوية على allowedDomains). نفس لاحقة `:port`، ويُقبل `*` المجرد (أو `*:22`) للرفض الكلي.
- `network.deniedDomainReasons` - خريطة اختيارية من إدخال `deniedDomains` (يُطابق حسب النص الحرفي) إلى سبب موجَّه للنموذج يظهر في سطر `<sandbox_violations>` عندما يرفض هذا الإدخال اتصالًا — اذكر ما تم حظره والبديل المعتمد (مثل `{"github.com:22": "SSH pushes to GitHub are blocked; use an https:// remote"}`). الإدخالات بدون سبب تُبلِغ عن سبب عام. لوجهات SSH (المنفذ 22)، يُسلَّم السبب أيضًا داخل النطاق: عميل SSH يتم توجيهه عبر ProxyCommand من نوع SOCKS بدون مصادقة (مثل BSD `nc -X 5`) يتلقى فصل SSH قبل تبادل المفاتيح، ويكون وصفه هو السبب، الذي يطبعه OpenSSH حرفيًا — اجعل هذه الأسباب أقل من ~400 حرف ASCII، بصيغة الأمر أولاً، لأن OpenSSH يقتطع ويهرب غير ASCII.
- `network.allowLocalBinding` - السماح بالربط بالمنافذ المحلية (قيمة منطقية، الافتراضي: false)

**إنهاء TLS** (`network.tlsTerminate`, تجريبي): عند ضبطه، يتم إنهاء اتصالات HTTPS CONNECT داخل العملية حتى يتمكن SRT من رؤية (وتصفية، عبر `network.filterRequest`) الطلبات المفكوكة تشفيرها. تُوجَّه العملية المعزولة إلى حزمة ثقة تحتوي على شهادة CA الخاصة بـ MITM (`caCertPath`/`caKeyPath`، أو CA مؤقتة إذا تم حذفهما) بالإضافة إلى الجذور المعتادة للمضيف، بحيث تتحقق كل من الشهادات المصدَرة من الوكيل وشهادات المنبع الحقيقية.

- `network.tlsTerminate.excludeDomains` - أنماط نطاقات (نفس صياغة `allowedDomains`) التي **لا** يتم إنهاؤها. تُمرَّر اتصالات CONNECT المطابقة عبر نفق بشكل غير شفاف بدلاً من ذلك: فهي لا تزال خاضعة لقائمة النطاقات المسموح بها، لكن العميل داخل الصندوق الرملي يُكمل مصافحة TLS الخاصة به مع المنبع الحقيقي، ولا تنطبق `filterRequest` / حقن بيانات الاعتماد على حركة HTTPS الخاصة بها. استخدم هذا للحالتين اللتين يكسر فيهما إنهاء TLS أساسًا:
  - **منابع mTLS** - فقط العميل داخل الصندوق الرملي يمتلك شهادة العميل، لذلك لا يمكن للوكيل إعادة بدء الاتصال نيابةً عنه.
  - **عملاء تثبيت الشهادة** - عملاء يتحققون من هوية المنبع بأنفسهم (مراجع تصديق مخصصة، تثبيت SAN) ويرفضون شهادة MITM.
- `network.tlsTerminate.extraCaCertPaths` - مسارات ملفات شهادات CA بصيغة PEM تُضاف إلى حزمة الثقة تلك، بعد MITM CA والجذور المعتادة للمضيف. يتم التحقق من المضيفات المستبعدة (غير المُنهَاة) بواسطة العميل داخل الصندوق الرملي، ومتغيرات بيئة الثقة التي يضبطها SRT (`SSL_CERT_FILE`, `GIT_SSL_CAINFO`, ...) _تستبدل_ إعدادات الثقة الخاصة بكل أداة، لذلك يجب أن يكون الجذر المحلي للموقع (مثل CA داخلية لـ mTLS) في الحزمة وإلا لا يمكن التحقق من تلك المضيفات أبدًا. يتم نسخ كتل `CERTIFICATE` فقط من كل ملف إلى الحزمة (أي شيء آخر، مثل مفتاح خاص في PEM مدمج، لا يُكشف أبدًا للصندوق الرملي)؛ يتم تخطي الملفات المفقودة أو غير القابلة للقراءة أو التي لا تحتوي على كتلة `CERTIFICATE` بصيغة PEM، لذلك من الآمن سرد مسارات موجودة على بعض المضيفات فقط.```json
{
  "network": {
    "allowedDomains": ["*.example.com", "internal-mtls.example.net"],
    "deniedDomains": [],
    "tlsTerminate": {
      "excludeDomains": ["internal-mtls.example.net"],
      "extraCaCertPaths": ["/etc/internal-mtls-roots.pem"]
    }
  }
}

إعدادات مقابس يونكس (سلوك خاص بالمنصة):

الإعدادmacOSLinux
allowUnixSockets: string[]قائمة سماح بمسارات المقابسمتجاهَل (لا يمكن لـ seccomp التصفية حسب المسار)
allowAllUnixSockets: booleanالسماح بجميع المقابستعطيل حظر seccomp

مقابس يونكس محظورة افتراضيًا على كلا المنصتين.

  • macOS: استخدم allowUnixSockets للسماح بمسارات محددة (مثل ["/var/run/docker.sock"])، أو allowAllUnixSockets: true للسماح بالكل.
  • Linux: يستخدم الحظر مرشّحات seccomp (x64/arm64 فقط). إذا لم تكن seccomp متاحة، تصبح المقابس غير مقيدة ويُعرض تحذير. استخدم allowAllUnixSockets: true لتعطيل الحظر صراحةً.

إعداد نظام الملفات

يستخدم نمطين مختلفين:

قيود القراءة (نمط المنع ثم السماح) - جميع القراءات مسموحة افتراضيًا:

  • filesystem.denyRead - مصفوفة مسارات لمنع الوصول للقراءة. مصفوفة فارغة = وصول كامل للقراءة.
  • filesystem.allowRead - مصفوفة مسارات لإعادة السماح بالقراءة داخل المناطق الممنوعة (لها أولوية على denyRead). ملاحظة: هذا عكس الكتابة، حيث denyWrite له أولوية على allowWrite.

قيود الكتابة (نمط السماح فقط) - جميع الكتابات ممنوعة افتراضيًا:

  • filesystem.allowWrite - مصفوفة مسارات للسماح بوصول الكتابة. مصفوفة فارغة = لا وصول للكتابة.
  • filesystem.denyWrite - مصفوفة مسارات لمنع الوصول للكتابة داخل المسارات المسموحة (له أولوية على allowWrite)

صيغة المسار (macOS):

تدعم المسارات أنماط glob بأسلوب git على macOS، على غرار صيغة .gitignore:

  • * - يطابق أي أحرف باستثناء / (مثل: *.ts يطابق foo.ts لكن ليس foo/bar.ts)
  • ** - يطابق أي أحرف بما في ذلك / (مثل: src/**/*.ts يطابق جميع ملفات .ts في src/)
  • ? - يطابق أي حرف واحد باستثناء / (مثل: file?.txt يطابق file1.txt)
  • [abc] - يطابق أي حرف من المجموعة (مثل: file[0-9].txt يطابق file3.txt)

أمثلة:

  • "allowWrite": ["src/"] - السماح بالكتابة في دليل src/ بالكامل
  • "allowWrite": ["src/**/*.ts"] - السماح بالكتابة لجميع ملفات .ts في src/ والمجلدات الفرعية
  • "denyRead": ["~/.ssh"] - منع قراءة دليل SSH
  • "denyRead": ["/Users"], "allowRead": ["."] - منع القراءة من /Users بالكامل، لكن إعادة السماح للدليل الحالي
  • "denyWrite": [".env"] - منع الكتابة إلى ملف .env (حتى لو كان الدليل الحالي مسموحًا)

صيغة المسار (Linux):

لا يدعم Linux حاليًا مطابقة glob. استخدم المسارات الحرفية فقط:

  • "allowWrite": ["src/"] - السماح بالكتابة في دليل src/
  • "denyRead": ["/home/user/.ssh"] - منع قراءة دليل SSH
  • "denyRead": ["/home"], "allowRead": ["."] - منع القراءة من /home بالكامل، لكن إعادة السماح للدليل الحالي

جميع المنصات:

  • يمكن أن تكون المسارات مطلقة (مثل /home/user/.ssh) أو نسبية إلى دليل العمل الحالي (مثل ./src)
  • ~ يتم توسيعه إلى الدليل الرئيسي للمستخدم

إعدادات أخرى

  • ignoreViolations - كائن يربط أنماط الأوامر بمصفوفات المسارات التي يجب تجاهل الانتهاكات فيها
  • enableWeakerNestedSandbox - تفعيل وضع sandbox أضعف لبيئات Docker (منطقي، الافتراضي: false)
  • enableWeakerNetworkIsolation - السماح بالوصول إلى com.apple.trustd.agent داخل sandbox على macOS (منطقي، الافتراضي: false). هذا مطلوب لبرامج Go (gh، gcloud، terraform، kubectl، إلخ) للتحقق من شهادات TLS عند استخدام httpProxyPort مع وكيل MITM وشهادة CA مخصصة. تحذير أمني: تفعيل هذا يفتح ناقلًا محتملًا لتسريب البيانات عبر خدمة trustd.
  • allowAppleEvents - السماح بإرسال Apple Events وطلبات فتح Launch Services من sandbox على macOS (منطقي، الافتراضي: false). بدون هذا، تفشل أوامر مثل open وosascript وأي شيء يفتح URLs أو يتحكم في تطبيقات أخرى عبر AppleScript مع خطأ AppleScript -600 ("التطبيق غير قيد التشغيل") أو أخطاء LaunchServices (-10822, -54). تحذير أمني: تفعيل هذا يعني أن sandbox لم يعد يوفر عزلًا لتنفيذ التعليمات البرمجية. يمكن لأمر داخل sandbox تشغيل تطبيقات أخرى عبر open دون أي مطالبة من المستخدم، وأي شيء يشغّله يعمل خارج قيود نظام الملفات والشبكة الخاصة بـ sandbox؛ كما أن التحكم في التطبيقات التي تعمل بالفعل عبر Apple Events يخضع إضافيًا لموافقة أتمتة TCC لكل تطبيق من المستخدم. يجب على المدمجين أخذ هذا الخيار فقط من إعدادات موثوقة على مستوى المستخدم — وليس أبدًا من ملفات محلية في مستودع مستخرج، لأن ذلك قد يسمح لمشروع من تأليف مهاجم برفع صلاحيات بيئة الحماية الخاصة به.

وصفات إعداد شائعة

السماح بالوصول إلى GitHub (جميع نقاط النهاية الضرورية):```json { "network": { "allowedDomains": [ "github.com", "*.github.com", "lfs.github.com", "api.github.com" ], "deniedDomains": [] }, "filesystem": { "denyRead": [], "allowWrite": ["."], "denyWrite": [] } }

**تقييد على أدلة محددة:**```json
{
  "network": {
    "allowedDomains": [],
    "deniedDomains": []
  },
  "filesystem": {
    "denyRead": ["~/.ssh"],
    "allowWrite": [".", "src/", "test/"],
    "denyWrite": [".env", "secrets/"]
  }
}

الوصول إلى نظام الملفات يقتصر على مساحة العمل فقط (منع القراءة خارج مساحة العمل):```json { "network": { "allowedDomains": [], "deniedDomains": [] }, "filesystem": { "denyRead": ["/Users"], "allowRead": ["."], "allowWrite": ["."], "denyWrite": [] } }

هذا يمنع القراءة من أي شيء تحت `/Users` (أو `/home` على لينكس)، ثم يعيد السماح بدليل العمل الحالي. تبقى مسارات النظام (`/usr`، `/lib`، إلخ) قابلة للقراءة.

### المشكلات الشائعة والنصائح

**تشغيل Jest:** استخدم علم `--no-watchman` لتجنب انتهاكات وضع الحماية:```bash
srt "jest --no-watchman"

Watchman يصل إلى ملفات خارج حدود منطقة العزل، مما سيؤدي إلى ظهور أخطاء في الأذونات. تعطيله يسمح لـ Jest بالعمل مع مراقب الملفات المدمج بدلاً من ذلك.

دعم المنصات

  • macOS: يستخدم sandbox-exec مع ملفات تعريف مخصصة (بدون تبعيات إضافية)
  • Linux: يستخدم bubblewrap (bwrap) للعزل
  • Windows: ألفا — يستخدم مساعدًا مرفقًا srt-win.exe (بدون تبعيات إضافية). راجع Windows (alpha) أدناه للإعداد ونموذج الأمان والقيود المعروفة

تبعيات خاصة بالمنصة

يتطلب Linux:

  • bubblewrap - بيئة تشغيل الحاويات
    • Ubuntu/Debian: apt-get install bubblewrap
    • Fedora: dnf install bubblewrap
    • Arch: pacman -S bubblewrap
  • socat - مرحّل المقابس لربط البروكسي
    • Ubuntu/Debian: apt-get install socat
    • Fedora: dnf install socat
    • Arch: pacman -S socat
  • ripgrep - أداة بحث سريعة لاكتشاف مسارات الرفض
    • Ubuntu/Debian: apt-get install ripgrep
    • Fedora: dnf install ripgrep
    • Arch: pacman -S ripgrep

ملاحظة Ubuntu 24.04+: تُمكّن هذه الإصدارات kernel.apparmor_restrict_unprivileged_userns افتراضيًا، وهو ما يسمح بـ unshare(CLONE_NEWUSER) لكنه يجرّد مساحة الأسماء الناتجة من الصلاحيات. يحتاج كل من bubblewrap وطبقة عزل seccomp إلى مساحات أسماء مستخدمين تحمل الصلاحيات. عطّل هذا التقييد باستخدام:```bash sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

أو أضف ملف تعريف AppArmor يمنح `userns` للملفات الثنائية ذات الصلة.

**تبعيات Linux الاختيارية (للبديل الاحتياطي لـ seccomp):**

تتضمن الحزمة عوامل تصفية seccomp BPF مولّدة مسبقًا لمعماريتي x86-64 وarm. هذه التبعيات مطلوبة فقط إذا كنت على معمارية مختلفة حيث لا تتوفر عوامل التصفية المولّدة مسبقًا:

- `gcc` أو `clang` - مترجم C
- `libseccomp-dev` - ملفات تطوير مكتبة Seccomp
  - Ubuntu/Debian: `apt-get install gcc libseccomp-dev`
  - Fedora: `dnf install gcc libseccomp-devel`
  - Arch: `pacman -S gcc libseccomp`

**يتطلب macOS:**

- `ripgrep` - أداة بحث سريعة لاكتشاف مسار المنع
  - التثبيت عبر Homebrew: `brew install ripgrep`
  - أو التنزيل من: https://github.com/BurntSushi/ripgrep/releases

**يتطلب Windows:**

- لا توجد تبعيات إضافية. الأداة المساعدة `srt-win.exe` (x64 وarm64) مضمّنة في حزمة npm. يلزم تنفيذ خطوة `windows-install` بصلاحيات مرتفعة لمرة واحدة — انظر أدناه.

## Windows (إصدار ألفا)

دعم Windows في مرحلة **ألفا**. تعمل العملية المعزولة تحت حساب مستخدم محلي مخصص `srt-sandbox`، معزولة عن المستخدم المُطلِق عبر آليات أمان Windows الأصلية — سياج خروج من Windows Filtering Platform (WFP) مرتبط بـ SID لحساب العزل، وACEs صريحة لكل جلسة تمنح أو ترفض وصول ذلك SID إلى مسارات نظام الملفات المُهيأة.

### الإعداد

يُشغَّل مرة واحدة لكل جهاز (يرفع الصلاحيات ذاتيًا؛ يظهر طلب UAC واحد):```powershell
npx @anthropic-ai/sandbox-runtime windows-install

يعمل هذا على توفير حساب المستخدم المحلي srt-sandbox (بكلمة مرور عشوائية مخزنة بتشفير DPAPI ضمن %LOCALAPPDATA%\sandbox-runtime\state.db)، والمجموعة المحلية sandbox-runtime-users، ويُثبّت مجموعة مرشحات WFP على مستوى الجهاز مربوطة بمعرّف الأمان (SID) الخاص بـ srt-sandbox. وهو idempotent — إذ أن إعادة تشغيله تُدير كلمة مرور حساب العزل وتُعيد مزامنة مجموعة المرشحات.

لا يلزم تسجيل الخروج. تستند مرشحات WFP إلى معرّف الأمان الخاص بحساب العزل المخصص، لذا فإن شبكتك وخدماتك وكل كيان آخر (principal) على الجهاز تبقى غير متأثرة.

بعد التثبيت، يعمل SandboxManager.initialize() وسطر الأوامر srt كما هو الحال على المنصات الأخرى. يتحقق initialize() من أن حساب العزل وسياج WFP يعملان، ويفشل مع خطأ إجرائي واضح إذا لم يكونا كذلك.

يتم توفير التثبيت/إلغاء التثبيت برمجيًا عبر installWindowsSandbox() / uninstallWindowsSandbox().

نموذج الأمان

يعمل الأمر المعزول بصلاحية حساب srt-sandbox وليس بصلاحية المستخدم المُطلِق. تقوم الأداة المساعدة المرفقة srt-win.exe بإطلاق على مرحلتين (two-hop): يستدعي الوسيط (broker) CreateProcessWithLogonW لتشغيل مشغّل (runner) باسم srt-sandbox، ثم يقوم المشغّل بتوليد العملية الهدف ضمن رمز وصول مقيد (restricted token) داخل كائن وظيفة (job object). ترث العملية الفرعية ملف التعريف المعزول لحساب العزل (%USERPROFILE%، %TEMP%، HKCU) وبيئة جديدة تُدمج معها فقط PATH الخاص بالوسيط ومتغيرات الوكيل المولّدة.

إن التشغيل تحت معرّف أمان (SID) مستخدم مختلف يُغلق بنيويًا صنف الهروب عبر التوليد البديل (surrogate-spawn) (مجدول المهام Task Scheduler، وPROC_THREAD_ATTRIBUTE_PARENT_PROCESS على عملية يملكها الوسيط، وBITS، وCOM خارج العملية مع RunAs="Interactive User"): أي عملية تتمكن العملية الفرعية من توليدها خارج النطاق لا تزال تحمل معرّف srt-sandbox، لذا تظل خاضعة لسياج الحظر الصادر WFP ولا تملك أي حقوق على ملفات المستخدم المُطلِق.

عزل الشبكة عبارة عن مجموعة مرشحات WFP من مرشحين عند FWPM_LAYER_ALE_AUTH_CONNECT_V4/V6: قاعدة PERMIT للوجهات الحلقية (loopback) داخل نطاق منفذ الوكيل المُهيأ (الافتراضي 60080–60089)، وقاعدة BLOCK لأي اتصال يحمل رمز وصوله معرّف srt-sandbox. لا تصل العملية المعزولة إلى الإنترنت إلا عبر وكلاء JS HTTP/SOCKS5 الذين يستمعون في ذلك النطاق؛ أي عملية تُجرد بيئتها من إعدادات الوكيل وتتصل مباشرةً تُحجب على مستوى النواة.

عزل نظام الملفات مفروض عبر قوائم التحكم بالوصول التقديرية (discretionary ACLs) في NTFS. لا يملك حساب srt-sandbox أي حقوق متأصلة على ملفات المستخدم المُطلِق، لذلك عند initialize() يقوم العزل بكتابة إضافات (additive) من ACEs صريحة قابلة للتوريث ومعرّفة لمعرّف الأمان srt-sandbox فقط — ولا يعيد أبدًا كتابة أو استبدال واصف الأمان الموجود لأي مسار:

  • يشير filesystem.allowWrite إلى ACE من نوع MODIFY ALLOW قابل للتوريث (READ|WRITE|EXECUTE|DELETE، مع حجب FILE_DELETE_CHILD). يمكن للعملية المعزولة إنشاء الملفات وتعديلها وحذفها داخل شجرة العمل؛ وحجب FILE_DELETE_CHILD من المنح هو دفاع في العمق لدعم قواعد المنع أدناه، وليس حارسًا على جذر الشجرة.
  • يشير filesystem.allowRead إلى ACE من نوع READ|EXECUTE ALLOW قابل للتوريث
  • يشير filesystem.denyRead / filesystem.denyWrite إلى ACE من نوع DENY قابل للتوريث على الهدف، بالإضافة إلى DENY قابل للتوريث من نوع FILE_DELETE_CHILD على المجلد الأب — وبالاقتران مع FILE_DELETE_CHILD المحجوب في منح شجرة العمل، يمنع ذلك العملية المعزولة من إعادة تسمية أو حذف مسار ممنوع عبر مجلده الأب

يزيل reset() كل ACE أضافته هذه الجلسة (مع عدّ مرجعي عبر المضيفين المتزامنين من خلال state.db؛ وتمريرة استرداد بعد الانهيار عند initialize() التالية تنظف أي أثر لخروج غير نظيف). الأهداف من نوع مجلدات مدعومة (تُورَّث ACEs إلى الشجرة الفرعية بأكملها). يتم توسيع أنماط glob إلى مسارات ملموسة في وقت initialize() — أي مسار مطابق يظهر لاحقًا لا يشمله التوسيع.

إنهاء TLS على ويندوز

يتطلب network.tlsTerminate وجود شهادة المرجع المصدق (CA) الخاصة بـMITM في مخزن الشهادات CurrentUser\Root التابع لمستخدم العزل (يعتمد schannel — وهو خلفية TLS التي تستخدمها System32\curl.exe، وPowerShell Invoke-WebRequest، و.NET، وإصدار git ذو الخلفية الافتراضية — على مخزن نظام التشغيل فقط، وليس على متغيرات البيئة). هذه خطوة تتم وقت التثبيت، وهي منفصلة عن windows-install:```typescript import { windowsTrustCa } from '@anthropic-ai/sandbox-runtime' windowsTrustCa('/path/to/mitm-ca.crt') // or: srt-win user trust-ca 

`initialize()` يقارن بصمة شهادة CA الخاصة بالجلسة مع تلك المثبتة، ويفشل برسالة إرشادية قابلة للتنفيذ عند عدم التطابق، بحيث لا يمكن لشهادة CA قديمة من وقت التثبيت أن تعطل TLS بصمت داخل وضع الحماية.

العملاء المعتمدون على OpenSSL (msys2 `curl`, `git -c http.sslBackend=openssl`, Node, Python, cargo) مشمولون بطبقة الثقة عبر متغيرات البيئة: حزمة الثقة نفسها المستخدمة على macOS/Linux تُمرَّر إلى وضع الحماية عبر `NODE_EXTRA_CA_CERTS`, `SSL_CERT_FILE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, `CARGO_HTTP_CAINFO`، وغيرها، ويُضاف مسار الحزمة إلى منح `allowRead` الخاص بالجلسة ليتمكن حساب وضع الحماية من فتحها.

### إعدادات خاصة بنظام Windows

كتلتا `filesystem` و `network` عبر المنصات تنطبقان كما هو موصوف أعلاه. الإعدادات الخاصة بنظام Windows فقط توجد تحت `windows`:

- `windows.proxyPortRange` — نطاق المنافذ الشامل `[low, high]` الذي ترتبط به بروكسيات JS داخله. **يجب أن يطابق** النطاق الممرَّر إلى `windows-install --proxy-port-range` (الافتراضي `[60080, 60089]`) — إذ يغطي تصريح PERMIT الخاص بـ WFP للـ loopback هذا النطاق فقط.

- `windows.sublayerGuid` — GUID للطبقة الفرعية (sublayer) في WFP التي ثُبِّتت عوامل التصفية (filters) تحتها. احذفه لاستخدام الافتراضي وقت الترجمة؛ اضبطه فقط عندما تكون أدوات المؤسسة قد ثبّتت عوامل التصفية تحت طبقة فرعية مخصصة.

- `windows.srtWin.path` — مسار ثنائي `srt-win`. احذفه لاستخدام الحزمة المرفقة `vendor/srt-win/<arch>/srt-win.exe`. اضبطه عند دمج واجهة سطر أوامر `srt-win` في ثنائي متعدد الوظائف؛ عندها تمرر العمليات المُشغَّلة `--srt-win` كوسيط `argv[1]` ليتمكن موزّع المُضمِّن من توجيهها إلى `srt_win::run_from_args`.

### القيود المعروفة

- **إبطال الشهادة في schannel.** جلب CRL/OCSP من CryptoAPI يخرج عبر WinHTTP تحت رمز المتصل، متجاهلاً بيئة البروكسي، لذا يتم حظره بواسطة حاجز الخروج (egress fence) في WFP. الأدوات التي تستخدم schannel مع تفعيل فحص الإبطال افتراضيًا تفشل مع `CRYPT_E_REVOCATION_OFFLINE` (`0x80092013`) ما لم يتم تعطيل الإبطال لكل أداة: `curl --ssl-no-revoke`, `git -c http.schannelCheckRevoke=false`, `CARGO_HTTP_CHECK_REVOKE=false`. لا تفحص `Invoke-WebRequest` و .NET `HttpClient` و `gh` الإبطال افتراضيًا ولا تتأثر. يُخطط لتوفير نقطة توزيع CRL من البروكسي المحلي (loopback) لإزالة هذا الحل البديل.

- **تثبيتات الأدوات لكل مستخدم لا يمكن الوصول إليها.** تعمل العملية المعزولة كمستخدم `srt-sandbox` وليس كمستخدمك، لذا الأدوات المثبتة ضمن ملفك الشخصي (Node المُدار عبر nvm/fnm، حزم `winget`/Scoop لكل مستخدم، `pip install --user`, `%LOCALAPPDATA%\Programs\…`) تُحل من `PATH` الموروث ولكن لا يمكن لحساب وضع الحماية فتحها. يُفضَّل استخدام تثبيتات على مستوى الجهاز (`Program Files`, `choco`/`winget --scope machine`)، أو إضافة مسارات الملف الشخصي المحددة إلى `filesystem.allowRead`.

- **تجاوزات `filesystem.allowRead` / `filesystem.allowWrite` لكل تنفيذ غير مدعومة.** تعمل `allowRead`/`allowWrite` على مستوى الجلسة (في الإعداد الممرَّر إلى `initialize()`) كما هو موصوف أعلاه؛ تمريرها لكل أمر في `customConfig` الخاص بـ `wrapWithSandbox` يسبب خطأ — تُطبَّق الأذونات على مستوى الجلسة عبر `srt-win acl grant` في `initialize()`، و`srt-win exec` يكشف فقط عن حالات الرفض لكل تنفيذ.

- **`proxyAuthToken` ظاهر في سطر أوامر المُشغِّل.** تُمرَّر بيئة البروكسي (بما في ذلك `HTTP_PROXY=http://srt:<token>@127.0.0.1:…`) إلى المُشغِّل ثنائي القفز كوسائط `--env` في argv الخاص بـ `srt-win exec`، لذا يمكن لأي كيان محلي لديه صلاحية فتح عملية المُشغِّل مع `PROCESS_QUERY_LIMITED_INFORMATION` قراءة الرمز. الرمز موجود ليتمكن المعالج المعزول من المصادقة على البروكسي المحلي، لذا فهو ليس سرًا من وضع الحماية نفسه؛ على جهاز تطوير أحادي المستخدم يكون هذا مقبولًا عمومًا، لكن على مضيف مشترك تعامل مع قائمة السماح بالبروكسي على أنها قابلة للوصول من قبل كيانات أخرى في نفس الجلسة.

- **حل أسماء DNS عبر محلل النظام غير مُسيَّج.** تخدم خدمة `Dnscache` التي تعمل كـ `NETWORK SERVICE` الدالة `getaddrinfo()`، لذا ينجح حل الأسماء حتى وإن كان `connect()` اللاحق من العملية المعزولة محظورًا. الأدوات التي تقوم بحل أسماء خاصة بها عبر UDP/53 (`nslookup`, `dig`) مُسيَّجة. هذا يعكس سلوك macOS.

### إلغاء التثبيت```powershell
npx @anthropic-ai/sandbox-runtime windows-uninstall

Removes the WFP filter set, the srt-sandbox account and its profile, the sandbox-runtime-users group, and clears the credential/setup marker from state.db (one UAC prompt). %LOCALAPPDATA%\sandbox-runtime\state.db itself is left in place (it is ACL-stamped broker-only); delete the directory manually for a full sweep.

التطوير```bash

Install dependencies

npm install

Build the project

npm run build

Run tests

npm test

Type checking

npm run typecheck

Lint code

npm run lint

Format code

npm run format

### بناء ثنائيات Seccomp

يتم تجميع مرشح BPF ومُحمّل `apply-seccomp` من مصدر C في `vendor/seccomp-src/` عبر `npm run build:seccomp` (لينكس فقط؛ يتطلب `gcc` و `libseccomp-dev`). تشغّله CI قبل الاختبارات على كل معمارية لينكس، ويبني سير عمل الإصدار كلا المعماريتين ويضمّنهما في الحزمة المنشورة.

## تفاصيل التنفيذ

### بنية عزل الشبكة

يعمل الصندوق الرملي على تشغيل خوادم وكيل HTTP وSOCKS5 على الجهاز المضيف تقوم بتصفية جميع طلبات الشبكة بناءً على قواعد الأذونات:

1. **حركة HTTP/HTTPS**: يعترض خادم وكيل HTTP الطلبات ويتحقق منها وفقًا للنطاقات المسموح بها/المرفوضة.
2. **حركة الشبكة الأخرى**: يتعامل وكيل SOCKS5 مع جميع اتصالات TCP الأخرى (SSH، واتصالات قواعد البيانات، إلخ.)
3. **فرض الأذونات**: تفرض الخوادم الوكيلة قواعد `permissions` من إعداداتك.

**الاتصال بالوكيل الخاص بكل نظام أساسي:**

- **لينكس**: يتم توجيه الطلبات عبر نظام الملفات باستخدام مقابس نطاق يونكس (باستخدام `socat` للربط). تتم إزالة مساحة اسم الشبكة من حاوية bubblewrap، مما يضمن أن جميع حركة الشبكة يجب أن تمر عبر الخوادم الوكيلة.

- **macOS**: يسمح ملف تعريف Seatbelt بالاتصال فقط بمنافذ localhost المحددة التي تستمع عليها الخوادم الوكيلة. يتم حظر جميع وصول الشبكة الأخرى.

- **ويندوز**: يمنع عامل تصفية WFP `ALE_AUTH_CONNECT` كل اتصال صادر من حساب `srt-sandbox` باستثناء الاتصال الحلقي بنطاق منافذ الوكيل المُعد. ترتبط الخوادم الوكيلة داخل هذا النطاق. تشير متغيرات البيئة (`HTTP_PROXY`، `HTTPS_PROXY`، `ALL_PROXY`، …) بالأدوات إلى الخوادم الوكيلة، لكن عامل تصفية WFP هو الحدود — فالعملية التي تتجاهلها أو تلغيها ما تزال محاطة بسياج.

### عزل نظام الملفات

يتم تطبيق قيود نظام الملفات على مستوى نظام التشغيل:

- **macOS**: يستخدم `sandbox-exec` مع ملفات تعريف Seatbelt المُولّدة ديناميكيًا والتي تحدد مسارات القراءة/الكتابة المسموح بها.
- **لينكس**: يستخدم `bubblewrap` مع عمليات تثبيت bind، مع تحديد الدلائل كقراءة فقط أو قراءة-كتابة بناءً على الإعدادات.
- **ويندوز**: يكتب ACEs صريحة `(OI)(CI)` إضافية لـ SID الخاص بـ `srt-sandbox` على المسارات المُعدّة (ALLOW على `allowRead`/`allowWrite`, وDENY على `denyRead`/`denyWrite`)، ثم يزيلها عند `reset()`.

**أذونات نظام الملفات الافتراضية:**

- **القراءة** (منع ثم السماح): مسموح بها في كل مكان افتراضيًا. يمكنك منع مناطق واسعة، ثم إعادة السماح بمسارات محددة داخلها. `allowRead` له أولوية على `denyRead`.

  - مثال: `denyRead: ["~/.ssh"]` لمنع الوصول إلى مفاتيح SSH.
  - مثال: `denyRead: ["/Users"], allowRead: ["."]` لمنع كل `/Users` باستثناء مساحة العمل.
  - `denyRead: []` فارغ = وصول قراءة كامل (لا شيء ممنوع).

- **الكتابة** (السماح فقط): ممنوعة في كل مكان افتراضيًا. يجب عليك السماح بالمسارات صراحةً.
  - مثال: `allowWrite: [".", "/tmp"]` للسماح بالكتابة إلى الدليل الحالي و /tmp.
  - `allowWrite: []` فارغ = لا يوجد وصول للكتابة (لا شيء مسموح به).
  - `denyWrite` ينشئ استثناءات داخل المسارات المسموح بها (المنع له الأولوية).

**الأولوية معاكسة عمدًا للقراءة مقابل الكتابة:** `allowRead` يتجاوز `denyRead`، بينما `denyWrite` يتجاوز `allowWrite`. يتيح لك هذا اقتطاع مناطق قابلة للقراءة داخل مناطق ممنوعة، واقتطاع مناطق محمية داخل مناطق قابلة للكتابة.

### مسارات المنع الإلزامية (الملفات المحمية تلقائيًا)

بعض الملفات والدلائل الحساسة **محظورة دائمًا من الكتابة**، حتى لو كانت ضمن مسار كتابة مسموح به. يوفر هذا دفاعًا متعمقًا ضد الهروب من الصندوق الرملي والعبث بالإعدادات.

**الملفات المحظورة دائمًا:**

- ملفات إعدادات الصدفة: `.bashrc`, `.bash_profile`, `.zshrc`, `.zprofile`, `.profile`
- ملفات إعدادات Git: `.gitconfig`, `.gitmodules`
- ملفات حساسة أخرى: `.ripgreprc`, `.mcp.json`

**الدلائل المحظورة دائمًا:**

- دلائل بيئة التطوير المتكاملة: `.vscode/`, `.idea/`
- دلائل إعدادات Claude: `.claude/commands/`, `.claude/agents/`
- خطافات Git والإعدادات: `.git/hooks/`, `.git/config`

هذه المسارات محظورة تلقائيًا - لا تحتاج إلى إضافتها إلى `denyWrite`. على سبيل المثال، حتى مع `allowWrite: ["."]`، ستفشل الكتابة إلى `.bashrc` أو `.git/hooks/pre-commit`:```bash
$ srt 'echo "malicious" >> .bashrc'
/bin/bash: .bashrc: Operation not permitted

$ srt 'echo "bad" > .git/hooks/pre-commit'
/bin/bash: .git/hooks/pre-commit: Operation not permitted

ملاحظة (Linux): على Linux، مسارات المنع الإلزامية تحجب الملفات الموجودة بالفعل فقط. لا يمكن حجب الملفات غير الموجودة ضمن هذه الأنماط عبر أسلوب bind-mount في bubblewrap. يستخدم macOS أنماط glob التي تحجب الملفات الموجودة والجديدة معًا.

عمق البحث على Linux: على Linux، يستخدم الصندوق الرملي ripgrep لمسح الملفات الخطيرة في المجلدات الفرعية ضمن مسارات الكتابة المسموح بها. افتراضيًا، يبحث حتى عمق 3 مستويات لتحسين الأداء. يمكنك ضبط هذا عبر mandatoryDenySearchDepth:```json { "mandatoryDenySearchDepth": 5, "filesystem": { "allowWrite": ["."] } }

- الافتراضي: `3` (البحث حتى 3 مستويات في العمق)
- النطاق: من `1` إلى `10`
- القيم الأعلى توفر حماية أكبر ولكن بأداء أبطأ
- الملفات في CWD (العمق 0) محمية دائمًا بغض النظر عن هذا الإعداد

### قيود مقابس Unix (Linux)

على نظام Linux، يستخدم صندوق الرمل **seccomp BPF (Berkeley Packet Filter)** لحظر إنشاء مقابس نطاق Unix على مستوى استدعاء النظام (syscall). يوفر هذا طبقة إضافية من الأمان لمنع العمليات من إنشاء مقابس نطاق Unix جديدة للاتصال المحلي بين العمليات (IPC) (ما لم يُسمح بذلك صراحة).

**كيف يعمل:**

1. **مرشح BPF مدمج**: تأتي الحزمة مع ملف ثنائي ثابت `apply-seccomp` لمعماريتي x64 وarm64 مع مرشح seccomp BPF مضمّن. المرشح خاص بالمعمارية لكنه مستقل عن libc، لذا يعمل الملف الثنائي مع كل من glibc وmusl.

2. **الاكتشاف في وقت التشغيل**: يكتشف صندوق الرمل تلقائيًا معمارية نظامك ويستخدم الملف الثنائي `apply-seccomp` المطابق.

3. **تصفية استدعاءات النظام**: يعترض مرشح BPF استدعاء النظام `socket()` ويمنع إنشاء مقابس `AF_UNIX` بإرجاع `EPERM`. يمنع هذا الكود المعزول في صندوق الرمل من إنشاء مقابس نطاق Unix جديدة.

4. **تطبيق على مرحلتين باستخدام الملف الثنائي apply-seccomp**:
   - ينشئ bwrap الخارجي صندوق الرمل مع قيود على نظام الملفات والشبكة ومساحة اسم PID
   - تبدأ عمليات جسر الشبكة (socat) داخل صندوق الرمل (تحتاج إلى مقابس Unix)
   - ينشئ apply-seccomp مساحة اسم متداخلة user+PID+mount ويعيد تركيب `/proc`
   - داخل مساحة الاسم المتداخلة، يعمل apply-seccomp كـ PID 1 (init/reaper غير قابل للتفريغ)
   - يقوم apply-seccomp بعمل fork، ويطبق مرشح seccomp عبر `prctl()`، وينفذ أمر المستخدم
   - يعمل أمر المستخدم مع جميع قيود صندوق الرمل بالإضافة إلى حظر إنشاء مقابس Unix

**عزل مساحة اسم PID**: تضمن مساحة اسم PID المتداخلة أن أمر المستخدم لا يمكنه رؤية أو مخاطبة أي عملية تعمل بدون مرشح seccomp (init الخاص بـ bwrap، أو غلاف shell، أو مساعدات socat). يحافظ هذا على حدود seccomp سليمة بغض النظر عن `kernel.yama.ptrace_scope`، نظرًا لأن المساعدات غير المفلترة لا يمكن الوصول إليها عبر `ptrace` أو `/proc/N/mem`. يضبط PID 1 الداخلي `PR_SET_DUMPABLE=0` بحيث لا يمكن تتبعه عبر ptrace أيضًا. إذا فشل إنشاء مساحة الاسم المتداخلة، يتوقف apply-seccomp بدلاً من العمل بدون عزل.

**حدود الأمان**: يحظر المرشح `socket(AF_UNIX, ...)` واستدعاءات النظام `io_uring_setup`/`io_uring_enter`/`io_uring_register` (الثلاثة الأخيرة لأن `IORING_OP_SOCKET` على Linux 5.19+ كان سيتجاوز قاعدة `socket()`). لا يمنع العمليات على واصفات ملفات مقابس Unix الموروثة من العمليات الأصلية أو الممررة عبر `SCM_RIGHTS`. في معظم سيناريوهات العزل، يكفي حظر إنشاء المقابس لمنع الاتصال غير المصرح به بين العمليات (IPC).

**صفر تبعيات وقت التشغيل**: يتم تضمين ملفات apply-seccomp الثنائية الثابتة المبنية مسبقًا ومرشحات BPF المولّدة مسبقًا لمعماريتي x64 وarm64. لا حاجة لأدوات تجميع أو تبعيات خارجية في وقت التشغيل.

**دعم المعماريات**: معماريتا x64 وarm64 مدعومتان بالكامل مع ملفات ثنائية مبنية مسبقًا. المعماريات الأخرى غير مدعومة حاليًا. لاستخدام العزل بدون حظر مقابس Unix على معماريات غير مدعومة، اضبط `allowAllUnixSockets: true` في إعداداتك.

### كشف الانتهاكات ومراقبتها

عندما تحاول عملية معزولة في صندوق الرمل الوصول إلى مورد مقيد:

1. **يحظر العملية** على مستوى نظام التشغيل (يعيد خطأ `EPERM`)
2. **يسجل الانتهاك** (آليات خاصة بالمنصة)
3. **يخطر المستخدم** (في Claude Code، يؤدي هذا إلى ظهور مطالبة إذن)

**macOS**: يصل وقت تشغيل صندوق الرمل إلى مخزن سجلات انتهاكات صندوق الرمل في نظام macOS. يوفر هذا إشعارات في الوقت الفعلي مع معلومات مفصلة حول ما تمت محاولته ولماذا تم حظره. هذه هي نفس الآلية التي يستخدمها Claude Code لكشف الانتهاكات.```bash
# View sandbox violations in real-time
log stream --predicate 'process == "sandbox-exec"' --style syslog

لينكس: لا يوفر Bubblewrap إبلاغًا مدمجًا عن الانتهاكات. استخدم strace لتتبع استدعاءات النظام وتحديد العمليات المحظورة:```bash

Trace all denied operations

strace -f srt 2>&1 | grep EPERM

Trace specific file operations

strace -f -e trace=open,openat,stat,access srt 2>&1 | grep EPERM

Trace network operations

strace -f -e trace=network srt 2>&1 | grep EPERM

### متقدم: استخدم وكيلك الخاص

لتصفية شبكة أكثر تطورًا، يمكنك تكوين بيئة الاختبار (sandbox) لاستخدام وكيلك الخاص بدلاً من الوكيل المدمج. يتيح ذلك:

- **فحص الحركة المرورية**: استخدم أدوات مثل [mitmproxy](https://mitmproxy.org/) لفحص وتعديل الحركة المرورية
- **منطق تصفية مخصص**: تنفيذ قواعد معقدة تتجاوز قوائم النطاقات المسموح بها
- **تسجيل التدقيق**: تسجيل جميع طلبات الشبكة لأغراض الامتثال أو التصحيح

**مثال باستخدام mitmproxy:**```bash
# Start mitmproxy with custom filtering script
mitmproxy -s custom_filter.py --listen-port 8888

Note: تكوين البروكسي المخصص غير مدعوم بعد في تنسيق الإعدادات الجديد. ستتم إضافة هذه الميزة في إصدار مستقبلي.

اعتبار أمني مهم: حتى مع قوائم السماح للنطاقات، قد توجد نواقل تسريب بيانات. على سبيل المثال، السماح بـ github.com يتيح لعملية ما الدفع إلى أي مستودع. مع بروكسي MITM مخصص وإعداد شهادات مناسب، يمكنك فحص استدعاءات API محددة وتصفيتها لمنع ذلك.

قيود عزل الشبكة

  • قيود عزل الشبكة: يعمل نظام تصفية الشبكة عن طريق تقييد النطاقات التي يُسمح للعمليات بالاتصال بها. وهو لا يفحص حركة المرور التي تمر عبر البروكسي بخلاف ذلك، ويتحمل المستخدمون مسؤولية ضمان السماح بالنطاقات الموثوقة فقط في سياستهم.
يجب أن يكون المستخدمون على دراية بالمخاطر المحتملة الناتجة عن السماح بنطاقات واسعة مثل `github.com` التي قد تسمح بتسريب البيانات. أيضًا، في بعض الحالات قد يكون من الممكن تجاوز تصفية الشبكة عبر [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting).
  • تصعيد الامتيازات عبر مقابس يونكس: يمكن لإعداد allowUnixSockets منح وصول غير مقصود إلى خدمات نظام قوية قد تؤدي إلى تجاوزات في عزل الحماية. على سبيل المثال، إذا تم استخدامه للسماح بالوصول إلى /var/run/docker.sock فإن ذلك سيمنح فعليًا وصولًا إلى النظام المضيف عبر استغلال مقبس دوكر. يُشجع المستخدمون على النظر بعناية في أي مقابس يونكس يسمحون بها عبر بيئة العزل.
  • تصعيد صلاحيات نظام الملفات: يمكن لصلاحيات الكتابة الواسعة بشكل مفرط في نظام الملفات أن تمكّن هجمات تصعيد الامتيازات. السماح بالكتابة إلى أدلة تحتوي على ملفات تنفيذية في $PATH، أو أدلة إعدادات النظام، أو ملفات إعدادات الصدفة للمستخدم (.bashrc, .zshrc) يمكن أن يؤدي إلى تنفيذ كود في سياقات أمنية مختلفة عندما يصل مستخدمون آخرون أو عمليات النظام إلى هذه الملفات.
  • قوة عزل لينكس: يوفر تنفيذ لينكس عزلًا قويًا لنظام الملفات والشبكة ولكنه يتضمن وضع enableWeakerNestedSandbox الذي يتيح العمل داخل بيئات دوكر بدون مساحات أسماء مميزة. يضعف هذا الخيار الأمان بشكل كبير ويجب استخدامه فقط في الحالات التي يتم فيها فرض عزل إضافي بوسائل أخرى.
  • عزل شبكة أضعف (macOS): يعيد خيار enableWeakerNetworkIsolation تمكين الوصول إلى com.apple.trustd.agent، وهو مطلوب لبرامج Go للتحقق من شهادات TLS عبر إطار عمل الأمان في macOS. يفتح هذا ناقلًا محتملًا لتسريب البيانات عبر خدمة trustd ويجب تمكينه فقط عندما يكون التحقق من TLS في Go مطلوبًا (على سبيل المثال، عند استخدام httpProxyPort مع بروكسي MITM وشهادة CA مخصصة).
  • أحداث Apple (macOS): يعيد خيار allowAppleEvents تمكين إرسال أحداث Apple وطلبات فتح Launch Services ((allow appleevent-send)، و(allow lsopen)، وعمليات mach-lookups لـ com.apple.coreservices.appleevents وcom.apple.CoreServices.coreservicesd وcom.apple.coreservices.quarantine-resolver)، والتي تتطلبها أدوات open وosascript وأدوات فتح عناوين URL. مع السماح بهذه، يمكن لأمر في بيئة العزل تشغيل تطبيقات عشوائية دون مطالبة المستخدم، وتعمل التطبيقات المشغّلة خارج بيئة العزل تمامًا — لذا يزيل هذا الخيار عزل تنفيذ الكود، وليس مجرد إضعافه. البرمجة النصية للتطبيقات قيد التشغيل بالفعل عبر أحداث Apple تخضع أيضًا لموافقة أتمتة TCC في macOS، لكن التشغيل عبر open ليس كذلك. قم بتمكين هذا فقط عندما تحتاج الأوامر داخل بيئة العزل فعليًا إلى فتح عناوين URL أو تطبيقات.

القيود المعروفة والعمل المستقبلي

تجاوز بروكسي لينكس: يستخدم حاليًا متغيرات البيئة (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) لتوجيه حركة المرور عبر البروكسيات. يعمل هذا مع معظم التطبيقات ولكنه قد يُتجاهل بواسطة البرامج التي لا تحترم هذه المتغيرات، مما يؤدي إلى عدم قدرتها على الاتصال بالإنترنت.

تحسينات مستقبلية:

  • دعم Proxychains: إضافة دعم لـ proxychains مع LD_PRELOAD على لينكس لاعتراض استدعاءات الشبكة على مستوى أدنى، مما يجعل التجاوز أكثر صعوبة

  • مراقبة انتهاكات لينكس: تنفيذ كشف تلقائي للانتهاكات يعتمد على strace في لينكس، مدمجًا مع مخزن الانتهاكات. حاليًا، يجب على مستخدمي لينكس تشغيل strace يدويًا لرؤية الانتهاكات، على عكس macOS الذي يوفر مراقبة تلقائية للانتهاكات عبر مخزن سجل النظام

اقرأ المزيد

الفئات

أدوات دفاعيةأمن الحاوياتالتحليل الديناميكي (عزل)تدقيق التكوينالمحاكاة الافتراضية للأمانأمن الشبكاتالاستجابة للحوادث