Skip to main content
SYSCALL separates collection, decoding, attribution, storage, and investigation. The kernel side is deliberately small; the evidence logic lives in Rust crates that can be tested without loading BPF.

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.
The ring-buffer callback performs no disk I/O: it decodes, attributes, and enqueues. The writer owns its own SQLite connection and commits batches transactionally.

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.
Process lifecycle samples from wire versions 1 and 2 remain decodable. File-open and network-connect samples require wire version 3. The full layout is in Event and storage schema.

Recording phases

record executes in ordered phases so privilege is held only for loading and attaching:
  1. Validate the request, target command, scope, and optional session ID.
  2. Inspect effective privilege, unprivileged_bpf_disabled, BTF, and tracefs.
  3. Load and attach the BPF skeleton while root or capable.
  4. Drop to the invoking user when launched through sudo; set umask 077.
  5. Create the session row as the invoking user.
  6. Spawn the target in its own process group.
  7. Register the root PID with the scope tracker.
  8. Poll the ring buffer, decode, attribute, and enqueue.
  9. On target exit or signal, drain, read loss counters, join the writer, and finalize the session.
A session row exists before the target starts. A normal unwind marks it 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.
For target-tree scope, attribution requires a tracked parent, a matching process instance, and lineage or a verified /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:
The writer batches up to 256 events or 200 ms of activity and commits each batch in one transaction. If a later batch fails, the writer reports the committed count and the error separately so partial evidence remains accounted for. Inspection commands open the database read-only and verify the schema version before querying. All values are bound parameters.

Clocks

Kernel events carry bpf_ktime_get_ns(), which is monotonic time since boot. At session start the collector captures:
Each event stores both the derived wall-clock timestamp and the raw monotonic timestamp. Prefer 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-analysis and 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.
The desktop workbench calls the same engines through a narrow Tauri command boundary. It does not contain SQL or duplicate rule logic.

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.