Documentation
¶
Overview ¶
Package sandbox provides a hardened wrapper around os/exec for running untrusted external tools (protoc, language plugins, code generators, etc.) with timeouts, output bounds, environment whitelisting and path validation.
The goal is not full OS-level isolation (that requires containers or seccomp), but to remove the most common foot-guns when invoking third-party binaries from a build pipeline:
- All commands run via exec.CommandContext so a canceled parent context terminates the child.
- WaitDelay caps how long a process may keep stdio open after the context is canceled (Go 1.20+).
- Output is captured into bounded buffers; runaway tools cannot exhaust memory.
- The process environment is built from an explicit whitelist instead of leaking the entire parent environment.
- When AllowedRoots is non-empty, every path-shaped argument must resolve inside one of the allowed roots; this prevents a malicious config from making protoc read or write arbitrary files.
Index ¶
Constants ¶
const DefaultMaxOutputBytes = 16 * 1024 * 1024 // 16 MiB
DefaultMaxOutputBytes bounds combined stdout+stderr capture per stream.
const DefaultTimeout = 5 * time.Minute
DefaultTimeout is applied when Options.Timeout is zero.
const DefaultWaitDelay = 5 * time.Second
DefaultWaitDelay bounds the grace period after context cancellation before the process is forcibly killed.
Variables ¶
This section is empty.
Functions ¶
func MinimalEnv ¶
func MinimalEnv() []string
MinimalEnv returns a copy of os.Environ filtered to envWhitelist plus BUFFALO_*. The result is safe to extend with ExtraEnv.
Types ¶
type Options ¶
type Options struct {
// Name is the program name or absolute path. Required.
Name string
// Args are the arguments passed to the program (excluding argv[0]).
Args []string
// Dir is the working directory. Empty uses the current process CWD.
Dir string
// Env is the explicit environment for the child process. When nil, a
// minimal whitelisted environment is built from os.Environ() (see
// MinimalEnv). Use ExtraEnv to add custom keys without losing the
// whitelist.
Env []string
// ExtraEnv adds KEY=VALUE entries on top of the whitelisted environment.
// Ignored when Env is non-nil.
ExtraEnv []string
// Stdin is the optional input stream piped to the child.
Stdin io.Reader
// Timeout caps total wall-clock execution time. Zero means DefaultTimeout.
Timeout time.Duration
// WaitDelay bounds the grace period after the context is canceled before
// the child is killed. Zero means DefaultWaitDelay.
WaitDelay time.Duration
// MaxOutputBytes bounds captured stdout and stderr each. Zero means
// DefaultMaxOutputBytes. Negative disables the bound (not recommended).
MaxOutputBytes int64
// AllowedRoots, when non-empty, restricts path-shaped arguments to be
// inside one of these directories. Each root must be an absolute path or
// will be made absolute relative to Dir (or process CWD).
AllowedRoots []string
}
Options controls a single sandboxed execution.
Source Files