sandbox

package
v0.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 3, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Overview

Package sandbox provides a WASM-based sandbox for secure code execution.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsDockerAvailable 

func IsDockerAvailable(ctx context.Context) bool

IsDockerAvailable checks if Docker is accessible.

func ParseNetworkMode 

func ParseNetworkMode(mode string) (string, error)

ParseNetworkMode validates and returns a network mode string.

Types

type Capability 

type Capability string

Capability represents a permission that can be granted to sandboxed code. 

const (
	// CapFSRead allows reading files from the filesystem.
	CapFSRead Capability = "fs_read"
	// CapFSWrite allows writing files to the filesystem.
	CapFSWrite Capability = "fs_write"
	// CapNetHTTP allows making HTTP requests.
	CapNetHTTP Capability = "net_http"
	// CapExecRun allows executing shell commands.
	CapExecRun Capability = "exec_run"
)

type Config 

type Config struct {
	// Capabilities granted to the sandboxed code.
	Capabilities []Capability

	// MemoryLimitMB is the maximum memory in megabytes (default: 16).
	MemoryLimitMB int

	// FuelLimit is the maximum number of instructions (0 = unlimited).
	FuelLimit uint64

	// Timeout is the maximum execution time.
	Timeout time.Duration

	// WorkingDir is the working directory for file operations.
	WorkingDir string

	// AllowedPaths restricts file access to these paths (empty = WorkingDir only).
	AllowedPaths []string

	// AllowedHosts restricts HTTP access to these hosts (empty = all allowed).
	AllowedHosts []string

	// AllowedCommands restricts exec to these commands (empty = none allowed).
	AllowedCommands []string

	// MaxOutputBytes limits the output size (default: 1MB).
	MaxOutputBytes int
}

Config configures a sandbox instance.

func DefaultConfig 

func DefaultConfig() Config

DefaultConfig returns a restrictive default configuration.

func (*Config) HasCapability 

func (c *Config) HasCapability(cap Capability) bool

HasCapability checks if a capability is granted.

type DockerConfig 

type DockerConfig struct {
	// Image is the Docker image to use (default: "alpine:latest").
	Image string

	// Mounts defines volume mounts for filesystem access.
	Mounts []DockerMount

	// NetworkMode controls network access ("none", "bridge", "host").
	NetworkMode string

	// Memory limit in bytes (0 = unlimited).
	MemoryLimit int64

	// CPU quota (0 = unlimited, 100000 = 1 CPU).
	CPUQuota int64

	// Timeout is the maximum execution time.
	Timeout time.Duration

	// Environment variables to pass to the container.
	Env []string

	// User to run as inside the container (e.g., "nobody", "1000:1000").
	User string

	// ReadonlyRootfs makes the container's root filesystem read-only.
	ReadonlyRootfs bool

	// CapDrop lists Linux capabilities to drop (e.g., "ALL").
	CapDrop []string

	// CapAdd lists Linux capabilities to add.
	CapAdd []string

	// SecurityOpt lists security options (e.g., "no-new-privileges").
	SecurityOpt []string

	// MaxOutputBytes limits output size (default: 1MB).
	MaxOutputBytes int
}

DockerConfig configures a Docker-based sandbox.

func DefaultDockerConfig 

func DefaultDockerConfig() DockerConfig

DefaultDockerConfig returns a secure default configuration.

type DockerMount 

type DockerMount struct {
	// HostPath is the path on the host system.
	HostPath string

	// ContainerPath is the path inside the container.
	ContainerPath string

	// ReadOnly makes the mount read-only.
	ReadOnly bool
}

DockerMount defines a volume mount.

type DockerSandbox 

type DockerSandbox struct {
	// contains filtered or unexported fields
}

DockerSandbox provides Docker-based isolation for command execution.

func NewDockerSandbox 

func NewDockerSandbox(ctx context.Context, config DockerConfig, appConfig *Config) (*DockerSandbox, error)

NewDockerSandbox creates a new Docker sandbox.

func (*DockerSandbox) Close 

func (d *DockerSandbox) Close() error

Close releases the Docker client resources.

func (*DockerSandbox) EnsureImage 

func (d *DockerSandbox) EnsureImage(ctx context.Context) error

EnsureImage pulls the configured image if not present.

func (*DockerSandbox) Run 

func (d *DockerSandbox) Run(ctx context.Context, command string, args []string) (*Result, error)

