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
	// ConfineNetwork runs every task in its own user, network and mount
	// namespaces (Linux; api RFC-060): only loopback exists, and the task's
	// way out is its forwarder (TaskSpec.EgressProxy, EgressDNS). It needs
	// unprivileged user namespaces (a container seccomp profile that
	// allows them; on a host with AppArmor's restriction, a profile for the
	// sensor). Where they are not available, tasks run unconfined and
	// Status.NetworkMissing says why, unless RequireNetwork is set.
	ConfineNetwork bool
	// RequireNetwork makes NewProcessBackend fail when ConfineNetwork
	// cannot be enforced (a shared sensor, where it is a requirement).
	RequireNetwork bool
	// Private are more directories hidden from every task, like the task
	// root: a task reads beneath them only what TaskSpec.ReadPaths grants
	// it (the sensor's content cache: one tenant's packs are never
	// readable by another tenant's task).
	Private []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's
	// network: the process backend with Config.ConfineNetwork, where user
	// namespaces are available, runs each task in its own network
	// namespace whose only way out is its forwarder (TaskSpec.EgressProxy,
	// EgressDNS). Without it 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"`
	// NetworkMissing says why network confinement was asked for and is not
	// enforced (empty when it is, or was not asked for).
	NetworkMissing string `json:"network_missing,omitempty"`
	// 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
	// ReadPaths are paths the task may read even beneath a private root
	// (Config.Private, the task root): the content packs of this task
	// (templates, rules, wordlists), which no other task may read. Never
	// beneath a protected path.
	ReadPaths []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
	// EgressProxy and EgressDNS are unix socket paths of the task's
	// forwarder (pkg/sensorkit/egress): its proxy listener and its DNS
	// stream listener. On a backend that confines the network (Status.
	// NetworkEnforced) they are the task's only way out: the task sees a
	// proxy on 127.0.0.1:1080 (HTTP_PROXY, HTTPS_PROXY, ALL_PROXY) and a
	// resolver on 127.0.0.1:53 that lead to them, and nothing else. Empty:
	// a confined task has no network at all. Ignored when the network is
	// not confined.
	EgressProxy string
	EgressDNS   string
}