Supported environment
The collector uses fixed tracepoint context structs rather than CO-RE. The build checks those layouts against the running kernel’s BTF before the programs are considered usable.
Install build dependencies
On Debian or Ubuntu:rustup.
bpftool is not required. libbpf-cargo invokes clang and generates the Rust skeleton during the Cargo build.
Build
Build only the CLI when you do not need the desktop packages:target/release/syscall. The desktop release binary is target/release/syscall-workbench after a Tauri release build.
Docker (UI preview and CLI container)
If you have Docker Desktop or Docker Compose, you can launch the standalone web UI preview and asyscall CLI container with one command:
- UI preview: http://localhost:8080 serves the standalone mock workbench from
ui/(in-memory preview data). - CLI container: run
docker compose exec syscall syscall --help. The repository is mounted at/work, so you can inspect, analyze, verify, and export mounted SQLite session databases.
docker compose down.
Check the eBPF object
_Static_assert checks in ebpf/syscall.bpf.c enforce context and event sizes at compile time. A layout mismatch fails the build instead of producing a truncated sample.
Verify tracepoint layouts
/sys/kernel/btf/vmlinux and verifies the fields used by the programs. It is read-only and works without root when BTF is readable.
Expected result:
Inspect the host
- Kernel release and distribution details when available.
- Whether
/sys/kernel/btf/vmlinuxis readable. - Whether tracefs is mounted and readable.
- Availability of the seven tracepoints, or
unknownwhen tracefs cannot be read. - Effective UID and capability mask.
- Whether unprivileged BPF is disabled.
- The selected database path and whether it exists.
--json for automation:
info never loads BPF and never changes host settings.
Recording privilege
Run the recorder through sudo or grant the binary the required capabilities. SYSCALL does not call sudo itself.- Loads and attaches the eBPF programs while privileged.
- Reads
SUDO_UIDandSUDO_GID. - Drops supplementary groups, GID, and UID to the invoking user.
- Verifies the drop and sets
umask 077. - Creates the database and spawns the target as that user.
SUDO_UID, it remains root and the target runs as root. That is an explicit operator choice.
The data directory is mode 0700, the database is mode 0600, and SQLite WAL/SHM sidecars inherit the restrictive umask.
Default paths
Override the database per invocation:
SYSCALL_DB is the environment equivalent. The desktop resolves its database once at startup from --db or SYSCALL_DB; frontend requests cannot change it.
Database compatibility
Inspection and verification open SQLite read-only. They do not migrate a database.- A missing schema or an unsupported newer schema is rejected explicitly.
- A writable recorder applies pending migrations in a transaction.
- Historical rows are not rewritten during a read-only open.
- Use a database produced by a compatible collector and storage schema. The current SQLite schema is version 5.
PRAGMA user_version before querying. See Schemas for the version contract.
Documentation preview
The documentation site lives indocs/ and uses Mintlify. Preview it locally: