Tetragon Agent Normalization

Current Status

src/RuntimeInstrumentation/StellaOps.Agent.Tetragon/ is now a buildable optional Linux Tetragon bridge. It is not the Stella Ops Linux agent and it is not a production runtime-observation publisher. It adapts local Tetragon export output into Agent.Core RuntimeObservation records for the Linux host agent when explicitly enabled.

The folder contains:

The legacy loose TetragonAgentCapability.cs source was removed because it carried local placeholder contracts for IAgentCapability, task models, and health models, direct production DateTimeOffset.UtcNow usage, and unresolved RuntimeInstrumentation bridge dependencies. The replacement bridge uses Agent.Core contracts directly and injects TimeProvider.

Supported Behavior

TetragonExportClient can:

TetragonRuntimeObservationSource can:

The bridge deliberately does not resolve image digests, publish evidence, sign evidence, or call downstream services. The Linux agent remains responsible for agent identity, local runtime status authority, digest gating, health snapshots, spool state, and future evidence publication.

Stack Trace Capture (Sprint 022 PHASE-C)

The bridge maps Tetragon process_kprobe events that carry user and/or kernel stack-trace arrays into the Agent.Core RuntimeObservation stack-frame payload (Sprint 022 PHASE-B contract).

Mapped Tetragon fields

Both flattened ({type: "process_kprobe", process: {...}, ...}) and canonical-Tetragon-nested ({process_kprobe: {process: {...}, ...}}) JSON shapes are accepted. The flattened shape continues to be used by some older Tetragon exporter configurations and by the bridge’s unit-test fixtures; the nested shape matches Tetragon’s upstream protobuf JSON.

Frame parsing rules

StackCaptureMode derivation

The bridge sets RuntimeObservation.StackCaptureMode from the resolved- symbol coverage of all frames across both stack lists:

Frame symbol coverageStackCaptureMode wire value
Zero frames present (no stack_trace_* arrays attached)null (field omitted)
Frames present, no frame has a symboladdresses-only
Frames present, some have symbol, some do notpartial-symbols
Frames present, all have symbolfull-symbols

The none wire value is reserved for producers that explicitly attest “no stack frames will ever attach”; the bridge does not emit it (a kprobe without stack arrays simply leaves StackCaptureMode null and both stack lists null, which is wire-compatible with the pre-PHASE-B contract).

Symbol resolution is best-effort and remains the responsibility of the Stella Ops Linux agent’s symbol resolver (Sprint 022 PHASE-D). The bridge ships whatever the Tetragon export endpoint provides. A future PHASE-D pass may upgrade an observation from addresses-only to partial-symbols or full-symbols by resolving frames against /proc/<pid>/maps and the matching ELF symbol tables; the bridge itself never performs ELF lookups.

Kind derivation for kprobe events

The bridge maps the kprobe function_name to a RuntimeObservationKind using a small allow-list keyed off the default Stella Ops TracingPolicy:

Tetragon function_name (case-insensitive)RuntimeObservationKind
sys_execve, __x64_sys_execve, do_execve, do_execveat_commonProcessStarted
tcp_connect, __sys_connect, inet_csk_acceptNetworkConnection
do_filp_open, do_sys_openat2, sys_openat, __x64_sys_openatFileAccess
sys_exit, sys_exit_group, do_exit, __x64_sys_exitProcessExited
anything else (or function_name absent)ProcessStarted (default)

Default TracingPolicy

A narrow-scope tracing policy ships at devops/agents-targets/tetragon/tracing-policy-stellaops-default.yaml. It enables user + kernel stack-trace collection on sys_execve, tcp_connect, and do_filp_open. Operators may extend this policy, but broader hook surfaces (e.g. high-frequency vfs_read/vfs_write) will require commensurate tuning of the digest gate, spool, and publication pipeline on the consuming Stella Ops Linux agent.

Remaining Blockers