BoxAgnts Introduction (3) — WebAssembly Sandbox

When an AI Agent possesses file read/write, Shell execution, and network access capabilities, who guarantees it won't do harm? The severity of this problem should not be underestimated. In traditional architectures, AI tools run directly on the host machine with the same system permissions as the user. This means: A prompt injection could lead to malicious file modifications A wrong Shell command could delete important data A hijacked network request could leak sensitive information BoxAgnts' answer is in the bottom layer — the WASM security sandbox. This is not an optional "security enhancement," but the trust foundation of the entire system. Why WebAssembly? Among numerous sandbox technologies, BoxAgnts chose WebAssembly — a mature technology validated by billions of browsers. Comparison Docker Container VM Virtual Machine WebAssembly (Wasmtime) Startup Speed Seconds Minutes Milliseconds Memory Overhead ~50MB+ ~500MB+ ~1MB Isolation Granularity Process-level Hardware-level Instruction-level (in-sandbox verification) Cross-platform ✅ ❌ ✅ Near-native Performance ✅ ❌ ✅ (Cranelift JIT) Embeddability Requires Docker Daemon Requires Hypervisor Library-level embedding WASM's instruction-level isolation means every memory access instruction is verified within sandbox boundaries. This is not a post-hoc check — it's hardware-assisted bounds checking during execution. BoxAgnts chose Wasmtime (from the Bytecode Alliance) as its runtime engine, one of the most mature and performant WASM runtimes available today. RunOption: The Sandbox's Fine-Grained Control Panel BoxAgnts' sandbox configuration is not a simple "on" or "off" — it's an 11-dimensional control panel: pub struct RunOption { pub work_dir: Option, // Host directory → Guest root directory mapping pub map_dirs: Option>, // Multi-directory mapping pub env_vars: Option)>>, // Environment variable injection pub allowed_outbound_hosts: Option>, // Outbound network whitelist pub block_url: Option, // Block specific URLs pub block_networks: Option>, // Block IP network ranges pub wasm_timeout: Option, // Execution timeout (seconds) pub wasm_max_memory_size: Option, // Max memory limit pub wasm_max_wasm_stack: Option, // Max stack size pub wasm_fuel: Option, // Instruction fuel (execution budget) pub wasm_cache_dir: Option, // Precompiled cache directory } Security Implications of Each Dimension 1. work_dir + map_dirs: Filesystem Isolation WASM components have no ability to directly access the host filesystem. All file operations must go through WASI's preopen mechanism — host directories are mapped to the guest's virtual filesystem root. This means: WASM code can only see explicitly mapped directories Sensitive system paths (e.g., /etc/passwd, C:\Windows\System32) are naturally invisible Multi-directory mapping supports more complex scenarios (e.g., separating shared library directories from project directories) 2. allowed_outbound_hosts: Network Access Whitelist This is one of the most critical security controls. It uses wildcard pattern matching: "https://*" → Allow all HTTPS connections "https://*.github.com" → Only allow *.github.com subdomains "*://localhost:*" → Allow all protocols to localhost on any port Every time a WASM component attempts to make a network connection, socket_addr_check() verifies: pub async fn socket_addr_check( addr: SocketAddr, addr_use: SocketAddrUse, allowed_outbound_hosts: OutboundAllowedHosts, blocked_networks: BlockedNetworks, ) -> bool TCP Bind and UDP Bind are directly rejected — components can only initiate outbound connections, not listen on ports. 3. block_networks: IP Blacklist In addition to hostname whitelisting, IP network range blacklisting is supported: --block-network 10.0.0.0/8 # Block Class A private network --block-network 192.168.0.0/16 # Block Class C private network --block-network private # Block all private networks block_networks uses the ip_network crate for precise IP range matching, including special handling for the private keyword — blocking the three RFC 1918 private network ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16. 4. wasm_timeout: Hard Execution Time Limit If WASM code enters an infinite loop or maliciously consumes CPU, the timeout mechanism forcibly terminates execution after the specified number of seconds. Wasmtime's epoch-based interruption mechanism ensures reliability — not "waiting" externally for a timeout, but periodically checking internally within the WASM execution engine. 5. wasm_max_memory_size + wasm_max_wasm_stack: Hard Memory Limits Prevents malicious or buggy WASM components from exhausting host resources through unlimited memory growth. When a linear memory growth request exceeds the limit, the memory.grow instruction returns -1, allowing the component to fail gracefully rather than causing OOM. 6. wasm_fuel: Instruction-Level Execution Budget This is a unique WASM security feature — "fuel metering." Each WASM instruction consumes 1 unit of fuel (some control flow instructions consume 0). When fuel runs out, execution terminates immediately. This provides more precise execution control than timeouts, preventing algorithmic complexity attacks. 7. wasm_cache_dir: Balancing Performance and Security Precompiled .cwasm file caching avoids recompiling WASM modules on every execution. This is both a performance optimization and a security enhancement — precompiled modules have already passed Wasmtime's validation and don't need re-verification. WasmTool: The Bridge Between Two Worlds WasmTool in wasm_tool.rs is the critical bridge connecting the middle-layer Tool trait with the bottom-layer WASM execution: pub struct WasmTool { name: String, // Tool name ("read", "write", "bash"...) wasm_file: String, // .wasm filename description: String, // AI-readable tool description input_schema: Value, // JSON Schema parameter definition } impl Tool for WasmTool { async fn execute(&self, input: Value, ctx: &ToolContext) -> ToolResult { // 1. Convert JSON parameters to CLI arguments let args = value_to_cli_args(input); // 2. Locate WASM file let wasm_file = ctx.get_app_extensions_dir() .join("tools/").join(&self.wasm_file); // 3. Build RunOption (extract security config from ToolContext) let mut options = RunOption::default(); options.work_dir = Some(work_dir); options.allowed_outbound_hosts = Some(ctx.get_allowed_outbound_hosts()); options.wasm_cache_dir = Some(cache_dir); options.block_url = ctx.block_url.clone(); // 4. Execute via Wasmtime let result = boxagnts_wasm_sandbox::run::execute( wasm_file, None, Some(args), options, None ).await; // 5. Parse stdout/stderr → ToolResult // ... } } JSON stdin/stdout Interface Pattern BoxAgnts' WASM components adopt a clean, practical interface pattern — JSON stdin/stdout: WASM Component stdin ← JSON parameters (e.g., {"file_path":"/src/main.rs","limit":50}) stdout → JSON result (e.g., {"content":"...","is_error":false}) stderr → Error messages Advantages of this design: Easy to debug: Can be tested directly with echo '{}' | wasmtime run tool.wasm Language agnostic: Any language that can read/write stdin/stdout can write WASM components Backward compatible: Adding fields won't break old components WASI: Standardized System Interface WASM itself is only a computation model. For WASM code to access filesystems and networks, WASI (WebAssembly System Interface) is needed. BoxAgnts' sandbox implements controlled system access through WASI: Filesystem Access: The preopen Mechanism Host Filesystem WASM Guest View ───────────────── ──────────────── /home/user/workspace/ ──map──→ / /home/user/workspace/src ──map──→ /src /tmp/wasm-cache/ ──map──→ /cache /etc/ (not mapped) Invisible /root/ (not mapped) Invisible WASM code's fopen("/etc/passwd") call is intercepted by the WASI layer — because /etc/ is not mapped to any host directory, this call fails directly. Network Access: socket_addr_check Every time WASM code attempts to create a network connection, a security check is triggered: // 1. TCP Bind → Directly rejected (components shouldn't listen on ports) SocketAddrUse::TcpBind => { eprintln!("Deny TCP bind: {}", addr); return false; } // 2. UDP Bind → Directly rejected SocketAddrUse::UdpBind => { return false; } // 3. Outbound connections → Check whitelist + blacklist SocketAddrUse::TcpConnect | UdpConnect => { // Check allowed_hosts whitelist // Check blocked_networks blacklist // Check private network } When a connection is denied, the system outputs a clear log message: A component tried to make an outbound network connection to disallowed destination 'http://internal-server:8080'. To allow this request, add 'http://internal-server:8080' to the allowed outbound hosts config. The Three-Layer Defense System in Full Combining the above mechanisms, BoxAgnts' sandbox forms a three-layer defense-in-depth system: Request to Execute Tool │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ Layer 1 │ │ Layer 2 │ │ Layer 3 │ │ Resource│ ──────→ │ WASI │ ──────→ │ Network │ │ Limits │ │ Intercept│ │ Control │ │ │ │ │ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ Memory/Stack/Fuel/ Filesystem Path Hostname Whitelist Timeout Hard Limits Virtualized Mapping IP Blacklist Layer 1: Resource Limits The WASM runtime sets hard resource boundaries when loading the module: Memory ceiling: wasm_max_memory_size Stack ceiling: wasm_max_wasm_stack Execution time: wasm_timeout Instruction budget: wasm_fuel These limits are guaranteed at the Wasmtime engine level — component code cannot bypass them because the limits are encoded into the WASM virtual machine's execution loop. Layer 2: WASI Filesystem Interception Filesystem access is virtualized through the WASI preopen mechanism. Key protections: Components can only "see" explicitly mapped directories Path traversal attacks (../../etc/passwd) are blocked by the WASI layer Symbolic link following is restricted to mapped directory scope Layer 3: Network Control Network access undergoes dual filtering: Hostname whitelist (wildcard matching) IP network range blacklist (CIDR matching + "private" keyword) The two filters are in AND relationship — the target must simultaneously pass the whitelist check and not be blocked by the blacklist. Wasmtime HTTP: An HTTP Client Inside the Sandbox The wasmtime_http/ module provides a restricted HTTP client for WASM components: // wasmtime_http/src/handler.rs // Intercepts HTTP requests from WASM components // Checks allowed_outbound_hosts // Checks blocked_networks // Forwards legitimate requests to reqwest // Returns responses to WASM components Key design decision: WASM components do not directly use the host OS's network stack. All HTTP requests go through BoxAgnts' proxy layer, ensuring: Every request passes whitelist validation Requests/responses can be logged and audited Malicious URL patterns can be blocked (via block_url parameter) Skill System: Intelligent Extensions Within the Sandbox Beyond the 7 WASM tool components, BoxAgnts also supports running specialized AI skills within the sandbox through the Skill system. 5 skills are pre-installed: Skill Function Config File code-review Code review and analysis skills/code-review/SKILL.md css-refactor-advisor CSS refactoring advice skills/css-refactor-advisor/SKILL.md current-weather Current weather query skills/current-weather/SKILL.md weather-forecast Weather forecast skills/weather-forecast/SKILL.md front-component-generator Frontend component generation skills/front-component-generator/SKILL.md How Skills Work The core of a Skill is a SKILL.md file — a Markdown-formatted description of the skill's specialized prompt. When the SkillTool is invoked: Read the target Skill's SKILL.md file Inject it as the system prompt for that conversation turn The AI uses the underlying tools to complete the task in that role The cost of creating a new skill is extremely low — write a Markdown description file, no code compilation needed. However, all underlying tools called by the Skill still run within the WASM sandbox, so security is not compromised. Two practical examples: Code Review Skill: When the AI analyzes code in the role of "code review expert," it uses the file-read tool to read source code, then provides analysis within the sandbox's permission constraints. The Skill defines the review focus (security, performance, readability), but the underlying file reading is still protected by the sandbox's path mapping. Weather Query Skill: When the AI works in the role of "weather expert," it uses the web-fetch tool to request weather APIs. The Skill defines the query format and output style, but the underlying network requests are still restricted by the allowed_outbound_hosts whitelist — if the weather API's domain is not in the whitelist, the request will be rejected. Extension Services: Static File Server The app/extensions/services/ directory contains a pre-installed WASM static file server component. This means you can: Have the AI generate a complete website Deploy it through the WASM file server Access it directly in the browser Service components share the same sandbox infrastructure as tool components — the same permission controls, network restrictions, and resource boundaries. This ensures that even long-running services cannot cross security boundaries. Performance Considerations: Sandbox Is Not Synonymous with Slowness Many people's first reaction to sandbox technology is "won't it be slow?" BoxAgnts answers this with its actual architecture: Compilation Optimization: Cranelift JIT Wasmtime uses the Cranelift compiler to compile WASM bytecode into machine code for the target platform. While not at the highest optimization level (that's LLVM's domain), Cranelift's compilation speed is extremely fast, suitable for JIT scenarios. Precompilation Cache compiler.rs supports precompiling .wasm files to .cwasm (Compiled WASM) and caching them: // compiler.rs // First load .wasm → compile → cache as .cwasm // Subsequent loads → use .cwasm directly → skip compilation This means the first use of a tool incurs a slight compilation overhead (milliseconds), but subsequent uses are nearly equivalent to native code startup speed. Zero-Copy Data Transfer Data transfer through stdin/stdout between host and WASM uses zero-copy optimization wherever possible. For typical AI Agent workloads (file reads/writes, web requests, command-line output), the sandbox overhead is far lower than the I/O overhead itself — you can barely feel its presence. Summary The bottom-layer WASM security sandbox is the trust foundation of BoxAgnts. Through three-layer defense-in-depth (resource limits → WASI filesystem interception → network control), it allows users to confidently grant AI file read/write, command execution, and network access capabilities. This design answers the second core question: how to let AI do things without doing harm? The answer is not a simple "sandbox" label, but a comprehensive fine-grained control system: 11-dimensional RunOption configuration panel Complete interception of WASI system interfaces Dual network filtering with hostname whitelist + IP blacklist Quadruple resource limits: memory, stack, time, fuel This "security depth" is what allows BoxAgnts to put "dangerous tools" like Bash execution and file editing into the Agent's toolbox — because trust comes not from "hoping the AI doesn't make mistakes," but from "ensuring mistakes are isolated within the sandbox." The spirit of this layer's design is worth learning for all AI Agent developers: security is not the price of capability sacrifice, but the prerequisite for capability expansion. Related Resources Boxagnts: https://github.com/guyoung/boxagnts