Z-Jail

用于Linux上原生代码执行的多层沙箱。
七层独立防御——无外部依赖，约73 KiB的PIE二进制文件。

┌──────────────────────────────────────────────────────┐
│                    Z-Jail                            │
├──────────────────────────────────────────────────────┤
│  Truthimatics PV  (基于证据的裁决引擎)                │
│  Namespaces       (mount, pid, net, ipc, uts)        │
│  pivot_root       (加强版 chroot)                     │
│  Capabilities     (丢弃全部，锁定 securebits)          │
│  NO_NEW_PRIVS     (禁止权限提升)                      │
│  seccomp-BPF      (白名单：仅15个系统调用)            │
│  Audit            (JSON 日志 + BLAKE2b 哈希)          │
└──────────────────────────────────────────────────────┘

目录

• 快速开始
• 为什么选择 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 监狱挑战和轻量级代码评估 而设计，无需引入容器运行时即可实现纵深防御。

架构

数据流

flowchart LR
    CLI[CLI 参数] --> P[parse_args]
    P --> C{clone 命名空间}
    C -->|子进程| CR[child_run]
    C -->|父进程| W[waitpid]
    CR --> RL[setrlimit]
    RL --> FD[关闭 >=3 的文件描述符]
    FD --> DUMP[PR_SET_DUMPABLE=0]
    DUMP --> PV[pivot_root]
    PV --> NNP[PR_SET_NO_NEW_PRIVS]
    NNP --> CAP[丢弃 capabilities]
    CAP --> SC[seccomp-BPF]
    SC --> SIG[通知父进程]
    SIG --> EX[execve 目标程序]
    W --> A[审计 JSON]
    A --> EXIT[退出]

防御层顺序

每一层都经过排序，使得后一层无法被前一层撤销：

1. setrlimit — 在其他操作之前限制 CPU、地址空间、文件数、进程数
2. 文件描述符清理 — 关闭除报告管道外的所有继承 fd
3. PR_SET_DUMPABLE=0 — 禁用核心转储，锁定 /proc/self/mem
4. pivot_root — 从主机文件系统脱离；旧根延迟卸载
5. PR_SET_NO_NEW_PRIVS — 此后禁止 setuid 和 capset 提权
6. drop_caps — 清零所有 capabilities，锁定 securebits
7. seccomp-BPF — 将系统调用限制为仅白名单
8. 通知父进程 — 告知父进程沙箱已就绪
9. execve — 用目标二进制替换当前进程

sequenceDiagram
    participant P as 父进程
    participant C as 子进程
    P->>C: clone (NEWNS|NEWPID|NEWNET|NEWIPC|NEWUTS)
    Note over C: setrlimit(CPU, AS, NOFILE, NPROC)
    Note over C: close(所有 >2 的 fd)
    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(全零) + securebits
    Note over C: seccomp(SECCOMP_MODE_FILTER, 白名单)
    C->>P: write(pipe, ready=1)
    Note over C: execve(目标)
    P->>P: waitpid
    P->>P: 写入审计 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 | ...)

进程在 capset 之前丢弃 setuid/setgid，以便在仍持有 CAP_SETUID 时使 uid 更改生效。capset 之后，所有 caps 都被移除且 securebits 被锁定——无法重新启用。

5. NO_NEW_PRIVS

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

阻止进程或其子进程通过 setuid 二进制文件、文件 capabilities 或 LSM 转换获得新权限。不可逆。

6. seccomp-BPF（白名单-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=<目录> [--seccomp-enforce] [--self-hash=<十六进制>]
       [--quiet] [--verbose] -- <程序> [参数...]

示例

# 使用所有保护运行静态二进制文件
sudo z_jail --root=./roots --seccomp-enforce -- bin/hello_static

# 使用二进制完整性验证运行
sudo z_jail --root=./roots --seccomp-enforce \
  --self-hash=$(sha256sum z_jail | cut -c1-64) -- bin/program

# 静默模式（无审计 JSON）
sudo z_jail --root=./roots --quiet -- bin/program

退出码

构建与安装

