envseal 0.3.14

//! Post-clone sandbox helper — finishes Lockdown setup and execs the target.
//!
//! `apply_sandbox(SandboxTier::Lockdown)` runs in the child's `pre_exec`
//! closure, which is restricted to async-signal-safe syscalls. It can call
//! [`unshare(2)`] to create the new namespaces but cannot call [`mount(2)`]
//! (not async-signal-safe). To finish the job we re-exec into envseal itself
//! in `__sandbox_helper` mode: by that point we are out of `pre_exec` and
//! free to use any syscall, but still inside the new namespaces.
//!
//! # Helper protocol
//!
//! ```text
//! envseal __sandbox_helper --target-fd <N> --arg0 <PATH> -- <argv1> [argv...]
//! ```
//!
//! - `--target-fd <N>` — file-descriptor (inherited from the parent without
//!   `FD_CLOEXEC`) pinning the target binary. The helper `execve`s
//!   `/proc/self/fd/N` so TOCTOU-binding is preserved across the helper
//!   indirection.
//! - `--arg0 <PATH>` — `argv[0]` to pass to the target so it sees its
//!   conventional path, not `/proc/self/fd/N`.
//! - `-- <argv1> ...` — the rest of the target's argv.
//!
//! # Setup performed
//!
//! - `MS_PRIVATE` propagation on `/` so subsequent mounts don't leak back to
//!   the host.
//! - Fresh `tmpfs` mounted on `/tmp`. This is what gives Lockdown its
//!   "child cannot exfiltrate via the filesystem" property: anything the
//!   child writes to `/tmp` lives in tmpfs that the host parent has no
//!   handle to.
//!
//! # Process lifetime
//!
//! Returns `!` — on success it never returns (it `execve`s the target).
//! On failure it prints to stderr and exits non-zero so the parent
//! supervisor can detect it.

#![cfg(target_os = "linux")]

use std::ffi::CString;
use std::os::unix::io::RawFd;

/// Enter helper mode: parse helper args, finish Lockdown setup, exec target.
///
/// Called from the CLI dispatcher when `argv[1] == "__sandbox_helper"`.
/// Never returns — either `execve`s the target or `exit`s with an error.
///
/// # Errors / exits
///
/// Writes a one-line diagnostic to stderr and `exit(127)`s on argv parse
/// failure, mount failure, or `execve` failure.
pub fn run_helper(args: &[String]) -> ! {
    let parsed = match parse_args(args) {
        Ok(p) => p,
        Err(msg) => {
            eprintln!("envseal __sandbox_helper: {msg}");
            std::process::exit(127);
        }
    };

    if let Err(msg) = setup_private_mounts() {
        eprintln!("envseal __sandbox_helper: mount setup failed: {msg}");
        std::process::exit(127);
    }

    // Audit H6: the original setup_private_mounts() remounts root
    // read-only and overlays tmpfs on /tmp, /dev/shm, /var/tmp — but
    // does NOT cover the inherited cwd. If the parent's cwd lived
    // outside those tmpfs mountpoints, the child could still write
    // there (and any process the host had cd'd into a project dir
    // when launching `envseal supervised` was such a parent). chdir
    // to /tmp before exec so writes via cwd hit the namespace-local
    // tmpfs, not the host filesystem.
    //
    // SAFETY: chdir is async-signal-safe and is allowed in
    // post-pre_exec helper code. Failure to chdir is escalated —
    // the entire premise of Lockdown is "sandbox or refuse".
    {
        let target = std::ffi::CString::new("/tmp").expect("/tmp is a valid CStr literal");
        // SAFETY: target is a valid NUL-terminated C string.
        let rc = unsafe { libc::chdir(target.as_ptr()) };
        if rc != 0 {
            let err = std::io::Error::last_os_error();
            eprintln!("envseal __sandbox_helper: chdir(\"/tmp\") failed: {err}");
            std::process::exit(127);
        }
    }

    // Audit M20: read the secret bytes from the inherited pipe-fd
    // and set the env var IMMEDIATELY before exec_target. The window
    // during which the secret lives in /proc/<helper_pid>/environ is
    // therefore the microseconds between this setenv and the
    // upcoming execve — orders of magnitude tighter than the entire
    // helper lifetime the env-var path used to expose.
    if let (Some(fd), Some(env_name)) = (parsed.secret_fd, parsed.secret_env_name.as_deref()) {
        match read_secret_from_fd(fd) {
            Ok(value) => {
                // Hold the secret bytes in Zeroizing so the heap
                // buffer is wiped on drop. The kernel scrubs the
                // heap on the upcoming execve regardless, but for
                // the microsecond window between setenv and exec,
                // an attacker who pauses the helper (e.g. ptrace)
                // would otherwise see the cleartext on heap.
                let value = zeroize::Zeroizing::new(value);
                if let Err(msg) = setenv_async_signal_safe(env_name, &value) {
                    eprintln!("envseal __sandbox_helper: setenv failed: {msg}");
                    std::process::exit(127);
                }
            }
            Err(msg) => {
                eprintln!("envseal __sandbox_helper: read secret-fd failed: {msg}");
                std::process::exit(127);
            }
        }
    }

    // `exec_target` returns `Result<Infallible, String>`. The `Ok` arm
    // cannot be constructed (`Infallible` is uninhabited), so this
    // match exhaustively handles the only reachable case — and we
    // never have to fabricate a panic for the impossible branch.
    match exec_target(&parsed) {
        Err(msg) => {
            eprintln!("envseal __sandbox_helper: exec failed: {msg}");
            std::process::exit(127);
        }
    }
}

