Bash Sandbox

The Bash Sandbox extension intercepts shell commands before execution, applying safety checks at multiple layers: command blocklists, domain allowlists, dangerous pattern detection, and optional container isolation.

Architecture

mermaid
flowchart TD
    A[exec tool call] --> B{Command length?}
    B -->|> max| X[BLOCK]
    B -->|ok| C{Blocklist?}
    C -->|match| X
    C -->|ok| D{Dangerous patterns?}
    D -->|match block| X
    D -->|match warn| W[WARN + continue]
    D -->|ok| E{Sudo?}
    E -->|blocked| X
    E -->|ok| F{Domain check?}
    F -->|blocked| X
    F -->|ok| G{Container?}
    G -->|enabled| H[Wrap in container]
    G -->|disabled| I[ALLOW]
    H --> I

The sandbox runs as a before_tool_call hook at priority 250 — it executes before the Interactive Permissions hook (200) and LLM Hooks.

Modes

Mode	Behavior
`enforce`	Block dangerous commands (default)
`warn`	Log warnings but allow execution
`off`	Disable sandbox entirely

Command blocklist

These commands are blocked by default:

mkfs, fdisk, dd, shutdown, reboot, halt, poweroff,
iptables, useradd, userdel, visudo, mount, chroot,
insmod, rmmod, sysctl

Matching is case-insensitive on the command basename.

Dangerous patterns

Six built-in patterns detect risky command sequences:

Pattern	Severity	Example
`recursive-delete-root`	block	`rm -rf /`
`env-exfil-curl`	block	`env \| curl ...`
`reverse-shell`	block	`bash -i >& /dev/tcp/...`
`crypto-mining`	block	`xmrig`, `minerd`
`pipe-to-shell`	block	`curl ... \| bash`
`chmod-world-writable`	warn	`chmod 777`

Custom patterns can be added via configuration with regex and severity levels.

Domain checking

Network commands (curl, wget, etc.) are validated against domain allowlists and denylists.

Default allowlist:

github.com, *.github.com, *.githubusercontent.com,
npmjs.org, *.npmjs.org, registry.yarnpkg.com,
pypi.org, crates.io, rubygems.org,
hub.apilium.com, api.apilium.com,
localhost, 127.0.0.1

The denylist always takes precedence over the allowlist. URLs are extracted via regex and domains are matched with wildcard support (*.github.com matches api.github.com).

Container isolation

For high-security environments, commands can be wrapped in Docker, Podman, or gVisor containers:

json5
{
  bashSandbox: {
    container: {
      enabled: true,
      runtime: "auto",              // "auto" | "docker" | "podman" | "gvisor"
      image: "ubuntu:22.04",
      mountPolicy: "workdir-only",  // "workdir-only" | "home" | "custom"
      networkMode: "none",          // "none" | "host" | "bridge"
      resourceLimits: {
        cpus: 2,
        memoryMb: 512,
        pidsLimit: 256
      },
      securityFlags: {
        blockPrivileged: true,
        blockHostNetwork: true,
        blockRootVolume: true,
        noNewPrivileges: true,
        dropCapabilities: ["ALL"]
      }
    }
  }
}

Trusted registries: docker.io, ghcr.io, gcr.io, quay.io.

Audit log

Every evaluated command is recorded in an in-memory ring buffer (max 1000 entries):

typescript
{
  timestamp: string;      // ISO timestamp
  command: string;
  action: "allowed" | "blocked" | "warned";
  reason?: string;
  matchedPattern?: string;
  sessionKey?: string;
}

View recent audit entries via mayros sandbox status.

Agent tools

Tool	Description
`bash_sandbox_test`	Dry-run a command — returns verdict, reasons, and parsed commands
`bash_container_status`	Show container config and detected runtimes

CLI

bash
mayros sandbox status                  # Config summary + recent blocks
mayros sandbox test "rm -rf /"         # Test a command
mayros sandbox allow *.example.com     # Add domain to session allowlist
mayros sandbox deny dangerous-cmd      # Add to session blocklist
mayros sandbox container detect        # List available container runtimes
mayros sandbox container status        # Show container config
mayros sandbox container pull [image]  # Pull container image

Configuration

json5
{
  bashSandbox: {
    mode: "enforce",                       // "enforce" | "warn" | "off"
    maxCommandLengthBytes: 8192,           // 64–65536
    allowSudo: false,
    allowCurlToArbitraryDomains: false,
    bypassEnvVar: "MAYROS_BASH_SANDBOX_BYPASS",
    domainAllowlist: ["github.com"],       // Add custom domains
    domainDenylist: [],                    // Always-blocked domains
    commandBlocklist: [],                  // Additional blocked commands
    commandAllowOverrides: [],             // Session bypass list
    dangerousPatterns: [],                 // Custom patterns
    container: { /* see above */ },
  }
}

sandbox CLI — sandbox management commands
Interactive Permissions — intent-based permission system
Security — security architecture overview