git.stella-ops.org/docs/reachability/probe-reference.md

Probe Reference

Overview

This document details each eBPF probe used for runtime evidence collection, including kernel requirements, captured data, and known limitations.

Tracepoint Probes

sys_enter_openat

Location: 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 File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/syscall_openat.bpf.c

Captured Fields:

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID
tid	u32	Thread ID
cgroup_id	u64	Kernel cgroup ID
dfd	int	Directory file descriptor
flags	int	Open flags (O_RDONLY, O_WRONLY, etc.)
mode	u16	File mode for creation
filename	char[256]	File path
comm	char[16]	Process command name

Filtering:

• Cgroup-based: Only capture events from specified containers
• Path-based: Allowlist/denylist patterns applied in user space

Fallback: For kernels without openat (pre-2.6.16), attaches to sys_enter_open instead.

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

---

sched_process_exec

Location: 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 File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/syscall_exec.bpf.c

Captured Fields:

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID (after exec)
ppid	u32	Parent process ID
cgroup_id	u64	Kernel cgroup ID
filename	char[256]	Executed binary path
comm	char[16]	Process command name
argv0	char[128]	First argument

Argv Capture:

• Limited to first 4 arguments for safety
• Each argument truncated to 128 bytes
• Uses bpf_probe_read_user_str() with bounds checking

Interpreter Detection:

• Recognizes shebangs for Python, Node, Ruby, Shell scripts
• Maps /usr/bin/python script.py to script path

Performance Impact: Minimal (exec rate typically low)

---

inet_sock_set_state

Location: 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 File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/syscall_network.bpf.c

Captured Fields:

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID
cgroup_id	u64	Kernel cgroup ID
oldstate	u8	Previous TCP state
newstate	u8	New TCP state
sport	u16	Source port
dport	u16	Destination port
family	u8	AF_INET (2) or AF_INET6 (10)
saddr_v4 / saddr_v6	u32 / u8[16]	Source address
daddr_v4 / daddr_v6	u32 / u8[16]	Destination address
comm	char[16]	Process command name

State Transition Filtering:

• Default: Only * -> ESTABLISHED and * -> CLOSE
• Configurable: All transitions for debugging

Address Formatting:

• IPv4: Dotted decimal (e.g., 192.168.1.1)
• IPv6: RFC 5952 compressed (e.g., 2001:db8::1)

Performance Impact: ~1% CPU at high connection rate

---

Uprobe Probes

libc connect/accept

Location:

• uprobe/libc.so.6:connect
• uretprobe/libc.so.6:connect
• uprobe/libc.so.6:accept
• uprobe/libc.so.6:accept4

Purpose: Capture network operations at libc level as alternative to kernel tracepoints.

Library Support:

• glibc: libc.so.6
• musl: libc.musl-*.so.1

Source File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/uprobe_libc.bpf.c

Captured Fields (connect):

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID
cgroup_id	u64	Kernel cgroup ID
fd	int	Socket file descriptor
family	u16	Address family
addr	varies	Remote address
port	u16	Remote port
comm	char[16]	Process command name
result	int	Return value (from uretprobe)

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):

• uprobe/libc.so.6:read and uprobe/libc.so.6:write
• Tracks bytes per file descriptor
• Aggregated to prevent event flood

---

OpenSSL SSL_read/SSL_write

Location:

• uprobe/libssl.so.3:SSL_read
• uretprobe/libssl.so.3:SSL_read
• uprobe/libssl.so.3:SSL_write
• uretprobe/libssl.so.3:SSL_write

Purpose: Capture TLS traffic volumes without decryption.

Library Support:

• OpenSSL 1.1.x: libssl.so.1.1
• OpenSSL 3.x: libssl.so.3
• LibreSSL: libssl.so.* (best-effort)
• BoringSSL: Limited support

Source File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/uprobe_openssl.bpf.c

Captured Fields:

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID
cgroup_id	u64	Kernel cgroup ID
operation	u8	READ (0) or WRITE (1)
requested_bytes	u32	Bytes requested
actual_bytes	u32	Bytes transferred (from uretprobe)
ssl_ptr	u64	SSL context pointer
comm	char[16]	Process command name

Session Correlation:

• ssl_ptr can correlate with SSL_get_fd for socket mapping
• Optional: SSL_get_peer_certificate for peer info

Byte Aggregation:

• High-throughput connections aggregate to periodic summaries
• Prevents event flood on bulk data transfer

---

Function Tracer (Generic)

Location: uprobe/{binary}:{symbol}

Purpose: Attach to arbitrary function symbols for custom evidence.

Source File: src/Signals/__Libraries/StellaOps.Signals.Ebpf/Probes/Bpf/function_tracer.bpf.c

Captured Fields:

Field	Type	Description
timestamp_ns	u64	Nanoseconds since boot
pid	u32	Process ID
cgroup_id	u64	Kernel cgroup ID
address	u64	Runtime address
symbol_id	u32	Symbol identifier (from BPF map)
comm	char[16]	Process command name

Symbol Resolution:

• User-space resolves address to symbol via ELF tables
• ASLR offset calculated from /proc/{pid}/maps
• Cached for performance

---

Kernel Version Compatibility

Feature	Minimum Kernel	Recommended
Basic eBPF	4.14	5.x+
BTF (CO-RE)	5.2	5.8+
Ring buffer	5.8	5.8+
sys_enter_openat	4.14	5.x+
sched_process_exec	4.14	5.x+
inet_sock_set_state	4.16	5.x+
Uprobes	4.14	5.x+

Known Limitations

Tracepoints

• sys_enter_openat: Path may be relative; resolution requires dfd lookup
• sched_process_exec: Argv reading limited by verifier complexity
• inet_sock_set_state: UDP not covered; use kprobe for UDP if needed

Uprobes

• Library resolution: May fail for statically linked binaries
• musl libc: Some symbol names differ from glibc
• OpenSSL: Version detection required for correct symbol names
• Stripped binaries: Uprobes require symbol tables

General

• eBPF verifier: Complex programs may be rejected
• Container namespaces: Paths may differ from host view
• High event rate: Ring buffer overflow possible under extreme load

Troubleshooting

Probe Failed to Attach

Error: Failed to attach tracepoint/syscalls/sys_enter_openat

• Check kernel version supports the tracepoint
• Verify eBPF is enabled (CONFIG_BPF=y, CONFIG_BPF_SYSCALL=y)
• Check permissions (CAP_BPF or root required)

Missing BTF

Error: BTF not found for kernel version

• Install kernel BTF package (linux-image-*-dbg on Debian/Ubuntu)
• Use BTFHub for external BTF files
• Fall back to pre-compiled probes for specific kernel

Ring Buffer Overflow

Warning: Ring buffer full, events dropped

• Increase buffer size: --ring-buffer-size 1M
• Enable more aggressive filtering
• Enable rate limiting: --max-events-per-second 10000