sandbox

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: May 12, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package sandbox provides sandbox mode for isolated command execution. devenv.go adds dynamic Dockerfile caching per project.

Package sandbox provides sandbox mode for isolated command execution. This uses namespace/container isolation where available.

Index

Constants

This section is empty.

Variables

View Source 
var ContainerImageTag = "latest"

ContainerImageTag is set at build time via ldflags. Falls back to "latest".

Functions

func ApplySeccomp 

func ApplySeccomp() error

ApplySeccomp applies the default seccomp-bpf filter to the current process. The filter is irreversible: once installed it cannot be removed. Requires PR_SET_NO_NEW_PRIVS to be set first (Landlock's Apply does this).

func Available 

func Available() bool

Available returns true on macOS when sandbox-exec is present.

func ContextWithMode 

func ContextWithMode(ctx context.Context, m Mode) context.Context

ContextWithMode attaches a sandbox Mode to a context.

func DefaultSeccompProfile 

func DefaultSeccompProfile() []byte

DefaultSeccompProfile returns a raw BPF program (as bytes) that blocks dangerous syscalls. Each blocked syscall returns EPERM to the caller.

func DockerAvailable 

func DockerAvailable() bool

DockerAvailable returns true if Docker daemon is reachable.

func GVisorAvailable 

func GVisorAvailable() bool

GVisorAvailable returns true if Docker is available with the runsc (gVisor) runtime.

func GVisorDockerArgs 

func GVisorDockerArgs() []string

GVisorDockerArgs returns additional Docker args to use gVisor runtime. This provides VM-class isolation without actual VMs.

func GenerateProfile 

func GenerateProfile(cfg SandboxConfig) string

GenerateProfile builds a macOS Seatbelt SBPL profile string for the given SandboxConfig.

func IsAvailable 

func IsAvailable() bool

IsAvailable checks if sandboxing is available on this system.

func LandlockAvailable 

func LandlockAvailable() bool

LandlockAvailable returns true if Landlock is supported on this kernel. It attempts to create a zero-length ruleset; ENOSYS or EOPNOTSUPP indicates no support.

func WrapCommand 

func WrapCommand(command string, cfg SandboxConfig) (string, []string)

WrapCommand returns the executable and argument list needed to run command inside a Seatbelt sandbox. If the mode is ModeOff the original command is returned unchanged (bash -c <command>).

Types

type CachedImage 

type CachedImage struct {
	Tag         string
	ContentHash string
	BuiltAt     time.Time
	Stale       bool
}

CachedImage holds metadata about a cached Docker image for a project.

type Config 

type Config struct {
	Enabled      bool     `json:"enabled"`
	Type         string   `json:"type"` // "namespace", "docker", "chroot", "none"
	AllowNetwork bool     `json:"allow_network"`
	AllowWrite   bool     `json:"allow_write"`
	ReadOnlyDirs []string `json:"read_only_dirs"`
	WritableDirs []string `json:"writable_dirs"`
	MaxMemoryMB  int      `json:"max_memory_mb"`
	MaxCPUPct    int      `json:"max_cpu_pct"`
}

Config describes sandbox configuration.

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a default sandbox configuration.

type ContainerSandbox 

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

ContainerSandbox executes commands inside a Docker container, providing full isolation. It supports dynamic Dockerfile generation for on-the-fly environment setup (inspired by herm's DevEnv pattern).

func NewContainerSandbox 

func NewContainerSandbox(projectDir string) *ContainerSandbox

NewContainerSandbox creates a container sandbox for the given project.

func (*ContainerSandbox) BuildFromDockerfile 

func (c *ContainerSandbox) BuildFromDockerfile(ctx context.Context, dockerfile string) (string, error)

BuildFromDockerfile builds a new image from a Dockerfile in the project. Returns the image tag that can be used for subsequent Start calls.

func (*ContainerSandbox) ContainerID 

func (c *ContainerSandbox) ContainerID() string

ContainerID returns the full container ID (empty if not running).

func (*ContainerSandbox) Exec 

func (c *ContainerSandbox) Exec(ctx context.Context, command string, timeout time.Duration) (string, error)

Exec runs a command inside the container and returns its output.

func (*ContainerSandbox) HotSwap 

func (c *ContainerSandbox) HotSwap(ctx context.Context) error

HotSwap stops the current container and starts a new one with the updated image.

func (*ContainerSandbox) Image 

func (c *ContainerSandbox) Image() string

Image returns the current image name.

func (*ContainerSandbox) Running 

func (c *ContainerSandbox) Running() bool

Running reports whether the container is active.

func (*ContainerSandbox) SetImage 

func (c *ContainerSandbox) SetImage(img string)

SetImage updates the image to use for the next Start call.

func (*ContainerSandbox) Start 

func (c *ContainerSandbox) Start(ctx context.Context) error

Start launches the container with the project directory mounted.

func (*ContainerSandbox) Stop 

func (c *ContainerSandbox) Stop() error

Stop terminates the container.

type DevEnvManager 

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

DevEnvManager caches Docker images per-project based on Dockerfile content hashes.

func NewDevEnvManager 

func NewDevEnvManager(projectDir string) *DevEnvManager

NewDevEnvManager creates a new DevEnvManager for the given project directory.

func (*DevEnvManager) GetOrBuild 

func (d *DevEnvManager) GetOrBuild(ctx context.Context, dockerfile string) (string, error)

GetOrBuild returns the cached image tag if the Dockerfile content hash matches, otherwise rebuilds and caches the new image.

func (*DevEnvManager) Invalidate 

func (d *DevEnvManager) Invalidate(projectDir string)

Invalidate marks the cache for the given project directory as stale.

func (*DevEnvManager) IsStale 

func (d *DevEnvManager) IsStale(projectDir string) bool

IsStale checks if the Dockerfile for the given project directory has changed since last build.

type IsolationLevel 

type IsolationLevel string

IsolationLevel represents the desired sandbox strength. 

const (
	IsolationDefault   IsolationLevel = "default"
	IsolationEnhanced  IsolationLevel = "enhanced"
	IsolationContainer IsolationLevel = "container"
	IsolationMaximum   IsolationLevel = "maximum"
	IsolationOff       IsolationLevel = "off"
)

type LandlockSandbox 

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

LandlockSandbox restricts filesystem access for the current process.

func NewLandlockSandbox 

func NewLandlockSandbox(projectDir string) *LandlockSandbox

NewLandlockSandbox creates a sandbox that allows read/write to the project directory and /tmp, and read-only access to essential system paths.

func (*LandlockSandbox) AddReadOnlyPath 

func (l *LandlockSandbox) AddReadOnlyPath(path string)

AddReadOnlyPath appends a read-only path to the sandbox configuration. Must be called before Apply.

func (*LandlockSandbox) AddReadWritePath 

func (l *LandlockSandbox) AddReadWritePath(path string)

AddReadWritePath appends a read-write path to the sandbox configuration. Must be called before Apply.

func (*LandlockSandbox) Apply 

func (l *LandlockSandbox) Apply() error

Apply enforces the Landlock rules on the current process. After this call, the process cannot access any path not explicitly allowed. This is irreversible for the lifetime of the process.

type Mode 

type Mode string

Mode represents the sandbox isolation level. 

const (
	ModeStrict    Mode = "strict"    // read-only filesystem
	ModeWorkspace Mode = "workspace" // write only in project dir + /tmp
	ModeOff       Mode = "off"       // no restrictions
)

func ModeFromContext 

func ModeFromContext(ctx context.Context) Mode

ModeFromContext retrieves the sandbox Mode from a context. Returns ModeOff when no mode is set.

func ParseMode 

func ParseMode(s string) Mode

ParseMode converts a string to a Mode, defaulting to ModeOff for unrecognised values.

type Sandbox 

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

Sandbox provides isolated execution environment.

func New 

func New(config *Config) (*Sandbox, error)

New creates a new sandbox.

func (*Sandbox) Close 

func (s *Sandbox) Close() error

Close cleans up sandbox resources.

func (*Sandbox) Run 

func (s *Sandbox) Run(ctx context.Context, command string) (*exec.Cmd, error)

Run executes a command in the sandbox.

type SandboxConfig 

type SandboxConfig struct {
	Mode         Mode
	WorkspaceDir string
	AllowNetwork bool
}

SandboxConfig describes how a command should be sandboxed.

type SandboxSelection 

type SandboxSelection struct {
	Backend string // "landlock", "seatbelt", "nsjail", "bwrap", "docker", "none"
	Reason  string // why this was selected
}

SandboxSelection represents the chosen sandbox backend.

func SelectSandbox 

func SelectSandbox(level IsolationLevel, projectDir string) SandboxSelection

SelectSandbox automatically chooses the best available sandbox backend for the current platform and requested isolation level.

macOS: seatbelt (always available) Linux: landlock+seccomp > nsjail > bubblewrap > docker > none

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.