sandbox

type BwrapPolicy string

type Capability struct {
	// Backend is one of the Backend* constants.
	Backend string `json:"backend"`
	// Version is backend specific, e.g. the Landlock ABI ("5") or the bwrap
	// version. Empty when unknown.
	Version string `json:"version,omitempty"`
	// Enforced is true only when Wrap really confines commands.
	Enforced bool `json:"enforced"`
	// Reason explains a degraded or unavailable backend, for the UI and logs.
	Reason string `json:"reason,omitempty"`
	// ProtectsNestedPaths: protected and deny paths inside writable roots
	// are enforced (read-only, deny paths hidden), however deep. False for
	// Linux without bubblewrap.
	ProtectsNestedPaths bool `json:"protectsNestedPaths"`
	// BlocksPorts: connections to individual TCP ports
	// (Policy.DenyConnectPorts) can be refused while the network is allowed.
	// False for Linux with a Landlock ABI below 4.
	BlocksPorts bool `json:"blocksPorts"`
}

type Counters struct {
	Applied             uint64 `json:"applied"`
	Denied              uint64 `json:"denied"`
	EscalationRequested uint64 `json:"escalationRequested"`
	EscalationGranted   uint64 `json:"escalationGranted"`
	EscalationDenied    uint64 `json:"escalationDenied"`
	Unavailable         uint64 `json:"unavailable"`
}

type Denial struct {
	Kind DenialKind `json:"kind"`
	// Evidence is the output line the decision was based on (trimmed).
	Evidence string `json:"evidence"`
	// Path is the absolute path the failing operation referred to, when one
	// could be extracted from the output.
	Path string `json:"path,omitempty"`
	// Op is OpWrite or OpRead when the output tells which one failed; empty
	// when unknown or for network denials.
	Op string `json:"op,omitempty"`
	// WorkspaceRootEntry is true when the path is a new entry directly in the
	// workspace root. The Landlock-only backend (no bubblewrap) grants a
	// writable root that contains protected paths entry by entry, so creating
	// new top-level files there fails although the workspace is writable.
	WorkspaceRootEntry bool `json:"workspaceRootEntry,omitempty"`
}

type DenialKind string

type EnvInherit string

type EnvPolicy struct {
	Inherit EnvInherit `json:"inherit"`
	// ScrubSecrets drops credential-looking variables (default true).
	ScrubSecrets bool `json:"scrubSecrets"`
	// Exclude are extra glob patterns (case-insensitive, '*' and '?') of
	// variable names to drop. Exclude wins over everything.
	Exclude []string `json:"exclude,omitempty"`
	// Keep are glob patterns of variable names always passed through, even
	// when they look like secrets or are outside the core set.
	Keep []string `json:"keep,omitempty"`
}

type Event struct {
	Time      time.Time `json:"time"`
	Type      EventType `json:"type"`
	SessionID string    `json:"sessionId,omitempty"`
	Backend   string    `json:"backend,omitempty"`
	Mode      string    `json:"mode,omitempty"`
	// Kind/Op/Path describe a denial (see Denial); empty for other event
	// types.
	Kind string `json:"kind,omitempty"`
	Op   string `json:"op,omitempty"`
	Path string `json:"path,omitempty"`
	// Command is the offending or escalated command line. Callers pass the
	// raw command; Emit redacts (internal/redact.String/Path) and truncates
	// it before it reaches the ring buffer, the JSONL file, the log line or
	// telemetry — a caller must never pre-redact it (that would double up
	// escaping and could hide the "[REDACTED]" markers themselves).
	Command string `json:"command,omitempty"`
	// Reason explains an unavailable backend (Capability.Reason) or an
	// escalation's justification.
	Reason string `json:"reason,omitempty"`
	// AutoAllowed is set on an EventEscalationRequested: whether the policy
	// allows this escalation to be granted without an explicit approval.
	AutoAllowed bool `json:"autoAllowed,omitempty"`
}

type EventType string

type Mode string

type Network string

