
Z-Jail v1.1.0
Um sandbox Linux leve e multicamadas que combina namespaces, pivot_root, seccomp-bpf, remoção de capabilities e um mecanismo de veredito baseado em evidências (Versão Pública Truthimatics) para execução de código segura e auditável.
Z-Jail
Sandbox multicamadas para execução de código nativo no Linux.
Sete camadas de isolamento ordenadas — sem dependências externas, binário PIE de ~81 KiB.
┌──────────────────────────────────────────────────────┐
│ 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) │
└──────────────────────────────────────────────────────┘
Índice
- Início Rápido
- Por que Z-Jail
- Arquitetura
- Camadas
- Uso
- Compilação e Instalação
- Testes
- Desempenho
- Modelo de Ameaças
- Documentação
- Roteiro
- 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 arquivos mínimo com o binário alvo e suas dependências (para binários estáticos, apenas o binário é suficiente).
Por que Z-Jail
As soluções de sandbox existentes fazem concessões:
| Z-Jail | Firecracker | gVisor | bwrap | nsjail | |
|---|---|---|---|---|---|
| Dependências externas | zero | libc, seccomp | Go runtime | libc | libc, protobuf |
| Tamanho do binário | ~81 KiB | 20+ MiB | 40+ MiB | ~70 KiB | ~1 MiB |
| Isolamento de VM | não | sim (microVM) | não (sandbox) | não | não |
| Whitelist seccomp | sim | não | sim | opcional | sim |
| Hash de conteúdo | sim | não | não | não | não |
| JSON de auditoria | sim | não | sim | não | parcial |
| Complexidade de build | um make | complexo | complexo | trivial | moderado |
Z-Jail preenche o nicho entre bwrap (mínimo, sem seccomp por padrão) e nsjail (repleto de recursos, dependências pesadas). Ele foi projetado para pipelines de CI, desafios de jail em CTF e avaliação leve de código onde você precisa de defesa em profundidade sem recorrer a um runtime de contêiner.
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]
Ordenação de Camadas
Cada camada é ordenada de forma que uma camada posterior não possa ser desfeita por uma anterior:
- setrlimit — limitar CPU, espaço de endereçamento, número de ficheiros, processos antes de tudo o resto
- fd scrub — fechar todos os fds herdados exceto o pipe de relatório
- PR_SET_DUMPABLE=0 — core dumps desativados, /proc/self/mem bloqueado
- pivot_root — desanexar do sistema de ficheiros do host; raiz antiga desmontada de forma preguiçosa
- PR_SET_NO_NEW_PRIVS — sem setuid, sem escalonamento via
capsetapós este ponto - drop_caps — zerar todas as capacidades, bloquear securebits
- seccomp-BPF — restringir syscalls apenas à lista de permissões
- signal parent — informar o processo pai que a sandbox está pronta
- 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
O Z-Jail aplica sete mecanismos de isolamento ordenados no processo filho antes do execve,
cada um escolhido de modo que uma etapa posterior não possa ser desfeita pela reexecução de uma etapa anterior.
O processo pai cria o filho com clone() solicitando cinco namespaces
(mount, PID, network, IPC, UTS), e então o filho executa o seguinte pipeline:
1. Limites de recursos
setrlimit limita o tempo de CPU, o espaço de endereçamento, os arquivos abertos e a contagem de processos
antes que qualquer código influenciado pelo convidado seja executado, limitando fork bombs e esgotamento de memória.
2. Limpeza de descritores de arquivo
Todos os descritores herdados, exceto o pipe de relatório do pai, são fechados,
evitando que handles vazados atravessem o execve.
3. Desativação de dump
PR_SET_DUMPABLE=0 desativa core dumps e restringe o acesso a /proc/self/mem.
4. pivot_root
A raiz do namespace de mount é substituída pelo diretório raiz fornecido:
o diretório é bind-montado sobre si mesmo, pivot_root troca a árvore de mounts,
o processo faz chdir para a nova raiz, e a raiz antiga é desanexada de forma preguiçosa
e removida. Isso é estritamente mais forte que chroot(2) porque a raiz anterior
é desmontada em vez de apenas ocultada.
5. NO_NEW_PRIVS
PR_SET_NO_NEW_PRIVS impede qualquer ganho subsequente de privilégios por meio de binários
setuid, file capabilities ou transições de LSM. Irreversível.
6. Redução de capabilities
Os IDs de usuário e grupo são alterados enquanto CAP_SETUID ainda está retido, após o que
capset zera todos os conjuntos de capabilities e os securebits são travados, de modo que
as capabilities não podem ser reativadas.
7. seccomp-BPF (whitelist-v1)
Um filtro de whitelist é instalado; chamadas fora da whitelist são encerradas. Lista de permissões de 24 syscalls: