# WebAssembly Sandbox (`wasm-sandbox`)
[](https://crates.io/crates/wasm-sandbox)
[](https://docs.rs/wasm-sandbox)
[](https://opensource.org/licenses/MIT)
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
```rust
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
```rust
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`:
```toml
[dependencies]
wasm-sandbox = "0.1.0"
```
For all features including Wasmer runtime support:
```toml
[dependencies]
wasm-sandbox = { version = "0.1.0", features = ["all-runtimes"] }
```
## Quick Start
```rust
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
```rust
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
```rust
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
```rust
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
```bash
# 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](CONTRIBUTING.md) for details.
## License
This project is licensed under the MIT License - see the [LICENSE](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.