type Policy struct {
	Mode    Mode    `json:"mode"`
	Network Network `json:"network"`
	// Workspace is the project directory the policy was resolved for.
	Workspace string `json:"workspace"`
	// WritableRoots may be written (recursively), except under
	// ProtectedPaths and DenyPaths.
	WritableRoots []string `json:"writableRoots,omitempty"`
	// ReadableRoots, when non-empty (strict mode), is the complete set of
	// readable directories. Empty means "read everything".
	ReadableRoots []string `json:"readableRoots,omitempty"`
	// ProtectedPaths stay read-only even inside WritableRoots: Pando's own
	// config and data (anti self-disable) and git code-exec vectors.
	ProtectedPaths []string `json:"protectedPaths,omitempty"`
	// DenyPaths are denied for both read and write. Entries may be globs.
	DenyPaths []string `json:"denyPaths,omitempty"`
	// Env controls environment scrubbing.
	Env EnvPolicy `json:"env"`
	// AutoAllowBash is the configured intent to skip the bash permission
	// prompt. It only applies while the sandbox is enforced; use the package
	// AutoAllowBash() helper, which checks both.
	AutoAllowBash bool `json:"autoAllowBash"`
	// UseBwrap is the Linux bubblewrap preference.
	UseBwrap BwrapPolicy `json:"useBwrap"`
	// ExtendTo lists the extra spawn sites wrapped besides bash.
	ExtendTo []Purpose `json:"extendTo,omitempty"`
	// AllowAutoEscalation lets a denied command be re-run unsandboxed without
	// an explicit approval.
	AllowAutoEscalation bool `json:"allowAutoEscalation"`
	// DenyConnectPorts are TCP ports a child must not connect to even though
	// the network is allowed: the listeners of Pando itself (API, AG-UI, MCP
	// HTTP, LLM proxy, IPC bus, ...) and of other live Pando processes, see
	// GuardedPorts. Reaching one of them would let a command change the
	// configuration or run code outside the sandbox. Filled by Resolve only
	// when the network is allowed (a restricted network already refuses all
	// TCP); part of Hash, so a new listener re-spawns the persistent shell.
	DenyConnectPorts []int `json:"denyConnectPorts,omitempty"`
	// Source is the layer that decided Mode. Informational; not hashed.
	Source Source `json:"-"`
}

type Purpose string

type ResolveOptions struct {
	// GOOS selects the per-OS path tables (default runtime.GOOS).
	GOOS string
	// HomeDir is the user's home directory.
	HomeDir string
	// LookupEnv reads environment variables (PANDO_SANDBOX, TMPDIR, cache
	// overrides, ...).
	LookupEnv func(string) (string, bool)
	// IsLocked reports whether a dotted config path (e.g. "sandbox.mode") is
	// locked by an enterprise overlay. A locked path ignores PANDO_SANDBOX.
	IsLocked func(path string) bool
	// DataDir is config Data.Directory (protected; relative to the workspace).
	DataDir string
	// LocalConfigFile is the project config file found for the workspace,
	// protected in addition to <ws>/.pando.{toml,json}.
	LocalConfigFile string
	// GuardedPorts are the TCP ports of Pando's own listeners (GuardedPorts),
	// copied into Policy.DenyConnectPorts while the network is allowed.
	GuardedPorts []int
}

type SBPLOptions struct {
	// Canonical returns the symlink-resolved form of an absolute path (for a
	// missing path: its deepest existing ancestor resolved, plus the rest).
	// nil means the identity.
	Canonical func(path string) string
	// Exists reports whether a path exists (without following a final
	// symlink). It only gates the ancestor rename guards: a missing ancestor
	// (e.g. <ws>/.git before `git init`) must stay creatable. nil means every
	// path exists.
	Exists func(path string) bool
}

type Source string

type Status struct {
	Policy     Policy     `json:"policy"`
	Capability Capability `json:"capability"`
	// Active: policy enabled and backend enforced.
	Active bool `json:"active"`
	// Hash is Policy.Hash().
	Hash string `json:"hash"`
	// Full: Active and without gaps (see Guarantees). Only then may bash
	// skip its permission prompt.
	Full bool `json:"full"`
	// Gaps lists what an Active sandbox does not guarantee here (Guarantees).
	Gaps []string `json:"gaps,omitempty"`
}

type Wrapper interface {
	// Capability reports the backend and whether it is enforced on this
	// machine. It is cheap: probes run once and are cached.
	Capability() Capability
	// Wrap rewrites cmd (Path, Args, ExtraFiles, SysProcAttr, ...) so that,
	// once started, it runs under p. It must be called before cmd.Start.
	//
	// Contract:
	//   - A disabled policy (p.Enabled() == false) leaves cmd untouched and
	//     returns nil.
	//   - When the backend is not enforced (Capability().Enforced == false)
	//     Wrap leaves cmd untouched and returns nil: the sandbox fails open,
	//     and callers surface that through Capability/Active.
	//   - An error means enforcement was available but could not be set up
	//     for this command (e.g. a path that cannot be encoded). cmd may be
	//     partially modified and must not be started; wrap such errors with
	//     ErrWrapFailed.
	//
	// Wrap does not touch cmd.Env; use ScrubEnv (or WrapCmd, which does both).
	Wrap(cmd *exec.Cmd, p Policy) error
}