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
DEFAULT_MAX_OUTPUT = 10000
DOCKER_CPU_LIMIT = "1"
DOCKER_DEFAULT_IMAGE = "alpine:latest"
DOCKER_MEMORY_LIMIT = "512m"
EXTRA_SEARCH_PATHS = ["/usr/local/bin", "/opt/homebrew/bin"]
IO_BUFFER_SIZE = 4096
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"
SIGNAL_GRACE_PERIOD = 0.5.seconds
TIMEOUT_EXIT_CODE = 124
WRITE_FILE_TIMEOUT = 30

Class methods

available?

Check if sandboxing is available

Source
build_sandbox_image(dockerfile : Path) : Bool

Build the sandbox Docker image from a Dockerfile.

Source
capture_command(command : String, args : Array(String), timeout : Int32, max_output_size : Int32 = DEFAULT_MAX_OUTPUT) : Tuple(Process::Status, String, String)

Runs a process, capturing stdout/stderr through pipes with a timeout. The read ends are closed once the process settles so reader fibers never block on daemons that inherit and keep the pipe write ends open.

Source
detect

Detect available sandbox tool (memoized)

Source
detect_override

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

Source
detect_override=(detect_override : Type | Nil)

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

Source
docker_image

Custom Docker image (set from config at startup)

Source
docker_image=(docker_image : String | Nil)

Custom Docker image (set from config at startup)

Source
docker_image_exists?(image : String) : Bool
Source
exec(command : String, workspace : Path, timeout : Int32, max_output_size : Int32 = DEFAULT_MAX_OUTPUT) : Tuple(Process::Status, String, String)

Execute a shell command in sandbox (for arbitrary commands with pipes/redirects). Returns: {Process::Status, stdout, stderr}

Source
exec_program(program : String, args : Array(String), workspace : Path, timeout : Int32, max_output_size : Int32 = DEFAULT_MAX_OUTPUT) : Tuple(Process::Status, String, String)

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

Source
forward_env_vars(args : Array(String)) : Nil

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

Source
list_dir(path : String, workspace : Path) : Tuple(Bool, String)
Source
read_file(path : String, workspace : Path, max_size : Int32 = DEFAULT_MAX_FILE_SIZE) : Tuple(Bool, String)
Source
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).

Source
require_sandbox!

Require sandbox or raise clear error

Source
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.

Source
resolve_type(config : String) : Type

Resolve sandbox type from config string

Source
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.

Source
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.

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

Nested types