proctree

README

Security Engineering Commons Proctree

Bounded process-tree execution, cancellation and cleanup for Go

Proctree executes a trusted local command and returns after its owned process tree terminates or cleanup fails. Proctree is not a privilege boundary or hostile-code sandbox

API

Run(context.Context, Command) accepts an absolute executable, arguments, working directory, closed environment, optional input, output limits and execution deadlines

Result includes start state, exit code, bounded output and a typed outcome. Errors preserve sentinel and native causes

Unix executables using Run must call DispatchWatchdog(os.Args) before ordinary dispatch

The complete guarantees and bounds are in the contract

Platforms

CI runs the supported Windows, Linux, macOS, BSD, illumos and Solaris targets listed in Platforms

Verification

go test -count=1 ./...
go test -race -count=1 ./...

CI also covers Go compatibility, cross-builds, containers, fuzzing and CodeQL

Documentation

Index

• Constants
• Variables
• func DispatchWatchdog([]string) (bool, int)
• type Command
• type Outcome
• type Result
  • func Run(ctx context.Context, command Command) (Result, error)

Constants

const DefaultCleanupTimeout = time.Second

const MaxArgumentBytes = 64 << 10

const MaxArguments = 256

const MaxCleanupTimeout = 30 * time.Second

const MaxEnvironment = 128

const MaxEnvironmentBytes = 64 << 10

const MaxInputBytes = 1 << 20

const MaxOutputBytes = 16 << 20

const MaxPathBytes = 4 << 10

const MaxTimeout = 30 * time.Minute

Variables

var ErrCancelled = errors.New("process execution cancelled")

var ErrCleanup = errors.New("process cleanup failed")

var ErrDeadline = errors.New("process execution deadline exceeded")

var ErrExit = errors.New("process exited unsuccessfully")

var ErrInvalid = errors.New("invalid process command")

var ErrOutputLimit = errors.New("process output exceeds its bound")

var ErrOwnership = errors.New("process ownership failed")

var ErrStart = errors.New("process start failed")

var ErrUnsupported = errors.New("process-tree ownership is unsupported")

Functions

func DispatchWatchdog

func DispatchWatchdog([]string) (bool, int)

Types

type Command

type Command struct {
	Executable     string
	Arguments      []string
	Directory      string
	Environment    []string
	Input          []byte
	StdoutLimit    int
	StderrLimit    int
	Timeout        time.Duration
	CleanupTimeout time.Duration
}

type Outcome

type Outcome string

const OutcomeCancelled Outcome = "cancelled"

const OutcomeCleanupFailure Outcome = "cleanup_failure"

const OutcomeCompleted Outcome = "completed"

const OutcomeDeadline Outcome = "deadline"

const OutcomeExitFailure Outcome = "exit_failure"

const OutcomeInvalid Outcome = "invalid"

const OutcomeOutputLimit Outcome = "output_limit"

const OutcomeOwnershipFailure Outcome = "ownership_failure"

const OutcomeStartFailure Outcome = "start_failure"

const OutcomeUnsupported Outcome = "unsupported"

type Result

type Result struct {
	Started  bool
	ExitCode int
	Stdout   []byte
	Stderr   []byte
	Outcome  Outcome
}

func Run

func Run(ctx context.Context, command Command) (Result, error)