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 isolation
const cfg: 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.