- A small, verifiable kernel collection surface.
- Strict decoding of untrusted kernel samples.
- Explicit userspace attribution.
- Durable, inspectable storage with bounded memory.
- Read-only investigation surfaces that share one evidence model.
Workspace layout
syscall-core has no eBPF or SQLite dependency. syscall-storage has no eBPF dependency. This keeps the event contract and database independently testable.
Kernel surface
ebpf/syscall.bpf.c attaches to seven stable tracepoints:
Syscall hooks pair enter and exit in bounded LRU hash maps keyed by the current task. Each map holds 8,192 entries. Enter stores arguments; exit looks up and removes them. A missing enter or eviction produces no event.
Samples are emitted only at exit and carry the raw return value. This makes attempt-versus-success explicit. The hook does not resolve paths, perform DNS, or inspect payloads.
The programs use fixed local structs instead of
vmlinux.h and CO-RE. Context layouts are protected by _Static_assert and checked against the running kernel BTF:
The sizes are bytes; the BTF helper reports bit offsets.
The programs write to a 4 MiB ring buffer. A one-entry array map accumulates output failures so userspace can persist a real loss counter. Pairing-map eviction is not separately counted; that gap is documented.
The eBPF side performs no filtering and no heap allocation. The file-open event is ring-buffer reserved because its 336-byte event plus 272-byte pairing arguments exceed the 512-byte BPF stack limit.
The exec filename is a
__data_loc string. The low 16 bits are an offset from the tracepoint context. bpf_probe_read_kernel_str copies it with a 256-byte bound and records the actual length.
Wire format
The header is 56 bytes. Sample sizes:
Wire v3 adds the activity types. Process samples from v1 and v2 remain decodable; activity types require v3.
The decoder checks magic, schema, type, minimum size, payload length, payload end bounds, NUL termination, address family, address length, and padding. Malformed samples are counted and discarded.
See Event and storage schema for every offset.
Recording orchestration
syscall_collector::record runs in phases:
- Validate the request, scope, target, and session ID.
- Inspect effective privilege,
unprivileged_bpf_disabled, BTF, and tracefs. - Load and attach the skeleton.
- Drop privileges when launched through sudo.
- Create the session 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.
- Stop, drain, read counters, join the writer, and finalize.
Drop guard marks unfinished sessions failed on ordinary unwinds. A hard crash leaves the row recording; committed evidence remains readable.
Scope and process identity are detailed in Identity and scope.
Storage and concurrency
SQLite is opened with WAL,synchronous=NORMAL, foreign keys on, a 5-second busy timeout, and trusted_schema=OFF.
The ring-buffer callback never performs disk I/O. It uses try_send on a bounded channel of 8,192 events. A full channel increments the userspace-drop counter.
A dedicated writer thread owns its own SQLite connection and batches up to 256 events or 200 ms. Each batch commits in one transaction. If a later batch fails, the writer reports the committed count and error separately.
Inspection opens read-only and verifies PRAGMA user_version. Queries use bound parameters and indexes for session/time, type, PID, process instance, and timestamp.
Failure handling
Analysis boundary
Analysis is offline.syscall-analysis reads persisted evidence through bounded storage APIs and emits versioned findings whose supporting events are original row IDs.
The collector does not run rules in the hot path. The analysis crate has no eBPF or collector dependency. Queries are read-only; analysis never migrates, updates, or executes recorded commands.
Event scans are bounded by max_events; findings by max_findings. Shell traversal, process-tree correlation, and per-finding support are independently capped.
The result model lives in syscall-core. CLI rendering and export assembly consume it. The desktop service calls the same engine.
Export boundary
syscall-export assembles session, process, event, analysis, and verification components with a SHA-256 manifest. Both the CLI and desktop use this crate.
The source database is read-only. The package is written atomically. Export and verification semantics are documented in Export format.
Desktop boundary
desktop/src-tauri/src/contract.rs and mirrored in desktop/src/types/contracts.ts. Backend DTO fields are camelCase. Existing analysis and verification reports remain snake_case because they are reused verbatim.
The renderer uses hash routes:
Tradeoffs
- Fixed tracepoint structs are less portable than CO-RE, but every field is checked by BTF and static assertions.
- Userspace target-tree attribution is transparent and simple, but the kernel still produces system-wide samples.
- One writer thread and one read-only connection per command keep the design small; there is no multi-reader aggregation layer.
- Activity is sampled at syscall exit. This is portable but cannot prove data access, transport protocol, or connection establishment.
- Only
openatandconnectare captured. - The wall-clock offset is captured once, favoring internal consistency over responding to clock steps.
- The desktop is read-only by design because a GUI record button would require root, cached credentials, or a new privileged helper.
Continue reading
Development
Build, test, BTF checks, privileged e2e, and change procedures.
Testing
What is verified, what CI covers, and what remains operator-run.
Schemas
Wire and storage contracts.
Roadmap
Delivered phases and open work.