Run executes a command inside a Docker container.

func (*DockerSandbox) RunShell 

func (d *DockerSandbox) RunShell(ctx context.Context, shellCommand string) (*Result, error)

RunShell executes a shell command inside a Docker container.

func (*DockerSandbox) RunWithStdin 

func (d *DockerSandbox) RunWithStdin(ctx context.Context, stdin []byte, command string, args []string) (*Result, error)

RunWithStdin executes a command with stdin input.

type ExecutionError 

type ExecutionError struct {
	Kind    string // "timeout", "memory", "capability", "runtime"
	Message string
	Cause   error
}

ExecutionError represents an error during sandboxed execution.

func NewCapabilityError 

func NewCapabilityError(cap Capability, operation string) *ExecutionError

NewCapabilityError creates a capability violation error.

func NewMemoryError 

func NewMemoryError(limit, used uint64) *ExecutionError

NewMemoryError creates a memory limit error.

func NewTimeoutError 

func NewTimeoutError(timeout time.Duration) *ExecutionError

NewTimeoutError creates a timeout error.

func (*ExecutionError) Error 

func (e *ExecutionError) Error() string

func (*ExecutionError) Unwrap 

func (e *ExecutionError) Unwrap() error

type HostFunctions 

type HostFunctions struct {
	// contains filtered or unexported fields
}

HostFunctions provides sandboxed implementations of host capabilities.

func NewHostFunctions 

func NewHostFunctions(config Config) *HostFunctions

NewHostFunctions creates host functions with the given configuration.

func (*HostFunctions) ExecRun 

func (h *HostFunctions) ExecRun(ctx context.Context, command string, args []string) ([]byte, []byte, int, error)

ExecRun executes a command if the exec_run capability is granted.

func (*HostFunctions) ExecuteCommand 

func (h *HostFunctions) ExecuteCommand(ctx context.Context, command string, args []string, timeout time.Duration) (*Result, error)

ExecuteCommand is a high-level helper for simple command execution.

func (*HostFunctions) FSRead 

func (h *HostFunctions) FSRead(ctx context.Context, path string) ([]byte, error)

FSRead reads a file if the fs_read capability is granted.

func (*HostFunctions) FSWrite 

func (h *HostFunctions) FSWrite(ctx context.Context, path string, data []byte) error

FSWrite writes a file if the fs_write capability is granted.

func (*HostFunctions) HTTPFetch 

func (h *HostFunctions) HTTPFetch(ctx context.Context, method, url string, body []byte, headers map[string]string) ([]byte, int, error)

HTTPFetch makes an HTTP request if the net_http capability is granted.

type Result 

type Result struct {
	// Output is the stdout from the execution.
	Output []byte

	// Error is the stderr from the execution.
	Error []byte

	// ExitCode is the exit code (0 = success).
	ExitCode int

	// Duration is how long the execution took.
	Duration time.Duration

	// MemoryUsed is the peak memory usage in bytes.
	MemoryUsed uint64

	// FuelConsumed is the number of instructions executed.
	FuelConsumed uint64
}

Result represents the result of a sandboxed execution.

type Runtime 

type Runtime struct {
	// contains filtered or unexported fields
}

Runtime manages WASM module execution with sandboxing.

func NewRuntime 

func NewRuntime(ctx context.Context, config Config) (*Runtime, error)

NewRuntime creates a new sandbox runtime.

func (*Runtime) Close 

func (r *Runtime) Close(ctx context.Context) error

Close releases all resources.

func (*Runtime) Compile 

func (r *Runtime) Compile(ctx context.Context, name string, wasm []byte) error

Compile compiles a WASM module and caches it.

func (*Runtime) Execute 

func (r *Runtime) Execute(ctx context.Context, name string, stdin []byte) (*Result, error)

Execute runs a compiled WASM module with the given input.

func (*Runtime) ExecuteBytes 

func (r *Runtime) ExecuteBytes(ctx context.Context, wasm, stdin []byte) (*Result, error)

ExecuteBytes compiles and runs WASM bytes directly (not cached).

func (*Runtime) RegisterHostModule 

func (r *Runtime) RegisterHostModule(ctx context.Context, moduleName string, builder func(wazero.HostModuleBuilder) wazero.HostModuleBuilder) error

RegisterHostModule registers a host module with functions that WASM modules can call.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.