executor

type Backend interface {
	// Name is the backend ("process").
	Name() string
	// Status is the protection tasks get.
	Status() Status
	// Prepare checks spec and sets up the task without starting it.
	Prepare(spec TaskSpec) (Task, error)
}

type Config struct {
	// Mode is how strictly tasks are sandboxed ("" is ModeAuto).
	Mode Mode
	// ReadDeny are paths no task may read or write: the sensor's key and
	// credentials, its outbox, its configuration and local policy. A path
	// that does not exist yet is skipped.
	ReadDeny []string
	// Limits are the default limits of every task (zero fields:
	// DefaultLimits).
	Limits Limits
	// WorkRoot is where private task directories are made (default
	// <os.TempDir()>/openctem-tasks).
	WorkRoot string
	// Launcher is the binary re-executed as the launcher (default: this
	// program). It must call RunLauncherIfRequested first thing in main.
	Launcher string
}

type Limits struct {
	// MemoryBytes bounds the data segment (heap and private mappings).
	MemoryBytes uint64 `json:"memory_bytes,omitempty"`
	// Processes is how many more processes and threads the task may create.
	Processes uint64 `json:"processes,omitempty"`
	// FileSizeBytes bounds any file the task writes.
	FileSizeBytes uint64 `json:"file_size_bytes,omitempty"`
	// OpenFiles bounds the task's open file descriptors.
	OpenFiles uint64 `json:"open_files,omitempty"`
	// CPUSeconds bounds CPU time per process (0: none; the timeout bounds
	// wall time).
	CPUSeconds uint64 `json:"cpu_seconds,omitempty"`
}

type Mode string

type NetworkClass string

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

type ProcessHooks struct {
	Configure func(*exec.Cmd)
	Started   func(*exec.Cmd)
	Finished  func(*exec.Cmd)
}

type Result struct {
	// ExitCode is the exit status (-1: killed by a signal or not run).
	ExitCode int
	// State is the process state (process backend).
	State *os.ProcessState
	// Killed is why the executor stopped the task ("" when it exited).
	Killed string
	// Duration is the wall time.
	Duration time.Duration
	// Sandbox is the protection the task ran under (runtime-stamped
	// provenance).
	Sandbox Status
	// Network is the task's network class.
	Network NetworkClass
}

type Status struct {
	Backend string `json:"backend"`
	Mode    Mode   `json:"mode"`
	// Sandboxed is true when tasks run through the launcher.
	Sandboxed bool `json:"sandboxed"`
	// Landlock is the Landlock ABI used (0: not available).
	Landlock   int  `json:"landlock,omitempty"`
	Seccomp    bool `json:"seccomp"`
	NoNewPrivs bool `json:"no_new_privs"`
	Rlimits    bool `json:"rlimits"`
	// NetworkEnforced is true when the backend itself confines the task to
	// its network class (a per-task network namespace or policy). The
	// process backend records the class but does not enforce it, so it is
	// false there; the sensor's target guard and egress settings apply
	// instead. Code from outside the project must not run on a backend
	// without it.
	NetworkEnforced bool `json:"network_enforced"`
	// Missing lists the controls this host could not enforce, and why.
	Missing []string `json:"missing,omitempty"`
}

type Task interface {
	// Workdir is the task's private directory.
	Workdir() string
	Start(ctx context.Context) error
	// Wait returns when the task ends. An error means it could not be
	// waited for; a non-zero exit is in the result.
	Wait() (*Result, error)
	// Kill stops the task and its process group; reason is recorded.
	Kill(reason string)
	Cleanup() error
}

type TaskSpec struct {
	// ID names the task in logs and the working directory (optional).
	ID string
	// Argv is the program and its arguments. Argv[0] is resolved on PATH
	// when it has no slash.
	Argv []string
	// Env is the task's environment ("KEY=value"), already filtered by the
	// caller (the SDK passes an allowlist; never the sensor's credentials).
	Env []string
	// SetEnv are variables the caller sets explicitly; they win over the
	// sandbox's own HOME, TMPDIR and XDG_* defaults.
	SetEnv map[string]string
	// Dir is the working directory; "" is the task's private directory.
	Dir string
	// WritePaths are paths the task may write besides its private
	// directory (an output file's directory, a tool cache it owns).
	WritePaths []string
	// Limits bound the task (zero fields: DefaultLimits).
	Limits Limits
	// Network is the network class (see NetworkClass).
	Network NetworkClass
	// Stdin is the task's standard input (nil: none). A tool that speaks
	// the adapter protocol reads its messages from it. Pass an *os.File
	// (the read end of an os.Pipe) so the process gets the descriptor
	// itself: any other reader is copied by a goroutine that Wait waits
	// for.
	Stdin io.Reader
	// Stdout and Stderr receive the task's output.
	Stdout, Stderr io.Writer
	// Hooks let the caller adjust the process (process backend only).
	Hooks ProcessHooks
}