تنفيذ Shell

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

عندما يقرر LLM أنه يحتاج إلى تنفيذ أمر shell، مثل تثبيت حزمة أو بناء كود أو الاستعلام عن حالة النظام أو تشغيل سكربت، فإنه يستدعي أداة shell بسلسلة الأمر. يقوم PRX بتغليف التنفيذ ضمن backend العزل المُعد، ويفرض مهلة افتراضية 60 ثانية، ويحد الإخراج إلى 1 MB، ويزيل متغيرات البيئة الحساسة قبل تشغيل العملية الفرعية.

عادةً ما تكون أداة shell الأقوى والأكثر تقييدًا ضمن PRX. وهي الهدف الرئيسي لمحرك سياسة الأمان، ومعظم النشرات تضبطها كـ supervised لتتطلب موافقة بشرية قبل التنفيذ.

الإعداد

أداة shell نفسها لا تملك قسم إعداد مستقلًا. سلوكها يُضبط عبر sandbox الأمان وحدود الموارد:

[security.sandbox]
enabled = true
backend = "auto"            # auto | landlock | firejail | bubblewrap | docker | none

[security.resources]
max_cpu_time_seconds = 60
max_memory_mb = 512
max_subprocesses = 10

لجعل shell في وضع supervised (طلب موافقة لكل استدعاء):

[security.tool_policy.tools]
shell = "supervised"

Backends العزل

يدعم PRX خمسة backends للعزل. عندما backend = "auto" يفحص PRX الـ backends المتاحة حسب الأولوية التالية ويختار أول backend متوفر:

Backend	المنصة	مستوى العزل	الكلفة	ملاحظات
Landlock	Linux (5.13+)	LSM لنظام الملفات	منخفضة جدًا	مدمج في النواة دون تبعيات إضافية، ويقيد مسارات الملفات على مستوى النواة.
Firejail	Linux	عزل كامل (شبكة، ملفات، PID)	منخفضة	sandbox مستخدم يدعم --net=none لعزل الشبكة وPID namespace وفلترة seccomp.
Bubblewrap	Linux, macOS	عزل مبني على namespaces	منخفضة	يستخدم user namespaces مع قوائم مسارات قابلة للكتابة/للقراءة فقط.
Docker	أي منصة	حاوية كاملة	مرتفعة	يشغّل الأوامر داخل حاوية مؤقتة. أعلى عزل وأعلى زمن تنفيذ.
None	أي منصة	طبقة التطبيق فقط	بلا كلفة	بدون عزل على مستوى النظام. يظل PRX يفرض المهلة وحد الإخراج، لكن العملية تملك وصولًا كاملًا للنظام.

Landlock

Landlock هو Linux Security Module متاح من نواة 5.13+. يقيد الوصول إلى نظام الملفات على مستوى النواة دون الحاجة إلى صلاحيات root. يستخدمه PRX لتحديد المسارات التي يمكن لأمر shell القراءة والكتابة منها وإليها.

Firejail

يوفّر Firejail عزلًا شاملًا عبر Linux namespaces وseccomp. يمكن تمرير وسائط مخصصة عبر firejail_args:

[security.sandbox]
backend = "firejail"
firejail_args = ["--net=none", "--noroot", "--nosound", "--no3d"]

Bubblewrap

يستخدم Bubblewrap (bwrap) user namespaces لإنشاء بيئات عزل مصغّرة. وهو أخف من Firejail ويعمل في بعض إعدادات macOS:

[security.sandbox.bubblewrap]
allow_network = false
writable_paths = ["/tmp", "/home/user/workspace"]
readonly_paths = ["/usr", "/lib", "/bin"]

Docker

يوفّر Docker عزلًا كاملًا بالحاويات. كل أمر يعمل داخل حاوية جديدة اعتمادًا على الصورة المُعدّة:

[security.sandbox.docker]
image = "prx-sandbox:latest"
network = "none"
memory_limit = "256m"
cpu_limit = "1.0"

الاستخدام

يتم استدعاء أداة shell من قبل LLM أثناء الحلقات الوكيلية. في محادثات الوكيل يولّد LLM استدعاء أداة كالتالي:

{
  "name": "shell",
  "arguments": {
    "command": "ls -la /home/user/project"
  }
}

من CLI يمكنك ملاحظة استدعاءات shell في مخرجات الوكيل. يُظهر استدعاء الأداة الأمر المُنفذ وbackend العزل المستخدم.

تدفق التنفيذ

