sandbox

Documentation

Overview

Package sandbox provides Docker-based sandboxed execution for CI/CD pipeline steps.

Index

• type DockerSandbox
  • func NewDockerSandbox(config SandboxConfig) (*DockerSandbox, error)
  • func (s *DockerSandbox) Close() error
  • func (s *DockerSandbox) CopyIn(ctx context.Context, srcPath, destPath string) error
  • func (s *DockerSandbox) CopyOut(ctx context.Context, srcPath string) (io.ReadCloser, error)
  • func (s *DockerSandbox) CreateContainer(ctx context.Context, cmd []string) error
  • func (s *DockerSandbox) Exec(ctx context.Context, cmd []string) (*ExecResult, error)
  • func (s *DockerSandbox) ExecInContainer(ctx context.Context, cmd []string, copyIn map[string]string, ...) (*ExecResult, map[string]io.ReadCloser, error)
  • func (s *DockerSandbox) RemoveContainer(ctx context.Context) error
• type ExecResult
• type Mount
• type SandboxConfig
  • func BuildSandboxConfig(profile, image string) SandboxConfig
  • func DefaultSecureSandboxConfig(image string) SandboxConfig
  • func (c SandboxConfig) GetProfile() string
• type SandboxRunner
  • func NewLocalDockerRunner(cfg SandboxConfig) (SandboxRunner, error)

Types

type DockerSandbox

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

DockerSandbox wraps the Docker Engine SDK to execute commands in isolated containers.

func NewDockerSandbox

func NewDockerSandbox(config SandboxConfig) (*DockerSandbox, error)

NewDockerSandbox creates a new DockerSandbox with the given configuration. It initializes a Docker client using environment variables (DOCKER_HOST, etc.).

func (*DockerSandbox) Close

func (s *DockerSandbox) Close() error

Close cleans up the Docker client.

func (*DockerSandbox) CopyIn

func (s *DockerSandbox) CopyIn(ctx context.Context, srcPath, destPath string) error

CopyIn copies a file from the host into the active container. Call CreateContainer first to set the active container ID.

func (*DockerSandbox) CopyOut

func (s *DockerSandbox) CopyOut(ctx context.Context, srcPath string) (io.ReadCloser, error)

CopyOut copies a file out of the active container. Returns a ReadCloser with the file contents. Call CreateContainer first to set the active container ID.

func (*DockerSandbox) CreateContainer

func (s *DockerSandbox) CreateContainer(ctx context.Context, cmd []string) error

CreateContainer creates and starts a container, storing its ID for use with CopyIn/CopyOut. Call RemoveContainer when done to clean up.

func (*DockerSandbox) Exec

func (s *DockerSandbox) Exec(ctx context.Context, cmd []string) (*ExecResult, error)

Exec creates a container, runs the given command, captures output, and removes the container.

func (*DockerSandbox) ExecInContainer

func (s *DockerSandbox) ExecInContainer(ctx context.Context, cmd []string, copyIn map[string]string, copyOutPaths []string) (*ExecResult, map[string]io.ReadCloser, error)

ExecInContainer creates a container, copies files in, runs the command, and allows file extraction. This is the higher-level API that manages the full container lifecycle with file I/O.

func (*DockerSandbox) RemoveContainer

func (s *DockerSandbox) RemoveContainer(ctx context.Context) error

RemoveContainer stops and removes the active container.

type ExecResult

type ExecResult struct {
	ExitCode int
	Stdout   string
	Stderr   string
}

ExecResult holds the output from a command execution inside the sandbox.

type Mount

type Mount struct {
	Source   string `yaml:"source"`
	Target   string `yaml:"target"`
	ReadOnly bool   `yaml:"read_only"`
}

Mount describes a bind mount from host to container.

type SandboxConfig

type SandboxConfig struct {
	// Profile is the security profile name that produced this config ("strict",
	// "standard", "permissive"). It is informational — it does not affect local
	// Docker execution but is forwarded to remote runners so they can apply their
	// own profile clamping (ADR 0019).
	Profile     string            `yaml:"profile,omitempty"`
	Image       string            `yaml:"image"`
	WorkDir     string            `yaml:"work_dir"`
	Env         map[string]string `yaml:"env"`
	Mounts      []Mount           `yaml:"mounts"`
	MemoryLimit int64             `yaml:"memory_limit"`
	CPULimit    float64           `yaml:"cpu_limit"`
	Timeout     time.Duration     `yaml:"timeout"`
	NetworkMode string            `yaml:"network_mode"`

	// Security hardening fields
	SecurityOpts    []string          `yaml:"security_opts"` // e.g., ["seccomp=default.json"]
	CapAdd          []string          `yaml:"cap_add"`       // capabilities to add
	CapDrop         []string          `yaml:"cap_drop"`      // e.g., ["ALL"]
	ReadOnlyRootfs  bool              `yaml:"read_only_rootfs"`
	NoNewPrivileges bool              `yaml:"no_new_privileges"`
	User            string            `yaml:"user"`       // e.g., "nobody:nogroup"
	PidsLimit       int64             `yaml:"pids_limit"` // max process count
	Tmpfs           map[string]string `yaml:"tmpfs"`      // e.g., {"/tmp": "size=64m,noexec"}
}

SandboxConfig holds configuration for a Docker sandbox execution environment.

func BuildSandboxConfig

func BuildSandboxConfig(profile, image string) SandboxConfig

BuildSandboxConfig maps a named security profile and image to a SandboxConfig. This is the single shared profile-→-config mapping used by step.sandbox_exec and reused by remote runner implementations (PR7/8) for their profile clamping.

Profiles:

• "strict" — hardened defaults via DefaultSecureSandboxConfig (no network, drop ALL caps, read-only rootfs).
• "standard" — drops a curated set of dangerous capabilities, bridges network.
• "permissive" — minimal restrictions, bridges network.

Unknown profiles default to "strict" (same behaviour as the step's original switch).

func DefaultSecureSandboxConfig

func DefaultSecureSandboxConfig(image string) SandboxConfig

DefaultSecureSandboxConfig returns a hardened SandboxConfig suitable for running untrusted workloads. It uses a minimal Wolfi-based image, drops all Linux capabilities, enables a read-only root filesystem, mounts /tmp as tmpfs with noexec, and disables network access.

func (SandboxConfig) GetProfile

func (c SandboxConfig) GetProfile() string

GetProfile returns the profile name stored in the config, falling back to "strict" (the safest default) when the field is empty.

type SandboxRunner

type SandboxRunner interface {
	// Exec runs cmd inside the sandbox and returns the combined result.
	Exec(ctx context.Context, cmd []string) (*ExecResult, error)
	// Close releases any resources held by the runner (e.g. Docker client).
	Close() error
}

SandboxRunner is the interface consumed by step.sandbox_exec. Only Exec and Close are required — all other DockerSandbox methods are lifecycle helpers not used by the step's Execute path.

func NewLocalDockerRunner

func NewLocalDockerRunner(cfg SandboxConfig) (SandboxRunner, error)

NewLocalDockerRunner creates a SandboxRunner backed by a local Docker daemon. It is the default runner used when exec_env is absent or set to "local-docker".