crates/gunnar-server/src/sandbox.rs
//! **An unprivileged network namespace of the caller's own.**
//!
//! Gunnar builds nothing (builds run in dwarves through Build Thing). This
//! module survives the build runner because the PID 1 networking tests
//! (`tests/pid1_edda_netns.rs`) enter a Linux **network namespace of their
//! own**, with nothing in it but a loopback interface that is down, to prove
//! the appliance's network bring-up without touching the host's.
//!
//! # How it works unprivileged, which is the whole trick
//!
//! Creating a network namespace needs `CAP_SYS_ADMIN`. An ordinary user does
//! not have it — but a user who first creates a **user** namespace is root
//! *inside* it, and root inside a user namespace may create the other kinds.
//! So the child does, in order, before `exec`:
//!
//! 1. `unshare(CLONE_NEWUSER)` — now it is uid 65534 (overflow) with no map;
//! 2. `deny` to `/proc/self/setgroups` — required before a uid map may be
//! written by an unprivileged process, and it is what stops the namespace
//! being used to drop groups;
//! 3. `0 <euid> 1` to `/proc/self/uid_map` and the same for gid — so inside the
//! namespace it is root, and outside it is still the same unprivileged user
//! it always was. **No privilege is gained**: every file access is still
//! checked against the real uid.
//! 4. `unshare(CLONE_NEWNET)` — allowed now, and the point of all of it.
//!
//! # Everything here runs between `fork` and `exec`
//!
//! Which is the most constrained place in Unix: the child has one thread, and
//! any lock another thread held at `fork` is held for ever. So there is no
//! allocation and no formatting — `rustix`'s `open`/`write` over stack buffers,
//! and the map integers rendered by hand. That is why this file looks the way it
//! does; it is not style.
//!
//! `rustix` and not `libc`, deliberately: the workspace chose it because on
//! `x86_64-linux` its backend is raw syscalls written in Rust, which is what
//! keeps the musl appliance free of a `PT_INTERP`. Reaching for `libc` to get
//! one syscall rustix already spells would have undone that.
//!
//! # What it does not do
//!
//! No mount namespace, no seccomp filter, no cgroup. A build can still read the
//! whole filesystem it is run as, and can still spend the machine's CPU. Those
//! are the next things and they are named rather than implied: this module
//! closes **network** hermeticity, which is the one that decides whether a
//! dependency came from the vendored tree or from the internet.
/// Everything the sandbox can fail at, as a number the child can report.
///
/// An enum rather than a message, because the failing code runs after `fork`
/// and cannot allocate one. The parent turns it back into a sentence.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SandboxError {
UserNamespace,
SetGroups,
UidMap,
GidMap,
NetworkNamespace,
}
impl SandboxError {
fn from_raw(code: i32) -> Option<SandboxError> {
Some(match code {
1 => SandboxError::UserNamespace,
2 => SandboxError::SetGroups,
3 => SandboxError::UidMap,
4 => SandboxError::GidMap,
5 => SandboxError::NetworkNamespace,
_ => return None,
})
}
/// What an operator can act on.
pub fn explain(self) -> &'static str {
match self {
SandboxError::UserNamespace => {
"this kernel refused to create a user namespace. Unprivileged user namespaces \
may be disabled (`kernel.unprivileged_userns_clone=0`, or an AppArmor/Docker \
profile). Without one, an ordinary user cannot make a network namespace and \
the build cannot be made hermetic."
}
SandboxError::SetGroups => {
"writing `deny` to /proc/self/setgroups failed, so no uid map may be written"
}
SandboxError::UidMap => "writing /proc/self/uid_map failed",
SandboxError::GidMap => "writing /proc/self/gid_map failed",
SandboxError::NetworkNamespace => {
"this kernel refused to create a network namespace inside the user namespace"
}
}
}
}
/// Turn the child's exit status back into a sandbox failure, if it is one.
///
/// The child exits with a small reserved code when it could not enter the
/// sandbox, **before** the build command runs. Reserved rather than shared with
/// the build's own exit codes, so "the sandbox failed" is never mistaken for
/// "the build failed" — the two need different people.
pub const SANDBOX_EXIT_BASE: i32 = 120;
/// The exit code a child uses when the sandbox could not be entered.
pub fn exit_code(error: SandboxError) -> i32 {
SANDBOX_EXIT_BASE
+ match error {
SandboxError::UserNamespace => 1,
SandboxError::SetGroups => 2,
SandboxError::UidMap => 3,
SandboxError::GidMap => 4,
SandboxError::NetworkNamespace => 5,
}
}
/// **Leave a forked child from its `pre_exec` hook**: `_exit(2)`, which ends the process
/// and runs nothing. NOT `std::process::exit` (libc `exit(3)`): that runs the atexit
/// handlers and the stdio cleanup of a process forked from a MULTI-threaded one, and a
/// lock another thread held at the fork is never released there — the child parks on a
/// futex for good (the gunnar suite, 2026-09-30: 2 h 30 min in the sandbox test; a server
/// whose sandbox cannot be entered would hold that build forever).
pub fn leave_child(code: i32) -> ! {
extern "C" {
fn _exit(status: i32) -> !;
}
// SAFETY: _exit(2) is async-signal-safe and takes no lock; it never returns.
unsafe { _exit(code) }
}
/// The failure a child's exit status describes, if it is a sandbox one.
pub fn error_from_exit(code: i32) -> Option<SandboxError> {
if !(SANDBOX_EXIT_BASE..SANDBOX_EXIT_BASE + 16).contains(&code) {
return None;
}
SandboxError::from_raw(code - SANDBOX_EXIT_BASE)
}
/// Write `bytes` to `path`, allocating nothing.
///
/// Called between `fork` and `exec`, where nothing may allocate or take a lock.
/// `rustix::fs::open` puts the path on the stack for a short one, and the write
/// is one syscall.
fn write_proc(path: &str, bytes: &[u8]) -> bool {
let Ok(fd) = rustix::fs::open(path, rustix::fs::OFlags::WRONLY, rustix::fs::Mode::empty())
else {
return false;
};
// One write, and it must take everything: `/proc` map files reject a
// partial write rather than continuing it, so a short write is a failure
// and not something to loop on.
matches!(rustix::io::write(&fd, bytes), Ok(n) if n == bytes.len())
}
/// Render `value` into `buf` as decimal, returning the slice used.
///
/// Hand-rolled because `format!` allocates and this runs after `fork`.
fn render(value: u32, buf: &mut [u8; 12]) -> &[u8] {
if value == 0 {
buf[0] = b'0';
return &buf[..1];
}
let mut at = buf.len();
let mut value = value;
while value > 0 {
at -= 1;
buf[at] = b'0' + (value % 10) as u8;
value /= 10;
}
// Shift to the front so the caller gets a slice starting at zero.
let len = buf.len() - at;
buf.copy_within(at.., 0);
&buf[..len]
}
/// Enter a user namespace and then a network namespace of our own.
///
/// # Safety
///
/// Must be called between `fork` and `exec`, from the child. `unshare` moves
/// the whole *process* into new namespaces, which is unsound while other
/// threads are running; a forked child has exactly one thread, which is what
/// makes this sound there and nowhere else. It also allocates nothing and takes
/// no lock — see the module docs for why that matters in the same place.
pub unsafe fn enter() -> Result<(), SandboxError> {
use rustix::thread::UnshareFlags;
let uid = rustix::process::geteuid().as_raw();
let gid = rustix::process::getegid().as_raw();
// `unshare_unsafe`, and the name is right: `unshare` changes the whole
// PROCESS's namespaces, which is unsound in a multi-threaded program. Here
// the process is a freshly forked child with exactly one thread, on its way
// to `exec` — the one place where it is sound, and the reason this function
// may only be called from `pre_exec`.
if unsafe { rustix::thread::unshare_unsafe(UnshareFlags::NEWUSER) }.is_err() {
return Err(SandboxError::UserNamespace);
}
// Required before an unprivileged uid map may be written, and it is what
// stops a user namespace being a way to drop supplementary groups.
if !write_proc("/proc/self/setgroups", b"deny") {
return Err(SandboxError::SetGroups);
}
// `0 <uid> 1` — root inside, the same user outside. No privilege is gained:
// every file access is still checked against the real uid.
let mut map = [0u8; 32];
let mut digits = [0u8; 12];
let mut at = 0usize;
map[at] = b'0';
at += 1;
map[at] = b' ';
at += 1;
let rendered = render(uid, &mut digits);
map[at..at + rendered.len()].copy_from_slice(rendered);
at += rendered.len();
map[at..at + 2].copy_from_slice(b" 1");
at += 2;
if !write_proc("/proc/self/uid_map", &map[..at]) {
return Err(SandboxError::UidMap);
}
let mut at = 0usize;
map[at] = b'0';
at += 1;
map[at] = b' ';
at += 1;
let rendered = render(gid, &mut digits);
map[at..at + rendered.len()].copy_from_slice(rendered);
at += rendered.len();
map[at..at + 2].copy_from_slice(b" 1");
at += 2;
if !write_proc("/proc/self/gid_map", &map[..at]) {
return Err(SandboxError::GidMap);
}
// The point of all of it.
if unsafe { rustix::thread::unshare_unsafe(UnshareFlags::NEWNET) }.is_err() {
return Err(SandboxError::NetworkNamespace);
}
Ok(())
}
/// Is an unprivileged sandbox available on this kernel at all?
///
/// Asked by forking a child that does nothing but try to enter one. **Not**
/// inferred from a sysctl: there are three separate ways a distribution can
/// forbid this (the sysctl, an AppArmor profile, a seccomp filter in a
/// container), and reading one of them would answer for one of the three.
pub fn available() -> Result<(), SandboxError> {
use std::os::unix::process::CommandExt as _;
// `true(1)` and not this binary: re-execing the server to probe would run
// whatever `main` does with no arguments, and the probe must do nothing at
// all beyond entering the namespace.
// A32-14, a process by design: the namespace probe runs `true(1)`, which does nothing, to learn whether this box may enter a namespace at all.
let mut command = std::process::Command::new("true");
// The hook is bound OUTSIDE the `unsafe` block: an `unsafe` block extends
// lexically into a closure written inside it, so the inner one was redundant (`unused_unsafe`) and its
// SAFETY note unenforced. Bound here, each `unsafe` covers one call.
let enter_sandbox = || {
// SAFETY: `pre_exec` runs in the forked child, single-threaded,
// before `exec` — which is `enter`'s whole requirement.
if let Err(err) = unsafe { enter() } {
leave_child(exit_code(err));
}
Ok(())
};
// SAFETY: `enter` allocates nothing and takes no lock, which is the whole
// requirement `pre_exec` imposes. [`leave_child`] (`_exit(2)`) in the child is the
// documented way to report a pre-exec failure without unwinding.
unsafe {
command.pre_exec(enter_sandbox);
}
let status = command
.stdin(std::process::Stdio::null())
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null())
.status();
// A probe that could not even be spawned is not a sandbox verdict, and must
// not be reported as one.
let Ok(status) = status else {
return Ok(());
};
match status.code().and_then(error_from_exit) {
Some(err) => Err(err),
None => Ok(()),
}
}
#[cfg(test)]
mod tests {
use super::*;
/// **A `pre_exec` hook leaves by `_exit(2)`, never by `exit(3)`** (found 2026-09-30:
/// the gunnar suite hung 2 h 30 min in `a_build_in_the_sandbox_cannot_reach_a_listener_the_host_can`,
/// its forked child in the new user namespace, parked on a futex — `enter` failed and
/// the hook called `std::process::exit`, which runs the atexit handlers and stdio
/// cleanup of a process forked from a MULTI-threaded one: a lock another thread held at
/// the fork is never released there; and `spawn` itself waits on the exec pipe, so the
/// parent hangs with it). Reproduced deterministically: an atexit handler that stalls
/// 3 s, only in a forked child. The control arm (`std::process::exit`) runs it — the
/// spawn is held that long; [`leave_child`] runs nothing and exits at once with its code.
#[test]
fn a_pre_exec_hook_that_fails_leaves_at_once_even_when_an_atexit_handler_would_block() {
use std::os::unix::process::CommandExt as _;
use std::sync::atomic::{AtomicI32, Ordering};
static PARENT: AtomicI32 = AtomicI32::new(0);
extern "C" fn blocks_in_a_child() {
if std::process::id() as i32 != PARENT.load(Ordering::SeqCst) {
std::thread::sleep(std::time::Duration::from_secs(3));
}
}
extern "C" {
fn atexit(f: extern "C" fn()) -> i32;
}
PARENT.store(std::process::id() as i32, Ordering::SeqCst);
// SAFETY: registering a plain extern "C" fn with libc's atexit.
assert_eq!(unsafe { atexit(blocks_in_a_child) }, 0);
// How long the spawn is held, and the code the child left with.
let timed = |leave: fn(i32) -> !| -> (std::time::Duration, Option<i32>) {
let mut c = std::process::Command::new("true");
// SAFETY: the hook only leaves; it is what is under test.
unsafe {
c.pre_exec(move || leave(97));
}
let t0 = std::time::Instant::now();
let st = c
.stdin(std::process::Stdio::null())
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null())
.status()
.expect("spawned");
(t0.elapsed(), st.code())
};
let (held, code) = timed(|c| std::process::exit(c));
assert!(held >= std::time::Duration::from_millis(2500), "the control: exit(3) in the forked child ran the stalling handler (held {held:?}, code {code:?})");
let (held, code) = timed(leave_child);
assert_eq!(code, Some(97), "leave_child exits with its code");
assert!(
held < std::time::Duration::from_millis(2500),
"leave_child ran an atexit handler: held {held:?}"
);
}
#[test]
fn the_exit_codes_round_trip_and_do_not_collide_with_ordinary_ones() {
for err in [
SandboxError::UserNamespace,
SandboxError::SetGroups,
SandboxError::UidMap,
SandboxError::GidMap,
SandboxError::NetworkNamespace,
] {
assert_eq!(error_from_exit(exit_code(err)), Some(err));
}
// A build that exits 1 is a failed build, not a failed sandbox. This is
// the confusion the reserved range exists to prevent.
for ordinary in [0, 1, 2, 101, 119] {
assert_eq!(error_from_exit(ordinary), None, "code {ordinary}");
}
}
#[test]
fn the_decimal_renderer_agrees_with_the_formatter() {
for value in [0u32, 1, 9, 10, 99, 1000, 65534, u32::MAX] {
let mut buf = [0u8; 12];
assert_eq!(
std::str::from_utf8(render(value, &mut buf)).unwrap(),
value.to_string(),
"rendering {value}"
);
}
}
}
#[cfg(test)]
mod live_tests {
use super::*;
use std::io::Read as _;
use std::os::unix::process::CommandExt as _;
/// Run `bash -c <script>`, optionally inside the sandbox, and report
/// whether it succeeded.
fn run(script: &str, sandboxed: bool) -> Option<bool> {
let mut command = std::process::Command::new("bash");
command.arg("-c").arg(script);
if sandboxed {
// SAFETY: `enter` allocates nothing and takes no lock.
unsafe {
command.pre_exec(|| {
if let Err(err) = enter() {
leave_child(exit_code(err));
}
Ok(())
});
}
}
let status = command
.stdin(std::process::Stdio::null())
.stdout(std::process::Stdio::null())
.stderr(std::process::Stdio::null())
.status()
.ok()?;
// A sandbox that could not be entered is not a verdict about the
// script, so it is `None` and the caller skips rather than asserting.
if status.code().and_then(error_from_exit).is_some() {
return None;
}
Some(status.success())
}
/// **The sandbox really cuts the network**, and the control says the test
/// could have noticed if it did not.
///
/// A listener on loopback is the target: inside a fresh network namespace
/// there is one interface, `lo`, and it is **down**, so the connect fails.
/// Outside, it succeeds — which is the half that makes the first assertion
/// mean something rather than being satisfied by a broken script.
#[test]
fn a_build_in_the_sandbox_cannot_reach_a_listener_the_host_can() {
let listener = std::net::TcpListener::bind("127.0.0.1:0").expect("bind");
let port = listener.local_addr().expect("addr").port();
// Accept in the background so a successful connect completes rather
// than sitting in the backlog.
std::thread::spawn(move || {
for mut stream in listener.incoming().take(4).flatten() {
let mut sink = [0u8; 1];
let _ = stream.read(&mut sink);
}
});
let script = format!("exec 3<>/dev/tcp/127.0.0.1/{port}");
let Some(outside) = run(&script, false) else {
unreachable!("the unsandboxed arm cannot report a sandbox failure")
};
assert!(
outside,
"the control failed: bash could not reach a listener on loopback without any \
sandbox, so this test cannot tell a cut network from a broken script"
);
match run(&script, true) {
None => eprintln!(
"skipped: this kernel does not allow unprivileged user namespaces, so the \
sandbox cannot be exercised here."
),
Some(inside) => assert!(
!inside,
"a process inside the sandbox reached a listener on the host's loopback. \
The network namespace is not being entered."
),
}
}
/// The sandbox does not break the ordinary case: a build that touches only
/// the filesystem still runs, and still runs **as the same user**.
#[test]
fn a_build_in_the_sandbox_still_owns_the_files_it_writes() {
let dir = tempfile::tempdir().expect("tempdir");
let path = dir.path().join("written");
let script = format!("echo hello > {}", path.display());
match run(&script, true) {
None => eprintln!("skipped: no unprivileged user namespaces on this kernel"),
Some(ok) => {
assert!(
ok,
"a build that only writes a file failed inside the sandbox"
);
assert_eq!(
std::fs::read_to_string(&path).expect("read it back"),
"hello\n",
"the sandboxed build could not write to the directory it was given. The uid \
map is wrong: inside the namespace it must be root and outside it must \
still be the same unprivileged user."
);
}
}
}
}