Collection path
1
Kernel tracepoints
Seven stable
sched and syscalls tracepoints observe process lifecycle and syscall activity and emit fixed-size wire samples.2
BPF ring buffer
Samples are written to a 4 MiB BPF ring buffer. The kernel drops samples when the buffer is full; loss is counted, not hidden.
3
Strict userspace decode
A userspace callback reads each sample, validates its header and payload, and discards malformed input without terminating the session.
4
Scope and identity attribution
Decoded events are attributed to canonical process instances and admitted or filtered according to the recording scope.
5
Buffered persistence
Attributed events pass through a bounded channel to a dedicated writer thread, which batches writes and commits them to SQLite.
Tracepoints
Seven stable tracepoints are attached:
The syscall hooks are paired in bounded LRU maps keyed by the current task. Enter stores the arguments; exit looks up and removes the entry. One attempt produces at most one event. A missing enter, an eviction, or a malformed sample produces no event rather than a fabricated one.
The programs use fixed local structs instead of
vmlinux.h and CO-RE. Context sizes and offsets are verified by static assertions and by the running kernel’s BTF. This trades portability for a small, inspectable kernel surface.
Wire format and decoding
Samples carry a 56-byte header with magic, wire schema version, event type, monotonic timestamp, PID/TGID, UID/GID, command name, payload length, and the observer-namespace TGID when known. The Rust decoder treats every sample as untrusted:- It checks magic, schema version, event type, and minimum size.
- It checks payload length and payload-end bounds.
- It checks NUL termination and field-specific address or path rules.
- It counts and discards malformed samples; a bad sample cannot terminate the session.
Recording phases
record executes in ordered phases so privilege is held only for loading and attaching:
- Validate the request, target command, scope, and optional session ID.
- Inspect effective privilege,
unprivileged_bpf_disabled, BTF, and tracefs. - Load and attach the BPF skeleton while root or capable.
- Drop to the invoking user when launched through sudo; set
umask 077. - Create the session row as the invoking user.
- Spawn the target in its own process group.
- Register the root PID with the scope tracker.
- Poll the ring buffer, decode, attribute, and enqueue.
- On target exit or signal, drain, read loss counters, join the writer, and finalize the session.
failed with a finalization error. A hard crash leaves it in recording, but already-committed data remains readable.
Scope and attribution
The tracepoints are system-wide. There is no kernel-side PID or cgroup filter.RecordingScope describes userspace admission:
target-tree: admit the launched target and descendants.system: admit every collected event observed on the host.
/proc ancestry path. A numeric PID match alone is not enough. Out-of-scope events are counted as filtered, not silently discarded.
The detailed identity and ancestry rules are in Identity and scope.
Storage and concurrency
SQLite is opened with:Clocks
Kernel events carrybpf_ktime_get_ns(), which is monotonic time since boot. At session start the collector captures:
monotonic_ns for ordering and correlation because a later NTP step can move the wall clock.
Failure behavior
Analysis and verification
Behavioral analysis and verification are offline. They read persisted evidence through bounded storage APIs and never execute recorded commands.- Analysis rules live in
syscall-analysisand produce findings that reference original event row IDs. - Verification checks structural, relational, lifecycle, ordering, and accounting consistency.
- Export assembles session, processes, events, analysis, verification, and a component manifest.
Continue reading
Identity and scope
How process instances, PID reuse, and target-tree admission work.
Evidence model
Sessions, events, counters, and what completeness means.
Architecture
Crate boundaries, concurrency, and design tradeoffs.
Limitations
The evidence gaps that remain by design.