Tetragon/eBPF Runtime Instrumentation Bridge (Runtime Witnesses, Build Correlation)

Module

RuntimeInstrumentation

Status

VERIFIED

Description

Runtime trace ingestion and query bridge for Tetragon/eBPF evidence with privacy canonicalization, hot-symbol aggregation, runtime timeline correlation to build artifacts, and disabled-mode null-service fallback.

Implementation Details

Runtime Traces API (ingest + query + score): src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTracesEndpoints.cs -- POST /api/v1/findings/{findingId}/runtime/traces for ingestion and GET runtime traces/score retrieval.
Runtime Timeline API: src/Findings/StellaOps.Findings.Ledger.WebService/Endpoints/RuntimeTimelineEndpoints.cs -- timeline query endpoint with time-window and bucket options.
Runtime Contracts: src/Findings/StellaOps.Findings.Ledger.WebService/Contracts/RuntimeTracesContracts.cs -- ingest request/response and runtime traces DTOs.
Runtime In-Memory Services: src/Findings/StellaOps.Findings.Ledger.WebService/Services/InMemoryRuntimeInstrumentationServices.cs -- deterministic observation store, address canonicalization, hot-symbol hit aggregation, and timeline construction.
Runtime Null Service (disabled mode): src/Findings/StellaOps.Findings.Ledger.WebService/Services/NullRuntimeTracesService.cs -- accepts ingest requests and returns non-materialized query behavior when runtime instrumentation is disabled.
Runtime Wiring Toggle: src/Findings/StellaOps.Findings.Ledger.WebService/Program.cs -- switches between in-memory runtime services and null runtime services via findings:ledger:runtime:enabled.
Runtime Signal Ingester: src/Unknowns/__Libraries/StellaOps.Unknowns.Core/Services/RuntimeSignalIngester.cs -- containment/blast-radius signal ingestion path used by unknowns analysis.
Signal Snapshot Builder: src/Findings/StellaOps.Findings.Ledger/Observations/SignalSnapshotBuilder.cs -- signal snapshot composition for replay/audit workflows.

E2E Test Plan

Submit a runtime trace event via the runtime traces endpoint and verify it is persisted and queryable.
Correlate runtime trace data to build artifact metadata and verify timeline details include component/artifact linkage.
Verify privacy filtering canonicalizes raw user-space memory addresses in returned symbol/file fields.
Verify hot-symbol tracking aggregates repeated symbol observations with higher hit counts.
Verify null runtime traces service handles requests without server errors when runtime instrumentation is disabled.
Query runtime timeline over a time range and verify chronological ordering and correlation metadata.

Verification

run-001 (2026-02-11): failed behavioral verification, triaged/confirmed missing ingest and runtime service wiring.
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/tier1-build-check.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/tier2-api-check.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/triage.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-001/confirmation.json
run-002 (2026-02-11): passed after fixes.
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier0-source-check.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier1-build-check.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/tier2-api-check.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/fix-summary.json
- docs/qa/feature-checks/runs/runtimeinstrumentation/tetragon-ebpf-runtime-instrumentation-bridge/run-002/retest-result.json

4.0 KiB Raw Blame History