1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126
//! Birdcage sandbox.
//!
//! This crate provides a cross-platform API for an embedded sandbox for macOS
//! and Linux.
//!
//! # Example
//!
//! ```rust
//! use std::fs;
//!
//! use birdcage::process::Command;
//! use birdcage::{Birdcage, Exception, Sandbox};
//!
//! // Reads without sandbox work.
//! fs::read_to_string("./Cargo.toml").unwrap();
//!
//! // Allow access to our test executable.
//! let mut sandbox = Birdcage::new();
//! sandbox.add_exception(Exception::ExecuteAndRead("/bin/cat".into())).unwrap();
//! let _ = sandbox.add_exception(Exception::ExecuteAndRead("/lib64".into()));
//! let _ = sandbox.add_exception(Exception::ExecuteAndRead("/lib".into()));
//!
//! // Initialize the sandbox; by default everything is prohibited.
//! let mut command = Command::new("/bin/cat");
//! command.arg("./Cargo.toml");
//! let mut child = sandbox.spawn(command).unwrap();
//!
//! // Reads with sandbox should fail.
//! let status = child.wait().unwrap();
//! assert!(!status.success());
//! ```
use std::env;
use std::path::PathBuf;
use crate::error::Result;
#[cfg(target_os = "linux")]
use crate::linux::LinuxSandbox;
#[cfg(target_os = "macos")]
use crate::macos::MacSandbox;
use crate::process::{Child, Command};
pub mod error;
#[cfg(target_os = "linux")]
mod linux;
#[cfg(target_os = "macos")]
mod macos;
pub mod process;
/// Default platform sandbox.
///
/// This type will automatically pick the default sandbox for each available
/// platform.
#[cfg(target_os = "linux")]
pub type Birdcage = LinuxSandbox;
/// Default platform sandbox.
///
/// This type will automatically pick the default sandbox for each available
/// platform.
#[cfg(target_os = "macos")]
pub type Birdcage = MacSandbox;
pub trait Sandbox: Sized {
/// Setup the sandboxing environment.
fn new() -> Self;
/// Add a new exception to the sandbox.
///
/// Exceptions added for symlinks will also automatically apply to the
/// symlink's target.
fn add_exception(&mut self, exception: Exception) -> Result<&mut Self>;
/// Setup sandbox and spawn a new process.
///
/// This will setup the sandbox in the **CURRENT** process, before launching
/// the sandboxee. Since most of the restrictions will also be applied to
/// the calling process, it is recommended to create a separate process
/// before calling this method. The calling process is **NOT** fully
/// sandboxed.
///
/// # Errors
///
/// Sandboxing will fail if the calling process is not single-threaded.
///
/// After failure, the calling process might still be affected by partial
/// sandboxing restrictions.
fn spawn(self, sandboxee: Command) -> Result<Child>;
}
/// Sandboxing exception rule.
///
/// An exception excludes certain resources from the sandbox, allowing sandboxed
/// applications to still access these resources.
#[derive(Debug, Clone)]
pub enum Exception {
/// Allow read access to the path and anything beneath it.
Read(PathBuf),
/// Allow writing and reading the path and anything beneath it.
WriteAndRead(PathBuf),
/// Allow executing and reading the path and anything beneath it.
///
/// This is grouped with reading as a convenience, since execution will
/// always also require read access.
ExecuteAndRead(PathBuf),
/// Allow reading an environment variable.
Environment(String),
/// Allow reading **all** environment variables.
FullEnvironment,
/// Allow networking.
Networking,
}
/// Restrict access to environment variables.
pub(crate) fn restrict_env_variables(exceptions: &[String]) {
// Invalid unicode will cause `env::vars()` to panic, so we don't have to worry
// about them getting ignored.
for (key, _) in env::vars().filter(|(key, _)| !exceptions.contains(key)) {
env::remove_var(key);
}
}