libvoid

libvoid is a Linux-only Zig sandboxing library with a small CLI (vb) for running processes inside configurable namespace/cgroup/filesystem/Landlock isolation.

What Is In This Repo

• Static library: lib/libvoid.zig
• CLI: bin/vb.zig
• Examples: examples/embedder_launch_shell.zig, examples/embedder_events.zig, examples/embedder_landlock.zig
• Build graph: build.zig

Requirements

• Linux host (build fails on non-Linux targets)
• Zig 0.15.x
• libc toolchain
• Optional: direnv (recommended in this repo)

Build

If you use direnv:

direnv allow
direnv exec"/doc/code/libvoid" make build

Or directly:

make build

Test

direnv exec"/doc/code/libvoid" zig build test

Integration tests are gated by environment variable:

LIBVOID_RUN_INTEGRATION=1 direnv exec"/doc/code/libvoid" zig build test

Install Library Artifact

make install

This installs:

• ~/.local/lib/libvoid.a

CLI Quick Use

direnv exec"/doc/code/libvoid" zig build vb
./zig-out/bin/vb -- /bin/sh -c 'echo hello'

Library Quick Use

See in-source docs at lib/libvoid.zig for embedder examples:

• launch shell config
• event callback wiring

Rootfs Mode Note (Parity)

• Bubblewrap-style behavior in libvoid uses pivot_root (default).
• chroot remains available only as an explicit libvoid extension via .runtime.use_pivot_root = false.
• chroot mode is less isolated than pivot_root and is not considered bubblewrap parity behavior.

Landlock LSM Support

Landlock (kernel 5.13+) restricts filesystem and network access at the kernel level. It works independently of namespaces, making libvoid dual-function: isolate processes (namespaces) or restrict processes (Landlock) or both.

# CLI: restrict a process to read /usr and /etc only
vb --landlock-read /usr --landlock-read /etc --landlock-rw /dev -- /bin/sh
# Portable rules: skip missing paths with -try variants
vb --landlock-read /usr --landlock-read-try /lib64 -- /bin/sh

// Library: Landlock without any namespace isolationconstcfg: libvoid.JailConfig= .{
.name="restricted",
.rootfs_path="/",
.cmd= &.{ "/bin/sh" },
.isolation= .{ .user=false, .net=false, .mount=false,
.pid=false, .uts=false, .ipc=false },
.security= .{ .landlock= .{ .enabled=true, .fs_rules= &.{
.{ .path="/usr", .access=.read },
.{ .path="/etc", .access=.read },
.{ .path="/dev", .access=.read_write },
} } },
};

See TLDR.md section 9.3 for full details.

Current Hardening Status

Recent work focused on:

• Landlock LSM filesystem/network restriction support (kernel 5.13+, ABI v1–v5)
• netlink parser bounds/alignment hardening and malformed-input tests
• fd/resource lifecycle cleanup in spawn/network/fs paths
• synchronization protocol validation between parent/child setup phases
• stress/regression coverage (sequential + parallel launch matrices)

The project is actively hardened and tested, but still expects Linux capability/ namespace availability from the host environment.

For detailed architecture, lifecycle, parser/network hardening notes, and operational troubleshooting, see TLDR.md.