Documentation
¶
Overview ¶
Package sandbox provides platform-aware sandboxed command execution.
On Linux, it uses bubblewrap (bwrap) for namespace isolation. On macOS, it uses seatbelt (sandbox-exec) for kernel-level sandboxing. Both provide: deny-default filesystem access, explicit mount/path allowlists, network access, per-execution env vars, and timeout enforcement.
Use New(Options) to get the appropriate sandbox for the current platform. ExecConfig carries per-execution env vars and mounts, and is threaded through context via ContextWithExecConfig / ExecConfigFromContext so tools can access it without explicit parameter threading.
Plane: shared
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ContextWithExecConfig ¶
func ContextWithExecConfig(ctx context.Context, cfg *ExecConfig) context.Context
ContextWithExecConfig stores an ExecConfig in the context.
Types ¶
type BwrapSandbox ¶ added in v1.1.0
BwrapSandbox executes commands using bubblewrap (bwrap) namespace isolation. Used on Linux.
func (*BwrapSandbox) Exec ¶ added in v1.1.0
func (s *BwrapSandbox) Exec( ctx context.Context, command string, cfg *ExecConfig, ) (stdout, stderr string, exitCode int, err error)
Exec runs a bash command inside the bubblewrap sandbox.
func (*BwrapSandbox) IsAvailable ¶ added in v1.1.0
func (s *BwrapSandbox) IsAvailable() bool
IsAvailable checks whether bwrap is available at the configured path.
type ExecConfig ¶
type ExecConfig struct {
Env []string // Extra env vars passed to the sandboxed process
MountDirs []Mount // Additional read-only bind mounts
}
ExecConfig holds per-execution sandbox settings.
func ExecConfigFromContext ¶
func ExecConfigFromContext(ctx context.Context) *ExecConfig
ExecConfigFromContext retrieves the ExecConfig from the context. Returns nil if not set.
type NoopSandbox ¶ added in v1.1.0
NoopSandbox runs commands directly without any sandbox isolation. Intended for local development when no platform sandbox is available and AllowUnsandboxed is true.
func (*NoopSandbox) Exec ¶ added in v1.1.0
func (n *NoopSandbox) Exec( ctx context.Context, command string, cfg *ExecConfig, ) (stdout, stderr string, exitCode int, err error)
Exec runs a bash command directly on the host, without sandboxing.
func (*NoopSandbox) IsAvailable ¶ added in v1.1.0
func (n *NoopSandbox) IsAvailable() bool
IsAvailable always returns true — no external binary required.
type Options ¶ added in v1.1.0
type Options struct {
BwrapPath string // Linux only; defaults to "bwrap"
Timeout time.Duration
AllowUnsandboxed bool // if true, fall back to NoopSandbox when no platform sandbox is found
}
Options configures the sandbox constructor.
type Sandbox ¶
type Sandbox interface {
Exec(ctx context.Context, command string, cfg *ExecConfig) (stdout, stderr string, exitCode int, err error)
IsAvailable() bool
}
Sandbox executes commands in an isolated environment.
func New ¶ added in v1.1.0
New creates the appropriate sandbox for the current platform. On macOS, it returns a SeatbeltSandbox if sandbox-exec is available. On Linux, it returns a BwrapSandbox if bwrap is available. Falls back to NoopSandbox when AllowUnsandboxed is true and no platform sandbox is found. Returns UnavailableSandbox when AllowUnsandboxed is false and no platform sandbox is found.
type SeatbeltSandbox ¶ added in v1.1.0
SeatbeltSandbox executes commands using macOS seatbelt (sandbox-exec). Used on macOS for kernel-level sandboxing with deny-default filesystem policy.
func (*SeatbeltSandbox) Exec ¶ added in v1.1.0
func (s *SeatbeltSandbox) Exec( ctx context.Context, command string, cfg *ExecConfig, ) (stdout, stderr string, exitCode int, err error)
Exec runs a bash command inside the seatbelt sandbox.
func (*SeatbeltSandbox) IsAvailable ¶ added in v1.1.0
func (s *SeatbeltSandbox) IsAvailable() bool
IsAvailable checks whether sandbox-exec is present on the system.
type UnavailableSandbox ¶ added in v1.1.0
type UnavailableSandbox struct {
}
UnavailableSandbox always returns an error from Exec. Used when no platform sandbox is available and AllowUnsandboxed is false.
func (*UnavailableSandbox) Exec ¶ added in v1.1.0
func (u *UnavailableSandbox) Exec(_ context.Context, _ string, _ *ExecConfig) (string, string, int, error)
Exec always returns an error explaining what sandbox is needed.
func (*UnavailableSandbox) IsAvailable ¶ added in v1.1.0
func (u *UnavailableSandbox) IsAvailable() bool
IsAvailable always returns false.
Source Files