Prerequisites
Checked environment:- Ubuntu 24.04 on WSL2, kernel
6.6.87.2-microsoft-standard-WSL2, x86_64. - Rust 1.99.1 through rustup.
- clang/LLVM 18.1.3,
llvm-objdump,make,pkg-config. - libbpf 1.3.0 development package.
- Readable
/sys/kernel/btf/vmlinux.
bpftool is not required. libbpf-cargo invokes clang and generates syscall.skel.rs during the build.
Build and test
unsafe_op_in_unsafe_fn; every unsafe block needs a safety comment.
The full workspace includes the Tauri crate and needs the desktop development packages. For a headless desktop check:
desktop-app feature gates the Tauri runner. scripts/check.sh falls back to the headless service layer when WebKitGTK and GTK development packages are absent.
Repository quality gate
- Formatting.
- Clippy with warnings denied.
- Workspace tests.
- CLI and collector builds.
- eBPF compilation and skeleton generation.
- BTF layout inspection.
- Desktop build and renderer tests.
- Both frontend builds.
eBPF development
Compile the object without Rust:_Static_assert checks in ebpf/syscall.bpf.c enforce context and event sizes at compile time.
Generate the skeleton through Cargo:
build.rs passes -D__TARGET_ARCH_x86 and explicit x86_64/libc include paths. Another architecture requires updating both the Makefile and build.rs.
Verify tracepoint layouts
Offsets in the BTF helper are bit offsets; divide by 8 for byte offsets. The check is read-only and needs no root when BTF is readable.
If it fails, do not load the program. Update the structs, offsets, and decoder together, then bump the wire schema if the layout changes.
Run the collector
Privileged testing policy
Unit and integration tests never load BPF and never require root. CI must not fake a kernel pass. The privileged path is an explicit operator action:- Refuses to run unless invoked through sudo for a non-root user.
- Verifies
inforeports BPF capability and visible lifecycle tracepoints. - Records a small target tree and inspects it as the invoking user.
- Sends SIGINT to a second recording and verifies exit
130andinterrupted. - Verifies database ownership and mode
600.
Diagnosing WSL2 failures
unprivileged_bpf_disabled=2means an unprivileged load must fail.- Tracefs is often root-only;
inforeports tracepoint visibility as unknown rather than guessing. /sys/kernel/btf/vmlinuxmust be readable for BTF checks.- If skeleton generation fails, verify clang and libbpf, then run
make -C ebpf clean check. - If load fails under root, preserve the exact libbpf error and do not report a pass.
Add a schema migration
- Add
crates/syscall-storage/migrations/00N_name.sql. - Add a
Migrationentry and bumpLATEST_SCHEMA_VERSION. - Add a migration test that opens version N-1 and verifies version N.
- Add read-only rejection tests for future versions.
- Update Schemas.
Add a collected event type
Adding an event requires all of:- A real eBPF program with bounded capture.
- Wire structs, decoder offsets, and BTF/layout checks.
- Payload construction and validation.
- Storage and index review.
- CLI and desktop rendering.
- Root-run e2e evidence.
Documentation
The documentation site uses Mintlify and lives indocs/.
docs/docs.json. Pages use .mdx with frontmatter. Keep the sidebar path in sync with the file path.
The screenshots in docs/screenshots/ are interface captures from the preview dataset, not live evidence. If you refresh them, label them honestly.
Change checklist
Before opening a pull request:- Formatting and Clippy pass.
- Relevant tests pass.
- eBPF object and BTF checks pass for kernel-facing changes.
- Privileged behavior is documented, not claimed from a unit test.
- Schema or wire changes update tests and references.
- User-visible changes update the relevant guide.
- No secrets, credentials, or unrelated evidence are committed.