إنتقل إلى المحتوى الرئيسي

eBPF runtime

What this page is​

The kernel-side telemetry path for the Linux sensor. Covers the eBPF program, the user-space loader that attaches it, the ring buffer that ferries events to user space, and the OCSF 1.3 normaliser that turns kernel events into Collector envelopes.

Why it exists this way​

ADR 008 pins the nightly Rust + LLVM stack the eBPF crate compiles under. The eBPF program uses CO-RE so a single object file attaches to any kernel that exposes BTF; the alternative (per-kernel rebuild) was rejected as too expensive at the fleet scale targeted by the architecture document.

OCSF 1.3 is the canonical normaliser output. The Envelope type the Collector accepts is the OCSF event wrapped in the sensor's transport contract; agents downstream consume the canonical shape rather than per-sensor formats.

How it works​

Three Rust modules collaborate:

  • crates/edr-linux-ebpf/ is the kernel-side crate. It attaches a tracepoint on sched_process_exec and writes a 32-byte ProcessExecEvent to a ring buffer per the layout in edr-linux/src/events.rs.
  • edr_linux::runtime consumes the ring buffer in a Tokio task, normalises each record into ocsf::ProcessActivity, and pushes the activity onto the transport channel.
  • edr_linux::loader probes the running kernel (release + BTF presence) before attempting to load, returns LoaderReadiness if the host is acceptable, and LoaderError otherwise.

The event size is asserted at compile time inside events.rs so the kernel and user-space views cannot drift apart silently; a layout change requires both crates to recompile and the assertion catches mismatches.

What goes wrong​

  • LoaderError::KernelTooOld, see the overview.
  • LoaderError::MissingBtf, /sys/kernel/btf/vmlinux not present. Some hardened kernels redact BTF; the capability advertisement records this and the central Collector knows the sensor cannot produce CO-RE telemetry on that host.
  • ocsf::normalise_process_exec returns a typed error when the kernel record fails to parse. The metrics counter malformed_events increments and the event is dropped; loss is bounded and visible.