Skip to main content
A SYSCALL session is a bounded collection of persisted events plus the metadata needed to interpret them. The database is an evidence record, not a complete reconstruction of the host.

Session lifecycle

A recording status after the recorder is gone usually means a hard crash. The data is still readable, but the session is incomplete and should be treated that way.

What each event establishes

The record preserves raw results and errno values. A failed open or connect is evidence of an attempt, not a recorder error.

Collection accounting

The session counters distinguish different reasons why observed activity may not appear as persisted rows. filtered_events is not the same as loss. It is activity outside the selected target tree. Ring-buffer loss, userspace drops, malformed samples, and persistence failures are collection gaps. A session can be internally consistent and still be incomplete. Verification reports both dimensions.

Completeness and confidence

Evidence is complete only when the session is completed, loss counters are zero, identity and ancestry are resolved, persistence did not fail, and any bounded scan was not truncated. When completeness is not established:
  • Findings and reports carry explicit limitations.
  • Analysis downgrades confidence.
  • Verification may return valid_but_incomplete rather than valid.
  • The workbench shows collection accounting separately from attribution limitations.
Absence of an event is not proof that activity did not occur. This is especially important for negative conclusions about network connections, file access, or process behavior.

Redaction

Target arguments are stored in the session row by default because they can be forensically useful. They can also contain secrets.
This stores "<redacted>" for all target arguments while retaining the command path. Redaction is preserved by inspection and export; original argument values are not present in the database. --redact-args does not redact file paths, network destinations, process names, or the command path. Record only activity you are authorized to collect.

Verification is not authenticity

syscall verify checks internal consistency:
  • Database and schema structure.
  • Session lifecycle and timestamp sanity.
  • Event ordering and row-count reconciliation.
  • Payload and identity consistency.
  • Activity result, errno, address, and path semantics.
  • Collection accounting.
It cannot prove that the database was authentic before verification, that no events were missed, or that the kernel was uncompromised. A valid assessment means the checks that could run did not find contradictions.

Export is not chain of custody

An evidence package contains deterministic components and a SHA-256 manifest. The manifest detects post-export changes when recomputed the same way, but it is not a digital signature and does not establish who handled the file. Use verification, hashing, and your own custody records for the guarantees they actually provide. See Verification and Export format.

Data not collected

SYSCALL does not capture:
  • File contents or memory.
  • Packet payloads, DNS names, or application protocols.
  • Environment variables or keystrokes.
  • Command output.
  • Activity from syscalls it does not hook, including open, openat2, sendto, sendmsg, and accept.
Target arguments are the exception among command-line data: they are stored unless --redact-args is used.

Collection and decoding

Tracepoints, pairing, ring buffer, writer, and failure behavior.

Identity and scope

Process instances, namespace correlation, and target-tree admission.

Verification guide

Assessments, finding codes, exit codes, and read-only guarantees.

Known limitations

The gaps that remain in the evidence.