Skip to content

Usage

Jump to bottom
thefoulowl edited this page Sep 4, 2026 · 2 revisions

Usage

Database path defaults to /var/lib/provctl/events.db. Override with --db <path> on any subcommand, or $PROVCTL_DB.

provctl watch

sudo provctl watch [--db path] [--quiet]

Attaches all five eBPF probes, streams decoded events to stdout, and persists them to SQLite in batches (every 150ms or 256 events, whichever comes first). Requires root (or CAP_BPF+CAP_PERFMON) and kernel BTF. Also seeds the store with already-running processes from /proc on startup, so events from long-lived processes (your shell, your browser) get a real name instead of a bare pid.

  • --quiet — persist events without printing them (useful for running as a long-lived background daemon).

Output is colorized by event type when attached to a terminal, and plain text when piped to a file or run under systemd/journald (also honors NO_COLOR). Stop with Ctrl+C (SIGINT) or SIGTERM — provctl flushes any buffered events before exiting.

Sample output:

15:04:05.123 FORK    bash(1234) forked -> pid 5678
15:04:05.124 EXEC    curl (pid 5678) exec'd /usr/bin/curl
15:04:05.140 CONNECT curl (pid 5678) connected to 185.199.109.133:443
15:04:05.141 OPEN    curl (pid 5678) opened /home/user/Downloads/file.zip
15:04:05.200 EXIT    curl (pid 5678) exited (code 0)

provctl trace <path>

provctl trace [--db path] <path>

Reconstructs a file's provenance from recorded history:

  1. Who first opened/wrote the path, and what that process connected to just before (the likely download source).
  2. Every later open of the same exact path by a different process (copy, extraction, antivirus scan, a shell about to exec it).
  3. Every time the path was executed, and — one level deep — what that run connected to or spawned.

No root needed; only reads the database watch already wrote.

Limitation: matches by exact path string. A file renamed or extracted under a new name breaks the chain unless watch was running and recorded both the old and new path being opened by the same process. See Known Limitations & Roadmap.

provctl timeline <pid>

provctl timeline [--db path] <pid>

Every recorded event for one process — its own start/exit, every file it opened, every connection it made, every child it spawned — merged and sorted by time. This is the "flight recorder" view.

provctl ps

provctl ps [--db path] [--all]

Prints the recorded process tree (parent → children), built from the processes table. By default shows only processes that haven't recorded an exit; --all includes exited ones too.

provctl top

provctl top [--db path]

A live TUI: a process tree on the left (the same live-process view as ps), a scrolling activity feed on the right. No root needed — it's a separate, read-only process that polls the same database watch is writing to; the two can run side by side in different terminals.

Keys: tab switches which pane arrow keys/j·k scroll; ↑/↓/j/k line scroll, pgup/pgdown/f/b page scroll; q or Ctrl+C quits.

The feed only shows the most recent ~500 lines (this is a live view, not a substitute for trace/timeline, which query the full history), and long paths are truncated from the left so the filename — not the directory prefix — stays visible.

Clone this wiki locally