要求

• Linux 内核 ≥ 5.4（命名空间、seccomp-BPF、pivot_root）
• GCC ≥ 11（已在 11.4、13.2、15.2 上测试）
• 无外部库——仅需标准 C 工具链

命令

make              # 构建 z_jail（约 130 KiB 的 PIE 二进制文件）
make install      # 安装到 /usr/local/bin + man 页面
make clean        # 删除构建产物
make dist         # 创建发布 tarball
make check        # 冒烟测试（--version + --help）

该二进制文件构建为位置无关可执行文件，启用 -fstack-protector-strong、-D_FORTIFY_SOURCE=2、完全 RELRO 和 -z now。

编译时选项

make CC=clang CFLAGS="-O3 -march=native"   # 自定义编译器/标志

测试

快速测试（无需 root）

# seccomp 过滤器逻辑（8 个测试）
tests/build/seccomp_filter_test

# BLAKE2b 已知答案测试
tests/build/blake2b_known

这些操作不需要 root，并且在 100 毫秒内完成。

完整测试套件

make -C tests setup          # 构建 payload + 测试根目录
sudo bash tests/run_tests.sh # 17 个场景

需要 root 权限来创建命名空间。测试套件涵盖：

性能

在 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 白名单、丢弃 capabilities 并执行 pivot_root。gVisor (runsc) 在此 WSL2 内核上出现段错误，无法测量；Firecracker 通过 microVM（VM 冷启动，属于不同的指标）进行隔离，因此从 fork 到 exec 的表格中排除。这些是单主机数据——请视为相对值。

注意：旧文档中的数字（约 8 毫秒，约 4 MiB，约 130 KiB）与当前 make 构建（约 73 KiB，约 5.9 毫秒）不匹配，似乎不准确；上面的数字是在此代码库上重新测量的。Truthimatics 仍为代码的一部分，并未移除（旧的 axiom_jail 报告只是使用了不同的二进制名称和工具）。在基准测试期间发现的挂载传播错误已在 src/sandbox.c 中修复（在绑定挂载前使用 MS_REC|MS_PRIVATE）；递归重新挂载是所测延迟的一部分。

威胁模型

范围内

• 不可信负载的任意原生代码执行
• 通过 chroot、mount、ptrace、socket、process_vm_writev 逃脱
• Fork 炸弹、CPU 耗尽（RLIMIT_CPU）、内存耗尽（RLIMIT_AS）
• 跨 execve 的文件描述符泄漏
• setuid / 动态链接器 / LD_PRELOAD 提权
• seccomp 过滤器移除或 capabilities 重新启用

范围外

• 允许的系统调用 surface 之外的内核零日漏洞
• 硬件侧信道攻击（Spectre、Meltdown）
• 通过共享的 /proc、/sys 挂载实现的同驻 VM 逃脱
• 超出 CLONE_NEWNET + 被阻止的 socket 所提供的网络出口
• 兄弟沙箱的资源饥饿（需要 cgroup 支持）

假设

• 主机内核是未修改的 Linux ≥ 5.4
• clone(CLONE_NEWNS|CLONE_NEWPID|...) 成功（需要 CAP_SYS_ADMIN）
• 目标二进制文件是静态链接的（或者动态库在 --root 中可用）
• 在生产部署中配置了 --self-hash=<hex>

文档

路线图

v1（当前）

• 7 层纵深防御沙箱
• BLAKE2b-256 内容指纹
• 审计 JSON 输出
• 17 个测试场景
• man 页面、补全（bash、zsh、fish）

v2（计划）

• 外部 seccomp 策略文件（JSON 或 BPF 源码）
• 每个沙箱实例的自定义命名空间标志
• 通过 CLI 可配置的系统调用白名单
• 用于 CI 集成的性能分析钩子
• 发布签名（minisign/signify）

状态

许可证

MIT — 完整文本见 LICENSE。

Z-Jail 构建于 WSL2（Kali Linux，GCC 15.2.0），目标为 Linux 5.4+。 由 Division-36 维护。请在问题跟踪器报告问题。