Crate wasm_sandbox

Source
Expand description

§WebAssembly Sandbox

A Rust crate providing secure WebAssembly-based sandboxing for untrusted code execution with flexible host-guest communication patterns and comprehensive resource limits.

§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(())
}

§Key Features

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

§Primary Goals

  1. Security: Isolate untrusted code in WebAssembly sandboxes with configurable capabilities
  2. Flexibility: Support various types of applications (HTTP servers, CLI tools, MCP servers)
  3. Performance: Efficient host-guest communication with minimal overhead
  4. Resource Control: Fine-grained control over memory, CPU, network, filesystem access
  5. Ease of Use: High-level APIs for common use cases with sensible defaults

§Examples and Documentation

§Examples Repository

The crate includes comprehensive examples:

  • Basic Usage - Simple function calling and sandbox setup
  • File Processor - Secure file processing with filesystem limits
  • HTTP Server - Web server running in sandbox with network controls
  • Plugin Ecosystem - Generic plugin system with hot reload

See the examples directory for working code you can run and modify.

§Complete Documentation

§Getting Help

§Architecture Overview

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

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

This design allows switching between different WebAssembly runtimes while maintaining type safety and performance.

§Runtime Support

  • Wasmtime: Full support with all features (default)
  • Wasmer: Full support with all features (requires wasmer-runtime feature)

Re-exports§

pub use error::Error;
pub use error::Result;
pub use error::SandboxError;
pub use error::ResourceKind;
pub use error::SecurityContext;
pub use config::InstanceConfigBuilder;
pub use config::SandboxConfigBuilder;
pub use config::InstanceConfigExt;
pub use config::SandboxConfigExt;
pub use config::AdvancedCapabilities;
pub use config::NetworkPolicy;
pub use config::FilesystemPolicy;
pub use config::MemoryUnit;
pub use config::TimeUnit;
pub use monitoring::DetailedResourceUsage;
pub use monitoring::ResourceMonitor;
pub use monitoring::MemoryUsage;
pub use monitoring::CpuUsage;
pub use monitoring::IoUsage;
pub use monitoring::ResourceSnapshot;
pub use communication::CommunicationChannel;
pub use communication::RpcChannel;
pub use runtime::RuntimeMetrics;
pub use runtime::WasmInstanceState;
pub use security::CpuLimits;
pub use security::EnvironmentCapability;
pub use security::FilesystemCapability;
pub use security::IoLimits;
pub use security::MemoryLimits;
pub use security::NetworkCapability;
pub use security::ProcessCapability;
pub use security::RandomCapability;
pub use security::TimeCapability;
pub use utils::manifest::SandboxManifest;
pub use streaming::StreamingExecution;
pub use streaming::StreamingExecutor;
pub use streaming::StreamingConfig;
pub use streaming::StreamingConfigExt;
pub use streaming::FunctionCall;
pub use streaming::FunctionResult;
pub use plugins::WasmPlugin;
pub use plugins::PluginManifest;
pub use plugins::EntryPoint;
pub use plugins::ExecutionContext;
pub use plugins::PluginHealth;
pub use plugins::HotReload;
pub use plugins::CompatibilityReport;
pub use plugins::PluginValidator;
pub use plugins::PluginRegistry;
pub use plugins::SecurityAuditReport;
pub use plugins::BenchmarkReport;
pub use simple::SimpleSandbox;
pub use simple::ReusableSandbox;
pub use simple::from_source;

Modules§

communication
Host-guest communication mechanisms
compiler
Wrapper compilation toolchain
config
Configuration builders with ergonomic APIs and human-readable units
error
monitoring
Resource monitoring and usage tracking
plugins
Generic plugin system traits and types for wasm-sandbox
runtime
WebAssembly runtime abstraction
security
Security policies and resource limitations
simple
Simplified one-liner APIs for common use cases
streaming
Streaming execution APIs for large datasets and batch operations
templates
Code template system
utils
Utility functions and helpers
wrappers
Code generation for wrapping applications

Structs§

InstanceConfig
Configuration for a sandbox instance
InstanceId
Unique identifier for a sandbox instance
SandboxConfig
Configuration for the sandbox
SandboxInstance
Sandbox instance
WasmSandbox
Main sandbox controller
WasmSandboxBuilder
Builder for creating WasmSandbox instances with progressive complexity.

Functions§

compile_source_to_wasm
Automatically compile source code to WebAssembly.
execute
Execute a complete program (not just a function) with command-line arguments.
run
Execute a single function in a WebAssembly module with automatic compilation and sandboxing.
run_with_timeout
Execute a function with a timeout for simple cases.