Documentation
¶
Overview ¶
Package sandbox implements the two-axis sandbox model (Scope x ApprovalMode). Scope is the OS-level confinement; ApprovalMode is the agent-loop policy for when to ask the user.
The sandbox is best-effort hardening, not a security boundary. If the host lacks the required helper (sandbox-exec on macOS, bwrap on Linux) Wrap degrades to running the bare command and emitting a warning.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrHelperMissing = errors.New("sandbox: helper binary not found")
ErrHelperMissing signals that the OS-level helper (bwrap, sandbox-exec) is not on PATH. The original cmd is returned so the caller can degrade.
var ErrUnsupported = errors.New("sandbox: platform not supported")
ErrUnsupported signals that wrapping is not implemented for this platform. Wrap returns this alongside the unwrapped command — the caller decides whether to abort or proceed with degraded confinement.
Functions ¶
func HelperMain ¶
func HelperMain() error
HelperMain is the entry point when bee is invoked as bee-sandbox-helper. Wave 2 will fill this in (parse policy from env, apply scope-specific confinement, exec the inner command). For now it's a placeholder that errors loudly so a misconfigured wave-2 invocation doesn't silently run unsandboxed.
func HelperPath ¶
HelperPath returns the symlink/argv0 alias to use when re-exec'ing bee as the helper. Resolves /proc/self/exe (or os.Executable) and returns its directory joined with helperName. The caller is expected to either symlink to this path or pass it as argv[0] to the exec syscall.
func IsHelper ¶
func IsHelper() bool
IsHelper reports whether argv[0] identifies this process as the sandbox helper. Callers should branch to HelperMain at the very top of main() when this returns true, before any normal CLI setup.
func IsKnownSafe ¶
IsKnownSafe reports whether cmd matches a built-in safe prefix. Used by Untrusted mode to auto-approve without escalation.
func Wrap ¶
Wrap returns the OS-appropriate wrapped command for the given policy.
If wrapping is impossible (helper missing, platform unsupported, or scope is DangerFullAccess) the original cmd is returned along with a non-nil error describing the reason. Callers should treat the error as a warning, not a fatal — the sandbox is hardening, not a security boundary.
Types ¶
type ApprovalMode ¶
type ApprovalMode string
ApprovalMode is the agent-loop policy for escalation prompts.
const ( // Untrusted: auto-run only known-safe commands; ask for everything else. Untrusted ApprovalMode = "untrusted" // OnRequest: model decides when to ask via request_permissions (default). OnRequest ApprovalMode = "on-request" // OnFailure: run optimistically; ask only when sandbox blocks. OnFailure ApprovalMode = "on-failure" // Never: fully autonomous; never ask. Never ApprovalMode = "never" )
type Policy ¶
type Policy struct {
Scope Scope
Approval ApprovalMode
Cwd string
AllowList []string // extra known-safe prefixes for Untrusted mode
}
Policy is the resolved sandbox configuration for one tool invocation.
type Scope ¶
type Scope string
Scope is the OS-level confinement applied to a child process.
const ( // ReadOnly: filesystem read-only, network blocked. ReadOnly Scope = "read-only" // WorkspaceWrite: writes confined to cwd (and tmp), network blocked. WorkspaceWrite Scope = "workspace-write" // WorkspaceWriteNet: like WorkspaceWrite but outbound network is allowed, so // package installs (npm/pip/go/cargo) work while writes stay confined to // cwd+tmp. The default — network isn't the security boundary (the approval // modal is), filesystem confinement is what this preserves. WorkspaceWriteNet Scope = "workspace-write-net" // DangerFullAccess: no sandbox applied. DangerFullAccess Scope = "danger-full-access" )
Source Files