Documentation
¶
Index ¶
Constants ¶
const MechanismSandboxUser = "sandbox-user"
MechanismSandboxUser is the capability mechanism of commands run as a dedicated sandbox account.
Variables ¶
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
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). Paths that do not exist yet are listed too; Seatbelt keeps 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
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.
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.
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 (*Policy) ExplainFailure ¶ added in v0.107.21
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.
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.