sandbox

package
v0.107.38 Latest Latest
Warning

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

Go to latest
Published: Nov 19, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const MechanismSandboxUser = "sandbox-user"

MechanismSandboxUser is the capability mechanism of commands run as a dedicated sandbox account.

Variables

View Source
var (
	// ErrSetupUnsupported is returned by Setup and Uninstall off Windows.
	ErrSetupUnsupported = errors.New("sandbox setup is only available on Windows")
	// ErrSetupDeclined is returned when the administrator approval prompt was
	// declined or dismissed.
	ErrSetupDeclined = errors.New("administrator approval was declined; nothing was changed")
)

Functions

func MaskedDirs added in v0.107.16

func MaskedDirs() []string

MaskedDirs are the credential directories hidden from sandboxed commands.

func ProtectedPaths added in v0.107.16

func ProtectedPaths(root string) []string

ProtectedPaths are the paths under a workspace that a later, unsandboxed session or the user's own git trusts without asking: project instructions and prompts, and the repository's hooks and configuration (which can name a hooks directory, an fsmonitor or a pager to run), together with the files that tell git where to read those from (commondir, gitdir files) or which configured drivers to run (info/attributes). Paths that do not exist yet are listed too; Seatbelt and the Landlock supervisor keep them from being created.

func Reprobe added in v0.107.22

func Reprobe()

Reprobe forgets the probed capability, so the next Probe checks again (after the sandbox setup changed).

func RootFromEnv

func RootFromEnv() string

func WithPolicy

func WithPolicy(ctx context.Context, policy *Policy) context.Context

Types

type Capability added in v0.107.16

type Capability struct {
	Supported      bool   `json:"supported"`
	Mechanism      string `json:"mechanism"`
	Platform       string `json:"platform"`
	NetworkControl bool   `json:"network_control"`
	ReadMasking    bool   `json:"read_masking"`
	// PathProtection reports whether the protected workspace paths (git hooks
	// and config, agent settings) stay read-only inside a writable root.
	PathProtection bool   `json:"path_protection"`
	Reason         string `json:"reason,omitempty"`
	// SetupAvailable is true where an elevated setup can be run (`kn sandbox
	// setup`, Windows only) and SetupHint tells a client what it changes; the
	// hint is empty once the setup is active and healthy.
	SetupAvailable bool   `json:"setup_available"`
	SetupHint      string `json:"setup_hint"`
}

Capability reports whether this machine can confine a run's commands.

func Probe added in v0.107.16

func Probe() Capability

Probe checks the platform mechanism once per process by running a trivial confined command, so a binary that exists but cannot start (no user namespaces in a container) reports unsupported instead of failing later.

func ProbeWithin added in v0.107.28

func ProbeWithin(d time.Duration) (c Capability, ok bool)

ProbeWithin is Probe for request paths that must answer: it waits at most d for a probe still in flight and reports ok=false instead of waiting longer.

type Denial added in v0.107.21

type Denial struct {
	// Kind is "write" (a write outside the writable roots), "protected" (a
	// protected or configured read-only path), "masked" (a hidden credential
	// directory) or "network" (network access is off for the run).
	Kind string `json:"kind"`
	// Path is the path the denial names, when there is one.
	Path string `json:"path,omitempty"`
	// SuggestedRoot is a directory the user could add as a writable workspace
	// root so the command can write Path. It is set only for a write the
	// command itself named (its text contains the path), so output a command
	// prints cannot steer the proposal, and never for a directory that holds
	// the home directory, a credential directory or a system top-level
	// directory.
	SuggestedRoot string `json:"suggested_root,omitempty"`
}

Denial explains why a sandboxed command most likely failed. It is a hint for the model and the client, recognized from the command's output; nothing is granted from it.

func (*Denial) Hint added in v0.107.21

func (d *Denial) Hint() string

Hint is the note added to the tool result the model reads.

type Policy

type Policy struct {
	Mode     string
	Backend  string
	Root     string
	Network  bool
	Writable []string
	ReadOnly []string
	// Masked directories are neither readable nor writable inside the sandbox
	// (credentials, the backend's own data). A workspace root inside one of them
	// stays usable; a root that encloses one is refused.
	Masked []string
	// Protected paths stay readable but not writable, even inside a writable
	// root: project instructions and hooks that a later, unsandboxed session
	// would trust.
	Protected []string
	// EnvKeep lists variable names (globs allowed) a sandboxed command still
	// inherits although they look like credentials (FilterEnv).
	EnvKeep []string
}

func ForRun added in v0.107.16

func ForRun(base *Policy, req RunRequest) (*Policy, error)

ForRun builds the policy for a run that asked for the workspace sandbox. A configured policy (base) is only ever tightened: its roots stay as they are, network stays off when either side turns it off, and the masks and protected paths are added. Without a configured policy the run's roots are the grants. The result fails closed: when the machine cannot confine commands an error is returned instead of a policy.

func FromContext

func FromContext(ctx context.Context) *Policy

func New

func New(mode, backend, root string, network bool, writable, readOnly []string) *Policy

func (*Policy) Enabled

func (p *Policy) Enabled() bool

func (*Policy) ExplainFailure added in v0.107.21

func (p *Policy) ExplainFailure(command, dir, output string, exitCode *int) *Denial

ExplainFailure recognizes a sandbox denial in the output of a command that exited with exitCode under p. It returns nil when the command succeeded, could not be found, or failed for a reason the sandbox does not explain, such as a permission error inside a writable root.

func (*Policy) FilterEnv added in v0.107.21

func (p *Policy) FilterEnv(env []string) []string

FilterEnv returns env without the variables a sandboxed command must not inherit, unless their names match p.EnvKeep. env is returned as is when the policy is off.

func (*Policy) ForRoot

func (p *Policy) ForRoot(root string) *Policy

func (*Policy) Wrap

func (p *Policy) Wrap(ctx context.Context, cmd *exec.Cmd) (*exec.Cmd, error)

Wrap returns cmd confined by the policy. It fails rather than run the command unconfined when the platform mechanism is missing or the root is unsafe.

type RunRequest added in v0.107.16

type RunRequest struct {
	Root string
	// Writable lists the run's other writable workspace roots.
	Writable []string
	Network  bool
	// Masked and Protected extend the defaults (MaskedDirs, ProtectedPaths).
	Masked    []string
	Protected []string
	// EnvKeep extends the policy's EnvKeep.
	EnvKeep []string
}

RunRequest is a run's request to confine its commands to the workspace.

type SetupStatus added in v0.107.22

type SetupStatus struct {
	Platform string `json:"platform"`
	// Available is true where the setup can be run (Windows).
	Available bool `json:"available"`
	// Installed is true when the setup's state exists for this user.
	Installed bool `json:"installed"`
	// Active is true when commands run as the sandbox accounts.
	Active    bool   `json:"active"`
	Mechanism string `json:"mechanism"`
	// NetworkControl is true when offline runs are blocked from the network.
	NetworkControl bool     `json:"network_control"`
	Accounts       []string `json:"accounts,omitempty"`
	Groups         []string `json:"groups,omitempty"`
	StatePath      string   `json:"state_path,omitempty"`
	Problem        string   `json:"problem,omitempty"`
	Hint           string   `json:"hint,omitempty"`
}

SetupStatus describes the sandbox-user setup of the current user.

func Setup added in v0.107.22

func Setup(ctx context.Context) (SetupStatus, error)

Setup creates or repairs the sandbox-user setup of the current user. It asks for administrator approval (UAC) unless the process is already elevated, and never elevates without asking. The sandbox capability is probed again afterwards.

func SetupStatusNow added in v0.107.22

func SetupStatusNow() SetupStatus

SetupStatusNow reports the current user's setup without changing anything.

func Uninstall added in v0.107.22

func Uninstall(ctx context.Context) (SetupStatus, error)

Uninstall removes the current user's sandbox accounts, groups, filters, stored password and the access entries the sandbox added. It is idempotent.

Jump to

Keyboard shortcuts

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