Phase 19: Capstone Projects

دراسة كابستون 26: راني صندوق الرمال مع دينيلست و سجن طريق

Type: Build

Languages: Python (stdlib)

Prerequisites: Phase 19 · 25 (verification gates and observation budget), Phase 14 · 33 (instructions as constraints), Phase 14 · 38 (verification gates)

Time: ~90 minutes

أهداف التعلم

• بناء Sandboxغلفة الفصلsubprocess.runمع وقف الوقت، القبض، وتقصير.
• رفض الأمر باسم ضد دينيليست وبشكل هيكلي ضد مفتش
• رفض أي حجة مسار تحل خارج جذور المشروع المعلن.
• رفض طابعات القذيفة عندما يكون وضع القذيفة مغلق.
• أعد المُهيّئSandboxResultيمكن أن تتناول الملاحظة التدريجية والحزمة التقييمية.

المشكلة

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

ثلاث فئات من الفشل تتكرر في آثار العميل.

الأول هو أجهزة تنفيذية خطيرة، نموذج تحت ضغط لإصلاح مشكلة المسار سوف تحاولsudo،chmod -R 777،rm -rf،mkfs،ddلا أحد من هؤلاء ينتمي إلى عملاء، "دانيلست" يلتقطهم باسمهم و باسم مستعار

الثاني هو خدعة الارغف، النموذج الذي قيل لا قذيفة سوف تنبيه هجوم من خلال مترجم:python3 -c "import os; os.system('rm -rf /')"،bash -c '...'،node -e '...'،perl -e '...'يجب أن يعرف المترجم أنّه يعمل مع-c- مثل العلم هو مجرد مكالمة قذيفة مع خطوات إضافية.

الثالث هو الهروب من المسار، ويقول النموذج أن يقرأ./src/main.pyوبدلاً من ذلك يقرأ../../etc/passwdالصندوق السريع يحتجز كل نزاع طريق من خلال حل ذلك من خلالos.path.realpathو تأكيد المُضاف

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

المفهوم

flowchart TD
  Call[ToolCall<br/>already passed gate chain] --> Run["Sandbox.run()"]
  Run --> S1[1. resolve executable against denylist<br/>rm, sudo, mkfs, ...]
  S1 --> S2[2. inspect argv<br/>interpreter -c, shell metachars when shell=False]
  S2 --> S3[3. resolve path-like arguments<br/>against project_root via realpath]
  S3 --> S4[4. spawn subprocess<br/>capture, wall-clock timeout, env scrub]
  S4 --> S5[5. truncate stdout/stderr to max_output_bytes]
  S5 --> Result[SandboxResult<br/>exit_code, stdout, stderr,<br/>truncated, timed_out, denied, reason]

صندوق الرمل لديه أربعة محورات رفض: اسم، argv، المسار، الهيكل. كل محور هو وظيفة نقية من الدعوة، لا عملية فرعية حتى الآن. تنشأ العملية الفرعية فقط بعد مرور كل محور.

• نعمSandboxResultرموز الخروج هي الرمز التقليدي: 0 نجاح، فشل غير صفر، بالإضافة إلى ثلاثة رموز حراسة لرفض (-100) ، وقت_out (-101) ، وتقصر (رمز الخروج هو الحقيقي، مع مجموعة العلامات). دروس أسفل النهر تقرأ هذه النتيجة المهيكلة بدلا من تحليل stderr.

الهندسة المعمارية

flowchart LR
  Harness[AgentHarness<br/>lesson 20-25] -->|call| Sandbox[Sandbox<br/>denylist<br/>path jail<br/>argv inspect<br/>timeout<br/>truncation]
  Sandbox -->|exec| Popen[subprocess.Popen]
  Sandbox --> Result[SandboxResult]

المجموعة هي مجموعة من الأسماء الأساسية القابلة للتنفيذ./bin/rm،/usr/bin/rmيقرر جميعها إلى نفس الاسم الأساسي. يعرف مفتش argv شكل المترجم: أي argv حيث argv[0] هو مترجم وأي arg لاحقا يبدأ ب-cأو-eيتم رفضها.;،|،&،>،<، الظهر ،$()) يسبب الرفض عندما لا يطلب الدعوة صراحة قذيفة.

