
Z-Jail v1.1.0
Un sandbox Linux leggero e multilivello che combina namespace, pivot_root, seccomp-bpf, riduzione delle capacità e un motore di verdetto basato su prove (Versione Pubblica di Truthimatics) per un'esecuzione sicura e verificabile del codice.
Z-Jail
Sandbox multi-livello per l'esecuzione di codice nativo su Linux.
Sette livelli di isolamento ordinati — nessuna dipendenza esterna, binario PIE di ~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) │
└──────────────────────────────────────────────────────┘
Indice
- Avvio rapido
- Perché Z-Jail
- Architettura
- Livelli
- Utilizzo
- Compilazione e installazione
- Test
- Prestazioni
- Modello di minaccia
- Documentazione
- Roadmap
- Licenza
Avvio rapido
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
La directory --root dovrebbe contenere un filesystem minimale con il binario di destinazione e le sue dipendenze (per i binari statici, è sufficiente il solo binario).
Perché Z-Jail
Le soluzioni di sandboxing esistenti comportano dei compromessi:
| Z-Jail | Firecracker | gVisor | bwrap | nsjail | |
|---|---|---|---|---|---|
| Dipendenze esterne | zero | libc, seccomp | Go runtime | libc | libc, protobuf |
| Dimensione binario | ~81 KiB | 20+ MiB | 40+ MiB | ~70 KiB | ~1 MiB |
| Isolamento VM | no | sì (microVM) | no (sandbox) | no | no |
| Whitelist seccomp | sì | no | sì | opzionale | sì |
| Hashing contenuti | sì | no | no | no | no |
| Audit JSON | sì | no | sì | no | parziale |
| Complessità build | un make | complessa | complessa | banale | moderata |
Z-Jail colma la nicchia tra bwrap (minimale, senza seccomp di default) e nsjail (ricco di funzionalità, dipendenze pesanti). È progettato per pipeline CI, challenge CTF jail e valutazione leggera del codice dove serve una difesa in profondità senza dover ricorrere a un container runtime.
Architettura
Flusso dei dati
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]
Ordinamento dei layer
Ogni layer è ordinato in modo che un layer successivo non possa essere annullato da uno precedente:
- setrlimit — limita CPU, spazio di indirizzamento, numero di file e processi prima di qualsiasi altra cosa
- fd scrub — chiude tutti i fd ereditati tranne la pipe del report
- PR_SET_DUMPABLE=0 — core dump disabilitati, /proc/self/mem bloccato
- pivot_root — scollega dal filesystem host; vecchia root smontata in modo lazy
- PR_SET_NO_NEW_PRIVS — nessun setuid, nessuna escalation tramite
capsetdopo questo punto - drop_caps — azzera tutte le capability, blocca i securebits
- seccomp-BPF — limita le syscall alla sola whitelist
- signal parent — comunica al parent che la sandbox è pronta
- execve — sostituisce il processo con il binario target
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
Livelli
Z-Jail applica sette meccanismi di isolamento ordinati nel processo figlio prima di execve,
ciascuno scelto in modo che un passaggio successivo non possa essere annullato rieseguendo uno precedente.
Il processo padre crea il figlio con clone() richiedendo cinque namespace
(mount, PID, network, IPC, UTS), poi il figlio esegue la seguente pipeline:
1. Limiti di risorse
setrlimit limita il tempo CPU, lo spazio degli indirizzi, i file aperti e il numero di processi
prima che venga eseguito qualsiasi codice influenzato dall'ospite, contenendo le fork bomb e l'esaurimento della memoria.
2. Pulizia dei file descriptor
Tutti i descrittori ereditati, eccetto la pipe di report verso il padre, vengono chiusi,
impedendo che handle trapelati attraversino execve.
3. Dumpability disattivata
PR_SET_DUMPABLE=0 disabilita i core dump e limita l'accesso a /proc/self/mem.
4. pivot_root
La radice del namespace di mount viene sostituita con la directory radice fornita:
la directory viene bind-montata su se stessa, pivot_root scambia l'albero dei mount,
il processo esegue chdir verso la nuova radice, e la vecchia radice viene scollegata in modo lazy
e rimossa. Questo è strettamente più forte di chroot(2) perché la radice precedente
viene smontata anziché semplicemente nascosta.
5. NO_NEW_PRIVS
PR_SET_NO_NEW_PRIVS impedisce qualsiasi successivo guadagno di privilegi tramite binari
setuid, file capabilities o transizioni LSM. Irreversibile.
6. Rimozione delle capability
Gli ID utente e gruppo vengono cambiati mentre CAP_SETUID è ancora detenuto, dopodiché
capset azzera tutti i set di capability e i securebits vengono bloccati, così
le capability non possono essere riabilitate.
7. seccomp-BPF (whitelist-v1)
Viene installato un filtro whitelist; le chiamate non presenti nella whitelist vengono terminate. Allow-list di 24 syscall: