flow_security/

sandbox.rs

//! Sandboxing primitives for shell commands run by `flow-adapter-shell`.
//!
//! The module exposes a capability-declarative API: each shell node carries a
//! [`Capabilities`] struct (network access, write paths, read paths, env
//! policy). Given a `Capabilities` plus a `cwd`, [`resolve_layer`] picks the
//! enforcement strategy the host OS supports, and [`wrap_command`] returns a
//! `tokio::process::Command` already configured to run under that strategy.
//!
//! Layers (in increasing order of enforcement):
//!
//! - [`SandboxLayer::Lightweight`] - always applied. Pins cwd, scrubs env per
//!   [`EnvPolicy`]. Output cap and timeout are enforced by the calling
//!   adapter (they live closer to the spawn loop).
//! - [`SandboxLayer::MacosSandboxExec`] - on macOS only, when `Capabilities`
//!   carries non-empty write/read paths or `net == false`. Wraps the user
//!   command with `sandbox-exec -p '<generated SBPL>'`. Apple deprecated
//!   `sandbox-exec` but it still works on macOS 15; the comment block at the
//!   top of [`build_macos_sbpl`] covers the migration path.
//! - [`SandboxLayer::LinuxLandlock`] - on Linux when the kernel exposes
//!   landlock (5.13+). v1 returns the layer marker so the adapter records it
//!   in the audit log; the actual `prctl`/`landlock_create_ruleset` syscalls
//!   are wired in a follow-up so we don't gate the whole build on a Linux-only
//!   crate.
//! - [`SandboxLayer::None`] - Windows, or when capability declarations are
//!   absent. The lightweight rails still apply; nothing OS-level enforces
//!   the declared capabilities.
//!
//! See the [project docs](../../../../docs/architecture/adapters.md) for the
//! end-to-end story and the sandbox matrix.

use std::collections::HashMap;
use std::path::{Path, PathBuf};

use serde::{Deserialize, Serialize};
use tokio::process::Command;

/// Per-node capability declaration. Defaults match the most permissive
/// "trust + log" baseline (network on, write to cwd, env scrubbed) so a node
/// without an explicit `capabilities` field still works the same as a manual
/// shell invocation.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Capabilities {
    #[serde(default = "default_net")]
    pub net: bool,
    /// Paths the command may write to. The literal token `"cwd"` is
    /// substituted with the actual `cwd` at wrap time.
    #[serde(default)]
    pub write_paths: Vec<String>,
    /// Paths the command may read from. Empty means read-anywhere (the
    /// command inherits the OS's default read access). Same `"cwd"` token
    /// substitution as `write_paths`.
    #[serde(default)]
    pub read_paths: Vec<String>,
    /// Environment forwarding policy.
    #[serde(default)]
    pub env: EnvPolicy,
}

fn default_net() -> bool {
    true
}

impl Default for Capabilities {
    /// Permissive default: no OS sandbox layer engaged. The lightweight
    /// rails (cwd pin, env scrub, output cap, timeout) still apply.
    /// Nodes that want stricter enforcement declare their own
    /// `capabilities` in `node.data` and the OS layer kicks in.
    fn default() -> Self {
        Self {
            net: true,
            write_paths: Vec::new(),
            read_paths: Vec::new(),
            env: EnvPolicy::default(),
        }
    }
}

/// Environment forwarding policy. `Scrubbed` is the default and matches the
/// allow-list used by major sandboxing tools.
#[derive(Debug, Clone, Serialize, Deserialize, Default)]
#[serde(rename_all = "snake_case")]
pub enum EnvPolicy {
    /// Forward only `HOME`, `USER`, `PATH`, `LANG`, `LC_*`, `TERM`, `SHELL`.
    #[default]
    Scrubbed,
    /// Forward the full inherited environment. Use sparingly; this is how
    /// `AWS_*` or `GITHUB_TOKEN` would leak into a curated tool node.
    Inherit,
    /// Explicit allow-list of variable names.
    Vars(Vec<String>),
}

/// Strategy used to enforce a [`Capabilities`] declaration on the host.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SandboxLayer {
    None,
    Lightweight,
    MacosSandboxExec,
    LinuxLandlock,
}

/// Pick the strongest enforcement layer the host supports for these
/// capabilities. Always returns at least [`SandboxLayer::Lightweight`].
pub fn resolve_layer(caps: &Capabilities) -> SandboxLayer {
    let needs_os = !caps.net || !caps.write_paths.is_empty() || !caps.read_paths.is_empty();
    if !needs_os {
        return SandboxLayer::Lightweight;
    }
    #[cfg(target_os = "macos")]
    {
        SandboxLayer::MacosSandboxExec
    }
    #[cfg(target_os = "linux")]
    {
        if landlock_available() {
            return SandboxLayer::LinuxLandlock;
        }
        return SandboxLayer::Lightweight;
    }
    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
    {
        SandboxLayer::Lightweight
    }
}

