exec

Documentation

Overview

Package exec provides process execution utilities for collectors. This package isolates subprocess management, environment handling, and output sanitization from collector workflow orchestration.

Index

• Constants
• func BuildEnv(baseEnv []string, name, configPath string, secrets []string, ...) []string
• func SanitizeStderr(stderr string) string
• func WriteConfig(config map[string]interface{}) (string, func(), error)
• type ProgressMessage
• type RunOptions
• type RunResult
  • func Run(ctx context.Context, name, execPath, configPath string, env []string, ...) RunResult

Constants

const CollectorProtocolVersion = 1

CollectorProtocolVersion is the current version of the collector protocol. This is passed to collectors via EPACK_PROTOCOL_VERSION env var.

Functions

func BuildEnv

func BuildEnv(baseEnv []string, name, configPath string, secrets []string, getenv func(string) string, insecureInheritPath bool) []string

BuildEnv constructs the environment for collector execution.

SECURITY: Uses BuildRestrictedEnvSafe to strip proxy credentials. Collectors are untrusted code and should not receive credentials embedded in proxy URLs.

func SanitizeStderr

func SanitizeStderr(stderr string) string

SanitizeStderr sanitizes collector stderr for safe inclusion in error messages.

SECURITY: Collector stderr is untrusted input that could contain secrets or log injection attacks. This function:

• Truncates to a reasonable length (first 500 bytes)
• Escapes control characters (newlines, tabs, etc.)
• Redacts patterns that look like secrets (via redact.Sensitive)

func WriteConfig

func WriteConfig(config map[string]interface{}) (string, func(), error)

WriteConfig writes collector config to a temporary JSON file. Returns the file path and a cleanup function.

SECURITY: Uses execsafe.WriteSecureConfigFile which creates the temp directory with umask 0077, eliminating the race condition between MkdirTemp and Chmod.

Types

type ProgressMessage

type ProgressMessage struct {
	Type            string `json:"type"`
	ProtocolVersion int    `json:"protocol_version"`
	Kind            string `json:"kind"` // "status" or "progress"
	Message         string `json:"message"`
	Current         int64  `json:"current,omitempty"`
	Total           int64  `json:"total,omitempty"`
}

ProgressMessage represents a progress update from a component.

type RunOptions

type RunOptions struct {
	// Timeout for collector execution. 0 uses DefaultCollectorTimeout.
	Timeout time.Duration

	// InsecureInheritPath allows inheriting PATH from the environment.
	// When false (default), collectors run with a safe, deterministic PATH.
	InsecureInheritPath bool

	// OnProgress is called for each progress message parsed from stdout.
	// If nil, progress messages are silently discarded.
	OnProgress func(ProgressMessage)
}

RunOptions configures collector process execution.

type RunResult

type RunResult struct {
	Stdout []byte
	Stderr string
	Err    error
}

RunResult contains the result of executing a collector process.

func Run

func Run(ctx context.Context, name, execPath, configPath string, env []string, opts RunOptions) RunResult

Run executes a collector binary and returns its output.

SECURITY: execPath must be a verified path from execsafe.VerifiedBinaryFD or an explicitly opted-in unverified path. This function does not perform verification - callers must verify before calling.

The function:

• Writes config to a secure temp file
• Builds a restricted environment with protocol variables
• Executes with timeout and output limits
• Streams stdout to parse progress messages in real-time
• Sanitizes stderr before returning errors