Skip to main content
SYSCALL is built from source. There is no package manager installation, signed installer, or prebuilt desktop bundle in this revision.

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:
For the desktop application:
Install Node.js 20 or later through your normal toolchain. A current stable Rust toolchain can be installed with 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:
Build the full workspace when the desktop prerequisites are installed:
The CLI binary is 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 a syscall 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.
Live eBPF record requires Linux kernel BPF/BTF/tracefs support and elevated privileges on the host kernel. Running record inside Docker Desktop’s Linux VM is environment-dependent and may not work the same as a native Linux host. Use a supported host for capture, then inspect the resulting database with the CLI container or a local build.
Stop the containers with docker compose down.

Check the eBPF object

A successful check includes seven tracepoint sections and the expected maps and license metadata:
The _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

The check reads /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:
If this fails, do not load the program. Update the context structs, payload offsets, and decoder together; bump the wire schema if the wire layout changes.

Inspect the host

The report includes:
  • Kernel release and distribution details when available.
  • Whether /sys/kernel/btf/vmlinux is readable.
  • Whether tracefs is mounted and readable.
  • Availability of the seven tracepoints, or unknown when tracefs cannot be read.
  • Effective UID and capability mask.
  • Whether unprivileged BPF is disabled.
  • The selected database path and whether it exists.
Use --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.
When launched through sudo, the collector:
  1. Loads and attaches the eBPF programs while privileged.
  2. Reads SUDO_UID and SUDO_GID.
  3. Drops supplementary groups, GID, and UID to the invoking user.
  4. Verifies the drop and sets umask 077.
  5. Creates the database and spawns the target as that user.
If SYSCALL is launched from a root shell with no 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.
Read-only opens verify PRAGMA user_version before querying. See Schemas for the version contract.

Documentation preview

The documentation site lives in docs/ and uses Mintlify. Preview it locally:
The preview prints a local URL. Validate links and configuration before publishing:
See Development for the complete contributor workflow.