Z-Jail

Многослойная песочница для выполнения нативного кода на Linux.
Семь независимых уровней защиты — без внешних зависимостей, 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 и лёгкой оценки кода, где нужна многоуровневая защита без привлечения container runtime.

Архитектура

Поток данных

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 — ограничить CPU, адресное пространство, число файлов и процессов до всего остального
2. fd scrub — закрыть все унаследованные файловые дескрипторы, кроме канала отчёта
3. PR_SET_DUMPABLE=0 — отключены core dump, /proc/self/mem заблокирован
4. pivot_root — отсоединение от файловой системы хоста; старый корень размонтируется лениво
5. PR_SET_NO_NEW_PRIVS — никаких setuid и повышения привилегий через capset после этой точки
6. drop_caps — обнулить все capabilities, заблокировать 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. Возможности (Capabilities)

Все capabilities сбрасываются через:

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

Процесс сбрасывает setuid/setgid до capset, чтобы смена uid вступила в силу, пока CAP_SETUID ещё удержан. После capset все capabilities исчезают, а securebits заблокированы — повторное включение невозможно.

5. NO_NEW_PRIVS

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

Предотвращает получение процессом или его потомками новых привилегий через setuid-бинарники, file capabilities или переходы 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) без необходимости root.

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

Коды возврата

Сборка и установка

Требования

• Ядро Linux ≥ 5.4 (namespaces, 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)

Бинарник собирается как Position Independent Executable с -fstack-protector-strong, -D_FORTIFY_SOURCE=2, полным RELRO и -z now.

Параметры времени компиляции

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

Тестирование

Быстрый тест (без root)

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

# BLAKE2b known-answer test
tests/build/blake2b_known

Эти тесты не требуют root и выполняются менее чем за 100 мс.

Полный набор тестов

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

Требуется root для создания пространств имён. Набор тестов покрывает:

Производительность

Измерено на WSL2 (ядро 6.18.x-microsoft-standard-WSL2, Kali Linux), 50 выборок на инструмент, единообразная нагрузка (freestanding-статический бинарник, тело которого — exit_group(0)), замеры с помощью обвязки getrusage. См. docs/BENCHMARKS.md — методология.

Сравнение (тот же хост, та же методология)

В протестированных условиях Z-Jail имеет наименьший резидентный набор среди трёх песочниц уровня процесса и задержку между bwrap и nsjail. Bubblewrap — самый быстрый, но по умолчанию не выполняет фильтрацию seccomp, поэтому делает меньше подготовительной работы; Z-Jail при каждом запуске устанавливает белый список seccomp, сбрасывает capabilities и выполняет pivot_root. gVisor (runsc) падает с segfault на этом ядре WSL2 и не мог быть измерен; Firecracker изолирует через microVM (холодный старт VM — другая метрика) и исключён из таблицы fork-to-exec. Это цифры одного хоста — относитесь к ним как к относительным.

Примечание: более старые задокументированные цифры (~8 ms, ~4 MiB, ~130 KiB) не соответствуют текущей сборке make (~73 KiB, ~5.9 ms) и, по-видимому, были неточными; цифры выше пересчитаны на этой кодовой базе. Truthimatics по-прежнему часть кода и не удалялась (старые отчёты axiom_jail просто использовали другое имя бинарника и обвязку). Баг с распространением монтирований, найденный во время бенчмаркинга, был исправлен в src/sandbox.c (MS_REC|MS_PRIVATE перед bind mount); рекурсивный remount вносит часть измеренной задержки.

Модель угроз

В зоне действия

• Выполнение произвольного нативного кода недоверенной нагрузкой
• Побег через chroot, mount, ptrace, socket, process_vm_writev
• Форк-бомбы, исчерпание CPU (RLIMIT_CPU), исчерпание памяти (RLIMIT_AS)
• Утечки файловых дескрипторов через execve
• Эскалация через setuid / динамический линковщик / LD_PRELOAD
• Удаление seccomp-фильтра или повторное включение capabilities

Вне зоны действия

• Zero-day уязвимости ядра за пределами разрешённой поверхности системных вызовов
• Аппаратные побочные каналы (Spectre, Meltdown)
• Побег из совмещённой VM через общие /proc, /sys монтирования
• Сетевой трафик за пределами того, что обеспечивают CLONE_NEWNET + заблокированный socket
• Истощение ресурсов соседних песочниц (требуется поддержка cgroup)

Допущения

• Ядро хоста — немодифицированный Linux ≥ 5.4
• clone(CLONE_NEWNS|CLONE_NEWPID|...) успешен (требуется CAP_SYS_ADMIN)
• Целевой бинарник статически слинкован (или динамические библиотеки доступны в --root)
• --self-hash=<hex> настроен в production-развёртываниях

Документация

План развития

v1 (текущая версия)

• Песочница с 7 уровнями защиты (defence-in-depth)
• BLAKE2b-256 хеширование содержимого
• Вывод аудита в JSON
• 17 тестовых сценариев
• man-страница, автодополнения (bash, zsh, fish)

v2 (планируется)

• Внешний файл политики seccomp (JSON или исходник BPF)
• Пользовательские флаги namespace для каждого экземпляра песочницы
• Настраиваемый белый список системных вызовов через CLI
• Хуки профилирования производительности для интеграции с CI
• Подпись релизов (minisign/signify)

Статус

Лицензия

MIT — полный текст см. в LICENSE.

Z-Jail был создан на WSL2 (Kali Linux, GCC 15.2.0), ориентирован на Linux 5.4+. Поддерживается Division-36. Сообщайте об ошибках в issue tracker.