Adding `cheeseburger` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add cheeseburger

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

cheeseburger = "0.1.0"

The cheeseburger library will be automatically available globally. Read the cheeseburger library documentation.

Back to the crate overview.

Readme

🍔 Cheeseburger

The Safe Script Execution Environment.

Overview

Cheeseburger is a secure script execution library for Rust that lets you run system commands with fine-grained control. I t provides a sandboxed environment that limits what commands can run and what files they can access.

Key Features:

Command allowlisting
Working directory confinement
Path protection with glob patterns
Command-specific protection overrides
Comprehensive execution results

Installation

Add Cheeseburger to your Cargo.toml:

[dependencies]
cheeseburger = "0.1.0"

or run:

cargo add cheeseburger

Quick Start

use cheeseburger::ScriptExecutor;

fn main() {
    // create a script executor a.k.a burger flipper with constraints
    let executor = BurgerFlipper::new(
        // list of allowed commands
        vec!["ls".to_string(), "echo".to_string()],
        // pwd that commands are confined to
        "/path/to/sandbox",
        // global protection patterns that apply to all commands
        vec!["**/secret*".to_string(), "**/.env".to_string()],
    );
    
    // execute a simple command
    match executor.execute("echo Hello world") {
        Ok(result) => {
            println!("Command output: {}", result.stdout);
            println!("Exit code: {}", result.exit_code);
        },
        Err(err) => {
            eprintln!("Error: {}", err);
        }
    }
}

Features

Command Allowlisting

Cheeseburger only executes commands that are explicitly allowed:

let executor = BurgerFlipper::new(
    vec!["ls".to_string(), "cat".to_string(), "echo".to_string()],
    working_dir,
    global_protected_patterns,
);

Attempts to run any command not in this list will result in a CommandNotAllowed error.

Working Directory Confinement

Commands can only access files within the specified working directory:

// this will fail with PathOutsideWorkingDir error
executor.execute("cat /etc/passwd");

Protected Files and Directories

Define global protection patterns that apply to all commands:

let global_protected = vec![
    "**/secret*".to_string(),     // protect anything with "secret" in the name
    "**/protected/**".to_string(), // protect the "protected" directory and its contents
    "**/.env".to_string(),        // protect .env files
];

Command-Specific Protection Rules

Set different protection rules for specific commands:

executor.add_command_protection(
    "echo".to_string(),
    // cmd-specific protections (in addition to global)
    vec!["**/important/**".to_string()], 
    // cmd-specific overrides (exceptions to global protection)
    vec!["**/public_secrets.txt".to_string()], 
);

Command Namespace Support

Run commands within namespaces like fs:

executor.execute("fs ls -la");

Security Considerations

Cheeseburger is designed with security in mind, but has some limitations:

It does not provide full containerization or process isolation
It does not restrict memory usage, CPU, or other system resources
It does not handle signals or provide timeout mechanisms
It validates paths but does not prevent symlink attacks by default

Higher-security environment features will be added in later releases.

Advanced Usage

Environment Variables

The ScriptEnvironment extension provides environment variable support:

let mut env = ScriptEnvironment::new(executor);

// set environment variables
env.set_env("PROJECT_DIR", "/tmp/sandbox/project");
env.set_env("LOG_LEVEL", "debug");

// execute scripts with environment variables
env.execute("echo Working in ${PROJECT_DIR} with log level ${LOG_LEVEL}");

Batch Execution

Run multiple commands in sequence:

let batch = [
    "mkdir -p ${PROJECT_DIR}",
    "touch ${PROJECT_DIR}/file.txt",
    "echo 'Hello world' > ${PROJECT_DIR}/file.txt",
    "cat ${PROJECT_DIR}/file.txt",
];

env.execute_batch(&batch);

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Adding cheeseburger library as a dependency

Adding `cheeseburger` library as a dependency