#[cfg(target_os = "linux")]
fn landlock_available() -> bool {
    // Minimum-viable probe: read /proc/self/status for "Landlock" disabled
    // line, or use prctl. v1 returns false to keep the layer marker honest;
    // a follow-up wires the real ruleset application and flips this to a
    // genuine availability check.
    false
}

/// Forward-only set used by [`EnvPolicy::Scrubbed`].
const SCRUB_ALLOW: &[&str] = &[
    "HOME", "USER", "PATH", "LANG", "TERM", "SHELL",
    // LC_* handled by prefix below.
];

fn lc_prefix(name: &str) -> bool {
    name.starts_with("LC_")
}

/// Build the env map a child should inherit per the declared policy.
pub fn scrub_env(policy: &EnvPolicy) -> HashMap<String, String> {
    match policy {
        EnvPolicy::Inherit => std::env::vars().collect(),
        EnvPolicy::Scrubbed => std::env::vars()
            .filter(|(k, _)| SCRUB_ALLOW.contains(&k.as_str()) || lc_prefix(k))
            .collect(),
        EnvPolicy::Vars(allow) => {
            let allow: Vec<&str> = allow.iter().map(String::as_str).collect();
            std::env::vars()
                .filter(|(k, _)| allow.contains(&k.as_str()))
                .collect()
        }
    }
}

/// Substitute the special `"cwd"` token in capability paths with the actual
/// working directory. Returns absolute paths.
fn expand_paths(paths: &[String], cwd: &Path) -> Vec<PathBuf> {
    paths
        .iter()
        .map(|p| {
            if p == "cwd" {
                cwd.to_path_buf()
            } else if let Some(stripped) = p.strip_prefix("~/") {
                if let Some(home) = std::env::var_os("HOME") {
                    PathBuf::from(home).join(stripped)
                } else {
                    PathBuf::from(p)
                }
            } else {
                PathBuf::from(p)
            }
        })
        .collect()
}

/// Wrap a user-provided command + argv into a `tokio::process::Command` that
/// is ready to spawn under the resolved sandbox layer. Returns `(Command,
/// SandboxLayer)` so the caller can record the actual layer in its audit log.
///
/// `program` is the binary to run (e.g. `git`, `sh`); `args` are its CLI
/// arguments. The wrapper may prepend `sandbox-exec -p ...` etc., but the
/// caller still sees the chosen layer through the returned tuple.
pub fn wrap_command(
    program: &str,
    args: &[String],
    cwd: &Path,
    caps: &Capabilities,
) -> (Command, SandboxLayer) {
    let layer = resolve_layer(caps);
    let mut cmd = match layer {
        SandboxLayer::MacosSandboxExec => {
            let sbpl = build_macos_sbpl(caps, cwd);
            let mut c = Command::new("sandbox-exec");
            c.arg("-p").arg(sbpl).arg(program).args(args);
            c
        }
        // Lightweight / LinuxLandlock / None: spawn the program directly.
        // (Landlock enforcement, when implemented, applies via a pre-exec
        // hook in a follow-up; the layer marker is recorded today.)
        _ => {
            let mut c = Command::new(program);
            c.args(args);
            c
        }
    };

    cmd.current_dir(cwd);
    cmd.env_clear();
    for (k, v) in scrub_env(&caps.env) {
        cmd.env(k, v);
    }

    (cmd, layer)
}

