use clap::{CommandFactory, FromArgMatches, Parser, Subcommand}; use sandbox_session::{changed_since, committed_root, replay_run, IsolateBackend, Session}; use sandbox_trace::{outcome_of, replay, FileChange, FsOp, Outcome, RunRecord, Trace}; use sandbox_types::{ErrorCode, ExecResult, SandboxError, SessionConfig}; use std::ffi::OsStr; use std::io::{BufRead, Write}; use std::path::{Path, PathBuf}; /// The version the binary reports. Release builds set SANDBOX_VERSION from the git /// tag, so `sandbox --version` matches the release. Other builds use the crate version. const VERSION: &str = match option_env!("SANDBOX_VERSION") { Some(version) => version, None => env!("CARGO_PKG_VERSION"), }; /// The canonical name the binary is invoked as. `frontal-sandbox` is the legacy /// alias; both names work identically. The binary chooses its clap help name /// from the name it was invoked as, so `sandbox --help` and /// `frontal-sandbox --help` each show the right name. fn invocation_name() -> &'static str { // The clap help name follows the name the binary was invoked as, so // `sandbox --help` and `frontal-sandbox --help` each show the right name. let exe = std::env::current_exe().ok(); match exe .as_deref() .and_then(Path::file_name) .and_then(OsStr::to_str) { Some("sandbox" | "sandbox.exe") => "sandbox", Some("frontal-sandbox" | "frontal-sandbox.exe") => "frontal-sandbox", _ => "frontal-sandbox", } } #[derive(Subcommand)] pub enum SandboxCommand { /// Print the session's environment (/etc/agent/env.json) as JSON. Info { /// Session ID session_id: String, }, /// Pin the session's current state as a checkpoint, and print its root. Checkpoint { /// Session ID session_id: String, }, /// Restore the filesystem from N checkpoints ago. The current state is kept as a /// checkpoint first. Processes are not kept. Undo { /// Session ID session_id: String, /// How many checkpoints back to restore #[arg(default_value = "1")] steps: u32, }, /// Fork the session's current state into N children and run a command in each. /// Prints one line per child. Exits 1 when a child's command failed. /// /// Example: sandbox fork -c 3 -- touch /r Fork { /// Session ID session_id: String, /// Number of children #[arg(short, long, default_value = "1")] count: u32, /// The command to run in each child #[arg(last = true, required = true)] command: Vec, }, } #[derive(Parser)] #[command(name = "frontal-sandbox", version = VERSION, about = "Frontal Sandbox CLI")] pub struct Cli { #[command(subcommand)] pub command: Commands, } #[derive(Subcommand)] #[allow(clippy::large_enum_variant)] pub enum Commands { /// Run a command in a new sandbox. Arguments are joined with spaces and run /// as one shell script, so quote the whole script if it has spaces. Run { /// Write a trace of the script to this file. See `sandbox replay`. #[arg(long)] trace: Option, /// Command to execute #[arg(required = true, num_args = 1..)] command: Vec, }, /// Start an interactive shell in a new sandbox. Reads one script per line /// from stdin; `exit` or end of input stops it. Shell { /// Write a trace of every line to this file when the shell exits. #[arg(long)] trace: Option, }, /// Snapshot a session on the server named by SANDBOX_BASE_URL. Uses SANDBOX_API_KEY. Snapshot { /// Session ID session_id: String, }, /// Fork a snapshot into sessions on the server named by SANDBOX_BASE_URL Fork { /// Snapshot ID snapshot_id: String, /// Number of forks #[arg(short, long, default_value = "1")] count: usize, }, /// Tier 1 session tools: environment, checkpoints, undo, and fork-with-command. /// Uses SANDBOX_BASE_URL and SANDBOX_API_KEY. Sandbox { #[command(subcommand)] command: SandboxCommand, }, /// Serve the sandbox to an MCP client over stdio: `exec`, `read_file`, /// `write_file`, and `list_dir`, backed by one in-process session. Mcp, /// Replay a trace in a fresh sandbox and report every run whose output /// differs from the recorded one. Exits 1 when any run diverges. Replay { /// Trace file path trace_file: PathBuf, }, /// Internal: run one `node` script from stdin in a contained child process. /// Frames go to stdout. See `sandbox_worker::script`. #[cfg(unix)] #[command(hide = true)] ScriptRun { /// Unshare the network, IPC, UTS, and mount namespaces before running. #[arg(long)] namespaces: bool, /// Install the seccomp denylist before running. #[arg(long)] seccomp: bool, }, /// Internal: serve one session as gRPC on a Unix socket, for a worker host. /// Unix only, because the socket is a Unix domain socket. #[cfg(unix)] #[command(hide = true)] Worker { /// Socket path to listen on. The host creates its directory with mode 0700. #[arg(long)] socket: PathBuf, /// Unshare the network, IPC, UTS, and mount namespaces before serving. #[arg(long)] namespaces: bool, /// Install the seccomp denylist before serving. #[arg(long)] seccomp: bool, }, /// Start the sandbox server in the foreground. Prints one API key to stderr. Serve { /// Load serve settings from this TOML file (infrastructure/PLAN.md §4). CLI flags /// override mapped fields; SANDBOX_* / OTLP env override file values. #[arg(long)] config: Option, /// Bind address #[arg(long)] addr: Option, /// Keep keys, snapshots, and sleeping sessions in this directory, so they /// survive a restart (ADR 0008). Without it the server is in memory only. #[arg(long)] data_dir: Option, /// Collect unreachable blobs every this many seconds (ADR 0013). 0 turns /// the schedule off, and `POST /v1/gc` remains available. #[arg(long)] gc_interval_secs: Option, /// Put a session to sleep after this many seconds with no request (PLAN /// §4.14). A request to a sleeping session wakes it. 0 turns idle sleep off. #[arg(long)] idle_sleep_secs: Option, /// Keep the state in this Postgres database, shared by every node that uses /// it, instead of in `--data-dir` alone (PLAN §4.8). `--data-dir` still holds /// the blobs, so it must be a directory every node can reach. #[arg(long, requires = "data_dir")] database_url: Option, /// A directory with `vmlinuz` and `initrd.gz`, the guest image (see /// docker/emulated-vm/build-image.sh). With it, a command the isolate tier cannot /// run moves the session to a Tier 2 VM. Without it, such a command is refused. #[arg(long)] vm_image: Option, /// The QEMU binary that runs the guest. #[arg(long)] qemu: Option, /// How QEMU runs the guest: `tcg` (software, works in Docker without KVM) or `kvm`. #[arg(long)] vm_accel: Option, /// Guest memory in MiB. #[arg(long)] vm_memory_mib: Option, /// Seconds to wait for a guest's agent to answer after boot. #[arg(long)] vm_boot_timeout_secs: Option, /// Guests kept booted ahead of promotions, so a promotion skips the boot. #[arg(long)] vm_warm_guests: Option, /// A directory with `python.wasm` and `python313.zip` (tools/wasm/python/build.sh). New /// isolate sessions get CPython installed, so `python` runs in them. Not yet combined /// with --data-dir or a VM image. #[arg(long)] python_artifacts: Option, /// An OTLP/HTTP collector to send one span per request to, such as /// http://127.0.0.1:4318. The OTEL_EXPORTER_OTLP_ENDPOINT variable does the same. #[arg(long)] otel_endpoint: Option, /// An S3 bucket that keeps every blob too, on a durable server (--data-dir), so a node /// that lacks a blob reads it from the bucket. Credentials come from the AWS_* variables. #[arg(long)] object_store_bucket: Option, /// The endpoint of an S3-compatible service, such as http://127.0.0.1:9000 for MinIO. /// Without it, the AWS endpoint is used. #[arg(long)] object_store_endpoint: Option, }, /// Time a fixed set of operations on the local runtime. Prints one JSON line per case. Bench { /// Benchmark name #[arg(short, long)] name: Option, }, } impl Cli { /// Parses arguments, runs the command, and exits with its status. pub fn run() { // The clap help/usage name follows the name the binary was invoked as, so // `sandbox --help` and `frontal-sandbox --help` each show the right name. let command = Cli::command().name(invocation_name()); let cli = Cli::from_arg_matches(&command.get_matches()) .expect("clap parse: the args are valid by construction"); if let Err(e) = install_script_runner(&cli.command) { eprintln!("Error: {}", e.message); std::process::exit(1); } match cli.execute() { Ok(code) => std::process::exit(code), Err(e) => { eprintln!("Error: {}", e.message); std::process::exit(1); } } } /// Runs the command and returns the process exit code. pub fn execute(&self) -> Result { match &self.command { Commands::Run { command, trace } => { run_script_once(&command.join(" "), trace.as_deref()) } Commands::Shell { trace } => interactive_shell(trace.as_deref()), Commands::Mcp => crate::mcp::serve_stdio(), Commands::Replay { trace_file } => replay_trace(trace_file), Commands::Bench { name } => { let rt = runtime()?; rt.block_on(crate::bench::run(name.as_deref())) } #[cfg(unix)] Commands::ScriptRun { namespaces, seccomp, } => { // Applies the isolation before any thread exists. See `run_script_child`. let isolation = sandbox_worker::Isolation { namespaces: *namespaces, seccomp: *seccomp, cgroup: None, }; sandbox_worker::run_script_child(&isolation)?; Ok(0) } #[cfg(unix)] Commands::Worker { socket, namespaces, seccomp, } => { // Before the runtime exists: namespaces and seccomp apply to the // calling thread and to threads created later. let isolation = sandbox_worker::Isolation { namespaces: *namespaces, seccomp: *seccomp, cgroup: None, }; sandbox_worker::enter(&isolation)?; let rt = runtime()?; rt.block_on(sandbox_worker::serve(socket))?; Ok(0) } Commands::Serve { config, addr, data_dir, gc_interval_secs, idle_sleep_secs, database_url, vm_image, qemu, vm_accel, vm_memory_mib, vm_boot_timeout_secs, vm_warm_guests, python_artifacts, otel_endpoint, object_store_bucket, object_store_endpoint, } => { let mut resolved = sandbox_server::load_config(config.as_deref()) .map_err(|e| SandboxError::invalid_argument(e.to_string()))?; if let Some(a) = addr { resolved.addr = a.clone(); } if let Some(d) = data_dir { resolved.data_dir = Some(d.clone()); } if let Some(n) = gc_interval_secs { resolved.gc_interval_secs = *n; } if let Some(n) = idle_sleep_secs { resolved.idle_sleep_secs = *n; } if let Some(u) = database_url { if !u.is_empty() { resolved.database_url = Some(u.clone()); } } if let Some(p) = python_artifacts { resolved.python_artifacts = Some(p.clone()); } if let Some(e) = otel_endpoint { if !e.is_empty() { resolved.otel_endpoint = Some(e.clone()); } } if let Some(b) = object_store_bucket { resolved.object_store_bucket = Some(b.clone()); } if let Some(e) = object_store_endpoint { resolved.object_store_endpoint = Some(e.clone()); } let qemu_bin = qemu .clone() .unwrap_or_else(|| PathBuf::from("qemu-system-x86_64")); let accel_name = vm_accel.clone().unwrap_or_else(|| "tcg".to_string()); let memory_mib = vm_memory_mib.unwrap_or(2048); let boot_timeout_secs = vm_boot_timeout_secs.unwrap_or(180); let warm_guests = vm_warm_guests.unwrap_or(1); let vm = match vm_image { None => None, Some(image) => Some(sandbox_server::VmConfig { qemu: qemu_bin, image: image.clone(), accel: match accel_name.as_str() { "tcg" => sandbox_vmm::Accel::Tcg, "kvm" => sandbox_vmm::Accel::Kvm, other => { return Err(SandboxError::invalid_argument(format!( "--vm-accel must be tcg or kvm, not {other}" ))) } }, memory_mib, boot_timeout: std::time::Duration::from_secs(boot_timeout_secs), warm_guests, }), }; let python = match resolved.python_artifacts.as_deref() { None => None, Some(dir) => Some(sandbox_wasm::PythonArtifacts::load(dir)?), }; let telemetry = sandbox_server::config::telemetry_from_resolved(&resolved); if resolved.object_store_bucket.is_some() && resolved.data_dir.is_none() { return Err(SandboxError::invalid_argument( "--object-store-bucket needs --data-dir, because the blobs live there", )); } let blob_remote = match resolved.object_store_bucket.as_deref() { None => None, Some(bucket) => Some(object_store_remote( bucket, resolved.object_store_endpoint.as_deref(), )?), }; serve( &resolved.addr, resolved.data_dir.as_deref(), resolved.gc_interval_secs, resolved.idle_sleep_secs, resolved.database_url.as_deref(), sandbox_server::ServerOptions { vm, python, telemetry, blob_remote, }, ) } Commands::Snapshot { session_id } => snapshot(session_id), Commands::Fork { snapshot_id, count } => fork(snapshot_id, *count), Commands::Sandbox { command } => sandbox_session(command), } } } fn runtime() -> Result { tokio::runtime::Builder::new_current_thread() .enable_all() .build() .map_err(|e| SandboxError::internal(format!("failed to start runtime: {e}"))) } fn print_output(stdout: &[u8], stderr: &[u8]) -> std::io::Result<()> { std::io::stdout().write_all(stdout)?; std::io::stdout().flush()?; std::io::stderr().write_all(stderr) } fn run_script_once(script: &str, trace: Option<&Path>) -> Result { let rt = runtime()?; rt.block_on(async { let session = IsolateBackend::new(SessionConfig::default()).await?; let (random_state, result, files) = run_traced(&session, script).await; if let Some(path) = trace { let runs = vec![record(1, script, &result, files, random_state)]; write_trace(path, runs)?; } let out = result?; print_output(&out.stdout, &out.stderr) .map_err(|e| SandboxError::internal(format!("failed to write output: {e}")))?; Ok(out.exit_code) }) } fn interactive_shell(trace: Option<&Path>) -> Result { let rt = runtime()?; let session = rt.block_on(IsolateBackend::new(SessionConfig::default()))?; let mut runs = Vec::new(); let lines = std::io::stdin() .lock() .lines() .map(|line| line.map_err(|e| SandboxError::internal(format!("failed to read stdin: {e}")))) .take_while(|line| !matches!(line, Ok(text) if text.trim() == "exit")); for line in lines { let line = line?; // A bad line reports its error and the session continues. let (random_state, result, files) = rt.block_on(run_traced(&session, &line)); if trace.is_some() { runs.push(record( runs.len() as u64 + 1, &line, &result, files, random_state, )); } match result { Ok(out) => print_output(&out.stdout, &out.stderr) .map_err(|e| SandboxError::internal(format!("failed to write output: {e}")))?, Err(e) => eprintln!("Error: {}", e.message), } } if let Some(path) = trace { write_trace(path, runs)?; } Ok(0) } /// Replays a trace in one fresh sandbox, in the order it was recorded, and /// prints every run whose outcome differs from the recording. fn replay_trace(path: &Path) -> Result { let text = std::fs::read_to_string(path).map_err(|e| { SandboxError::new( ErrorCode::InvalidArgument, format!("cannot read {}: {e}", path.display()), ) })?; let trace = Trace::parse(&text).map_err(|e| { SandboxError::new( ErrorCode::InvalidArgument, format!("{}: {e}", path.display()), ) })?; let rt = runtime()?; let report = rt.block_on(async { let session = IsolateBackend::new(SessionConfig::default()).await?; let report = replay(&trace, |run| { let session = &session; let run = run.clone(); async move { replay_run(session, &run).await } }) .await; Ok::<_, SandboxError>(report) })?; println!( "replayed {} runs: {} diverged", report.runs, report.divergences.len() ); for d in &report.divergences { // Scripts come from the trace file, so they are escaped before printing. let what = match &d.fs { Some(FsOp::Write { path, data }) => { format!("write {} ({} bytes)", escaped(path), data.len()) } Some(FsOp::Delete { path }) => format!("delete {}", escaped(path)), None => escaped(&d.script), }; println!("run {} diverged: {what}", d.seq); println!(" expected: {}", describe(&d.expected)); println!(" actual: {}", describe(&d.actual)); } Ok(if report.matches() { 0 } else { 1 }) } /// Runs one script and returns its result with the files it changed. async fn run_traced( session: &IsolateBackend, script: &str, ) -> ( Option, Result, Result, SandboxError>, ) { let before = committed_root(session).await; // The generator state before the run, so a replay draws the same $RANDOM values. let random_state = Some(session.random_state().await); let result = session.run_script(script).await; let files = match before { Ok(before) => changed_since(session, before) .await .map(|changes| changes.into_iter().map(FileChange::from).collect()), Err(e) => Err(e), }; (random_state, result, files) } /// One run as the trace records it. Files that could not be read leave the run /// without its file list, and the error is reported on stderr. fn record( seq: u64, script: &str, result: &Result, files: Result, SandboxError>, random_state: Option, ) -> RunRecord { let files = files.unwrap_or_else(|e| { eprintln!( "Warning: the trace does not list the files this run changed: {}", e.message ); Vec::new() }); let outcome = outcome_of( result .as_ref() .map(|out| (out.exit_code, out.stdout.clone(), out.stderr.clone())) .map_err(|e| SandboxError::new(e.code, e.message.clone())), ); RunRecord { seq, script: script.to_string(), fs: None, outcome, files, random_state, } } fn write_trace(path: &Path, runs: Vec) -> Result<(), SandboxError> { let text = Trace { runs } .to_jsonl() .map_err(|e| SandboxError::internal(format!("cannot encode the trace: {e}")))?; std::fs::write(path, text) .map_err(|e| SandboxError::internal(format!("cannot write trace {}: {e}", path.display()))) } /// A short, readable form of an outcome for the replay report. fn describe(outcome: &Outcome) -> String { const PREVIEW: usize = 120; match outcome { Outcome::Completed { exit_code, stdout, stderr, } => { let out = String::from_utf8_lossy(stdout); let err = String::from_utf8_lossy(stderr); format!( "exit {exit_code}, stdout {:?}, stderr {:?}", out.chars().take(PREVIEW).collect::(), err.chars().take(PREVIEW).collect::() ) } Outcome::Failed { code, message } => format!("error {code}: {}", escaped(message)), } } /// Escapes control characters, so text from a trace or from a script cannot /// move the cursor or set the title of the terminal it is printed to. fn escaped(text: &str) -> String { text.escape_debug().collect() } /// Opens the Postgres-backed state. A build without the `clustered` feature refuses. #[cfg(feature = "clustered")] fn clustered_open( rt: &tokio::runtime::Runtime, scheduler: std::sync::Arc, url: &str, dir: &Path, vm: Option, blob_remote: Option>, ) -> Result<(axum::Router, sandbox_server::AppState, Option), SandboxError> { rt.block_on(sandbox_server::open_clustered_with_remote( scheduler, url, dir, vm, blob_remote, )) } #[cfg(not(feature = "clustered"))] fn clustered_open( _rt: &tokio::runtime::Runtime, _scheduler: std::sync::Arc, _url: &str, _dir: &Path, _vm: Option, _blob_remote: Option>, ) -> Result<(axum::Router, sandbox_server::AppState, Option), SandboxError> { Err(SandboxError::new( ErrorCode::Unsupported, "--database-url needs a build with the clustered feature: cargo build --features clustered", )) } /// Runs the server until the process is stopped. The key is printed once, to /// stderr, because keys live in memory and nothing else can provision them. /// The object store the blobs are kept in: an S3 bucket, or an S3-compatible service at `endpoint`. fn object_store_remote( bucket: &str, endpoint: Option<&str>, ) -> Result, SandboxError> { let mut builder = object_store::aws::AmazonS3Builder::from_env().with_bucket_name(bucket); if let Some(endpoint) = endpoint { builder = builder .with_endpoint(endpoint) .with_allow_http(endpoint.starts_with("http://")) .with_virtual_hosted_style_request(false); } let store = builder.build().map_err(|e| { SandboxError::invalid_argument(format!("cannot open the object store: {e}")) })?; Ok(std::sync::Arc::new(store)) } fn serve( addr: &str, data_dir: Option<&Path>, gc_interval_secs: u64, idle_sleep_secs: u64, database_url: Option<&str>, options: sandbox_server::ServerOptions, ) -> Result { use std::sync::Arc; let sandbox_server::ServerOptions { vm, python, telemetry, blob_remote, } = options; // Log to stderr, so stdout keeps its key line. RUST_LOG overrides the default. let filter = tracing_subscriber::EnvFilter::try_from_default_env() .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info")); let _ = tracing_subscriber::fmt() .with_env_filter(filter) .with_writer(std::io::stderr) .try_init(); let scheduler = Arc::new(sandbox_scheduler::Scheduler::new()); let rt = runtime()?; let (app, state, new_key) = match (data_dir, database_url) { (Some(_), Some(_)) if telemetry.is_some() => { return Err(sandbox_types::SandboxError::new( sandbox_types::ErrorCode::Unsupported, "span export is not yet wired into the clustered server", )) } (Some(dir), Some(url)) => clustered_open(&rt, scheduler, url, dir, vm, blob_remote)?, (Some(dir), None) => rt.block_on(sandbox_server::open_durable_with_options( scheduler, dir, sandbox_server::ServerOptions { vm, python, telemetry, blob_remote, }, ))?, (None, _) => { let auth = Arc::new(sandbox_server::auth::AuthManager::new()); let key = auth.create_key(); let (app, state) = sandbox_server::create_router_with_options( scheduler, auth, sandbox_server::ServerOptions { vm, python, telemetry, blob_remote: None, }, ); (app, state, Some(key)) } }; rt.block_on(async { if gc_interval_secs > 0 { sandbox_server::gc::schedule( state.clone(), std::time::Duration::from_secs(gc_interval_secs), ); } if idle_sleep_secs > 0 { // Sweep at least once a second and at most every 30 seconds, so a // session sleeps soon after its idle time, not much later. let every = std::time::Duration::from_secs(idle_sleep_secs.clamp(1, 30)); sandbox_server::idle::schedule( state, std::time::Duration::from_secs(idle_sleep_secs), every, ); } let listener = tokio::net::TcpListener::bind(addr) .await .map_err(|e| SandboxError::unavailable(format!("binding {addr}: {e}")))?; eprintln!("sandbox server listening on {addr}"); if let Some(dir) = data_dir { eprintln!("state directory: {}", dir.display()); } // Printed once, on the first run of a durable server, and on every run of // an in-memory one. Keys are stored as digests, so the key cannot be shown // again. if let Some(key) = &new_key { eprintln!("API key (shown once): {key}"); } axum::serve(listener, app) .await .map_err(|e| SandboxError::unavailable(format!("server stopped: {e}"))) })?; Ok(0) } fn client() -> Result { frontal_sandbox_sdk::Client::from_env() } fn snapshot(session_id: &str) -> Result { let session: sandbox_types::SessionId = session_id .parse() .map_err(|_| SandboxError::invalid_argument(format!("not a session id: {session_id}")))?; let rt = runtime()?; let id = rt.block_on(client()?.snapshot(session))?; println!("{id}"); Ok(0) } fn fork(snapshot_id: &str, count: usize) -> Result { let snapshot: sandbox_types::SnapshotId = snapshot_id .parse() .map_err(|_| SandboxError::invalid_argument(format!("not a snapshot id: {snapshot_id}")))?; let count = u32::try_from(count).map_err(|_| SandboxError::invalid_argument("count is too large"))?; let rt = runtime()?; let ids = rt.block_on(client()?.fork(snapshot, count))?; for id in ids { println!("{id}"); } Ok(0) } fn parse_session(raw: &str) -> Result { raw.parse() .map_err(|_| SandboxError::invalid_argument(format!("not a session id: {raw}"))) } fn sandbox_session(command: &SandboxCommand) -> Result { let rt = runtime()?; match command { SandboxCommand::Info { session_id } => { let env = rt.block_on(client()?.info(parse_session(session_id)?))?; println!("{}", serde_json::to_string_pretty(&env).unwrap_or_default()); Ok(0) } SandboxCommand::Checkpoint { session_id } => { let pinned = rt.block_on(client()?.checkpoint(parse_session(session_id)?))?; println!("{}", pinned.root); Ok(0) } SandboxCommand::Undo { session_id, steps } => { let undone = rt.block_on(client()?.undo(parse_session(session_id)?, *steps))?; println!("{}", undone.root); Ok(0) } SandboxCommand::Fork { session_id, count, command, } => { let children = rt.block_on(client()?.fork_command(parse_session(session_id)?, *count, command))?; let mut code = 0; for child in &children { let outcome = match (child.exit_code, &child.error) { (Some(0), _) => "ok".to_string(), (Some(exit), _) => { code = 1; format!("exit {exit}") } (None, error) => { code = 1; format!("error: {}", error.as_deref().unwrap_or("unknown")) } }; println!( "{} {} changed={}", child.session_id, outcome, child.changed_files ); } Ok(code) } } } /// Chooses where `node` scripts run on this host. /// /// On Linux the top-level process runs each script in a child process with /// namespaces, seccomp, and a cgroup memory limit. Elsewhere no runner is installed, /// so `node` is disabled. `FRONTAL_SANDBOX_UNSAFE_IN_PROCESS_SCRIPTS=1` runs scripts /// in this process with no containment. It is for development only. /// /// A worker, and a script child, already run inside an isolated process: the worker /// process is the boundary, with its own cgroup memory cap. Those run scripts in /// their own process. A second containment layer inside them would be nested, and /// the worker's inherited seccomp filter and undelegated cgroup make that impossible. #[cfg(unix)] fn install_script_runner(command: &Commands) -> Result<(), SandboxError> { if std::env::var_os("FRONTAL_SANDBOX_UNSAFE_IN_PROCESS_SCRIPTS").is_some_and(|v| v == "1") { eprintln!("warning: node scripts run in-process without containment"); return sandbox_runtime::install_in_process_script_runner(); } if matches!( command, Commands::Worker { .. } | Commands::ScriptRun { .. } ) { return sandbox_runtime::install_in_process_script_runner(); } if cfg!(target_os = "linux") { let program = std::env::current_exe().map_err(|e| { SandboxError::internal(format!("locating the script runner binary: {e}")) })?; let runner = sandbox_worker::ScriptProcess::new(program); return sandbox_runtime::install_script_runner(std::sync::Arc::new(runner)); } Ok(()) } #[cfg(not(unix))] fn install_script_runner(_command: &Commands) -> Result<(), SandboxError> { Ok(()) } #[cfg(test)] mod tests { use super::*; #[test] fn sandbox_fork_takes_the_command_after_a_separator() { let cli = Cli::try_parse_from([ "frontal-sandbox", "sandbox", "fork", "01HZZZZZZZZZZZZZZZZZZZZZZZ", "-c", "3", "--", "touch", "/r", ]) .unwrap(); let Commands::Sandbox { command: SandboxCommand::Fork { count, command, .. }, } = cli.command else { panic!("expected sandbox fork"); }; assert_eq!(count, 3); assert_eq!(command, ["touch", "/r"]); } #[test] fn sandbox_fork_takes_the_command_after_a_separator_under_sandbox_name() { // The same command parses when the argv[0] is the canonical `sandbox` name. let cli = Cli::try_parse_from([ "sandbox", "sandbox", "fork", "01HZZZZZZZZZZZZZZZZZZZZZZZ", "-c", "3", "--", "touch", "/r", ]) .unwrap(); let Commands::Sandbox { command: SandboxCommand::Fork { count, command, .. }, } = cli.command else { panic!("expected sandbox fork"); }; assert_eq!(count, 3); assert_eq!(command, ["touch", "/r"]); } #[test] fn sandbox_fork_needs_a_command() { assert!(Cli::try_parse_from([ "frontal-sandbox", "sandbox", "fork", "01HZZZZZZZZZZZZZZZZZZZZZZZ", ]) .is_err()); } #[test] fn replay_refuses_a_missing_trace_as_invalid_argument() { let replay = Cli::try_parse_from(["frontal-sandbox", "replay", "no-such-trace.jsonl"]).unwrap(); assert_eq!( replay.execute().unwrap_err().code, sandbox_types::ErrorCode::InvalidArgument ); } #[test] fn run_returns_the_script_exit_code() { let ok = Cli::try_parse_from(["frontal-sandbox", "run", "true"]).unwrap(); assert_eq!(ok.execute().unwrap(), 0); let failed = Cli::try_parse_from(["frontal-sandbox", "run", "false"]).unwrap(); assert_eq!(failed.execute().unwrap(), 1); } #[test] fn run_reports_syntax_errors() { let cli = Cli::try_parse_from(["frontal-sandbox", "run", "echo", "'unterminated"]).unwrap(); assert_eq!( cli.execute().unwrap_err().code, sandbox_types::ErrorCode::ShellError ); } /// Both invocation names build the same `Cli` from the same argv, so the help /// name is the only thing that differs. This pins that `invocation_name()` /// recognizes both binaries and falls back to the legacy alias otherwise. #[test] fn invocation_name_matches_the_binary_it_was_invoked_as() { assert_eq!(invocation_name_for("sandbox"), "sandbox"); assert_eq!(invocation_name_for("sandbox.exe"), "sandbox"); assert_eq!(invocation_name_for("frontal-sandbox"), "frontal-sandbox"); assert_eq!( invocation_name_for("frontal-sandbox.exe"), "frontal-sandbox" ); assert_eq!(invocation_name_for("something-else"), "frontal-sandbox"); } fn invocation_name_for(file_name: &str) -> &'static str { // Mirrors the match in `invocation_name()`, so the test does not depend on // the actual on-disk path of the running binary. match file_name { "sandbox" | "sandbox.exe" => "sandbox", "frontal-sandbox" | "frontal-sandbox.exe" => "frontal-sandbox", _ => "frontal-sandbox", } } }