Z-Jail

حاجز حماية متعدد الطبقات لتنفيذ الأكواد الأصلية على لينكس.
سبع طبقات دفاع مستقلة — لا تبعيات خارجية، ملف ثنائي PIE بحجم ~73 KiB.

┌──────────────────────────────────────────────────────┐
│                    Z-Jail                            │
├──────────────────────────────────────────────────────┤
│  Truthimatics PV  (evidence-based verdict engine)    │
│  Namespaces       (mount, pid, net, ipc, uts)        │
│  pivot_root       (chroot on steroids)               │
│  Capabilities     (drop all, lock securebits)        │
│  NO_NEW_PRIVS     (no privilege escalation)          │
│  seccomp-BPF      (whitelist: 15 syscalls only)      │
│  Audit            (JSON logging + BLAKE2b hashing)   │
└──────────────────────────────────────────────────────┘

جدول المحتويات

• البداية السريعة
• لماذا Z-Jail
• البنية
• الطبقات
• الاستخدام
• البناء والتثبيت
• الاختبار
• الأداء
• نموذج التهديد
• التوثيق
• خارطة الطريق
• الترخيص

البداية السريعة

git clone https://github.com/Division-36/Z-Jail.git
cd Z-Jail
make
sudo ./z_jail --root=/path/to/rootfs --seccomp-enforce -- /bin/ls

يجب أن يحتوي دليل --root على نظام ملفات أدنى يتضمن الملف الثنائي المستهدف وتبعياته (بالنسبة للملفات الثنائية ثابتة الربط، يكفي الملف الثنائي وحده).

لماذا Z-Jail

حلول العزل الحالية تنطوي على مقايضات:

يسدّ Z-Jail الفجوة بين bwrap (بسيط، بدون seccomp افتراضياً) وnsjail (غني بالميزات، تبعيات ثقيلة). وهو مصمم لـخطوط CI، وتحديات CTF jail، وتقييم الأكواد خفيف الوزن حيث تحتاج إلى دفاع متعمق دون سحب بيئة تشغيل حاويات.

البنية

تدفق البيانات

flowchart LR
    CLI[CLI args] --> P[parse_args]
    P --> C{clone namespaces}
    C -->|child| CR[child_run]
    C -->|parent| W[waitpid]
    CR --> RL[setrlimit]
    RL --> FD[close fds >= 3]
    FD --> DUMP[PR_SET_DUMPABLE=0]
    DUMP --> PV[pivot_root]
    PV --> NNP[PR_SET_NO_NEW_PRIVS]
    NNP --> CAP[drop capabilities]
    CAP --> SC[seccomp-BPF]
    SC --> SIG[signal parent]
    SIG --> EX[execve target]
    W --> A[audit JSON]
    A --> EXIT[exit]

ترتيب الطبقات

تُرتَّب الطبقات بحيث لا يمكن لطبقة لاحقة أن تُبطَل بواسطة طبقة سابقة:

1. setrlimit — وضع سقف لوحدة المعالجة المركزية، ومساحة العناوين، وعدد الملفات، والعمليات قبل أي شيء آخر
2. fd scrub — إغلاق كل واصفات الملفات الموروثة باستثناء أنبوب التقرير
3. PR_SET_DUMPABLE=0 — تعطيل ملفات التفريغ الأساسية، وتأمين /proc/self/mem
4. pivot_root — الانفصال عن نظام ملفات المضيف؛ إلغاء تحميل الجذر القديم بشكل كسول
5. PR_SET_NO_NEW_PRIVS — لا setuid، ولا تصعيد capset بعد هذه النقطة
6. drop_caps — تصفير جميع القدرات، وقفل securebits
7. seccomp-BPF — تقييد استدعاءات النظام إلى القائمة البيضاء فقط
8. signal parent — إخبار العملية الأم بأن بيئة العزل جاهزة
9. execve — استبدال العملية بالملف الثنائي المستهدف

sequenceDiagram
    participant P as Parent
    participant C as Child
    P->>C: clone (NEWNS|NEWPID|NEWNET|NEWIPC|NEWUTS)
    Note over C: setrlimit(CPU, AS, NOFILE, NPROC)
    Note over C: close(all fds > 2)
    Note over C: PR_SET_DUMPABLE=0
    Note over C: pivot_root → chdir("/") → umount -l
    Note over C: PR_SET_NO_NEW_PRIVS
    Note over C: capset(all zero) + securebits
    Note over C: seccomp(SECCOMP_MODE_FILTER, whitelist)
    C->>P: write(pipe, ready=1)
    Note over C: execve(target)
    P->>P: waitpid
    P->>P: write audit JSON

الطبقات

1. النسخة العامة من Truthimatics

محرك أحكام قائم على الأدلة. يجمع ملاحظات موزونة حول الملف الثنائي المنفَّذ ويحدد حكماً نهائياً (DETERMINISTIC أو REJECT أو UNCERTAIN). تحمل كل ملاحظة وزناً؛ أي ملاحظة واحدة بوزن أكبر من 50% من الإجمالي تحسم الحكم.

2. مساحات الأسماء

