Skip to main content
Investigation commands read a persisted SQLite database. They do not attach eBPF, execute recorded commands, or modify the source database. All commands accept the global --db PATH and --json options. --json changes the output format, not the evidence selection.

Start with the session

sessions lists sessions newest first, with status, scope, time, event count, and duration. inspect adds:
  • Session ID, command, arguments as recorded, scope, status, and termination state.
  • Kernel and collector provenance.
  • Event counts by type.
  • Collection and loss counters.
  • Observed process summaries.
  • The database path in use.
Read the counters before reading the conclusions. A small event count can mean a short session, a narrow scope, or collection loss.

Find a session

List more than the default 50:
Use JSON for scripts:
Select a different database:

Reconstruct process relationships

processes lists process instances derived from recorded events. Depending on the evidence, each row may include:
  • Canonical process-instance ID.
  • Canonical PID.
  • Recorded executable and command line.
  • Parent PID and parent instance when linkage is unambiguous.
  • First and last observed times.
  • Event count and whether an exit was observed.
  • Unresolved identity or ancestry flags.
tree renders the hierarchy. It uses process-instance identity, not PID alone. Ambiguous PID-reuse matches are left unresolved, missing parents are marked, and cycles are reported rather than followed forever.

Read the event stream

events is the raw chronological event listing:
timeline is the investigation-oriented view. It supports more filters and a stable, paged order:
Timeline filters: Accepted time forms:
  • Integer nanoseconds since the Unix epoch.
  • RFC3339 UTC such as 2026-11-10T12:34:56Z or with fractional seconds.
Ordering is deterministic: timestamp_ns ASC, monotonic_ns ASC, id ASC.

Follow filesystem attempts

Fields include event ID, UTC time, process identity, command name, raw path, flags, dirfd, raw result, success or errno, and notes for relative or truncated paths. Important interpretation:
  • The path is the string passed to openat, not a resolved absolute path.
  • dirfd == -100 means AT_FDCWD; other values identify a directory descriptor.
  • Relative paths are preserved as recorded and cannot be resolved without the process working directory and descriptor state.
  • Truncated paths are marked.
  • An open attempt does not prove that file contents were read or written.
  • open, openat2, and other file syscalls are not captured.

Follow network attempts

Fields include event ID, UTC time, process identity, family, source and destination addresses and ports when available, raw result, and outcome or errno. Important interpretation:
  • A connect event is an attempt, not an established session.
  • The tracepoint cannot distinguish TCP from UDP.
  • Source metadata is often unavailable and is stored as null.
  • A successful local connection still does not prove application-level establishment or data transfer.

Summarize evidence accounting

stats reports duration, process-instance count, event counts by type, collection counters, kernel ring-buffer loss, userspace drops, unresolved identity counts when available, and session termination state. --verify adds a read-only verification assessment. Verification is never required to inspect counters.

Interpret the result

Absence of a row is never proof that activity did not occur.

Machine-readable output

Every inspection command supports --json. JSON output is valid UTF-8 and preserves nulls for unavailable values rather than inventing placeholders.
Use Behavioral analysis to turn patterns into explainable findings, and Verification to check the session’s internal consistency.