sandbox

Documentation

Index

• Variables
• type DomainAllowList
  • func NewDomainAllowList(allowed ...string) *DomainAllowList
  • func (p *DomainAllowList) Allow(host string)
  • func (p *DomainAllowList) Allowed() []string
  • func (p *DomainAllowList) Validate(host string) error
• type FileSystemAllowList
  • func NewFileSystemAllowList(root string, allow ...string) *FileSystemAllowList
  • func (p *FileSystemAllowList) Allow(path string)
  • func (p *FileSystemAllowList) Roots() []string
  • func (p *FileSystemAllowList) Validate(path string) error
• type FileSystemPolicy
• type Manager
  • func NewManager(fs FileSystemPolicy, nw NetworkPolicy, rp ResourcePolicy) *Manager
  • func (m *Manager) CheckNetwork(host string) error
  • func (m *Manager) CheckPath(path string) error
  • func (m *Manager) CheckToolPermission(tool string, params map[string]any) (security.PermissionDecision, error)
  • func (m *Manager) CheckUsage(usage ResourceUsage) error
  • func (m *Manager) Enforce(path string, host string, usage ResourceUsage) error
  • func (m *Manager) Limits() ResourceLimits
  • func (m *Manager) PermissionAudits() []security.PermissionAudit
• type NetworkPolicy
• type ResourceLimiter
  • func NewResourceLimiter(limits ResourceLimits) *ResourceLimiter
  • func (r *ResourceLimiter) Limits() ResourceLimits
  • func (r *ResourceLimiter) Validate(usage ResourceUsage) error
• type ResourceLimits
• type ResourcePolicy
• type ResourceUsage

Variables

var (
	// ErrPathDenied indicates the path escapes the configured filesystem allowlist.
	ErrPathDenied = errors.New("sandbox: path denied")
	// ErrSymlinkDetected is returned when validation encounters a symlink hop.
	ErrSymlinkDetected = errors.New("sandbox: symlink detected")
	// ErrDomainDenied indicates outbound traffic targets a host outside the allowlist.
	ErrDomainDenied = errors.New("sandbox: domain denied")
	// ErrResourceExceeded signals a resource budget violation.
	ErrResourceExceeded = errors.New("sandbox: resource limit exceeded")
)

Types

type DomainAllowList

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

DomainAllowList guards outbound hosts against a normalized white-list.

func NewDomainAllowList

func NewDomainAllowList(allowed ...string) *DomainAllowList

NewDomainAllowList creates an allowlist seeded with hosts.

func (*DomainAllowList) Allow

func (p *DomainAllowList) Allow(host string)

Allow permits traffic towards host (exact or suffix match).

func (*DomainAllowList) Allowed

func (p *DomainAllowList) Allowed() []string

Allowed returns the normalised domains kept by the policy.

func (*DomainAllowList) Validate

func (p *DomainAllowList) Validate(host string) error

Validate ensures host belongs to the allowlist.

type FileSystemAllowList

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

FileSystemAllowList enforces path boundaries using PathResolver to block traversal and symlinks.

func NewFileSystemAllowList

func NewFileSystemAllowList(root string, allow ...string) *FileSystemAllowList

NewFileSystemAllowList initialises a policy rooted at root with optional extra allowed prefixes.

func (*FileSystemAllowList) Allow

func (p *FileSystemAllowList) Allow(path string)

Allow registers an additional allowed absolute path prefix.

func (*FileSystemAllowList) Roots

func (p *FileSystemAllowList) Roots() []string

Roots returns a copy of the allowlist.

func (*FileSystemAllowList) Validate

func (p *FileSystemAllowList) Validate(path string) error

Validate ensures the provided path resolves inside the allowlist without crossing symlinks.

type FileSystemPolicy

type FileSystemPolicy interface {
	Allow(path string)
	Validate(path string) error
	Roots() []string
}

FileSystemPolicy guards filesystem access.

type Manager

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

Manager bundles fs/net/resource policies for callers that only need a single entrypoint.

func NewManager

func NewManager(fs FileSystemPolicy, nw NetworkPolicy, rp ResourcePolicy) *Manager

NewManager wires a sandbox manager using the provided policies.

func (*Manager) CheckNetwork

func (m *Manager) CheckNetwork(host string) error

CheckNetwork validates an outbound hostname.

func (*Manager) CheckPath

func (m *Manager) CheckPath(path string) error

CheckPath validates filesystem access against the configured policy.

func (*Manager) CheckToolPermission

func (m *Manager) CheckToolPermission(tool string, params map[string]any) (security.PermissionDecision, error)

CheckToolPermission consults the permission matcher when configured. Missing rules default to allow.

func (*Manager) CheckUsage

func (m *Manager) CheckUsage(usage ResourceUsage) error

CheckUsage validates resource consumption.

func (*Manager) Enforce

func (m *Manager) Enforce(path string, host string, usage ResourceUsage) error

Enforce executes every configured guard in order.

func (*Manager) Limits

func (m *Manager) Limits() ResourceLimits

Limits reports the resource ceilings when configured.

func (*Manager) PermissionAudits

func (m *Manager) PermissionAudits() []security.PermissionAudit

PermissionAudits returns a snapshot of the latest audited permission decisions.

type NetworkPolicy

type NetworkPolicy interface {
	Allow(domain string)
	Validate(host string) error
	Allowed() []string
}

NetworkPolicy guards outbound connections.

type ResourceLimiter

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

ResourceLimiter is a minimal implementation of ResourcePolicy.

func NewResourceLimiter

func NewResourceLimiter(limits ResourceLimits) *ResourceLimiter

NewResourceLimiter builds a limiter with the provided ceilings.

func (*ResourceLimiter) Limits

func (r *ResourceLimiter) Limits() ResourceLimits

Limits reports the configured ceilings.

func (*ResourceLimiter) Validate

func (r *ResourceLimiter) Validate(usage ResourceUsage) error

Validate checks the supplied usage against configured ceilings.

type ResourceLimits

type ResourceLimits struct {
	MaxCPUPercent  float64
	MaxMemoryBytes uint64
	MaxDiskBytes   uint64
}

ResourceLimits constrains runtime consumption.

type ResourcePolicy

type ResourcePolicy interface {
	Limits() ResourceLimits
	Validate(usage ResourceUsage) error
}

ResourcePolicy enforces resource ceilings.

type ResourceUsage

type ResourceUsage struct {
	CPUPercent  float64
	MemoryBytes uint64
	DiskBytes   uint64
}

ResourceUsage captures measured resource consumption.