Skip to main content
This path takes you from a source checkout to an inspected, verified, and exported session. It assumes a Linux host with the build prerequisites already installed; see Installation for package commands and host checks.

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, and pkg-config.
  • Root or CAP_BPF + CAP_PERFMON for record only. 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

The binary is 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

Recording requires privilege. SYSCALL attaches the programs, drops back to the invoking user, creates the database, and runs the target in its own process group. It never prompts for a password or stores credentials.Without --db, the database is the invoking user’s default data path, normally ~/.local/share/syscall/syscall.db.
The command exits with the target’s exit code when recording succeeds. A refused connection is an expected failed 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:
Every command accepts --json and a global --db <PATH> before or after the subcommand:

Analyze and verify

Analysis returns deterministic findings tied to recorded event IDs. Verification checks internal consistency and interpretability without modifying the database. verify uses assessment-specific exit codes:

Export a package

Export writes a new deterministic JSON package with a SHA-256 manifest and leaves the source database untouched. The output file is created with mode 0600. An existing file is not replaced without --force.

Open the workbench

Build the desktop application if you have its system packages:
Then open a recorded database read-only:
The workbench has no recording control. Record with the CLI, then open the result. See Workbench for the screen guide and the Tauri security boundary.
To launch a quick web UI preview without building the desktop app, run docker compose up --build -d and open http://localhost:8080. This serves the standalone mock workbench; for evidence-backed investigation of real session databases, use the native desktop workbench or the CLI. See Installation.

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.