Claude Code في حاوية تطوير معزولة

بيئة تطوير معزولة (devcontainer) لتشغيل Claude Code مع تفعيل bypassPermissions بأمان. صُممت في Trail of Bits لسير عمل المراجعات الأمنية.

لماذا نستخدم هذا؟

تشغيل Claude مع bypassPermissions على جهازك المضيف أمر محفوف بالمخاطر—إذ يمكنه تنفيذ أي أمر دون تأكيد. توفر حاوية التطوير هذه عزلًا لنظام الملفات بحيث تحصل على فوائد إنتاجية Claude غير المقيّد دون المخاطرة بنظامك المضيف.

مصممة من أجل:

• المراجعات الأمنية: مراجعة كود العملاء دون المخاطرة بجهازك المضيف
• المستودعات غير الموثوقة: استكشاف قواعد بيانات كود غير معروفة بأمان
• العمل التجريبي: ترك Claude يعدّل الكود بحرية داخل بيئة معزولة
• المشاريع متعددة المستودعات: العمل على عدة مستودعات مترابطة

المتطلبات الأساسية

• بيئة تشغيل Docker (واحدة من):

  • Docker Desktop - تأكد من أنه يعمل
  • OrbStack
  • Colima: brew install colima docker && colima start

• لأعمال الطرفية الطرفية (تثبيت لمرة واحدة):

  root@kitploit:~

  npm install -g @devcontainers/cli
  git clone https://github.com/trailofbits/claude-code-devcontainer ~/.claude-devcontainer
  ~/.claude-devcontainer/install.sh self-install
  

# إيقاف وحذف الجهاز الافتراضي الحالي (يزيل الحاويات والصور)
colima stop && colima delete

# البدء بالإعدادات المحسّنة
colima start \
  --cpu 4 \
  --memory 8 \
  --disk 100 \
  --vm-type vz \
  --vz-rosetta \
  --mount-type virtiofs

بدء سريع

اختر النمط الذي يناسب سير عملك:

النمط أ: حاوية لكل مشروع (معزولة)

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

الطرفية:

git clone <untrusted-repo>
cd untrusted-repo
devc .          # تثبيت القالب + تشغيل الحاوية
devc shell      # فتح شل داخل الحاوية

VS Code / Cursor:

1. ثبّت إضافة Dev Containers:

   • VS Code: ms-vscode-remote.remote-containers
   • Cursor: anysphere.remote-containers

2. قم بإعداد devcontainer (اختر أحد الخيارات):

   root@kitploit:~

   # الخيار أ: استخدام devc (موصى به)
   devc .
   
   # الخيار ب: الاستنساخ يدويًا
   git clone https://github.com/trailofbits/claude-code-devcontainer .devcontainer/
   

3. افتح مجلد مشروعك في VS Code، ثم:

   • اضغط Cmd+Shift+P (على Mac) أو Ctrl+Shift+P (على Windows/Linux)
   • اكتب "Reopen in Container" واختر Dev Containers: Reopen in Container

النمط ب: حاوية مساحة عمل مشتركة (مجموعة)

يحتوي مجلد رئيسي على إعداد devcontainer، وتستنسخ داخله عدة مستودعات. وحدات تخزين مشتركة عبر جميع المستودعات. الأفضل لمشاريع العملاء، أو المستودعات المترابطة، أو العمل المستمر.

# إنشاء مساحة عمل لمشروع عميل
mkdir -p ~/sandbox/client-name
cd ~/sandbox/client-name
devc .          # تثبيت القالب + تشغيل الحاوية
devc shell      # فتح شل داخل الحاوية

# داخل الحاوية:
git clone <client-repo-1>
git clone <client-repo-2>
cd client-repo-1
claude          # جاهز للعمل

المصادقة المستندة إلى الرمز المميز (بدون واجهة رسومية)

للخوادم بدون واجهة رسومية أو لتخطي معالج تسجيل الدخول التفاعلي:

claude setup-token                          # يُشغّل على المضيف، لمرة واحدة
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
devc rebuild                                # إعادة البناء مع الرمز المميز

يتم تمرير الرمز المميز إلى الحاوية. عند كل إنشاء للحاوية، يقوم post_install.py بتشغيل مصافحة مصادقة لمرة واحدة بحيث يبدأ claude دون معالج تسجيل الدخول.

