Probe Reference

Overview

This document describes each eBPF probe used for runtime evidence collection: its attach point, why it exists, what kind of data it captures, and its known limitations. It is an altitude reference — it gives the shape of each probe and its event, not a field-by-field transcription. Exact struct layouts, field names, and sizes live in the authoritative sources below and are kept in sync there; when this page and the source disagree, the source wins.

Authoritative sources

WhatWhere
On-the-wire event structs (header + one struct per event type, all sizes/MAX_* constants)src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/stella_common.h
Per-probe BPF programs (attach points, filtering, capture logic)src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/*.bpf.c
User-space NDJSON event shape and field semanticsevidence-schema.md → docs/schemas/runtime-evidence-v1.json
Kernel/BTF version requirements (deployment matrix)deployment-guide.md
Ring buffer, component architecture, CO-RE/BTF source selectionebpf-architecture.md
Collector options (RingBufferSize, MaxEventsPerSecond, etc.)src/Signals/__Libraries/StellaOps.Signals.Ebpf/Services/IRuntimeSignalCollector.cs

Every event begins with a common event_header (timestamp, pid/tid, cgroup_id, event-type discriminator, comm); the per-probe notes below describe only the fields that are specific to that probe. See stella_common.h for both the header and each event struct.

Tracepoint Probes

sys_enter_openat

Attach point: tracepoint/syscalls/sys_enter_openat Purpose: Capture file access operations to prove which files were read or written. Kernel requirement: 2.6.16+ (openat syscall), 4.14+ for eBPF attachment. Source: Probes/Bpf/syscall_openat.bpf.c (event: file_open_event in stella_common.h)

Captured shape: the directory fd, open flags, file mode, and the resolved filename, on top of the common header.

Filtering:

Fallback: for kernels without openat (pre-2.6.16), attaches to sys_enter_open instead (same event struct, dfd set to the AT_FDCWD value).

Performance impact: ~1-2% CPU at 10,000 opens/second.

sched_process_exec

Attach point: tracepoint/sched/sched_process_exec Purpose: Capture process execution to prove which binaries were invoked. Kernel requirement: 3.4+ for tracepoint, 4.14+ for eBPF attachment. Source: Probes/Bpf/syscall_exec.bpf.c (event: process_exec_event in stella_common.h)

Captured shape: parent pid, executed binary path, and the first argument (argv0), on top of the common header.

Argv capture:

Interpreter detection:

Performance impact: minimal (exec rate is typically low).

inet_sock_set_state

Attach point: tracepoint/sock/inet_sock_set_state Purpose: Capture TCP connection lifecycle to prove network communication patterns. Kernel requirement: 4.16+ (tracepoint added), BTF recommended for CO-RE. Source: Probes/Bpf/syscall_network.bpf.c (event: tcp_state_event in stella_common.h)

Captured shape: old/new TCP state, address family, source/destination ports, and source/destination addresses (a v4/v6 union), on top of the common header.

State transition filtering:

Address formatting (user space):

Performance impact: ~1% CPU at high connection rate.

Uprobe Probes

libc connect/accept

Attach points: uprobe/uretprobe on connect, and uprobe on accept/accept4, in libc. Purpose: Capture network operations at the libc level as an alternative to kernel tracepoints. Library support: glibc (libc.so.6) and musl (libc.musl-*.so.1). Source: Probes/Bpf/uprobe_libc.bpf.c (event: net_connect_event in stella_common.h)

Captured shape: socket fd, address family, remote address/port, and the syscall return value (captured on the uretprobe), on top of the common header.

Library path resolution:

  1. Parse /etc/ld.so.cache for library locations.
  2. Fall back to common paths (/lib/x86_64-linux-gnu/, etc.).
  3. Handle container-specific paths via /proc/{pid}/root.

Byte counting (optional): read/write uprobes track bytes per file descriptor, aggregated to prevent an event flood.

OpenSSL SSL_read/SSL_write

Attach points: uprobe/uretprobe on SSL_read and SSL_write in libssl. Purpose: Capture TLS traffic volumes without decryption. Library support: OpenSSL 1.1.x (libssl.so.1.1) and 3.x (libssl.so.3); LibreSSL best-effort; BoringSSL limited. Source: Probes/Bpf/uprobe_openssl.bpf.c (event: ssl_op_event in stella_common.h)

Captured shape: operation (read/write), requested vs. actual byte counts (actual captured on the uretprobe), and the SSL* pointer for correlation, on top of the common header.

Session correlation: ssl_ptr can be correlated with SSL_get_fd for socket mapping; optionally SSL_get_peer_certificate for peer info.

Byte aggregation: high-throughput connections aggregate to periodic summaries to prevent an event flood on bulk transfer.

Function Tracer (Generic)

Attach point: uprobe/{binary}:{symbol} — arbitrary function symbols. Purpose: Attach to arbitrary function symbols for custom evidence. Source: Probes/Bpf/function_tracer.bpf.c (event: function_call_event in stella_common.h)

Captured shape: runtime address and a symbol identifier (resolved against a BPF map), plus call-stack context, on top of the common header.

Symbol resolution: user space resolves the runtime address to a symbol via ELF tables, applying the ASLR offset from /proc/{pid}/maps; results are cached.

Kernel Version Compatibility

The per-probe Kernel requirement lines above are version floors summarized for narrative; the authoritative attach points are the SEC(...) declarations in each Probes/Bpf/*.bpf.c. For the deployment-facing minimum/recommended kernel and BTF requirements, see deployment-guide.md (and the CO-RE/BTF source-selection details in ebpf-architecture.md).

Known Limitations

Tracepoints

Uprobes

General

Troubleshooting

Probe Failed to Attach

Error: Failed to attach tracepoint/syscalls/sys_enter_openat

Missing BTF

Error: BTF not found for kernel version

Ring Buffer Overflow

Warning: Ring buffer full, events dropped