syscall record loads the eBPF programs, attaches seven tracepoints, drops privilege, creates a session, and runs one target command.
Before recording
- Check the host with
syscall info. - Confirm the target and database paths are authorized and writable by the invoking user.
- Decide whether target arguments should be persisted.
- Choose
target-treeunless host-wide activity is explicitly required.
CAP_BPF + CAP_PERFMON, or CAP_SYS_ADMIN on older kernels. SYSCALL never invokes sudo or prompts for a password.
Command shape
-- separator is required. Target flags are passed to the target, not parsed as recorder flags.
Options
The database path can also be set with
SYSCALL_DB.
Scope
The kernel tracepoints are system-wide in both modes. Scope is userspace admission, not a kernel security boundary.
Out-of-scope events are counted as filtered. They are not collection loss.
Redaction
Target arguments are persisted by default:--redact-args replaces all arguments with "<redacted>". The executable path is still stored. File paths and network destinations recorded by tracepoints are not redacted.
Session identity and database
A generated session ID is time- and randomness-based. Use--session-id when an external workflow requires a stable identifier.
The default database is ~/.local/share/syscall/syscall.db. To keep an investigation isolated:
0600; the data directory is expected to be mode 0700.
After sudo, the database, WAL sidecar, and target process are owned by the invoking user.
What happens during recording
- The request, scope, target, and session ID are validated.
- Privilege, BTF, tracefs, and
unprivileged_bpf_disabledare inspected. - The BPF skeleton is loaded and all seven programs are attached.
- Privilege is dropped to the invoking user.
- The session row is created.
- The target starts in its own process group.
- The root PID is registered with the scope tracker.
- Events are decoded, attributed, and written in batches.
- On exit or signal, the recorder drains, finalizes counters, and joins the writer.
failed. A hard crash leaves it recording, but committed rows remain inspectable.
Signals and exit codes
record mirrors the target when recording succeeds.
On SIGINT or SIGTERM, the recorder stops accepting work, sends SIGTERM to the target process group, waits up to two seconds, sends SIGKILL if needed, drains for up to 500 ms, and finalizes the session as
interrupted.
Detached descendants
The recorder follows the launched target tree while the target is alive. Descendants that detach and outlive the target are not followed after finalization. If long-running background processes are part of the investigation, keep the target alive for the required duration or record with an explicit wrapper that waits for them.Failure behavior
Do not treat a
failed or recording session as a clean capture. Inspect its counters before using it.
Confirm the result
- Status and termination reason.
- Persisted event count versus received, decoded, and attributed counts.
- Ring-buffer loss, userspace drops, malformed samples, and persistence failures.
- Filtered events if target-tree scope was used.
- Unresolved identity or ancestry.