isolation

Documentation

Index

• type FallbackIsolator
  • func NewFallbackIsolator() *FallbackIsolator
  • func (f *FallbackIsolator) Capabilities() IsolatorCaps
  • func (f *FallbackIsolator) Wrap(ctx context.Context, cmd *exec.Cmd, limits ResourceLimits) (*exec.Cmd, func(), error)
• type Isolator
  • func NewIsolator() (Isolator, error)
• type IsolatorCaps
• type LinuxIsolator
  • func NewLinuxIsolator() (*LinuxIsolator, error)
  • func (l *LinuxIsolator) Capabilities() IsolatorCaps
  • func (l *LinuxIsolator) Wrap(ctx context.Context, cmd *exec.Cmd, limits ResourceLimits) (*exec.Cmd, func(), error)
• type PathAccessMode
• type ResourceLimits
  • func (r ResourceLimits) ValidatePath(path string, mode PathAccessMode) error

Types

type FallbackIsolator

type FallbackIsolator struct{}

FallbackIsolator provides minimal process isolation using os/exec + timeout. Used on platforms where kernel-level isolation is unavailable. Only timeout enforcement is provided; all capabilities report false.

func NewFallbackIsolator

func NewFallbackIsolator() *FallbackIsolator

NewFallbackIsolator creates a FallbackIsolator.

func (*FallbackIsolator) Capabilities

func (f *FallbackIsolator) Capabilities() IsolatorCaps

Capabilities returns all-false caps (FallbackIsolator only enforces timeout).

func (*FallbackIsolator) Wrap

func (f *FallbackIsolator) Wrap(ctx context.Context, cmd *exec.Cmd, limits ResourceLimits) (*exec.Cmd, func(), error)

Wrap clones the command onto a context-aware exec.Cmd with timeout enforcement. The returned cleanup function must always be called after process completion. The caller must use the returned *exec.Cmd, not the original.

type Isolator

type Isolator interface {
	// Wrap returns an isolated *exec.Cmd and a cleanup function.
	// The cleanup function MUST be called after the command completes (or fails to start).
	// It is safe to defer cleanup() immediately after Wrap() returns. Cleanup is idempotent.
	// The caller must use the returned *exec.Cmd, not the original.
	Wrap(ctx context.Context, cmd *exec.Cmd, limits ResourceLimits) (*exec.Cmd, func(), error)
	Capabilities() IsolatorCaps
}

Isolator wraps a command with platform-specific process isolation. Implementations are auto-detected at startup: Linux → Cgroups v2, Fallback → os/exec + timeout.

func NewIsolator

func NewIsolator() (Isolator, error)

NewIsolator returns the platform-appropriate Isolator. On Linux, attempts LinuxIsolator (cgroups v2). Falls back to FallbackIsolator if cgroups v2 is unavailable.

type IsolatorCaps

type IsolatorCaps struct {
	CanLimitMemory  bool `json:"can_limit_memory"`
	CanLimitCPU     bool `json:"can_limit_cpu"`
	CanLimitNetwork bool `json:"can_limit_network"`
	CanIsolateFS    bool `json:"can_isolate_fs"`
	CanIsolatePID   bool `json:"can_isolate_pid"`
}

IsolatorCaps describes what a platform's isolator can enforce.

type LinuxIsolator

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

LinuxIsolator provides kernel-level process isolation using cgroups v2 and Linux namespaces (PID, network).

func NewLinuxIsolator

func NewLinuxIsolator() (*LinuxIsolator, error)

NewLinuxIsolator creates a LinuxIsolator backed by cgroups v2. Returns error if cgroups v2 is not available.

func (*LinuxIsolator) Capabilities

func (l *LinuxIsolator) Capabilities() IsolatorCaps

Capabilities returns the detected isolation capabilities.

func (*LinuxIsolator) Wrap

func (l *LinuxIsolator) Wrap(ctx context.Context, cmd *exec.Cmd, limits ResourceLimits) (*exec.Cmd, func(), error)

Wrap creates an isolated execution environment for cmd using cgroups v2 and namespaces. The returned cleanup function must always be called after process completion. The caller must use the returned *exec.Cmd, not the original.

type PathAccessMode

type PathAccessMode int

PathAccessMode indicates the type of filesystem access being requested.

const (
	PathAccessRead PathAccessMode = iota
	PathAccessWrite
)

type ResourceLimits

type ResourceLimits struct {
	MaxMemoryBytes int64         `json:"max_memory_bytes,omitempty"`
	MaxCPUPercent  int           `json:"max_cpu_percent,omitempty"`
	MaxDiskIOBPS   int64         `json:"max_disk_io_bps,omitempty"`
	Timeout        time.Duration `json:"timeout,omitempty"`
	AllowNetwork   bool          `json:"allow_network"`
	ReadOnlyPaths  []string      `json:"read_only_paths,omitempty"`
	WritablePaths  []string      `json:"writable_paths,omitempty"`
	DenyPaths      []string      `json:"deny_paths,omitempty"`
}

ResourceLimits specifies constraints for isolated process execution.

func (ResourceLimits) ValidatePath

func (r ResourceLimits) ValidatePath(path string, mode PathAccessMode) error

ValidatePath checks whether the given path is permitted under these limits. Empty path lists mean unrestricted access (permissive default for dev/fallback). DenyPaths always takes precedence over allow lists. Note: this is a best-effort check subject to TOCTOU races; kernel-level isolation (namespaces/chroot in LinuxIsolator) provides the hard guarantee.