class

Autobot::Tools::Sandbox

Inherits Reference < Object

Kernel-enforced sandboxing for command execution Uses bubblewrap or Docker to restrict file access at OS level

Constants

DEFAULT_MAX_FILE_SIZE = 1000000

DOCKER_CPU_LIMIT = "1"

DOCKER_DEFAULT_IMAGE = "alpine:latest"

DOCKER_MEMORY_LIMIT = "512m"

DOCKER_NAME_PREFIX = "autobot-sandbox-"

EXTRA_SEARCH_PATHS = ["/usr/local/bin", "/opt/homebrew/bin"]

LIST_DIR_TIMEOUT = 10

Log = ::Log.for(self)

MAX_LIST_OUTPUT = 100000

MAX_WRITE_OUTPUT = 10000

MKDIR_TIMEOUT = 5

READ_FILE_TIMEOUT = 10

SANDBOX_DOCKERFILE = "Dockerfile.sandbox"

SANDBOX_IMAGE_TAG = "autobot-sandbox"

SYSTEM_CONFIG_PATHS = ["/etc/alternatives", "/etc/ld.so.cache", "/etc/ld.so.conf", "/etc/ld.so.conf.d", "/etc/resolv.conf", "/etc/hosts", "/etc/nsswitch.conf", "/etc/ssl", "/etc/ca-certificates", "/etc/localtime", "/etc/passwd", "/etc/group", "/etc/matplotlibrc"]

/usr/bin/python3 and friends are symlinks into /etc/alternatives on Debian-based hosts

WRITE_FILE_TIMEOUT = 30

Class methods

available?

Check if sandboxing is available

build_sandbox_image(dockerfile : Path) : Bool

Build the sandbox Docker image from a Dockerfile.

detect

Detect available sandbox tool (memoized)

detect_override

Test override for sandbox detection (set to nil to use real detection)

detect_override=(detect_override : Type | Nil)

Test override for sandbox detection (set to nil to use real detection)

docker_image

Custom Docker image (set from config at startup)

docker_image=(docker_image : String | Nil)

Custom Docker image (set from config at startup)

docker_image_exists?(image : String) : Bool

exec(command : String, workspace : Path, timeout : Int32, max_output_size : Int32 = CommandRunner::DEFAULT_MAX_OUTPUT) : CommandRunner::Result

Execute a shell command in sandbox (for arbitrary commands with pipes/redirects).

exec_program(program : String, args : Array(String), workspace : Path, timeout : Int32, max_output_size : Int32 = CommandRunner::DEFAULT_MAX_OUTPUT) : CommandRunner::Result

Execute a program with explicit args in sandbox (no shell interpretation). Safer than exec for structured operations like file reads.

forward_env_vars(args : Array(String)) : Nil

Forward explicitly allowed environment variables to Docker container. Only variables listed in sandbox_env config are forwarded.

list_dir(path : String, workspace : Path) : Tuple(Bool, String)

read_file(path : String, workspace : Path, max_size : Int32 = DEFAULT_MAX_FILE_SIZE) : Tuple(Bool, String)

read_file_base64(path : String, workspace : Path, max_size : Int32 = DEFAULT_MAX_FILE_SIZE) : Tuple(Bool, String)

Read a file and return its contents as base64-encoded string. Safe for binary files (images, GIFs, documents).

require_sandbox!

Require sandbox or raise clear error

resolve_sandbox_image(config_dir : Path) : Nil

Resolve the Docker image to use, checking for a Dockerfile.sandbox in the given directory. If found and no explicit docker_image is set, builds and caches the image automatically.

resolve_type(config : String) : Type

Resolve sandbox type from config string

sandbox_env

Env var names to forward into Docker containers (set from config at startup). Only listed variables are forwarded — empty by default for security.

sandbox_env=(sandbox_env : Array(String))

Env var names to forward into Docker containers (set from config at startup). Only listed variables are forwarded — empty by default for security.

shell_escape(arg : String) : String

system_config_binds(paths : Array(String) = SYSTEM_CONFIG_PATHS) : Array(String)

write_file(path : String, content : String, workspace : Path) : Tuple(Bool, String)

Nested types

Autobot::Tools::Sandbox::Type