sandbox

Documentation

Index

• Constants
• func EnsureImage(ctx context.Context, dockerfilePath string) error
• type Sandbox
  • func New(packageDir, pkg string, needsPtrace bool, ecosystem, containerRuntime string) *Sandbox
  • func (s *Sandbox) Cleanup(ctx context.Context) error
  • func (s *Sandbox) ContainerID() string
  • func (s *Sandbox) Create(ctx context.Context) error
  • func (s *Sandbox) Exec(ctx context.Context, command []string) ([]byte, error)
  • func (s *Sandbox) ImportCommands() [][]string
  • func (s *Sandbox) ImportCommandsMulti(pkgs []string) [][]string
  • func (s *Sandbox) InstallAllCommand(pkgs []string) []string
  • func (s *Sandbox) InstallCommand() []string
  • func (s *Sandbox) InstallPackage(ctx context.Context) ([]byte, error)
  • func (s *Sandbox) Logs(ctx context.Context) (string, error)
  • func (s *Sandbox) PID(ctx context.Context) (uint32, error)
  • func (s *Sandbox) Pause(ctx context.Context) error
  • func (s *Sandbox) SetLocalMode(local bool)
  • func (s *Sandbox) Start(ctx context.Context) error
  • func (s *Sandbox) StartPaused(ctx context.Context) error
  • func (s *Sandbox) Unpause(ctx context.Context) error
  • func (s *Sandbox) WriteProbeScripts(ctx context.Context)
  • func (s *Sandbox) WriteProbeScriptsMulti(ctx context.Context, pkgs []string)

Constants

const (
	RuntimeDefault = ""      // Docker default (runc).
	RuntimeGVisor  = "runsc" // gVisor user-space kernel.

)

Runtime selects the container runtime.

const SandboxImage = "kojuto-sandbox:latest"

SandboxImage is the Docker image used for the sandbox container.

const SandboxPythonVersion = "3.12"

SandboxPythonVersion must match the Python version in Dockerfile.sandbox.

Functions

func EnsureImage

func EnsureImage(ctx context.Context, dockerfilePath string) error

EnsureImage checks if the sandbox image exists, builds it if not.

Types

type Sandbox

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

Sandbox manages a Docker container for isolated package installation.

func New

func New(packageDir, pkg string, needsPtrace bool, ecosystem, containerRuntime string) *Sandbox

New creates a new Sandbox instance.

func (*Sandbox) Cleanup

func (s *Sandbox) Cleanup(ctx context.Context) error

Cleanup stops and removes the container, and cleans up temporary files.

func (*Sandbox) ContainerID

func (s *Sandbox) ContainerID() string

ContainerID returns the container ID.

func (*Sandbox) Create

func (s *Sandbox) Create(ctx context.Context) error

Create creates the sandbox container without starting it. The container is configured with an isolated network, --no-new-privileges, and --read-only. Writable tmpfs mounts are provided only where needed. The host filesystem is protected by Docker's copy-on-write isolation. When SYS_PTRACE is needed, a restrictive seccomp profile is applied.

func (*Sandbox) Exec

func (s *Sandbox) Exec(ctx context.Context, command []string) ([]byte, error)

Exec runs a command inside the sandbox container and returns the combined output.

func (*Sandbox) ImportCommands

func (s *Sandbox) ImportCommands() [][]string

ImportCommands returns commands to import/require the installed package under multiple simulated OS identities. This defeats OS-gated payloads that only activate on specific platforms (e.g. "if Windows: attack()").

For Python: patches platform.system(), sys.platform, os.name before import. For Node.js: overrides process.platform before require().

Each command simulates a different target OS so that platform-conditional code paths are exercised regardless of the container's actual OS.

func (*Sandbox) ImportCommandsMulti

func (s *Sandbox) ImportCommandsMulti(pkgs []string) [][]string

ImportCommandsMulti returns 3 import commands (one per OS identity) that import all packages.

func (*Sandbox) InstallAllCommand

func (s *Sandbox) InstallAllCommand(pkgs []string) []string

InstallAllCommand returns a pip install command that installs multiple packages at once. All wheels must already be in the mount point directory.

func (*Sandbox) InstallCommand

func (s *Sandbox) InstallCommand() []string

InstallCommand returns the install command for the ecosystem.

func (*Sandbox) InstallPackage

func (s *Sandbox) InstallPackage(ctx context.Context) ([]byte, error)

InstallPackage runs the install command inside the sandbox.

func (*Sandbox) Logs

func (s *Sandbox) Logs(ctx context.Context) (string, error)

Logs returns the container logs.

func (*Sandbox) PID

func (s *Sandbox) PID(ctx context.Context) (uint32, error)

PID returns the init PID of the sandbox container on the host.

func (*Sandbox) Pause

func (s *Sandbox) Pause(ctx context.Context) error

Pause freezes all processes in the container.

func (*Sandbox) SetLocalMode

func (s *Sandbox) SetLocalMode(local bool)

SetLocalMode enables local package installation mode (sdist support).

func (*Sandbox) Start

func (s *Sandbox) Start(ctx context.Context) error

Start creates and starts the sandbox container (convenience for strace-container mode which does not need the pause-before-probe pattern).

func (*Sandbox) StartPaused

func (s *Sandbox) StartPaused(ctx context.Context) error

StartPaused starts the container and immediately pauses it. This minimizes the TOCTOU window between container start and probe attachment.

func (*Sandbox) Unpause

func (s *Sandbox) Unpause(ctx context.Context) error

Unpause resumes all processes in the container.

func (*Sandbox) WriteProbeScripts

func (s *Sandbox) WriteProbeScripts(ctx context.Context)

WriteProbeScripts writes the OS-simulation import scripts into the container's /tmp directory. Must be called before ImportCommands.

func (*Sandbox) WriteProbeScriptsMulti

func (s *Sandbox) WriteProbeScriptsMulti(ctx context.Context, pkgs []string)

WriteProbeScriptsMulti writes one combined import probe script per OS identity. This reduces Python/Node process launches from N*3 to just 3.