تُنشأ خمس مساحات أسماء عبر clone():

يتطلب CAP_SYS_ADMIN في مساحة الأسماء الأولية.

3. pivot_root

يستبدل جذر مساحة أسماء التركيب بدليل --root:

1. ربط-تركيب دليل الجذر على نفسه (MS_BIND|MS_REC)
2. pivot_root(new_root, put_old) — مبادلة شجرة التركيب
3. chdir("/") — الانتقال إلى الجذر الجديد
4. umount2("/.pivot_old", MNT_DETACH) — فصل الجذر القديم
5. rmdir("/.pivot_old") — التنظيف

هذا أقوى بصرامة من chroot(2) — لا توجد طريقة للعملية المعزولة للهروب عائدة إلى جذر المضيف، حتى مع CLONE_NEWNS من داخل بيئة العزل (وهو محظور أصلاً بواسطة seccomp).

4. القدرات

تُسقَط جميع القدرات عبر:

capset(hdr, data)  // data = {0, 0, 0}
prctl(SECBIT_KEEP_CAPS_LOCKED | SECBIT_NO_SETUID_FIXUP | ...)

تُسقط العملية setuid/setgid قبل capset بحيث يسري تغيير uid بينما ما تزال CAP_SETUID محتفظاً بها. بعد capset، تختفي جميع القدرات ويُقفل securebits — لا يمكن إعادة التمكين.

5. NO_NEW_PRIVS

prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0);

يمنع العملية أو عملياتها الفرعية من اكتساب امتيازات جديدة عبر الملفات الثنائية setuid، أو قدرات الملفات، أو انتقالات LSM. لا رجعة فيه.

6. seccomp-BPF (whitelist-v1)

قائمة سماح من 15 استدعاء نظام — أي شيء غير موجود في القائمة يحصل على SECCOMP_RET_KILL:

يُولَّد مرشح BPF ديناميكياً: لكل إدخال في القائمة البيضاء، تُصدَر سلسلة قفزات تسمح بالاستدعاء (إذا تطابق استدعاء النظام) أو تصل إلى KILL. تُفحص البنية أولاً (AUDIT_ARCH_X86_64).

يُتحقَّق من المرشح بشكل مستقل عبر اختبار قائم بذاته (tests/seccomp_filter_test.c، نجاح 8/8) ينفّذ fork+execve لحالات اختبار مقابل prctl(PR_SET_SECCOMP) حقيقي دون الحاجة إلى صلاحيات الجذر.

7. التدقيق

كل عملية تنفيذ تُنتج سجلاً بتنسيق JSON:

{
  "schema": "z-jail.audit/v1",
  "build_id": "Z-Jail/v1+dev",
  "timestamp": 1749000000,
  "duration_ns": 8500000,
  "executable": "/bin/ls",
  "verdict": "DETERMINISTIC",
  "exit_code": 0,
  "sandbox": {
    "seccomp_filter": "whitelist-v1",
    "seccomp_whitelist_size": 15,
    "seccomp_arg_rules_size": 2,
    "namespaces": ["mount","pid","net","ipc","uts"],
    "pivot_root": "/var/run/z-jail/roots/default",
    "no_new_privs": true,
    "capabilities_dropped": true
  },
  "content_fingerprint": "0e5751c026e543b2e8ab2eb06099daa1..."
}

يُكتب إلى build/audits/<binary-name>.audit.json. إن content_fingerprint هو تجزئة BLAKE2b-256 للملف الثنائي المستهدف، تُحسب بواسطة العملية الأم بعد انتهاء العملية الفرعية.

الاستخدام

z_jail --root=<dir> [--seccomp-enforce] [--self-hash=<hex>]
       [--quiet] [--verbose] -- <program> [args...]

أمثلة

# Run a static binary with all protections
sudo z_jail --root=./roots --seccomp-enforce -- bin/hello_static

# Run with binary integrity verification
sudo z_jail --root=./roots --seccomp-enforce \
  --self-hash=$(sha256sum z_jail | cut -c1-64) -- bin/program

# Quiet mode (no audit JSON)
sudo z_jail --root=./roots --quiet -- bin/program

رموز الخروج

البناء والتثبيت

المتطلبات

• نواة لينكس ≥ 5.4 (مساحات الأسماء، seccomp-BPF، pivot_root)
• GCC ≥ 11 (مُختبَر على 11.4، 13.2، 15.2)
• لا مكتبات خارجية — فقط سلسلة أدوات C القياسية

الأوامر

make              # build z_jail (~130 KiB PIE binary)
make install      # install to /usr/local/bin + man page
make clean        # remove build artifacts
make dist         # create release tarball
make check        # smoke test (--version + --help)

يُبنى الملف الثنائي كملف تنفيذي مستقل عن الموقع (PIE) مع -fstack-protector-strong و-D_FORTIFY_SOURCE=2 وRELRO كامل و-z now.

خيارات زمن الترجمة

make CC=clang CFLAGS="-O3 -march=native"   # custom compiler/flags

الاختبار

اختبار سريع (بدون صلاحيات الجذر)