1. يولّد LLM استدعاء shell مع معامل command.
2. يتحقق محرك سياسة الأمان مما إذا كان الاستدعاء مسموحًا أو مرفوضًا أو يحتاج إشرافًا.
3. عند الإشراف، يطلب PRX موافقة المستخدم قبل المتابعة.
4. يغلف backend العزل الأمر بطبقة العزل المناسبة.
5. تُنقّى متغيرات البيئة (انظر أدناه).
6. ينفّذ الأمر مع مهلة 60 ثانية.
7. يتم التقاط stdout وstderr مع قصهما إلى 1 MB عند الحاجة.
8. تُعاد النتيجة إلى LLM كـ ToolResult بحالة نجاح/فشل.

المعاملات

المعامل	النوع	مطلوب	الافتراضي	الوصف
command	string	نعم	--	أمر shell المراد تنفيذه. يُمرر إلى /bin/sh -c (أو ما يعادله).

تعيد الأداة ToolResult يحتوي على:

الحقل	النوع	الوصف
success	bool	true إذا خرج الأمر بكود 0
output	string	دمج stdout وstderr، مقصوص إلى 1 MB
error	string?	رسالة خطأ إذا فشل الأمر أو تجاوز المهلة

تنقية البيئة

تمرير متغيرات البيئة إلى العمليات الفرعية يقتصر على قائمة بيضاء صارمة. الهدف منع تسريب مفاتيح API أو الرموز السرية الموجودة في بيئة daemon.

متغيرات البيئة المسموح بها:

المتغير	الغرض
PATH	مسار البحث عن الملفات التنفيذية
HOME	مجلد المستخدم
TERM	نوع الطرفية
LANG	لغة locale
LC_ALL	تجاوز locale
LC_CTYPE	locale لنوع المحارف
USER	اسم المستخدم الحالي
SHELL	مسار shell الافتراضي
TMPDIR	المجلد المؤقت

كل المتغيرات الأخرى، بما فيها API_KEY وAWS_SECRET_ACCESS_KEY وGITHUB_TOKEN وOPENAI_API_KEY وأي متغيرات مخصصة، تُزال من بيئة العملية الفرعية. هذا حد أمان ثابت لا يمكن تجاوزه عبر الإعداد.

حدود الموارد

الحد	الافتراضي	قابل للضبط	الوصف
المهلة	60 ثانية	security.resources.max_cpu_time_seconds	أقصى زمن فعلي لكل أمر
حجم الإخراج	1 MB	--	أقصى حجم مدمج لـ stdout + stderr
الذاكرة	512 MB	security.resources.max_memory_mb	أقصى استهلاك ذاكرة لكل أمر
العمليات الفرعية	10	security.resources.max_subprocesses	أقصى عدد عمليات فرعية

عندما يتجاوز الأمر المهلة، يرسل PRX إشارة SIGTERM ثم SIGKILL بعد فترة سماح. وتعرض نتيجة الأداة خطأ مهلة.

عند تجاوز الإخراج 1 MB يتم قصه مع إضافة ملاحظة تفيد بحدوث القص.

الأمان

• عزل sandbox: الأوامر تعمل داخل backend العزل المهيأ لتقييد الوصول إلى الملفات والشبكة والعمليات.
• تنقية البيئة: تمرير 9 متغيرات بيئة فقط من القائمة البيضاء.
• محرك السياسات: كل استدعاء shell يمر عبر سياسة الأمان قبل التنفيذ.
• سجل التدقيق: جميع أوامر shell ونتائجها تسجّل في audit log عند security.audit.enabled = true.
• وضع الإشراف: يمكن وسم أداة shell بـ supervised لطلب موافقة صريحة قبل كل تنفيذ.
• حدود الموارد: حدود صارمة للمهلة والذاكرة وحجم الإخراج وعدد العمليات تمنع استنزاف الموارد.

تخفيف التهديدات

أداة shell هي المسار الأساسي لهجمات حقن المطالبات. إذا تمكّن مهاجم من التأثير على تفكير LLM (مثلًا عبر محتوى مستند خبيث)، فغالبًا سيحاول استخدام shell لتنفيذ أوامر. يخفف PRX هذا الخطر عبر:

1. حصر داخل sandbox: حتى مع تنفيذ أمر خبيث، يبقى ضمن وصول مقيد للملفات والشبكة.
2. تجريد البيئة: مفاتيح API والأسرار لا تُتاح للعملية الفرعية.
3. وضع الإشراف: يمكن للإنسان مراجعة كل أمر قبل التنفيذ.
4. أثر تدقيقي: جميع الأوامر مسجلة للمراجعة والتحليل الجنائي.

مرتبط

• Security Sandbox -- توثيق backends العزل بالتفصيل
• Policy Engine -- قواعد التحكم في الوصول للأدوات
• Configuration Reference -- حقول security.sandbox وsecurity.resources
• نظرة عامة على الأدوات -- جميع الأدوات ونظام التسجيل