/// Build a macOS Seatbelt (SBPL) profile string from the declared
/// capabilities. The profile starts from `(deny default)` and grants
/// only what `caps` explicitly allows.
///
/// References:
///
/// - Apple's Seatbelt is undocumented but stable; community references exist
///   at [chromium.googlesource.com](https://chromium.googlesource.com) and
///   in macOS's own `/System/Library/Sandbox/Profiles/`.
/// - Apple has signalled `sandbox-exec` is deprecated. The stable replacement
///   for our use case (user-controlled child sandboxing) is the Endpoint
///   Security framework, which is heavyweight and requires entitlements;
///   that migration is a future track. Until then `sandbox-exec` works.
pub fn build_macos_sbpl(caps: &Capabilities, cwd: &Path) -> String {
    let mut out = String::new();
    out.push_str("(version 1)\n");
    out.push_str("(deny default)\n");
    out.push_str("(import \"system.sb\")\n");

    // Process control + signals are needed for any practical child.
    out.push_str("(allow process-fork process-exec)\n");
    out.push_str("(allow signal (target self))\n");
    out.push_str("(allow sysctl-read)\n");
    out.push_str("(allow mach-lookup)\n");
    out.push_str("(allow ipc-posix-shm)\n");

    // File reads: explicit paths plus the binary search path. Allow reading
    // the cwd unconditionally so the program can `stat` itself.
    out.push_str(&format!(
        "(allow file-read* (subpath {:?}))\n",
        cwd.to_string_lossy()
    ));
    for p in expand_paths(&caps.read_paths, cwd) {
        out.push_str(&format!(
            "(allow file-read* (subpath {:?}))\n",
            p.to_string_lossy()
        ));
    }
    // Always allow reading shared system bits and the user's PATH.
    out.push_str("(allow file-read* (subpath \"/usr\"))\n");
    out.push_str("(allow file-read* (subpath \"/bin\"))\n");
    out.push_str("(allow file-read* (subpath \"/sbin\"))\n");
    out.push_str("(allow file-read* (subpath \"/System\"))\n");
    out.push_str("(allow file-read* (subpath \"/Library\"))\n");
    out.push_str("(allow file-read* (subpath \"/private/etc\"))\n");
    out.push_str("(allow file-read* (subpath \"/dev\"))\n");

    // File writes: the workspace (cwd) is always writable - it's the run's
    // working area - plus any declared paths.
    out.push_str(&format!(
        "(allow file-write* (subpath {:?}))\n",
        cwd.to_string_lossy()
    ));
    for p in expand_paths(&caps.write_paths, cwd) {
        out.push_str(&format!(
            "(allow file-write* (subpath {:?}))\n",
            p.to_string_lossy()
        ));
    }
    out.push_str("(allow file-write* (subpath \"/private/tmp\"))\n");
    out.push_str("(allow file-write* (subpath \"/private/var/folders\"))\n");

    // Network: deny by default unless capability requests it.
    if caps.net {
        out.push_str("(allow network*)\n");
    }

    out
}

/// Error returned by [`confine_path`] when a candidate path escapes the
/// workspace root (traversal, absolute path outside the root, or a symlink
/// pointing out). Carries human-readable detail for the adapter's error.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PathEscape(pub String);

