Z-Jail

Sandbox de múltiplas camadas para execução de código nativo no Linux.
Sete camadas de defesa independentes — sem dependências externas, binário PIE de ~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)   │
└──────────────────────────────────────────────────────┘

Índice

• Início Rápido
• Porquê Z-Jail?
• Arquitetura
• Camadas
• Utilização
• Compilação e Instalação
• Testes
• Desempenho
• Modelo de Ameaças
• Documentação
• Roadmap
• Licença

Início Rápido

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

O diretório --root deve conter um sistema de ficheiros mínimo com o binário alvo e as suas dependências (para binários estáticos, basta o próprio binário).

Porquê Z-Jail?

As soluções de sandboxing existentes envolvem compromissos:

O Z-Jail preenche o nicho entre o bwrap (mínimo, sem seccomp por defeito) e o nsjail (cheio de funcionalidades, dependências pesadas). Foi concebido para pipelines de CI, desafios de jail em CTF e avaliação leve de código, onde é necessária defesa em profundidade sem depender de um runtime de contentores.

Arquitetura

Fluxo de Dados

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]

Ordem das Camadas

Cada camada está ordenada de modo a que uma camada posterior não possa ser desfeita por uma anterior:

1. setrlimit — limitar CPU, espaço de endereçamento, número de ficheiros e processos antes de qualquer outra coisa
2. limpeza de fds — fechar todos os fds herdados, exceto o pipe de relatório
3. PR_SET_DUMPABLE=0 — core dumps desativados, /proc/self/mem bloqueado
4. pivot_root — desanexar do sistema de ficheiros do host; a raiz antiga é desmontada em modo lazy
5. PR_SET_NO_NEW_PRIVS — sem setuid, sem escalonamento via capset a partir deste ponto
6. drop_caps — zerar todas as capabilities, bloquear os securebits
7. seccomp-BPF — restringir syscalls apenas à lista de permissões
8. sinalizar o pai — informar o processo pai de que a sandbox está pronta
9. execve — substituir o processo pelo binário alvo

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

Camadas

1. Versão Pública Truthimatics

Mecanismo de veredito baseado em evidências. Recolhe observações ponderadas sobre o binário executado e determina um veredito final (DETERMINISTIC, REJECT ou UNCERTAIN). Cada observação tem um peso; qualquer observação individual com peso >50% do total decide o veredito.

2. Namespaces

Cinco namespaces são criados através de clone():

Requer CAP_SYS_ADMIN no namespace inicial.

3. pivot_root

Substitui a raiz do namespace de montagem pelo diretório --root:

1. Faz bind-mount do diretório raiz sobre si próprio (MS_BIND|MS_REC)
2. pivot_root(new_root, put_old) — troca a árvore de montagens
3. chdir("/") — entra na nova raiz
4. umount2("/.pivot_old", MNT_DETACH) — desanexa a raiz antiga
5. rmdir("/.pivot_old") — limpeza

Isto é estritamente mais forte do que chroot(2) — não há forma de o processo em sandbox escapar de volta para a raiz do host, mesmo com CLONE_NEWNS a partir do interior da sandbox (que já é bloqueado pelo seccomp).

4. Capabilities

Todas as capabilities são removidas através de:

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

O processo remove setuid/setgid antes do capset, para que a alteração de uid tenha efeito enquanto CAP_SETUID ainda está detida. Após o capset, todas as caps desaparecem e os securebits ficam bloqueados — não é possível reativá-las.

5. NO_NEW_PRIVS

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

Impede que o processo ou os seus filhos obtenham novos privilégios através de binários setuid, capabilities de ficheiro ou transições LSM. Irreversível.

6. seccomp-BPF (whitelist-v1)

Lista de permissões de 15 syscalls — tudo o que não estiver na lista recebe SECCOMP_RET_KILL:

O filtro BPF é gerado dinamicamente: para cada entrada da lista de permissões, é emitida uma cadeia de saltos que permite (se a syscall corresponder) ou cai no KILL. A arquitetura é verificada primeiro (AUDIT_ARCH_X86_64).

O filtro é verificado de forma independente por um teste autónomo (tests/seccomp_filter_test.c, 8/8 passam) que faz fork+execve de casos de teste contra um prctl(PR_SET_SECCOMP) real, sem precisar de root.

7. Auditoria

Cada execução produz um registo de auditoria 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..."
}

Escrito em build/audits/<binary-name>.audit.json. O content_fingerprint é um hash BLAKE2b-256 do binário alvo, calculado pelo processo pai depois de o filho terminar.

Utilização

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

Exemplos

