---

┌──────────────────────────────────────────────────────┐
│                    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	Firecracker	gVisor	bwrap	nsjail
Внешние зависимости	нет	libc, seccomp	Go runtime	libc	libc, protobuf
Размер бинарника	~73 KiB	20+ MiB	40+ MiB	~70 KiB	~1 MiB
Изоляция VM	нет	да (microVM)	нет (песочница)	нет	нет
Белый список seccomp	да	нет	да	опционально	да
Хеширование содержимого	да	нет	нет	нет	нет
Аудит JSON	да	нет	да	нет	частично
Сложность сборки	один make	сложная	сложная	тривиальная	умеренная

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():

Пространство имён	Флаг	Назначение
Mount	CLONE_NEWNS	Изолированное дерево файловой системы
PID	CLONE_NEWPID	Пространство идентификаторов процессов (дочерний процесс — pid 1)
Net	CLONE_NEWNET	Нет сетевых интерфейсов
IPC	CLONE_NEWIPC	Нет общей памяти / семафоров
UTS	CLONE_NEWUTS	Отдельное имя хоста

Требуется 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: