Z-Jail

Mehrschichtige Sandbox für die Ausführung von nativem Code unter Linux.
Sieben unabhängige Verteidigungsschichten – keine externen Abhängigkeiten, ~73 KiB PIE-Binärdatei.

┌──────────────────────────────────────────────────────┐
│                    Z-Jail                            │
├──────────────────────────────────────────────────────┤
│  Truthimatics PV  (evidenzbasierte Bewertungsengine) │
│  Namespaces       (mount, pid, net, ipc, uts)        │
│  pivot_root       (chroot unter Steroiden)           │
│  Capabilities     (alle entfernen, securebits sperren)│
│  NO_NEW_PRIVS     (keine Privilegienerhöhung)        │
│  seccomp-BPF      (Whitelist: nur 15 Syscalls)       │
│  Audit            (JSON-Logging + BLAKE2b-Hashing)   │
└──────────────────────────────────────────────────────┘

Inhaltsverzeichnis

• Schnellstart
• Warum Z-Jail
• Architektur
• Schichten
• Verwendung
• Build & Installation
• Tests
• Leistung
• Bedrohungsmodell
• Dokumentation
• Roadmap
• Lizenz

Schnellstart

git clone https://github.com/Division-36/Z-Jail.git
cd Z-Jail
make
sudo ./z_jail --root=/pfad/zu/rootfs --seccomp-enforce -- /bin/ls

Das Verzeichnis --root sollte ein minimales Dateisystem mit der Zielbinärdatei und ihren Abhängigkeiten enthalten (für statische Binärdateien reicht die Binärdatei selbst).

Warum Z-Jail

Bestehende Sandbox-Lösungen machen Kompromisse:

Z-Jail füllt die Nische zwischen bwrap (minimal, kein seccomp standardmäßig) und nsjail (funktionsreich, schwere Abhängigkeiten). Es ist für CI-Pipelines, CTF-Jail-Challenges und leichtgewichtige Code-Auswertung konzipiert, bei denen eine abgestufte Verteidigung ohne Container-Laufzeitumgebung benötigt wird.

Architektur

Datenfluss

flowchart LR
    CLI[CLI-Argumente] --> P[parse_args]
    P --> C{clone namespaces}
    C -->|Kind| CR[child_run]
    C -->|Eltern| W[waitpid]
    CR --> RL[setrlimit]
    RL --> FD[schließe fds >= 3]
    FD --> DUMP[PR_SET_DUMPABLE=0]
    DUMP --> PV[pivot_root]
    PV --> NNP[PR_SET_NO_NEW_PRIVS]
    NNP --> CAP[Capabilities entfernen]
    CAP --> SC[seccomp-BPF]
    SC --> SIG[Eltern signalisieren]
    SIG --> EX[execve-Ziel]
    W --> A[Audit-JSON]
    A --> EXIT[exit]

Schichten-Reihenfolge

Jede Schicht ist so angeordnet, dass eine spätere Schicht nicht von einer früheren rückgängig gemacht werden kann:

1. setrlimit – CPU, Adressraum, Dateianzahl, Prozesse begrenzen, bevor etwas anderes passiert
2. fd-Bereinigung – alle geerbten Dateideskriptoren schließen bis auf die Bericht-Pipe
3. PR_SET_DUMPABLE=0 – Core-Dumps deaktiviert, /proc/self/mem gesperrt
4. pivot_root – vom Host-Dateisystem trennen; altes Root wird lazy ausgehängt
5. PR_SET_NO_NEW_PRIVS – keine setuid, keine capset-Eskalation nach diesem Punkt
6. drop_caps – alle Capabilities auf null setzen, securebits sperren
7. seccomp-BPF – Syscalls auf Whitelist beschränken
8. Eltern signalisieren – dem Elternprozess mitteilen, dass die Sandbox bereit ist
9. execve – Prozess durch die Zielbinärdatei ersetzen

sequenceDiagram
    participant P as Eltern
    participant C as Kind
    P->>C: clone (NEWNS|NEWPID|NEWNET|NEWIPC|NEWUTS)
    Note over C: setrlimit(CPU, AS, NOFILE, NPROC)
    Note over C: close(alle 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(alle null) + securebits
    Note over C: seccomp(SECCOMP_MODE_FILTER, Whitelist)
    C->>P: write(pipe, ready=1)
    Note over C: execve(Ziel)
    P->>P: waitpid
    P->>P: Audit-JSON schreiben

Schichten

1. Truthimatics Public Version

Evidenzbasierte Bewertungsengine. Sammelt gewichtete Beobachtungen über die ausgeführte Binärdatei und ermittelt ein endgültiges Urteil (DETERMINISTIC, REJECT oder UNCERTAIN). Jede Beobachtung hat ein Gewicht; jede einzelne Beobachtung mit einem Gewicht >50 % der Gesamtsumme entscheidet über das Urteil.

2. Namespaces

Fünf Namespaces werden via clone() erstellt:

Erfordert CAP_SYS_ADMIN im ursprünglichen Namespace.

3. pivot_root

Ersetzt das Wurzelverzeichnis des Mount-Namespace durch das --root-Verzeichnis:

1. Binde das Wurzelverzeichnis auf sich selbst ein (MS_BIND|MS_REC)
2. pivot_root(new_root, put_old) – tausche den Mount-Baum
3. chdir("/") – in das neue Wurzelverzeichnis wechseln
4. umount2("/.pivot_old", MNT_DETACH) – altes Root lösen
5. rmdir("/.pivot_old") – aufräumen

Dies ist strikt stärker als chroot(2) – es gibt für den sandboxierten Prozess keine Möglichkeit, zum Host-Root zurückzukehren, selbst mit CLONE_NEWNS von innerhalb der Sandbox (was bereits durch seccomp blockiert ist).

4. Capabilities

Alle Capabilities werden entfernt via:

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

Der Prozess entfernt setuid/setgid vor capset, sodass die UID-Änderung wirksam wird, während CAP_SETUID noch gehalten wird. Nach capset sind alle Caps weg und die securebits sind gesperrt – eine erneute Aktivierung ist nicht möglich.

5. NO_NEW_PRIVS

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

Verhindert, dass der Prozess oder seine Kinder neue Privilegien über setuid-Binärdateien, Datei-Capabilities oder LSM-Übergänge erlangen. Irreversibel.

6. seccomp-BPF (Whitelist-v1)

Erlaubnisliste von 15 Syscalls – alles, was nicht auf der Liste steht, bekommt SECCOMP_RET_KILL:

Der BPF-Filter wird dynamisch generiert: Für jeden Whitelist-Eintrag wird eine Sprungkette ausgegeben, die entweder erlaubt (wenn der Syscall übereinstimmt) oder zu KILL durchfällt. Die Architektur wird zuerst geprüft (AUDIT_ARCH_X86_64).

Der Filter wird unabhängig von einem eigenständigen Test (tests/seccomp_filter_test.c, 8/8 bestanden) verifiziert, der via fork+execve Testfälle gegen ein echtes prctl(PR_SET_SECCOMP) ohne Root-Rechte ausführt.

7. Audit

Jede Ausführung erzeugt einen JSON-Auditdatensatz:

{
  "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..."
}

Geschrieben nach build/audits/<binary-name>.audit.json. Der content_fingerprint ist ein BLAKE2b-256-Hash der Zielbinärdatei, der vom Elternprozess berechnet wird, nachdem das Kind beendet ist.

Verwendung

z_jail --root=<verz> [--seccomp-enforce] [--self-hash=<hex>]
       [--quiet] [--verbose] -- <programm> [argumente...]

Beispiele

# Statische Binärdatei mit allen Schutzmaßnahmen ausführen
sudo z_jail --root=./roots --seccomp-enforce -- bin/hello_static

# Mit Integritätsprüfung der Binärdatei ausführen
sudo z_jail --root=./roots --seccomp-enforce \
  --self-hash=$(sha256sum z_jail | cut -c1-64) -- bin/programm

# Stiller Modus (kein Audit-JSON)
sudo z_jail --root=./roots --quiet -- bin/programm

Exit-Codes

Build & Installation

Voraussetzungen

• Linux-Kernel ≥ 5.4 (Namespaces, seccomp-BPF, pivot_root)
• GCC ≥ 11 (getestet mit 11.4, 13.2, 15.2)
• Keine externen Bibliotheken – nur die Standard-C-Toolchain

Befehle

make              # z_jail bauen (~130 KiB PIE-Binärdatei)
make install      # nach /usr/local/bin + Manpage installieren
make clean        # Build-Artefakte entfernen
make dist         # Release-Tarball erstellen
make check        # Rauchtest (--version + --help)

Die Binärdatei wird als Positionsunabhängiges Executable mit -fstack-protector-strong, -D_FORTIFY_SOURCE=2, vollständigem RELRO und -z now gebaut.

Compile-Zeit-Optionen

make CC=clang CFLAGS="-O3 -march=native"   # benutzerdefinierter Compiler/Flags

Tests

Schnelltest (kein Root)

# seccomp-Filter-Logik (8 Tests)
tests/build/seccomp_filter_test

# BLAKE2b Known-Answer-Test
tests/build/blake2b_known

Diese benötigen kein Root und laufen in unter 100 ms.

Vollständige Testsuite

make -C tests setup          # Payloads + Test-Roots bauen
sudo bash tests/run_tests.sh # 17 Szenarien

Erfordert Root für die Namespace-Erstellung. Die Testsuite deckt ab:

Leistung

Gemessen auf WSL2 (Kernel 6.18.x-microsoft-standard-WSL2, Kali Linux), 50 Proben pro Werkzeug, einheitliche Arbeitslast (eine freistehende statische Binärdatei, deren Körper exit_group(0) ist), zeitlich erfasst mit einem getrusage-Testrahmen. Siehe docs/BENCHMARKS.md für die Methodik.

Direkter Vergleich (gleicher Host, gleiche Methodik)

Unter den getesteten Bedingungen hat Z-Jail die kleinste residente Menge der drei prozessorientierten Sandboxen und eine Latenz zwischen bwrap und nsjail. Bubblewrap ist am schnellsten, führt aber standardmäßig keine seccomp-Filterung durch, macht also weniger Einrichtungsarbeit; Z-Jail installiert bei jedem Lauf eine seccomp-Whitelist, entfernt Capabilities und führt pivot_root aus. gVisor (runsc) stürzt auf diesem WSL2-Kernel ab und konnte nicht gemessen werden; Firecracker isoliert über eine MicroVM (VM-Kaltstart, eine andere Metrik) und ist von der Fork-zu-Exec-Tabelle ausgeschlossen. Dies sind Einzel-Host-Zahlen – behandeln Sie sie als relativ.

Hinweis: Die älteren dokumentierten Werte (~8 ms, ~4 MiB, ~130 KiB) stimmen nicht mit einem aktuellen make-Build (~73 KiB, ~5,9 ms) überein und scheinen ungenau gewesen zu sein; die obigen Zahlen wurden an dieser Codebasis neu gemessen. Truthimatics ist immer noch Teil des Codes und wurde nicht entfernt (die alten axiom_jail-Berichte verwendeten einfach einen anderen Binärnamen und Testrahmen). Ein während des Benchmarkings gefundener Mount-Propagation-Fehler wurde in src/sandbox.c behoben (MS_REC|MS_PRIVATE vor dem Bind-Mount); das rekursive Remount trägt zur gemessenen Latenz bei.

Bedrohungsmodell

Im Scope

• Beliebige native Codeausführung durch eine nicht vertrauenswürdige Nutzlast
• Ausbruch via chroot, mount, ptrace, socket, process_vm_writev
• Fork-Bomben, CPU-Auslastung (RLIMIT_CPU), Speicherüberlastung (RLIMIT_AS)
• Dateideskriptor-Leaks über execve
• setuid / dynamischer Linker / LD_PRELOAD-Eskalation
• Entfernung des seccomp-Filters oder erneute Aktivierung von Capabilities

Nicht im Scope

• Kernel-Zero-Days außerhalb der erlaubten Syscall-Oberfläche
• Hardware-Seitenkanäle (Spectre, Meltdown)
• Ausbruch aus ko-lokalisierter VM via gemeinsame /proc, /sys-Mounts
• Netzwerkausgang über das hinaus, was CLONE_NEWNET + blockiertes socket bietet
• Ressourcenaushungerung von Geschwister-Sandboxen (benötigt cgroup-Unterstützung)

Annahmen

• Host-Kernel ist unveränderter Linux ≥ 5.4
• clone(CLONE_NEWNS|CLONE_NEWPID|...) ist erfolgreich (erfordert CAP_SYS_ADMIN)
• Zielbinärdatei ist statisch gelinkt (oder dynamische Bibliotheken sind in --root verfügbar)
• --self-hash=<hex> ist in Produktionsumgebungen konfiguriert

Dokumentation

Roadmap

v1 (aktuell)

• 7-schichtige abgestufte Verteidigungssandbox
• BLAKE2b-256-Inhalts-Fingerprinting
• Audit-JSON-Ausgabe
• 17 Testszenarien
• Manpage, Vervollständigungen (bash, zsh, fish)

v2 (geplant)

• Externe seccomp-Richtliniendatei (JSON oder BPF-Quelle)
• Anpassbare Namespace-Flags pro Sandbox-Instanz
• Konfigurierbare Syscall-Whitelist über CLI
• Performance-Profiling-Hooks für CI-Integration
• Release-Signierung (minisign/signify)

Status

Lizenz

MIT – siehe LICENSE für den vollständigen Text.

Z-Jail wurde auf WSL2 (Kali Linux, GCC 15.2.0) erstellt, Ziel ist Linux 5.4+. Gepflegt von Division-36. Fehler bitte im Issue-Tracker melden.