execguard

Documentation

Overview

Package execguard runs only allowlisted absolute executables with exact argument patterns. No shell, no env inheritance by default.

Index

• Variables
• type CommandRule
• type Guard
  • func New(policy Policy) (*Guard, error)
  • func (g *Guard) Run(ctx context.Context, req Request) (Result, error)
  • func (g *Guard) Validate(req Request) error
• type Policy
• type Request
• type Result

Variables

var (
	ErrDenied       = errors.New("execguard: command denied")
	ErrRelativePath = errors.New("execguard: relative executable path")
	ErrShell        = errors.New("execguard: shell execution forbidden")
	ErrOutputLimit  = errors.New("execguard: output size limit exceeded")
	ErrTimeout      = errors.New("execguard: execution timeout")
)

Types

type CommandRule

type CommandRule struct {
	Path        string
	AllowedArgs [][]string // each inner slice is a full argv after the executable
}

CommandRule allowlists one absolute executable and exact argv patterns.

type Guard

type Guard struct {
	// contains filtered or unexported fields
}

Guard evaluates and optionally runs allowlisted commands.

func New

func New(policy Policy) (*Guard, error)

New validates policy and returns a Guard.

func (*Guard) Run

func (g *Guard) Run(ctx context.Context, req Request) (Result, error)

Run validates then executes (or dry-runs) the request.

func (*Guard) Validate

func (g *Guard) Validate(req Request) error

Validate checks whether the request would be allowed without running it.

type Policy

type Policy struct {
	Commands       []CommandRule
	Timeout        time.Duration
	MaxOutputBytes int
	EnvAllowlist   []string // names copied from current env when set
	WorkDir        string   // if set, must be absolute
	DryRun         bool
}

Policy configures the guard.

type Request

type Request struct {
	Path string
	Args []string
}

Request is a proposed execution.

type Result

type Result struct {
	Path     string
	Args     []string
	DryRun   bool
	ExitCode int
	Stdout   []byte
	Stderr   []byte
}

Result is a sanitized execution outcome (no secrets assumed in stdout).