
Z-Jail v1.1.0
Un sandbox Linux ligero y multicapa que combina namespaces, pivot_root, seccomp-bpf, supresión de capacidades (capability dropping) y un motor de veredictos basado en evidencia (Truthimatics Public Version) para una ejecución de código segura y auditable.
Z-Jail
Sandbox multicapa para la ejecución de código nativo en Linux.
Siete capas de aislamiento ordenadas — sin dependencias externas, binario 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) │
└──────────────────────────────────────────────────────┘
Tabla de Contenidos
- Inicio Rápido
- Por qué Z-Jail
- Arquitectura
- Capas
- Uso
- Compilación e Instalación
- Pruebas
- Rendimiento
- Modelo de Amenazas
- Documentación
- Hoja de Ruta
- Licencia
Inicio 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
El directorio --root debe contener un sistema de archivos mínimo con el binario objetivo y sus dependencias (para binarios estáticos, basta con el binario).
Por qué Z-Jail
Las soluciones de sandboxing existentes hacen concesiones:
| Z-Jail | Firecracker | gVisor | bwrap | nsjail | |
|---|---|---|---|---|---|
| Dependencias externas | cero | libc, seccomp | Go runtime | libc | libc, protobuf |
| Tamaño del binario | ~81 KiB | 20+ MiB | 40+ MiB | ~70 KiB | ~1 MiB |
| Aislamiento por VM | no | sí (microVM) | no (sandbox) | no | no |
| Lista blanca de seccomp | sí | no | sí | opcional | sí |
| Hashing de contenido | sí | no | no | no | no |
| JSON de auditoría | sí | no | sí | no | parcial |
| Complejidad de compilación | un make | compleja | compleja | trivial | moderada |
Z-Jail cubre el nicho entre bwrap (mínimo, sin seccomp por defecto) y nsjail (con muchas funciones, dependencias pesadas). Está diseñado para pipelines de CI, retos de jail en CTF y evaluación ligera de código donde se necesita defensa en profundidad sin recurrir a un runtime de contenedores.
Arquitectura
Flujo de datos
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]
Ordenación de capas
Cada capa se ordena de modo que una capa posterior no pueda ser deshecha por una anterior:
- setrlimit — limitar CPU, espacio de direcciones, número de archivos y procesos antes que cualquier otra cosa
- fd scrub — cerrar todos los fds heredados excepto la tubería de informes
- PR_SET_DUMPABLE=0 — volcados de núcleo deshabilitados, /proc/self/mem bloqueado
- pivot_root — desvincularse del sistema de archivos del host; la raíz antigua se desmonta de forma diferida
- PR_SET_NO_NEW_PRIVS — sin setuid, sin escalada mediante
capseta partir de este punto - drop_caps — poner a cero todas las capacidades, bloquear securebits
- seccomp-BPF — restringir las llamadas al sistema únicamente a la lista blanca
- signal parent — indicar al proceso padre que el sandbox está listo
- execve — reemplazar el proceso con el binario objetivo
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
Capas
Z-Jail aplica siete mecanismos de aislamiento ordenados en el hijo antes de execve,
cada uno elegido de modo que un paso posterior no pueda deshacerse reejecutando uno anterior.
El padre crea el hijo con clone() solicitando cinco namespaces
(mount, PID, network, IPC, UTS), luego el hijo ejecuta el siguiente pipeline:
1. Límites de recursos
setrlimit limita el tiempo de CPU, el espacio de direcciones, los archivos abiertos y el número de procesos
antes de que se ejecute cualquier código influenciado por el invitado, acotando las bombas fork y el agotamiento de memoria.
2. Limpieza de descriptores de archivo
Todos los descriptores heredados excepto el pipe de reporte del padre se cierran,
evitando que los handles filtrados crucen execve.
3. Dumpability desactivado
PR_SET_DUMPABLE=0 desactiva los volcados de núcleo y restringe el acceso a /proc/self/mem.
4. pivot_root
La raíz del namespace de montaje se reemplaza con el directorio raíz proporcionado:
el directorio se monta por bind sobre sí mismo, pivot_root intercambia el árbol de montaje,
el proceso hace chdir a la nueva raíz, y la raíz antigua se desacopla de forma diferida
y se elimina. Esto es estrictamente más fuerte que chroot(2) porque la raíz anterior
se desmonta en lugar de simplemente ocultarse.
5. NO_NEW_PRIVS
PR_SET_NO_NEW_PRIVS impide cualquier ganancia de privilegios posterior mediante binarios
setuid, capacidades de archivo o transiciones de LSM. Irreversible.
6. Reducción de capacidades
Los IDs de usuario y grupo se cambian mientras CAP_SETUID aún se mantiene, después de lo cual
capset pone a cero todos los conjuntos de capacidades y los securebits se bloquean, de modo que
las capacidades no pueden volver a habilitarse.
7. seccomp-BPF (whitelist-v1)
Se instala un filtro de lista blanca; las llamadas que no están en la lista blanca se terminan. Lista de permitidos de 24 syscalls: