Before you begin
- Linux x86_64 with BPF, BTF, tracefs, and ring-buffer support. Kernel 5.8 or later is typical.
- Rust 1.82 or later,
clang, libbpf headers and library, andpkg-config. - Root or
CAP_BPF+CAP_PERFMONforrecordonly. Everything else runs unprivileged. - Node.js 20 or later only if you want the desktop workbench.
Build and check the host
1
Build the CLI
target/release/syscall. Building the whole workspace also compiles the desktop crate and requires the desktop packages.2
Inspect readiness
info reports the kernel, BTF availability, tracefs visibility, effective capabilities, and the selected database path. It does not load BPF or change the host.3
Record a target
--db, the database is the invoking user’s default data path, normally ~/.local/share/syscall/syscall.db.connect attempt, not a recorder failure.
Inspect the session
inspect summarizes the session, collection accounting, event counts, and observed processes. Use the other commands to follow the recorded activity:
--json and a global --db <PATH> before or after the subcommand:
Analyze and verify
verify uses assessment-specific exit codes:
Export a package
0600. An existing file is not replaced without --force.
Open the workbench
Build the desktop application if you have its system packages:Next steps
Record safely
Privilege, scope, redaction, signals, and exit behavior.
Investigate methodically
Move from session overview to processes, timeline, and activity filters.
Read the evidence model
Understand what the counters and lifecycle states mean.
Review limitations
Know what the record cannot establish before drawing conclusions.