# seccomp filter logic (8 tests)
tests/build/seccomp_filter_test

# BLAKE2b known-answer test
tests/build/blake2b_known

لا تحتاج هذه إلى صلاحيات الجذر وتُنجز في أقل من 100 ms.

مجموعة الاختبارات الكاملة

make -C tests setup          # build payloads + test roots
sudo bash tests/run_tests.sh # 17 scenarios

يتطلب صلاحيات الجذر لإنشاء مساحات الأسماء. تغطي مجموعة الاختبارات:

الأداء

قِيس على WSL2 (النواة 6.18.x-microsoft-standard-WSL2، Kali Linux)، 50 عينة لكل أداة، حمولة موحدة (ملف ثنائي ثابت مستقل نصُّه exit_group(0))، مع ضبط الوقت عبر أداة getrusage. راجع docs/BENCHMARKS.md للمنهجية.

مقارنة مباشرة (نفس المضيف، نفس المنهجية)

في الظروف المختبرة، يمتلك Z-Jail أصغر مجموعة مقيمة بين بيئات العزل الثلاث على مستوى العمليات، وزمن استجابة بين bwrap وnsjail. Bubblewrap هو الأسرع لكنه لا يجري أي ترشيح seccomp افتراضياً، لذا يؤدي عملاً تحضيرياً أقل؛ يثبّت Z-Jail قائمة seccomp بيضاء، ويسقط القدرات، وينفّذ pivot_root في كل تشغيل. يتعطل gVisor (runsc) بخطأ segfault على نواة WSL2 هذه ولم يمكن قياسه؛ يعزل Firecracker عبر microVM (إقلاع بارد للجهاز الافتراضي، وهو مقياس مختلف) ويُستبعد من جدول fork-to-exec. هذه أرقام من مضيف واحد — تعامل معها على أنها نسبية.

ملاحظة: الأرقام الموثقة سابقاً (~8 ms، ~4 MiB، ~130 KiB) لا تطابق بناء make حالياً (~73 KiB، ~5.9 ms) ويبدو أنها كانت غير دقيقة؛ أُعيد قياس الأرقام أعلاه على قاعدة الأكواد هذه. ما تزال Truthimatics جزءاً من الكود ولم تُحذف (تقارير axiom_jail القديمة استخدمت ببساطة اسم ملف ثنائي وأداة مختلفة). أُصلح خطأ في انتشار التركيب (mount propagation) اكتُشف أثناء القياس في src/sandbox.c (MS_REC|MS_PRIVATE قبل ربط-التركيب)؛ تساهم إعادة التركيب العودية بجزء من زمن الاستجابة المقاس.

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

ضمن النطاق

• تنفيذ كود أصلي عشوائي بواسطة حمولة غير موثوقة
• الهروب عبر chroot، mount، ptrace، socket، process_vm_writev
• قنابل fork، واستنزاف وحدة المعالجة المركزية (RLIMIT_CPU)، واستنزاف الذاكرة (RLIMIT_AS)
• تسريب واصفات الملفات عبر execve
• تصعيد setuid / الموصول الديناميكي / LD_PRELOAD
• إزالة مرشح seccomp أو إعادة تمكين القدرات

خارج النطاق

• ثغرات اليوم صفر في النواة خارج سطح استدعاءات النظام المسموح
• القنوات الجانبية للعتاد (Spectre، Meltdown)
• هروب جهاز افتراضي متجاور عبر تركيبات /proc و/sys المشتركة
• خروج الشبكة بما يتجاوز ما توفره CLONE_NEWNET + حظر socket
• تجويع الموارد لبيئات العزل الشقيقة (يتطلب دعم cgroup)

الافتراضات

• نواة المضيف لينكس غير معدَّلة ≥ 5.4
• نجاح clone(CLONE_NEWNS|CLONE_NEWPID|...) (يتطلب CAP_SYS_ADMIN)
• الملف الثنائي المستهدف مرتبط ثابتاً (أو المكتبات الديناميكية متوفرة في --root)
• ضبط --self-hash=<hex> في عمليات النشر الإنتاجية

التوثيق

خارطة الطريق

v1 (الحالي)

• بيئة عزل ذات دفاع متعمق من 7 طبقات
• بصمة محتوى BLAKE2b-256
• مخرجات تدقيق JSON
• 17 سيناريو اختبار
• صفحة دليل، وإكمال تلقائي (bash، zsh، fish)

v2 (المخطط)

• ملف سياسة seccomp خارجي (JSON أو مصدر BPF)
• علامات مساحة أسماء مخصصة لكل مثيل بيئة عزل
• قائمة بيضاء قابلة للضبط لاستدعاءات النظام عبر CLI
• خطافات قياس أداء لتكامل CI
• توقيع الإصدارات (minisign/signify)

الحالة

الترخيص

MIT — راجع LICENSE للنص الكامل.

بُني Z-Jail على WSL2 (Kali Linux، GCC 15.2.0)، مستهدفاً لينكس 5.4+. تتم الصيانة بواسطة Division-36. أبلغ عن المشكلات في متتبع المشكلات.