sandbox

package
v1.3.103 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ContextWithGitAccess

func ContextWithGitAccess(ctx context.Context, allowed bool) context.Context

func FormatSandboxInfo

func FormatSandboxInfo(s Sandbox) string

FormatSandboxInfo returns a human-readable description of the sandbox state.

func GitAccessFromContext

func GitAccessFromContext(ctx context.Context) bool

func GitAccessRequired

func GitAccessRequired(command, workDir string) bool

GitAccessRequired conservatively identifies commands that may access Git metadata. It is only an approval hint; the sandbox deny rule remains the actual enforcement boundary.

func IsGitDeniedPath

func IsGitDeniedPath(path string) bool

Types

type AvailabilityErrorProvider

type AvailabilityErrorProvider interface {
	AvailabilityError() error
}

type BwrapCapabilities

type BwrapCapabilities struct {
	UnshareUser   bool
	UnsharePID    bool
	UnshareIPC    bool
	UnshareUTS    bool
	NewSession    bool
	DieWithParent bool
	MountProc     bool
	MountDev      bool
	MountTmpfs    bool
	TmpfsSize     bool
	MountBind     bool
	ChangeDir     bool
	Hostname      bool
}

BwrapCapabilities describes the flags and runtime features required by MothX.

type BwrapSandbox

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

BwrapSandbox implements sandbox using bubblewrap (bwrap).

func NewBwrapSandbox

func NewBwrapSandbox(projectDir string, level Level) *BwrapSandbox

NewBwrapSandbox creates a new bubblewrap sandbox.

func NewBwrapSandboxWithOptions

func NewBwrapSandboxWithOptions(projectDir string, level Level, opts Options) *BwrapSandbox

NewBwrapSandboxWithOptions creates a bubblewrap sandbox with a policy.

func (*BwrapSandbox) AvailabilityError

func (s *BwrapSandbox) AvailabilityError() error

AvailabilityError explains why bwrap could not be used.

func (*BwrapSandbox) IsAvailable

func (s *BwrapSandbox) IsAvailable() bool

IsAvailable checks if bwrap is available on this system.

func (*BwrapSandbox) Level

func (s *BwrapSandbox) Level() Level

Level returns the sandbox level.

func (*BwrapSandbox) Name

func (s *BwrapSandbox) Name() string

Name returns "bwrap".

func (*BwrapSandbox) WrapCommand

func (s *BwrapSandbox) WrapCommand(ctx context.Context, shell, cmd string, opts ExecOpts) *exec.Cmd

WrapCommand wraps a command for execution inside bubblewrap.

func (*BwrapSandbox) WrapCommandWithGitAccess

func (s *BwrapSandbox) WrapCommandWithGitAccess(ctx context.Context, shell, cmd string, opts ExecOpts) *exec.Cmd

WrapCommandWithGitAccess runs one command with the protected .git deny carveout removed. The sandbox instance itself is immutable; only this prepared command receives the temporary transform.

type CommandCleanupProvider

type CommandCleanupProvider interface {
	CleanupCommand(*exec.Cmd)
}

type ExecOpts

type ExecOpts struct {
	WritablePaths []string          // Additional writable paths
	ReadOnlyPaths []string          // Additional read-only paths (for standard mode)
	NetworkAccess bool              // Deprecated: sandbox preserves host network access
	EnvVars       map[string]string // Additional environment variables
	WorkDir       string            // Working directory
	Timeout       time.Duration     // Command timeout
}

ExecOpts contains options for executing a command in a sandbox.

type GitAccessSandbox

type GitAccessSandbox interface {
	WrapCommandWithGitAccess(ctx context.Context, shell, cmd string, opts ExecOpts) *exec.Cmd
}

GitAccessSandbox is implemented by backends that can temporarily remove the protected Git deny rule for exactly one command.

type Level

type Level int

Level defines the sandbox restriction level.

const (
	LevelStrict   Level = iota // Required sandbox: read-only project
	LevelStandard              // Best-effort sandbox: read-write project
	LevelNone                  // Direct execution
)

func ParseLevel

func ParseLevel(s string) (Level, error)

ParseLevel parses a string into a Level.

func (Level) String

func (l Level) String() string

String returns the string representation of a Level.

type Manager

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

Manager manages sandbox selection based on mode and availability.

func NewManager

func NewManager(projectDir string) *Manager

NewManager creates a manager with the default sandbox policy.

func NewManagerWithOptions

func NewManagerWithOptions(projectDir string, opts Options) *Manager

NewManagerWithOptions creates a manager using the supplied sandbox policy.

func (*Manager) FallbackError

func (m *Manager) FallbackError() error

FallbackError reports why a best-effort sandbox fell back to direct execution.

func (*Manager) GetActive

func (m *Manager) GetActive() Sandbox

GetActive returns the active sandbox.

func (*Manager) GetForLevel

func (m *Manager) GetForLevel(level Level) (Sandbox, error)

GetForLevel returns the sandbox for a specific level, checking availability.

func (*Manager) SetLevel

func (m *Manager) SetLevel(level Level) error

SetLevel activates the requested execution policy. Standard sandboxing is best-effort and falls back to direct execution when the platform backend is unavailable. Strict sandboxing is required and never silently degrades.

type NoneSandbox

type NoneSandbox struct{}

NoneSandbox executes commands without any sandbox restrictions.

func NewNoneSandbox

func NewNoneSandbox() *NoneSandbox

NewNoneSandbox creates a new no-op sandbox.

func (*NoneSandbox) IsAvailable

func (s *NoneSandbox) IsAvailable() bool

IsAvailable always returns true.

func (*NoneSandbox) Level

func (s *NoneSandbox) Level() Level

Level returns LevelNone.

func (*NoneSandbox) Name

func (s *NoneSandbox) Name() string

Name returns "none".

func (*NoneSandbox) WrapCommand

func (s *NoneSandbox) WrapCommand(ctx context.Context, shell, cmd string, opts ExecOpts) *exec.Cmd

WrapCommand returns a plain command without any sandbox restrictions. It inherits the full parent environment and overlays opts.EnvVars on top.

type Options

type Options struct {
	BwrapPath    string
	AllowNetwork bool // Deprecated: sandbox always preserves host network access
	AllowedRead  []string
	AllowedWrite []string
	DeniedPaths  []string
	PassEnv      []string
	TmpSize      string
	ProtectGit   bool
}

Options controls sandbox backends. It deliberately uses primitive values so callers from every runtime can share the same policy without importing config.

func NormalizeOptions

func NormalizeOptions(projectDir string, opts Options) (Options, error)

NormalizeOptions resolves sandbox path rules against projectDir and rejects ambiguous allow/deny overlaps before a backend constructs any mounts.

type Sandbox

type Sandbox interface {
	// WrapCommand wraps a command for execution inside the sandbox.
	WrapCommand(ctx context.Context, shell, cmd string, opts ExecOpts) *exec.Cmd

	// IsAvailable checks if the sandbox can be used on this system.
	IsAvailable() bool

	// Name returns the sandbox implementation name.
	Name() string

	// Level returns the sandbox level.
	Level() Level
}

Sandbox is the interface for sandbox implementations.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL