一个轻量级的多层 Linux 沙箱,结合了命名空间、pivot_root、seccomp-bpf、能力降级以及基于证据的判决引擎(Truthimatics 公开版),用于安全、可审计的代码执行。
Linux 上原生代码执行的多层沙箱。
七个有序隔离层——无外部依赖,约 81 KiB 的 PIE 二进制文件。
┌──────────────────────────────────────────────────────┐
│ Z-Jail │
├──────────────────────────────────────────────────────┤
│ rlimits (CPU, AS, NOFILE, NPROC caps) │
│ Namespaces (mount, pid, net, ipc, uts) │
│ pivot_root (chroot on steroids) │
│ NO_NEW_PRIVS (no privilege escalation) │
│ Capabilities (drop all, lock securebits) │
│ seccomp-BPF (whitelist-v1: 24 syscalls) │
│ Audit (JSON logging + BLAKE2b hashing) │
└──────────────────────────────────────────────────────┘
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 | Firecracker | gVisor | bwrap | nsjail | |
|---|---|---|---|---|---|
| 外部依赖 | 零 | libc, seccomp | Go 运行时 | libc | libc, protobuf |
| 二进制大小 | ~81 KiB | 20+ MiB | 40+ MiB | ~70 KiB | ~1 MiB |
| 虚拟机隔离 | 否 | 是(microVM) | 否(沙箱) | 否 | 否 |
| seccomp 白名单 | 是 | 否 | 是 | 可选 | 是 |
| 内容哈希 | 是 | 否 | 否 | 否 | 否 |
| 审计 JSON | 是 | 否 | 是 | 否 | 部分 |
| 构建复杂度 | 一次 make | 复杂 | 复杂 | 简单 | 中等 |
Z-Jail 填补了 bwrap(极简,默认无 seccomp)与 nsjail(功能丰富,依赖繁重)之间的空白。它专为 CI 流水线、CTF 隔离挑战和轻量级代码评估 而设计,在这些场景中,你需要在无需引入容器运行时的情况下实现纵深防御。
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]
每一层的顺序都经过精心设计,确保后续层不会被前面的层撤销:
capset 提权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
Z-Jail 在 execve 之前对子进程依次应用七种隔离机制,每种机制的选择都确保后续步骤无法通过重新执行先前步骤而被撤销。
父进程通过 clone() 创建子进程,请求五个命名空间
(mount、PID、network、IPC、UTS),随后子进程运行以下流水线:
setrlimit 在任何受访客影响的代码运行之前限制 CPU 时间、地址空间、打开文件数和进程数,从而约束 fork 炸弹和内存耗尽。
除父进程报告管道外的所有继承描述符均被关闭,防止泄漏的句柄跨越 execve。
PR_SET_DUMPABLE=0 禁用核心转储并限制 /proc/self/mem 访问。
pivot_root挂载命名空间的根被替换为提供的根目录:
该目录被绑定挂载到自身,pivot_root 交换挂载树,
进程 chdir 到新根,旧根被惰性分离
并移除。这严格强于 chroot(2),因为先前的
根是被卸载而非仅仅被隐藏。
NO_NEW_PRIVSPR_SET_NO_NEW_PRIVS 阻止任何后续通过 setuid
二进制、文件能力或 LSM 转换获得的权限提升。不可逆。
在仍持有 CAP_SETUID 时更改用户和组 ID,之后
capset 将所有能力集清零并锁定 securebits,因此
能力无法被重新启用。
安装白名单过滤器;非白名单调用被终止。 允许列表包含 24 个系统调用:
| 系统调用 | 编号 | 备注 |
|---|---|---|
read | 0 | stdin |
write | 1 | stdout/stderr + 报告管道 |
openat | 257 | 文件访问(非 open) |
close | 3 | — |
lseek | 8 | — |
brk | 12 | 堆管理 |
mmap | 9 | 参数受限:flags == 0x22 精确匹配(MAP_PRIVATE|MAP_ANONYMOUS)且 prot & PROT_EXEC == 0 |
munmap | 11 | — |
execve | 59 | 启动时单次 exec |
exit_group | 231 | 干净进程退出 |
rt_sigaction | 13 | 信号处理程序 |
rt_sigprocmask | 14 | 信号屏蔽 |
getrandom | 318 | 随机数源 |
clock_gettime | 228 | 计时 |
fstat | 5 | 文件元数据 |
arch_prctl | 158 | TLS 设置 |
mprotect | 10 | 参数受限:prot & PROT_EXEC == 0(保持 W^X) |
prlimit64 | 302 | 参数受限:new_limit == NULL 完整 64 位(低字和高字均为零;只读) |
readlinkat | 267 | — |
rseq | 334 | glibc 可重启序列 |
set_robust_list | 273 | glibc 线程初始化 |
set_tid_address | 218 | glibc 初始化 |
access | 21 | — |
pread64 | 17 | — |
最后九个(arch_prctl .. pread64)是现代静态链接 glibc 程序在 main 之前所需的 C 运行时启动调用。BPF 过滤器是动态生成的:对于每个白名单条目,生成一条跳转链,要么允许(如果系统调用匹配),要么落入 KILL。首先检查架构(AUDIT_ARCH_X86_64)。
三条参数级规则保持了策略的意图:
mmap 限制为 flags == MAP_PRIVATE|MAP_ANONYMOUS (0x22) 且 PROT_EXEC 清除mprotect 受限,使 PROT_EXEC 永不设置(强制 W^X)prlimit64 限制为 NULL 新限制参数,检查完整 64 位(访客可读取但不能提高限制)该过滤器由独立测试(tests/seccomp_filter_test.c,9/9 通过)独立验证,该测试对真实 prctl(PR_SET_SECCOMP) 进行 fork+execve 测试用例,无需 root。
子进程退出后,父进程会生成一条符合版本化 schema(z-jail.audit/v1)的 JSON 审计记录。该记录包含执行时长、退出码、判定字段、当前启用的 seccomp 过滤器名称与白名单大小、已启用的命名空间,以及 content_fingerprint:由父进程计算的目标二进制文件的 BLAKE2b-256 摘要。可选的 --self-hash 标志允许操作员固定预期摘要,从而在信任结果之前检测可执行文件是否被篡改。
写入 build/audits/<binary-name>.audit.json。content_fingerprint 是目标二进制文件的规范 BLAKE2b-256 哈希(可用 b2sum -l 256 复现),由父进程在子进程结束后计算。记录通过 prev_hash 形成哈希链,文件在任何路径组件中都不会跟随符号链接打开,并被标记为仅追加(chattr +a),因此无法被截断或原地覆盖。参见 docs/AUDIT_SCHEMA.md。
z_jail --root=<dir> [--seccomp-enforce] [--self-hash=<hex>]
[--quiet] [--verbose] -- <program> [args...]
| 标志 | 描述 |
|---|---|
--root=<dir> | 沙箱根目录(必需) |
--seccomp-enforce | 启用 seccomp-BPF 系统调用白名单 |
--self-hash=<hex> | 验证二进制文件是否与预期的 BLAKE2b-256 哈希匹配 |
--quiet | 抑制审计输出 |
--no-audit | 完全禁用审计文件创建 |
--verbose | 启用调试日志记录 |
--version | 显示构建 ID(Z-Jail/v1+dev) |
--help | 显示用法并退出 |
# 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=$(b2sum -l 256 z_jail | cut -c1-64) -- bin/program
# Quiet mode (no audit JSON)
sudo z_jail --root=./roots --quiet -- bin/program
# Disable audit file creation entirely
sudo z_jail --root=./roots --no-audit -- bin/program