---

┌──────────────────────────────────────────────────────┐
│                    Z-Jail                            │
├──────────────────────────────────────────────────────┤
│  Truthimatics PV  (motore di verdetto basato su prove) │
│  Namespaces       (mount, pid, net, ipc, uts)        │
│  pivot_root       (chroot potenziato)                │
│  Capacità         (elimina tutto, blocca securebits) │
│  NO_NEW_PRIVS     (nessuna escalation di privilegi)  │
│  seccomp-BPF      (whitelist: solo 15 syscall)       │
│  Audit            (logging JSON + hashing BLAKE2b)   │
└──────────────────────────────────────────────────────┘

---

Indice

• Avvio Rapido
• Perché Z-Jail
• Architettura
• Livelli
• Utilizzo
• Build 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 deve contenere un filesystem minimo con il binario target e le sue dipendenze (per binari statici è sufficiente il binario stesso).

---

Perché Z-Jail

Le soluzioni di sandboxing esistenti fanno compromessi:

	Z-Jail	Firecracker	gVisor	bwrap	nsjail
Dipendenze esterne	zero	libc, seccomp	runtime Go	libc	libc, protobuf
Dimensione binario	~73 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 contenuto	sì	no	no	no	no
Audit JSON	sì	no	sì	no	parziale
Complessità build	un make	complessa	complessa	banale	moderata

Z-Jail colma il divario tra bwrap (minimale, nessun seccomp di default) e nsjail (ricco di funzionalità, dipendenze pesanti). È progettato per pipeline CI, sfide CTF jail e valutazione leggera di codice dove serve difesa in profondità senza tirare dentro un runtime container.

---

Architettura

Flusso Dati

flowchart LR
    CLI[argomenti CLI] --> P[parse_args]
    P --> C{clone namespaces}
    C -->|figlio| CR[child_run]
    C -->|genitore| W[waitpid]
    CR --> RL[setrlimit]
    RL --> FD[chiudi fd >= 3]
    FD --> DUMP[PR_SET_DUMPABLE=0]
    DUMP --> PV[pivot_root]
    PV --> NNP[PR_SET_NO_NEW_PRIVS]
    NNP --> CAP[elimina capacità]
    CAP --> SC[seccomp-BPF]
    SC --> SIG[segnala genitore]
    SIG --> EX[execve target]
    W --> A[audit JSON]
    A --> EXIT[exit]

Ordine dei Livelli

Ogni livello è ordinato in modo che un livello successivo non possa essere annullato da uno precedente:

1. setrlimit — limita CPU, spazio di indirizzi, numero di file, processi prima di qualsiasi altra cosa
2. fd scrub — chiude tutti i fd ereditati tranne il pipe di report
3. PR_SET_DUMPABLE=0 — disabilita core dump, blocca /proc/self/mem
4. pivot_root — si distacca dal filesystem host; la vecchia root viene smontata lazy
5. PR_SET_NO_NEW_PRIVS — niente setuid, niente escalation capset dopo questo punto
6. drop_caps — azzera tutte le capacità, blocca securebits
7. seccomp-BPF — limita le syscall alla sola whitelist
8. segnala genitore — dice al genitore che la sandbox è pronta
9. execve — sostituisce il processo con il binario target

sequenceDiagram
    participant P as Genitore
    participant C as Figlio
    P->>C: clone (NEWNS|NEWPID|NEWNET|NEWIPC|NEWUTS)
    Note over C: setrlimit(CPU, AS, NOFILE, NPROC)
    Note over C: close(tutti i fd > 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(tutti 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: scrivi audit JSON

---

Livelli

1. Truthimatics Public Version

Motore di verdetto basato su prove. Raccoglie osservazioni pesate sul binario eseguito e determina un verdetto finale (DETERMINISTIC, REJECT o UNCERTAIN). Ogni osservazione ha un peso; ogni singola osservazione con peso >50% del totale decide il verdetto.

2. Namespace

Vengono creati cinque namespace tramite clone():

Namespace	Flag	Scopo
Mount	CLONE_NEWNS	Albero del filesystem isolato
PID	CLONE_NEWPID	Spazio degli ID dei processi (il figlio è pid 1)
Net	CLONE_NEWNET	Nessuna interfaccia di rete
IPC	CLONE_NEWIPC	Nessuna memoria condivisa / semafori
UTS	CLONE_NEWUTS	Hostname separato

Richiede CAP_SYS_ADMIN nel namespace iniziale.

3. pivot_root

Sostituisce la root del mount namespace con la directory --root:

1. Bind-mount della directory root su se stessa (MS_BIND|MS_REC)
2. pivot_root(new_root, put_old) — scambia l'albero dei mount
3. chdir("/") — si sposta nella nuova root
4. umount2("/.pivot_old", MNT_DETACH) — distacca la vecchia root
5. rmdir("/.pivot_old") — pulizia

Questo è strettamente più forte di chroot(2) — non c'è modo per il processo in sandbox di scappare di nuovo alla root host, nemmeno con CLONE_NEWNS dall'interno della sandbox (cosa già bloccata da seccomp).

4. Capacità

Tutte le capacità vengono eliminate tramite:

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

Il processo elimina setuid/setgid prima di capset in modo che il cambio di uid avvenga mentre CAP_SETUID è ancora attiva. Dopo capset, tutte le capacità sono sparite e i securebits sono bloccati — nessuna riattivazione è possibile.

5. NO_NEW_PRIVS

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

Impedisce al processo o ai suoi figli di ottenere nuovi privilegi tramite binari setuid, capacità dei file o transizioni LSM. Irreversibile.

6. seccomp-BPF (whitelist-v1)

Lista di consenso di 15 syscall — tutto ciò che non è nella lista riceve SECCOMP_RET_KILL: