WebAssembly Sandbox (wasm-sandbox)

A secure WebAssembly sandbox for running untrusted code with flexible host-guest communication, comprehensive resource limits, and capability-based security.

Key Features

• 🔒 Security First: Isolate untrusted code in WebAssembly sandboxes with fine-grained capability controls
• 🚀 High Performance: Efficient host-guest communication with minimal overhead
• 🔧 Flexible APIs: High-level convenience APIs and low-level control for advanced use cases
• 📦 Multiple Runtimes: Support for Wasmtime and Wasmer WebAssembly runtimes
• 🌐 Application Wrappers: Built-in support for HTTP servers, MCP servers, and CLI tools
• 📊 Resource Control: Memory, CPU, network, and filesystem limits with monitoring
• 🔄 Async/Await: Full async support for non-blocking operations

Usage Examples

Basic Sandbox Usage

use wasm_sandbox::{WasmSandbox, SandboxConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Initialize the sandbox with default configuration
    let mut sandbox = WasmSandbox::new()?;
    
    // Load a WebAssembly module
    let wasm_bytes = std::fs::read("my_module.wasm")?;
    let module_id = sandbox.load_module(&wasm_bytes)?;
    
    // Create an instance of the module
    let instance_id = sandbox.create_instance(module_id, None)?;
    
    // Call a function in the module
    let result: String = sandbox.call_function(instance_id, "greet", &"World").await?;
    
    println!("Result: {}", result);
    
    Ok(())
}

Sandboxing an HTTP Server

use wasm_sandbox::{
    WasmSandbox, InstanceConfig, 
    security::{Capabilities, NetworkCapability}
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut sandbox = WasmSandbox::new()?;
    
    // Load module
    let wasm_bytes = std::fs::read("http_server.wasm")?;
    let module_id = sandbox.load_module(&wasm_bytes)?;
    
    // Configure instance with network capabilities
    let mut capabilities = Capabilities::minimal();
    capabilities.network = NetworkCapability::Loopback;
    
    let instance_config = InstanceConfig {
        capabilities,
        ..InstanceConfig::default()
    };
    
    // Create instance
    let instance_id = sandbox.create_instance(module_id, Some(instance_config))?;
    
    // Start the HTTP server
    let port: u16 = sandbox.call_function(instance_id, "start", &8080).await?;
    
    println!("HTTP server running on port {}", port);
    
    // Wait for user to press Enter
    let mut input = String::new();
    std::io::stdin().read_line(&mut input)?;
    
    // Stop the server
    let _: () = sandbox.call_function(instance_id, "stop", &()).await?;
    
    Ok(())
}

Installation

Add this to your Cargo.toml:

[dependencies]

wasm-sandbox = "0.2.0"

For all features including Wasmer runtime support:

[dependencies]

wasm-sandbox = { version = "0.2.0", features = ["all-runtimes"] }

Architecture Overview

The crate features a trait-based architecture with two main patterns:

• Dyn-Compatible Core Traits: WasmRuntime, WasmInstance, WasmModule - can be used as trait objects
• Extension Traits: WasmRuntimeExt, WasmInstanceExt - provide async and generic operations

This design allows for maximum flexibility while maintaining type safety. See TRAIT_DESIGN.md for detailed information.

Quick Start

use wasm_sandbox::WasmSandbox;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a new sandbox
    let mut sandbox = WasmSandbox::new()?;
    
    // Load a WebAssembly module
    let wasm_bytes = std::fs::read("module.wasm")?;
    let module_id = sandbox.load_module(&wasm_bytes)?;
    
    // Create an instance with default security settings
    let instance_id = sandbox.create_instance(module_id, None)?;
    
    // Call a function
    let result: i32 = sandbox.call_function(instance_id, "add", &(5, 3)).await?;
    println!("5 + 3 = {}", result);
    
    Ok(())
}

Advanced Features

Security Configuration

use wasm_sandbox::{WasmSandbox, InstanceConfig};
use wasm_sandbox::security::{Capabilities, NetworkCapability, FilesystemCapability};

let mut capabilities = Capabilities::minimal();
capabilities.network = NetworkCapability::Loopback;  // Only localhost
capabilities.filesystem = FilesystemCapability::ReadOnly(vec!["./data".into()]);

let config = InstanceConfig {
    capabilities,
    max_memory: Some(64 * 1024 * 1024), // 64MB limit
    max_execution_time: Some(std::time::Duration::from_secs(30)),
    ..Default::default()
};

let instance_id = sandbox.create_instance(module_id, Some(config))?;

Resource Monitoring

use wasm_sandbox::security::ResourceLimits;

let limits = ResourceLimits {
    max_memory: 128 * 1024 * 1024,  // 128MB
    max_cpu_time: std::time::Duration::from_secs(60),
    max_file_descriptors: 10,
    max_network_connections: 5,
    ..Default::default()
};

// Monitor resource usage
let usage = sandbox.get_resource_usage(instance_id)?;
println!("Memory used: {} bytes", usage.memory_used);

HTTP Server Wrapping

use wasm_sandbox::wrappers::HttpServerWrapper;

let wrapper = HttpServerWrapper::new()?;
let server_spec = wrapper.create_server_spec(
    "./my_server.wasm",
    8080,
    Some("./static".into()),
)?;

// Start the HTTP server in a sandbox
let server_id = wrapper.start_server(server_spec).await?;
println!("Server running on http://localhost:8080");

Building from Source

# Clone the repository

git clone https://github.com/username/wasm-sandbox.git

cd wasm-sandbox


# Build the project

cargo build --release


# Run tests

cargo test --all-features


# Run benchmarks

cargo bench


# Build examples

cargo build --examples


# Run an example

cargo run --example http_server

Examples

The repository includes several examples:

• HTTP Server: cargo run --example http_server
• MCP Server: cargo run --example mcp_server
• CLI Tool: cargo run --example cli_wrapper

Architecture

The crate is organized into several key modules:

• Runtime: WebAssembly runtime abstraction (Wasmtime, Wasmer)
• Security: Capability-based security and resource limits
• Communication: Host-guest communication channels and RPC
• Wrappers: Application-specific wrappers and templates
• Compiler: WebAssembly compilation utilities

Performance

Benchmarks show excellent performance characteristics:

• Function calls: < 1μs overhead for simple function calls
• Memory communication: > 1GB/s throughput for large data transfers
• Startup time: < 10ms for typical modules
• Resource monitoring: < 0.1% CPU overhead

Run cargo bench to see detailed performance metrics.

Contributing

Contributions are welcome! Please see our contributing guidelines for details.

License

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

Safety and Security

This crate uses WebAssembly's sandboxing capabilities to provide security isolation. However:

• Always validate input to guest functions
• Set appropriate resource limits for your use case
• Review WebAssembly modules before execution
• Consider additional security measures for production use

For security-sensitive applications, consider using additional sandboxing layers such as containers or process isolation.