# Runtime Instrumentation

> Bridges eBPF-based runtime monitoring into the Stella Ops platform, converting kernel-level events into canonical format for reachability validation and signal scoring.

## Purpose

Runtime Instrumentation adapts raw eBPF events from Tetragon into the Stella Ops canonical `RuntimeCallEvent` format. This enables the platform to incorporate live runtime observations (system calls, function probes, process lifecycle) into reachability validation and evidence-weighted vulnerability scoring without coupling downstream modules to any specific eBPF agent.

## Quick Links

- [Architecture](./architecture.md) - Technical design and implementation details

## Status

| Attribute | Value |
|-----------|-------|
| **Maturity** | Beta |
| **Source** | `src/RuntimeInstrumentation/` |

## Key Features

- **Tetragon gRPC client:** Connects to the Tetragon agent's gRPC stream and ingests raw eBPF events in real time
- **eBPF probe type mapping:** Supports all major probe types -- Kprobe, Kretprobe, Uprobe, Uretprobe, Tracepoint, USDT, Fentry, Fexit, ProcessExec, ProcessExit
- **Stack frame canonicalization:** Converts raw kernel/user-space stack frames into `CanonicalStackFrame` with symbol resolution and address normalization
- **Hot symbol index updates:** Publishes observed symbols to the hot symbol index for runtime reachability correlation
- **Privacy filtering:** Strips sensitive data (environment variables, command arguments, file paths) before events leave the instrumentation boundary

## Dependencies

### Upstream (this module depends on)
- **Tetragon** - External eBPF agent providing kernel-level event streams via gRPC

### Downstream (modules that depend on this)
- **Signals** - Consumes `RuntimeCallEvent` data for runtime signal scoring (RTS dimension)
- **Scanner** - Uses runtime observations for reachability validation
- **Policy** - Incorporates runtime evidence into policy evaluation and verdicts

## Related Documentation

- [Signals](../signals/) - Runtime signal scoring using RTS dimension
- [Signals eBPF Contract](../signals/contracts/ebpf-micro-witness-determinism-profile.md) - Determinism profile for eBPF witnesses
- [Scanner](../scanner/) - Reachability validation
- [Policy](../policy/) - Runtime evidence in policy decisions