سجن الطريق هو الجزء الأكثر خفية، صندوق الرمل يقبلproject_rootفي البناء. أي حجة تبدو كمسار (تحتوي على/أو يطابق ملف موجود) يتم تعديلها من خلال os.path.realpathإذا لم يكن الهدف المحل تحت الجذر، رفض. يتم حظر محاولات الهروب من Symlink (رابط رمزي في الجذر من المشروع الذي يشير إلى الخارج) عن طريق التحقق من truepath، وليس المسار الحرفي.

ما ستبني

التنفيذ هوmain.pyبالإضافة إلى اختبارات

1. SandboxResultفئة البيانات: exit_code, stdout, stderr, truncated, timed_out, denied, reason, duration_ms.
2. SandboxConfigفئة البيانات: project_root، max_output_bytes، timeout_seconds، denylist، interpreter_block.
3. Sandboxفئة: run(argv, *, shell=False, cwd=None)يعود الـSandboxResult. . .
4. المساعدون الداخليون في رفض:_check_executable_denylist،_check_argv_interpreter،_check_shell_metachars،_check_path_jail. . .
5. خفض الخروج مع صافيtruncatedالعلم وخط مرشح في التيار المقبض عليه
6. التجربة في الأسفل: سلسلة من المكالمات المشروعة والمعادلة.

الصندوق الرملي يستخدمsubprocess.runمعshell=Falseبطبيعة الحال وcapture_output=True. توقيت الساعة الحائطية يستخدمtimeoutالحجةTimeoutExpired، يقتل صندوق الرمال مجموعة العمليات و يخلق نتيجة

لماذا هذا ليس صندوق رمل حقيقي

لا تستخدم مربع الرمل الدروس مساحات الأسماء أو مجموعات أو seccomp أو gVisor أو Firecracker أو أي عزل على مستوى النواة. أي شيء يمكن أن تفعله العملية الفرعية ، يمكن أن تفعله مربع الرمل. الحماية هي هيكلية: يتم رفض العميل الأكثر شيوعاً دعوات خطيرة ، ويتم إصدار رفض صاخب في قابلية للملاحظة بدلاً من التشغيل بصمت.

بالنسبة لعاملات الإنتاج تقوم بتطبيق طبقة فوق: تشغيل داخل حاوية Docker غير محظورة، تشغيل داخل microVM، إمكانات التخلص من، وضع قراءة فقط للعملية الجذر والشقق dir القراءة-الكتابة، وضع حد على الذاكرة والمتحركات المعالجة المركزية، مسح البيئة إلى قائمة بيضاء آمنة معروفة. الدروس 29 تفعل بعض هذا. عزل النظام التشغيلي خارج نطاق هذا الدروس.

أديرها

bashCopycd phases/19-capstone-projects/26-sandbox-runner-denylist
python3 code/main.py
python3 -m pytest code/tests/ -v

يقوم المشاهد بإنشاء دليل مؤقت، ويقوم بإلقاء ملف نظيف فيه، ثم تشغيل بطارية من المكالمات. النجاح المكالمات القانونية. المكالمات التي تم رفضها تعود إلى SandboxResult مع denied=Trueوسبب، تعود التوقيتtimed_out=True. مجموعات التقطيعtruncated=True. الظهور يطبخ جدول JSON من النتائج و يخرج من الصفر.

كيف يتوافق هذا مع بقية المسار A

دروس 25 أنتج سلسلة البوابة. دروس 26 هي المنفذ الذي يعمل بعد بوابة المسموح بها. دروس 27 تقارن حزمة تقييم نتائج مربع الرمل مع رمز الخروج المتوقع لكل مهمة. دروس 28 ينبعث gen_ai.tool.executionيمتد حول كل واحد Sandbox.runالتدعو، التجربة المشتركة في الدروس 29 تُشغل وكيلًا حقيقيًا للتشفير عبر كلا الطبقتين

This free lesson is part of the AI Engineering from Scratch curriculum. Read the full explanation, run the lesson code, and verify the result in the interactive reader or from the repository source.

Browse the complete course catalog or open this lesson on GitHub.