Runtime Status Source Matrix

Runtime status sources are local authorities for image identity and container context. They are not reachability proof, and they do not publish Stella Ops evidence by themselves. The Linux and Windows host agents must use these sources only to resolve immutable image digests and runtime context before the digest-gated publisher can create evidence.

Binding Rules

Container ids are lookup keys only. A container id must never be converted into image evidence, even when it looks like a digest.
Tags are mutable and must never become image evidence.
Publishable runtime evidence requires a valid sha256:<64-hex> image digest from runtime metadata or an approved local runtime status source.
Missing, stale, unreadable, unauthorized, malformed, timed-out, over-large, tag-only, not-found, or ambiguous status fails closed.
Native runtime APIs stay inactive until Stella Ops owns or approves the protocol/API contract, generated types, dependency license review, fixtures, and tests.
Kubernetes API sources are historical and retired. RuntimeInstrumentation must not add Kubernetes watches, informers, Helm charts, or DaemonSets.

Source Matrix

Source	OS	Status	Authority level	Permissions	Freshness	Failure behavior
File-backed CRI/container snapshot	Linux now, Windows-compatible	Active baseline in current resolver/worker and Linux agent	Local runtime status snapshot created by an operator-approved watcher or import step	Read access to configured absolute file path	Refreshed on host start and optional background interval; agents carry refreshed/observed timestamps into `HostRuntimeStatus`	Missing, unreadable, unauthorized, malformed, tag-only, not-found, or ambiguous records fail closed
Command-backed CRI/container snapshot	Linux now, Windows-compatible	Active baseline in current resolver/worker and Linux agent	Output from an explicitly configured local runtime command	Execute permission for a fully qualified executable path; no shell invocation	Fresh per command run, bounded by timeout and output limit	Non-zero exit, timeout, over-large output, malformed JSON, tag-only, not-found, or ambiguous records fail closed
Native CRI/containerd/Docker/Podman API client	Linux	Planned, inactive	Direct local runtime API response	Runtime socket/API access with least privilege	Must include API response time and status freshness before publication	Must remain inactive until contracts, generated types, licenses, fixtures, and tests are approved
File-backed Windows runtime snapshot	Windows	Active baseline in Windows host agent	Local Windows runtime snapshot created by an operator-approved watcher or import step	Read access under Windows service account ACLs	Carries refreshed/observed timestamps into `HostRuntimeStatus` before publication	Missing, unreadable, unauthorized, malformed, tag-only, stale, not-found, or ambiguous records fail closed
Windows command/named-pipe/API source	Windows	Command-backed active baseline; named-pipe/API planned inactive	Approved Windows runtime API, Docker named pipe, containerd-on-Windows, or bounded command output	Service account permission to the API, named pipe, executable, or file path	Fresh per read or command run; timeout and output bounds required	Permission denied, unavailable runtime, timeout, malformed response, tag-only, stale, not-found, or ambiguous records fail closed
Tetragon	Linux	Optional observation source, not status authority	Sensor observation only	Local Tetragon access when explicitly enabled	Event freshness is sensor-side; image evidence still needs local runtime status digest	Cannot publish directly; absent, disabled, malformed, or disconnected Tetragon does not block the Linux agent from using other local status
Kubernetes pod status/API/watch	Linux historical	Retired, unsupported active source	Historical compatibility fixture only	Not applicable for active product scope	Not applicable	Options validation rejects enabled Kubernetes sources; new work must not expand this path

Current Implementation Notes

The current code lives in src/RuntimeInstrumentation/StellaOps.RuntimeInstrumentation.Tetragon/ and src/RuntimeInstrumentation/StellaOps.Agent.Linux/, and src/RuntimeInstrumentation/StellaOps.Agent.Windows/. The former remains the fail-closed resolver baseline for the existing worker slice. The Linux and Windows host-agent bases use Agent.Core runtime status contracts directly.

FileRuntimeContainerImageStatusSnapshotSource reads configured local snapshot files.
CommandRuntimeContainerImageStatusSnapshotSource executes configured fully qualified commands with typed arguments, no shell, timeout bounds, and output limits.
LinuxFileRuntimeStatusSource and LinuxCommandRuntimeStatusSource implement Agent.Core IRuntimeStatusSource for the Linux host agent, parse CRI status/list JSON into HostRuntimeStatus, preserve source identity, and normalize only valid sha256 image digests.
LinuxRuntimeStatusGate blocks missing, malformed, tag-only, stale, and ambiguous local status before anything reaches the bounded Linux spool.
WindowsFileRuntimeStatusSource and WindowsCommandRuntimeStatusSource implement Agent.Core IRuntimeStatusSource for the Windows host agent, parse Windows/Docker-style status/list JSON into HostRuntimeStatus, preserve source identity, and normalize only valid sha256 image digests.
WindowsRuntimeStatusGate blocks missing, malformed, tag-only, stale, and ambiguous local status before anything reaches the bounded Windows spool.
SnapshotRuntimeContainerImageStatusProvider converts parse/read failures into misses so digest resolution does not reuse stale status.
RefreshingRuntimeContainerImageStatusProvider clears its status snapshot on parse, IO, or authorization failures.
DigestPinnedContainerImageDigestResolver accepts only digest-pinned image id/reference values and rejects tags or container-id-derived identity.

Native runtime clients must adapt into the same fail-closed behavior before they can be marked active.