DEV Community

Guyoung Studio
Guyoung Studio

Posted on

BoxAgnts Introduction (3) — WebAssembly Sandbox

#architecture #security #ai #agents

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<String>,              // Host directory → Guest root directory mapping
    pub map_dirs: Option<Vec<(String, String)>>, // Multi-directory mapping
    pub env_vars: Option<Vec<(String, Option<String>)>>, // Environment variable injection
    pub allowed_outbound_hosts: Option<Vec<String>>, // Outbound network whitelist
    pub block_url: Option<String>,             // Block specific URLs
    pub block_networks: Option<Vec<String>>,    // Block IP network ranges
    pub wasm_timeout: Option<u32>,              // Execution timeout (seconds)
    pub wasm_max_memory_size: Option<u32>,      // Max memory limit
    pub wasm_max_wasm_stack: Option<u32>,       // Max stack size
    pub wasm_fuel: Option<u32>,                  // Instruction fuel (execution budget)
    pub wasm_cache_dir: Option<String>,          // Precompiled cache directory
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
        // ...
    }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Advantages of this design:

  1. Easy to debug: Can be tested directly with echo '{}' | wasmtime run tool.wasm
  2. Language agnostic: Any language that can read/write stdin/stdout can write WASM components
  3. 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
Enter fullscreen mode Exit fullscreen mode

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
}
Enter fullscreen mode Exit fullscreen mode

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.
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Hostname whitelist (wildcard matching)
  2. 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
Enter fullscreen mode Exit fullscreen mode

Key design decision: WASM components do not directly use the host OS's network stack. All HTTP requests go through BoxAgnts' proxy layer, ensuring:

  1. Every request passes whitelist validation
  2. Requests/responses can be logged and audited
  3. 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:

  1. Read the target Skill's SKILL.md file
  2. Inject it as the system prompt for that conversation turn
  3. 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:

  1. Have the AI generate a complete website
  2. Deploy it through the WASM file server
  3. 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
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)