impl std::fmt::Display for PathEscape {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

impl std::error::Error for PathEscape {}

/// Confine `candidate` to within `root`, returning the resolved absolute path
/// or [`PathEscape`] if it lands outside.
///
/// This is the filesystem-jail primitive the `flow-adapter-fs` adapter calls
/// on **every** read/write/edit/glob/grep so the on-device coding agent can
/// only touch files inside the user-chosen workspace root.
///
/// Resolution rules:
/// - `candidate` may be absolute or relative; relative paths resolve against
///   `root`.
/// - The **root** must exist and is canonicalized (symlinks resolved) so the
///   prefix check compares real paths.
/// - For the candidate we canonicalize the **longest existing ancestor** and
///   re-append the not-yet-existing tail (so writing a new file under the root
///   is allowed while still resolving symlinks on the existing portion - this
///   blocks a symlinked parent dir that points outside the root).
/// - `..` components are normalized away before resolution so plain traversal
///   (`../../etc/passwd`) is caught even when intermediate dirs don't exist.
pub fn confine_path(root: &Path, candidate: &Path) -> Result<PathBuf, PathEscape> {
    let root_canon = root
        .canonicalize()
        .map_err(|e| PathEscape(format!("workspace root {} is unusable: {e}", root.display())))?;

    // Resolve the candidate against the root when relative.
    let joined = if candidate.is_absolute() {
        candidate.to_path_buf()
    } else {
        root_canon.join(candidate)
    };

    // Normalize `.` and `..` lexically first so traversal is caught even for
    // paths whose tail doesn't exist yet.
    let normalized = lexically_normalize(&joined);

    // Canonicalize the longest existing prefix (resolves symlinks on the
    // existing portion), then re-attach the non-existent tail.
    let resolved = canonicalize_existing_prefix(&normalized);

    if resolved == root_canon || resolved.starts_with(&root_canon) {
        Ok(resolved)
    } else {
        Err(PathEscape(format!(
            "path {} escapes workspace root {}",
            candidate.display(),
            root.display()
        )))
    }
}

/// Lexically remove `.` and resolve `..` without touching the filesystem.
/// Leading `..` that would climb above the path root are dropped.
fn lexically_normalize(p: &Path) -> PathBuf {
    use std::path::Component;
    let mut out: Vec<std::ffi::OsString> = Vec::new();
    let mut prefix_root = PathBuf::new();
    for comp in p.components() {
        match comp {
            Component::Prefix(_) | Component::RootDir => {
                prefix_root.push(comp.as_os_str());
            }
            Component::CurDir => {}
            Component::ParentDir => {
                out.pop();
            }
            Component::Normal(seg) => out.push(seg.to_os_string()),
        }
    }
    let mut result = prefix_root;
    for seg in out {
        result.push(seg);
    }
    result
}

/// Canonicalize the longest existing ancestor of `p` (resolving symlinks on
/// the existing portion) and re-append the remaining non-existent components.
fn canonicalize_existing_prefix(p: &Path) -> PathBuf {
    let mut existing = p.to_path_buf();
    let mut tail: Vec<std::ffi::OsString> = Vec::new();
    loop {
        if let Ok(canon) = existing.canonicalize() {
            let mut result = canon;
            for seg in tail.iter().rev() {
                result.push(seg);
            }
            return result;
        }
        match existing.file_name() {
            Some(name) => {
                tail.push(name.to_os_string());
                if !existing.pop() {
                    break;
                }
            }
            None => break,
        }
    }
    // Nothing existed (shouldn't happen since root is canonical); fall back to
    // the lexical path so the caller's prefix check still runs.
    p.to_path_buf()
}

/// Audit-log directory: `~/.flow-studio/logs/audit/`. Created lazily.
///
/// Co-located with the app's general tracing logs (see
/// `apps/frontend/src-tauri/src/logging.rs`) so users have a single
/// folder to inspect when investigating an issue. Earlier builds wrote to
/// `~/.flow-studio/audit/` and then `~/flow-studio/Logs/audit/`; neither is
/// written any more, and stale logs there can be moved or deleted manually.
pub fn audit_log_path(date_yyyy_mm_dd: &str) -> PathBuf {
    let home = std::env::var_os("HOME")
        .map(PathBuf::from)
        .unwrap_or_else(|| PathBuf::from("."));
    let dir = home.join(".flow-studio").join("logs").join("audit");
    let _ = std::fs::create_dir_all(&dir);
    dir.join(format!("shell-{}.log", date_yyyy_mm_dd))
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::path::PathBuf;

    fn caps_with_paths(net: bool, writes: &[&str]) -> Capabilities {
        Capabilities {
            net,
            write_paths: writes.iter().map(|s| s.to_string()).collect(),
            read_paths: Vec::new(),
            env: EnvPolicy::Scrubbed,
        }
    }

    fn unique_tmp(tag: &str) -> PathBuf {
        use std::sync::atomic::{AtomicU64, Ordering};
        static COUNTER: AtomicU64 = AtomicU64::new(0);
        let n = COUNTER.fetch_add(1, Ordering::Relaxed);
        std::env::temp_dir().join(format!("flow-{tag}-{}-{n}", std::process::id()))
    }

    #[test]
    fn confine_allows_paths_inside_root() {
        let tmp = unique_tmp("confine");
        std::fs::create_dir_all(tmp.join("sub")).unwrap();
        std::fs::write(tmp.join("sub/a.txt"), b"x").unwrap();

        // Existing file inside root.
        let ok = confine_path(&tmp, Path::new("sub/a.txt")).unwrap();
        assert!(ok.starts_with(tmp.canonicalize().unwrap()));

        // Not-yet-existing file under an existing dir is allowed (writes).
        let new_file = confine_path(&tmp, Path::new("sub/new.txt")).unwrap();
        assert!(new_file.starts_with(tmp.canonicalize().unwrap()));
        assert!(new_file.ends_with("new.txt"));

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn confine_rejects_traversal_escape() {
        let tmp = unique_tmp("confine");
        std::fs::create_dir_all(&tmp).unwrap();

        // Plain traversal out of the root.
        let err = confine_path(&tmp, Path::new("../../etc/passwd"));
        assert!(err.is_err(), "traversal must be rejected: {err:?}");

        // Absolute path outside the root.
        let err2 = confine_path(&tmp, Path::new("/etc/passwd"));
        assert!(err2.is_err(), "absolute outside must be rejected: {err2:?}");

        let _ = std::fs::remove_dir_all(&tmp);
    }

    #[test]
    fn confine_rejects_symlink_escape() {
        // A symlinked subdir pointing outside the root must not let writes
        // through it. Skip on platforms without symlink support.
        #[cfg(unix)]
        {
            let tmp = unique_tmp("confine");
            let outside = unique_tmp("outside");
            std::fs::create_dir_all(&tmp).unwrap();
            std::fs::create_dir_all(&outside).unwrap();
            std::os::unix::fs::symlink(&outside, tmp.join("link")).unwrap();

            let err = confine_path(&tmp, Path::new("link/evil.txt"));
            assert!(err.is_err(), "symlink escape must be rejected: {err:?}");

            let _ = std::fs::remove_dir_all(&tmp);
            let _ = std::fs::remove_dir_all(&outside);
        }
    }

    #[test]
    fn env_scrubbed_keeps_safe_vars_only() {
        std::env::set_var("FLOW_TEST_SECRET", "should-not-leak");
        std::env::set_var("HOME", "/Users/test");
        let map = scrub_env(&EnvPolicy::Scrubbed);
        assert!(map.contains_key("HOME"));
        assert!(!map.contains_key("FLOW_TEST_SECRET"));
        std::env::remove_var("FLOW_TEST_SECRET");
    }

    #[test]
    fn env_inherit_passes_secrets() {
        std::env::set_var("FLOW_TEST_INHERIT", "yes");
        let map = scrub_env(&EnvPolicy::Inherit);
        assert_eq!(
            map.get("FLOW_TEST_INHERIT").map(String::as_str),
            Some("yes")
        );
        std::env::remove_var("FLOW_TEST_INHERIT");
    }

    #[test]
    fn env_vars_explicit_allow_list() {
        std::env::set_var("FLOW_TEST_ALLOWED", "yes");
        std::env::set_var("FLOW_TEST_DENIED", "no");
        let policy = EnvPolicy::Vars(vec!["FLOW_TEST_ALLOWED".to_string()]);
        let map = scrub_env(&policy);
        assert!(map.contains_key("FLOW_TEST_ALLOWED"));
        assert!(!map.contains_key("FLOW_TEST_DENIED"));
        std::env::remove_var("FLOW_TEST_ALLOWED");
        std::env::remove_var("FLOW_TEST_DENIED");
    }

    #[test]
    fn resolve_layer_lightweight_when_no_caps() {
        let caps = Capabilities {
            net: true,
            write_paths: Vec::new(),
            read_paths: Vec::new(),
            env: EnvPolicy::Scrubbed,
        };
        // No write/read paths declared and net=true: nothing for the OS layer
        // to enforce, so we stay at lightweight.
        assert_eq!(resolve_layer(&caps), SandboxLayer::Lightweight);
    }

    #[cfg(target_os = "macos")]
    #[test]
    fn resolve_layer_picks_macos_sandbox_exec_when_caps_set() {
        let caps = caps_with_paths(false, &["cwd"]);
        assert_eq!(resolve_layer(&caps), SandboxLayer::MacosSandboxExec);
    }

    #[test]
    fn build_macos_sbpl_denies_network_when_net_false() {
        let caps = caps_with_paths(false, &["cwd"]);
        let cwd = PathBuf::from("/tmp/flow-test");
        let sbpl = build_macos_sbpl(&caps, &cwd);
        assert!(sbpl.contains("(deny default)"));
        assert!(!sbpl.contains("(allow network*)"));
    }

    #[test]
    fn build_macos_sbpl_grants_network_when_net_true() {
        let caps = caps_with_paths(true, &["cwd"]);
        let cwd = PathBuf::from("/tmp/flow-test");
        let sbpl = build_macos_sbpl(&caps, &cwd);
        assert!(sbpl.contains("(allow network*)"));
    }

    #[test]
    fn build_macos_sbpl_grants_write_to_declared_paths() {
        let caps = caps_with_paths(false, &["cwd", "~/.cache"]);
        let cwd = PathBuf::from("/tmp/flow-test");
        let sbpl = build_macos_sbpl(&caps, &cwd);
        assert!(sbpl.contains("/tmp/flow-test"));
        // The home expansion happens; we just verify a write rule appears.
        assert!(sbpl.matches("(allow file-write*").count() >= 2);
    }

    #[test]
    fn build_macos_sbpl_always_grants_write_to_cwd() {
        // No declared write_paths: the workspace cwd must still be writable.
        let caps = caps_with_paths(false, &[]);
        let cwd = PathBuf::from("/tmp/flow-workspace");
        let sbpl = build_macos_sbpl(&caps, &cwd);
        assert!(sbpl.contains("(allow file-write* (subpath \"/tmp/flow-workspace\"))"));
    }

    #[test]
    fn audit_log_path_lives_under_flow_studio_audit() {
        let p = audit_log_path("2026-05-04");
        let s = p.to_string_lossy();
        assert!(s.contains(".flow-studio/logs/audit/"));
        assert!(s.ends_with("shell-2026-05-04.log"));
    }
}