Sandboxing & Security

Moxxy v4 provides multiple layers of security to isolate agent execution and prevent unauthorized access to system resources.

Overview

┌──────────────────────────────────────────────────────────┐
│                    Moxxy Gateway                         │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │              OS-Level Sandbox                      │  │
│  │  sandbox-exec (macOS) / bubblewrap (Linux)        │  │
│  │                                                    │  │
│  │  ┌──────────────────────────────────────────────┐  │  │
│  │  │           PathPolicy                         │  │  │
│  │  │  Workspace confinement                       │  │  │
│  │  │  Symlink/traversal protection                │  │  │
│  │  ├──────────────────────────────────────────────┤  │  │
│  │  │           Allowlists                         │  │  │
│  │  │  Command allowlist (shell.exec)              │  │  │
│  │  │  Domain allowlist (http.request)             │  │  │
│  │  ├──────────────────────────────────────────────┤  │  │
│  │  │           WASI Plugins                       │  │  │
│  │  │  Wasmtime 29, Ed25519 signed manifests       │  │  │
│  │  │  Capability-based permissions                │  │  │
│  │  └──────────────────────────────────────────────┘  │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

OS-Level Sandbox

Moxxy uses the operating system's native sandboxing facilities to confine agent processes:

Platform	Technology	Description
macOS	sandbox-exec	Apple's seatbelt sandbox profiles
Linux	bubblewrap (bwrap)	Unprivileged namespace-based sandboxing

The OS sandbox restricts what system calls and resources the agent's child processes can access, providing a hard security boundary regardless of what the agent attempts.

Sandbox Profiles

Three profiles are available:

Profile	Description
strict	Minimal access. No network, no filesystem outside workspace. Suitable for untrusted agents or sensitive environments.
standard	Default profile. Allows network access to approved domains and filesystem access within the workspace. Appropriate for most use cases.
none	No OS-level sandboxing. Use only for trusted development environments.

The standard profile is the default and provides a good balance between security and functionality.

PathPolicy: Workspace Confinement

PathPolicy enforces that agents can only access files within their designated workspace directory. It provides:

• Workspace root enforcement -- All file operations are confined to the agent's workspace directory
• Symlink protection -- Symlinks that point outside the workspace are blocked, preventing sandbox escape via symlink chains
• Path traversal protection -- Sequences like ../ that would escape the workspace are rejected
• Canonical path resolution -- All paths are resolved to their canonical form before access checks

Any attempt to access a path outside the workspace results in a security.violation event and the operation is denied.

Command Allowlists

When an agent invokes the shell.exec primitive to run a shell command, the command is checked against a per-agent allowlist stored in the database.

• Only commands on the allowlist are permitted
• Commands not on the list are rejected with a security.violation event
• Allowlists are configured per agent, so different agents can have different permitted commands
• The allowlist is checked before the command reaches the OS sandbox, providing defense in depth

Example Allowlist

An agent configured for Git operations might have:

git
ls
cat
grep
diff

Any other command (e.g., rm, curl, sudo) would be blocked.

Domain Allowlists

When an agent uses the http.request primitive, the target domain is checked against an allowlist:

• Only requests to approved domains are permitted
• Requests to other domains are rejected with a security.violation event
• Configured per agent in the database
• Prevents data exfiltration and limits the agent's network footprint

Example Domain Allowlist

api.openai.com
api.anthropic.com
github.com
api.github.com

WASI Plugins

Moxxy supports extending agent capabilities through WebAssembly System Interface (WASI) plugins.

Runtime

• Engine: Wasmtime 29
• Interface: WASI (WebAssembly System Interface)
• Capability model: Each plugin declares required capabilities and is only granted what it needs

Plugin Security

Plugins are secured through Ed25519 signed manifests:

1. Each plugin ships with a manifest declaring its name, version, required capabilities, and entry point
2. The manifest is signed with an Ed25519 private key
3. Moxxy verifies the signature against a known public key before loading the plugin
4. If the signature is invalid or missing, the plugin is rejected

This ensures that only trusted, unmodified plugins can be loaded.

Capability-Based Permissions

WASI plugins operate under a capability-based security model:

• Filesystem access -- Plugins can only access directories explicitly granted to them
• Network access -- Disabled by default, must be explicitly enabled per plugin
• Environment variables -- Not inherited from host unless explicitly mapped
• Memory limits -- Each plugin has a configurable memory ceiling

Plugin Manifest Example

{
  "name": "image-processor",
  "version": "1.0.0",
  "entry": "image_processor.wasm",
  "capabilities": {
    "filesystem": ["./workspace"],
    "network": false,
    "max_memory_mb": 64
  },
  "signature": "base64-encoded-ed25519-signature"
}

Security Events

All security-related actions emit events on the SSE stream:

Event	Description
security.violation	An agent attempted a blocked action
security.redacted	Content was redacted by security policy
vault.denied	An agent attempted to access a secret without a valid grant

These events include details about what was attempted and why it was blocked, providing a real-time audit trail.

Configuration

Sandbox settings are configured per agent. The sandbox profile can be set when creating or updating an agent through the API.

Setting the Sandbox Profile

curl -X PATCH http://127.0.0.1:3000/v1/agents/researcher \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "sandbox_profile": "strict"
    }
  }'

Updating Command Allowlist

Command and domain allowlists are stored in the database and managed through the agent's configuration.

Best Practices

1. Use standard or strict profile for production agents
2. Minimize allowlists -- only permit commands and domains the agent actually needs
3. Review security events -- monitor the SSE stream or audit log for security.violation events
4. Sign WASI plugins -- never load unsigned plugins in production
5. Isolate sensitive agents -- use strict profile for agents handling sensitive data
6. Rotate secrets -- use the vault grant system to control secret access, and revoke grants that are no longer needed