/// Read the secret bytes from the inherited pipe read-end, capped
/// at 64 KiB so a malicious caller cannot make the helper allocate
/// unbounded memory through the pipe. Returns the bytes verbatim
/// (the caller is expected to setenv with the buffer as-is).
fn read_secret_from_fd(fd: RawFd) -> Result<Vec<u8>, String> {
    use std::io::Read;
    use std::os::fd::FromRawFd;

    /// Cap matches the vault's MAX_SECRET_SIZE_BYTES from `vault::store`.
    const MAX_SECRET_BYTES: u64 = 64 * 1024;

    // SAFETY: fd was passed in via --secret-fd; the parent is responsible
    // for handing us a valid pipe-read fd. We take ownership so the
    // file is closed after we read EOF.
    let mut file = unsafe { std::fs::File::from_raw_fd(fd) };
    let mut buf = Vec::with_capacity(1024);
    file.by_ref()
        .take(MAX_SECRET_BYTES)
        .read_to_end(&mut buf)
        .map_err(|e| format!("read secret-fd: {e}"))?;
    Ok(buf)
}

/// `setenv` for an arbitrary byte slice. We avoid `std::env::set_var`
/// because it requires UTF-8; secret values *are* validated as UTF-8
/// at vault decrypt time, but going through `libc::setenv` keeps the
/// path async-signal-safe and avoids an extra utf-8 round-trip in
/// the post-`pre_exec` window.
fn setenv_async_signal_safe(name: &str, value: &[u8]) -> Result<(), String> {
    use std::ffi::CString;
    let name_c = CString::new(name).map_err(|_| "env name contains NUL".to_string())?;
    let value_c = CString::new(value).map_err(|_| "secret value contains NUL".to_string())?;
    // SAFETY: setenv is documented async-signal-safe on Linux + macOS.
    // The CString allocations live for the duration of this call and
    // are freed on return; libc copies the bytes into its own
    // env block.
    let rc = unsafe { libc::setenv(name_c.as_ptr(), value_c.as_ptr(), 1) };
    if rc != 0 {
        return Err(std::io::Error::last_os_error().to_string());
    }
    Ok(())
}

struct ParsedArgs {
    target_fd: RawFd,
    arg0: String,
    rest_argv: Vec<String>,
    /// Audit M20: the helper now reads the secret from an inherited
    /// pipe-read fd instead of the environment. Both fields are
    /// populated together; presence of one without the other is a
    /// usage error.
    secret_fd: Option<RawFd>,
    secret_env_name: Option<String>,
}

fn parse_args(args: &[String]) -> Result<ParsedArgs, String> {
    let sep = args
        .iter()
        .position(|a| a == "--")
        .ok_or_else(|| "missing `--` separator before target argv".to_string())?;
    let head = &args[..sep];
    let tail = &args[sep + 1..];

    let mut found_target_fd: Option<RawFd> = None;
    let mut found_arg0: Option<String> = None;
    let mut found_secret_fd: Option<RawFd> = None;
    let mut found_secret_env_name: Option<String> = None;
    let mut iter = head.iter();
    while let Some(arg) = iter.next() {
        match arg.as_str() {
            "--target-fd" => {
                let v = iter
                    .next()
                    .ok_or_else(|| "--target-fd requires a value".to_string())?;
                found_target_fd = Some(
                    v.parse::<RawFd>()
                        .map_err(|e| format!("invalid --target-fd {v:?}: {e}"))?,
                );
            }
            "--arg0" => {
                found_arg0 = Some(
                    iter.next()
                        .ok_or_else(|| "--arg0 requires a value".to_string())?
                        .clone(),
                );
            }
            "--secret-fd" => {
                let v = iter
                    .next()
                    .ok_or_else(|| "--secret-fd requires a value".to_string())?;
                found_secret_fd = Some(
                    v.parse::<RawFd>()
                        .map_err(|e| format!("invalid --secret-fd {v:?}: {e}"))?,
                );
            }
            "--secret-env-name" => {
                found_secret_env_name = Some(
                    iter.next()
                        .ok_or_else(|| "--secret-env-name requires a value".to_string())?
                        .clone(),
                );
            }
            other => return Err(format!("unrecognized helper flag: {other}")),
        }
    }

    if found_secret_fd.is_some() != found_secret_env_name.is_some() {
        return Err(
            "--secret-fd and --secret-env-name must be passed together (or neither)".to_string(),
        );
    }

    Ok(ParsedArgs {
        target_fd: found_target_fd.ok_or_else(|| "--target-fd is required".to_string())?,
        arg0: found_arg0.ok_or_else(|| "--arg0 is required".to_string())?,
        rest_argv: tail.to_vec(),
        secret_fd: found_secret_fd,
        secret_env_name: found_secret_env_name,
    })
}

/// Set up private mounts inside the helper's mount namespace.
///
/// 1. Mark all mounts `MS_PRIVATE`/`MS_REC` so further mounts in this
///    namespace don't propagate back to the host.
/// 2. Remount the root filesystem read-only so the child cannot write to
///    host paths.
/// 3. Mount a fresh `tmpfs` over `/tmp` so writes there live in tmpfs that
///    the host has no handle to.
/// 4. Mount fresh `tmpfs` over `/dev/shm` and `/var/tmp` for ephemeral
///    scratch spaces.
fn setup_private_mounts() -> Result<(), String> {
    // SAFETY: before touching mounts, verify we are in a distinct mount
    // namespace from PID 1. If we are not, remounting root read-only would
    // cripple the host system.
    if !in_private_mount_ns() {
        return Err("refusing to modify mounts: not in a private mount namespace".to_string());
    }

    let root = CString::new("/").map_err(|e| e.to_string())?;
    let none = CString::new("none").map_err(|e| e.to_string())?;
    let tmp = CString::new("/tmp").map_err(|e| e.to_string())?;
    let tmpfs = CString::new("tmpfs").map_err(|e| e.to_string())?;
    let dev_shm = CString::new("/dev/shm").map_err(|e| e.to_string())?;
    let var_tmp = CString::new("/var/tmp").map_err(|e| e.to_string())?;
    // H batch 6 (audit, May 2026): /run, /var/run, /var/lock are
    // common writable paths the original tmpfs overlay missed. A
    // sandboxed child could write to /run/user/<uid>/ to exfiltrate
    // data the host parent could observe. Adding them to the
    // overlay set isolates them too. mount() is idempotent across
    // a fresh mount; if /run was somehow not mountable on a host,
    // we silently skip rather than abort the whole sandbox.
    let run = CString::new("/run").map_err(|e| e.to_string())?;
    let var_run = CString::new("/var/run").map_err(|e| e.to_string())?;
    let var_lock = CString::new("/var/lock").map_err(|e| e.to_string())?;
    let opts = CString::new("size=256m,mode=1777").map_err(|e| e.to_string())?;

    unsafe {
        let ret = libc::mount(
            none.as_ptr(),
            root.as_ptr(),
            std::ptr::null(),
            libc::MS_REC | libc::MS_PRIVATE,
            std::ptr::null(),
        );
        if ret != 0 {
            let err = std::io::Error::last_os_error();
            return Err(format!("MS_PRIVATE on /: {err}"));
        }

        // Remount root read-only to block writes to host filesystem
        let ret = libc::mount(
            none.as_ptr(),
            root.as_ptr(),
            std::ptr::null(),
            libc::MS_REMOUNT | libc::MS_RDONLY | libc::MS_BIND,
            std::ptr::null(),
        );
        if ret != 0 {
            let err = std::io::Error::last_os_error();
            return Err(format!("MS_REMOUNT | MS_RDONLY on /: {err}"));
        }

        // Mount fresh tmpfs on common writable paths. /tmp,
        // /dev/shm, /var/tmp are mandatory (failure aborts the
        // sandbox). /run, /var/run, /var/lock are best-effort —
        // some minimal images don't have these mountpoints, and
        // we'd rather have a slightly leakier sandbox than no
        // sandbox at all.
        for mount_point in [&tmp, &dev_shm, &var_tmp] {
            let ret = libc::mount(
                tmpfs.as_ptr(),
                mount_point.as_ptr(),
                tmpfs.as_ptr(),
                0,
                opts.as_ptr().cast::<libc::c_void>(),
            );
            if ret != 0 {
                let err = std::io::Error::last_os_error();
                return Err(format!(
                    "mount tmpfs on {}: {err}",
                    mount_point.to_string_lossy()
                ));
            }
        }
        for mount_point in [&run, &var_run, &var_lock] {
            // Best-effort: ignore errors. The mountpoint may not
            // exist on minimal images.
            let _ = libc::mount(
                tmpfs.as_ptr(),
                mount_point.as_ptr(),
                tmpfs.as_ptr(),
                0,
                opts.as_ptr().cast::<libc::c_void>(),
            );
        }
    }

    Ok(())
}

/// Check whether the current process is in a mount namespace different
/// from PID 1 (init). Returns `false` if we can't tell, forcing the caller
/// to abort rather than risk modifying the host's mounts.
fn in_private_mount_ns() -> bool {
    let self_ns = std::fs::read_link("/proc/self/ns/mnt");
    let init_ns = std::fs::read_link("/proc/1/ns/mnt");
    match (self_ns, init_ns) {
        (Ok(a), Ok(b)) => a != b,
        _ => false,
    }
}

/// `execve` the target binary via its inherited fd, preserving TOCTOU pinning.
///
/// On success this function never returns (control transfers into the
/// target binary). On failure it returns the OS error wrapped as a
/// `String`. We use [`std::convert::Infallible`] for the success-arm
/// type because it expresses "this branch is unreachable" while
/// staying on stable Rust (the experimental `!` type is not
/// available without nightly).
fn exec_target(parsed: &ParsedArgs) -> Result<std::convert::Infallible, String> {
    let exec_path = format!("/proc/self/fd/{}", parsed.target_fd);
    let exec_path_c = CString::new(exec_path.as_bytes()).map_err(|e| e.to_string())?;
    let arg0_c = CString::new(parsed.arg0.as_bytes()).map_err(|e| e.to_string())?;

    // Build argv: [arg0_c, rest_argv..., NULL]. Keep CStrings alive via
    // a Vec so the raw pointers we hand to execv stay valid through the call.
    let mut argv_cstrings: Vec<CString> = Vec::with_capacity(parsed.rest_argv.len() + 1);
    argv_cstrings.push(arg0_c);
    for a in &parsed.rest_argv {
        argv_cstrings.push(CString::new(a.as_bytes()).map_err(|e| e.to_string())?);
    }

    let mut argv_ptrs: Vec<*const libc::c_char> =
        argv_cstrings.iter().map(|c| c.as_ptr()).collect();
    argv_ptrs.push(std::ptr::null());

    unsafe {
        libc::execv(exec_path_c.as_ptr(), argv_ptrs.as_ptr());
    }
    // execv only returns on failure.
    let err = std::io::Error::last_os_error();
    Err(format!("execv({exec_path}): {err}"))
}