# 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

Códigos de Saída

Compilação e Instalação

Requisitos

• Kernel Linux ≥ 5.4 (namespaces, seccomp-BPF, pivot_root)
• GCC ≥ 11 (testado em 11.4, 13.2, 15.2)
• Sem bibliotecas externas — apenas o toolchain C padrão

Comandos

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)

O binário é compilado como um Executável Independente de Posição (PIE) com -fstack-protector-strong, -D_FORTIFY_SOURCE=2, RELRO completo e -z now.

Opções de Compilação

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

Testes

Teste Rápido (sem root)

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

# BLAKE2b known-answer test
tests/build/blake2b_known

Estes não precisam de root e são executados em menos de 100 ms.

Suite de Testes Completa

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

Requer root para a criação de namespaces. A suite de testes cobre:

Desempenho

Medido em WSL2 (kernel 6.18.x-microsoft-standard-WSL2, Kali Linux), 50 amostras por ferramenta, carga de trabalho uniforme (um binário estático freestanding cujo corpo é exit_group(0)), cronometrado com um harness getrusage. Consulte docs/BENCHMARKS.md para a metodologia.

Comparação Direta (mesmo host, mesma metodologia)

Nas condições testadas, o Z-Jail apresenta o menor conjunto residente das três sandboxes a nível de processo e uma latência entre o bwrap e o nsjail. O Bubblewrap é o mais rápido, mas não efetua qualquer filtragem seccomp por defeito, pelo que faz menos trabalho de configuração; o Z-Jail instala uma lista de permissões seccomp, remove capabilities e executa pivot_root em cada execução. O gVisor (runsc) sofre um segfault neste kernel WSL2 e não pôde ser medido; o Firecracker isola através de uma microVM (cold-boot de VM, uma métrica diferente) e fica excluído da tabela fork-to-exec. Estes números provêm de um único host — trate-os como relativos.

Nota: os valores documentados anteriormente (~8 ms, ~4 MiB, ~130 KiB) não correspondem a uma compilação make atual (~73 KiB, ~5.9 ms) e parecem ter sido imprecisos; os números acima foram re-medidos neste codebase. O Truthimatics continua a fazer parte do código e não foi removido (os relatórios antigos do axiom_jail simplesmente usavam um nome de binário e um harness diferentes). Um bug de propagação de montagens encontrado durante os benchmarks foi corrigido em src/sandbox.c (MS_REC|MS_PRIVATE antes do bind mount); o remount recursivo contribui com parte da latência medida.

Modelo de Ameaças

No Âmbito

• Execução de código nativo arbitrário por um payload não confiável
• Fuga através de chroot, mount, ptrace, socket, process_vm_writev
• Fork bombs, exaustão de CPU (RLIMIT_CPU), exaustão de memória (RLIMIT_AS)
• Fugas de file descriptors através de execve
• Escalonamento via setuid / dynamic linker / LD_PRELOAD
• Remoção do filtro seccomp ou reativação de capabilities

Fora do Âmbito

• Zero-days do kernel fora da superfície de syscalls permitida
• Canais laterais de hardware (Spectre, Meltdown)
• Fuga de VM co-localizada através de montagens partilhadas /proc, /sys
• Saída de rede para além do que CLONE_NEWNET + socket bloqueado proporciona
• Escassez de recursos de sandboxes irmãs (requer suporte a cgroups)

Premissas

• O kernel do host é Linux ≥ 5.4 não modificado
• clone(CLONE_NEWNS|CLONE_NEWPID|...) é bem-sucedido (requer CAP_SYS_ADMIN)
• O binário alvo está ligado estaticamente (ou as bibliotecas dinâmicas estão disponíveis em --root)
• --self-hash=<hex> está configurado em implementações de produção

Documentação

Roadmap

v1 (atual)

• Sandbox de defesa em profundidade com 7 camadas
• Fingerprinting de conteúdo BLAKE2b-256
• Saída de auditoria JSON
• 17 cenários de teste
• Página de manual, completions (bash, zsh, fish)

v2 (planeado)

• Ficheiro de política seccomp externo (JSON ou fonte BPF)
• Flags de namespace personalizadas por instância de sandbox
• Lista de permissões de syscalls configurável via CLI
• Hooks de profiling de desempenho para integração em CI
• Assinatura de releases (minisign/signify)

Status

Licença

MIT — consulte LICENSE para o texto completo.

O Z-Jail foi desenvolvido em WSL2 (Kali Linux, GCC 15.2.0), com o alvo Linux 5.4+. Mantido pela Division-36. Comunique problemas no rastreador de issues.