يعمل هذا كحل بديل لمعالج الإعداد التفاعلي في Claude Code الذي يظهر دائمًا في الحاويات، حتى مع وجود بيانات اعتماد صالحة (#8938).

إذا لم تعيّن رمزًا مميزًا، فسيعمل تدفق تسجيل الدخول التفاعلي كما كان سابقًا.

أوامر المساعدة في CLI

devc .              تثبيت القالب + تشغيل الحاوية في الدليل الحالي
devc up             تشغيل حاوية التطوير
devc rebuild        إعادة بناء الحاوية (يحافظ على وحدات التخزين الدائمة)
devc destroy [-f]   إزالة الحاوية ووحدات التخزين والصور للمشروع الحالي
devc down           إيقاف الحاوية
devc shell          فتح شل zsh داخل الحاوية
devc exec CMD       تنفيذ أمر داخل الحاوية
devc upgrade        ترقية Claude Code داخل الحاوية
devc mount SRC DST  إضافة ربط تحميل (مضيف ← حاوية)
devc sync [NAME]    مزامنة جلسات Claude Code من حاويات التطوير إلى المضيف
devc template DIR   نسخ ملفات devcontainer إلى دليل
devc self-install   تثبيت devc في ~/.local/bin

ملاحظة: استخدم devc destroy لتنظيف موارد Docker الخاصة بمشروع ما. إزالة الحاويات يدويًا (مثلًا docker rm) ستترك وحدات تخزين وصورًا يتيمة لن يتمكن devc destroy من العثور عليها.

مزامنة الجلسات لأمر /insights

يقوم أمر /insights في Claude Code بتحليل سجل جلساتك، لكنه يقرأ فقط من ~/.claude/projects/ على المضيف. الجلسات داخل وحدات تخزين حاوية التطوير غير مرئية له.

يقوم devc sync بنسخ سجلات الجلسات من جميع حاويات التطوير (قيد التشغيل والمتوقفة) إلى المضيف بحيث يمكن لـ /insights تضمينها:

devc sync              # مزامنة جميع حاويات التطوير
devc sync crypto       # تصفية حسب اسم المشروع (تطابق جزئي)

يتم اكتشاف حاويات التطوير تلقائيًا عبر تسميات Docker—لا حاجة لمعرفة أسماء الحاويات أو معرّفاتها. المزامنة تزايدية، لذا يمكن تشغيلها مرارًا بأمان.

مشاركة الملفات

VS Code / Cursor

اسحب الملفات من جهاز المضيف إلى لوحة Explorer في VS Code—سيتم نسخها إلى /workspace/ تلقائيًا. لا حاجة إلى أي إعداد.

الطرفية: devc mount

لجعل دليل مضيف متاحًا داخل الحاوية:

devc mount ~/drop /drop           # قراءة وكتابة
devc mount ~/secrets /secrets --readonly

يضيف هذا ربط تحميل إلى devcontainer.json ويعيد إنشاء الحاوية. يتم الحفاظ على التحميلات الموجودة عبر تحديثات devc template.

نصيحة: "مجلد إسقاط" مشترك مفيد لتمرير الملفات دون تحميل دليل منزلك بالكامل.

ملاحظة أمنية: تجنب تحميل أدلة مضيف كبيرة (مثل $HOME). كل مسار محمّل قابل للكتابة من داخل الحاوية ما لم يتم تحديد --readonly، مما يضعف عزل نظام الملفات الذي يوفره هذا المشروع.

عزل الشبكة

بشكل افتراضي، تتمتع الحاويات بوصول شبكة صادر كامل. لأمان أكثر صرامة، استخدم iptables لتقييد الوصول إلى الشبكة.

متى يتم تفعيل عزل الشبكة

• مراجعة كود قد يحتوي على تبعيات خبيثة
• تدقيق برمجيات تحتوي على تتبع أو سلوك اتصال بالمنزل
• أقصى عزل للمراجعات شديدة الحساسية

مثال: Claude + GitHub + سجلات الحزم

sudo iptables -A OUTPUT -d api.anthropic.com -j ACCEPT
sudo iptables -A OUTPUT -d github.com -j ACCEPT
sudo iptables -A OUTPUT -d raw.githubusercontent.com -j ACCEPT
sudo iptables -A OUTPUT -d registry.npmjs.org -j ACCEPT
sudo iptables -A OUTPUT -d pypi.org -j ACCEPT
sudo iptables -A OUTPUT -d files.pythonhosted.org -j ACCEPT
sudo iptables -A OUTPUT -o lo -j ACCEPT
sudo iptables -A OUTPUT -j DROP

المفاضلات

• يمنع مديري الحزم ما لم تقم بإدراج السجلات في القائمة المسموحة
• قد يكسر الأدوات التي تتطلب وصولًا إلى الشبكة
• تحليل DNS ما زال يعمل (فكر في حظره إذا كنت شديد الحذر)

نموذج التهديد

التهديد الأساسي الذي يعالجه هذا المشروع هو تشغيل Claude Code لأوامر عشوائية على جهازك المضيف. عندما يكون bypassPermissions مفعّلًا، ينفذ Claude أوامر الشل، ويثبّت الحزم، ويعدّل الملفات دون تأكيد. على جهاز مضيف، يعني هذا أنه يمكنه تعديل إعدادات الشل لديك، أو تنفيذ rm -rf خارج دليل المشروع، أو إساءة استخدام بيانات الاعتماد المخزنة محليًا. تحصر حاوية التطوير كل ذلك في حاوية قابلة للتخلص حيث يقتصر نصف قطر الانفجار على /workspace.

تتضمن الحاوية أدوات تطوير شائعة بحيث يمكنك القيام بكل أعمال التطوير داخلها—وليس مجرد تشغيل Claude. سير العمل المقصود هو: استنساخ مستودع، وتشغيل حاوية التطوير، والعمل بالكامل داخلها. إذا كان مشروعك يحتاج إلى بيئات تشغيل أو أدوات إضافية تتجاوز ما هو مضمّن، فإما أضفها إلى Dockerfile للاستخدام المتكرر أو ثبّتها بشكل مؤقت باستخدام devc exec.

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

نموذج الأمان

توفر حاوية التطوير هذه عزلًا لنظام الملفات ولكن ليس حماية كاملة بالعزل.

معزول: نظام الملفات (ملفات المضيف غير قابلة للوصول)، العمليات (معزولة عن المضيف)، تثبيت الحزم (تبقى داخل الحاوية)

غير معزول: الشبكة (وصول صادر كامل افتراضيًا—انظر عزل الشبكة)، هوية git (~/.gitconfig محمّل للقراءة فقط)، وكيل SSH (المقبس مُمرَّر، المفاتيح تبقى على المضيف)، مقبس Docker (غير محمّل افتراضيًا)

تكوّن الحاوية تلقائيًا وضع bypassPermissions—ينفذ Claude الأوامر دون تأكيد. سيكون هذا محفوفًا بالمخاطر على جهاز مضيف، لكن الحاوية نفسها هي بيئة العزل.

تفاصيل الحاوية

تُخزَّن وحدات التخزين خارج الحاوية، لذا يبقى سجل الشل الخاص بك، وإعدادات Claude، وتسجيل دخول gh حتى بعد devc rebuild. يتم تحميل ~/.gitconfig من المضيف للقراءة فقط لهوية git.

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

"devcontainer CLI not found"

npm install -g @devcontainers/cli

الحاوية لا تبدأ

1. تحقق من أن Docker يعمل
2. جرّب إعادة البناء: devc rebuild
3. افحص السجلات: docker logs $(docker ps -lq)

مصادقة GitHub CLI لا تبقى

قد يحتاج حجم gh إلى إصلاح الملكية:

sudo chown -R $(id -u):$(id -g) ~/.config/gh

Python/uv لا يعمل

تتم إدارة Python عبر uv:

uv run script.py              # تشغيل سكربت
uv add package                # إضافة تبعية للمشروع
uv run --with requests py.py  # تبعية مؤقتة

التطوير

بناء الصورة يدويًا:

devcontainer build --workspace-folder .

اختبار الحاوية:

devcontainer up --workspace-folder .
devcontainer exec --workspace-folder . zsh