PROCSCOPE(1)

NAME
procscope - process-scoped runtime investigation tool

SYNOPSIS
procscope [OPTIONS] [-- COMMAND [ARGS...]]
procscope -p PID [OPTIONS]
procscope -n NAME [OPTIONS]

DESCRIPTION
procscope launches a command under observation, or attaches to an existing process, and observes its runtime behavior at the kernel level using eBPF.

It captures process lifecycle events (exec, fork, exit), file activity, network connections, privilege transitions, namespace changes, and mount operations. Output is provided as a live terminal timeline, JSONL event stream, evidence bundle, and/or Markdown summary report.

Designed for authorized security research, malware triage, reverse engineering support, incident response, and deep debugging.

OPTIONS

-p, --pid PID
    Attach to an existing process by PID.

-n, --name NAME
    Attach to a process by name (first match).

-o, --out DIR
    Write evidence bundle to directory DIR.

--jsonl FILE
    Write events as JSONL to FILE. Use - for stdout.

--summary FILE
    Write Markdown summary report to FILE.

--no-color
    Disable ANSI color output.

-q, --quiet
    Suppress live terminal timeline output.

--max-args N
    Maximum number of argv elements to capture (default: 64).

--max-path N
    Maximum path string length (default: 4096).

--skip-checks
    Skip privilege and kernel compatibility checks.

--version
    Print version information and exit.

EXAMPLES

Trace a suspicious binary:
    sudo procscope -- ./suspicious-binary

Attach to a running process:
    sudo procscope -p 1234

Generate evidence bundle and report:
    sudo procscope --out case-001 --summary report.md -- ./installer.sh

Stream events as JSONL:
    sudo procscope --jsonl events.jsonl -- ./tool

REQUIREMENTS
Linux kernel 5.8+ with BTF support (CONFIG_DEBUG_INFO_BTF=y).

Root privileges or CAP_BPF + CAP_PERFMON + CAP_SYS_RESOURCE capabilities.

EVIDENCE BUNDLE
When invoked with --out, procscope creates a directory containing:

    •   metadata.json - investigation metadata

    •   events.jsonl - complete event stream

    •   process-tree.txt - human-readable process tree

    •   files.json - file activity summary

    •   network.json - network activity summary

    •   notable.json - security-relevant events

    •   summary.md - Markdown executive summary

LIMITATIONS

•   File activity is best-effort; not all I/O paths are traced.

•   DNS visibility is limited to userspace UDP queries to port 53.

•   io_uring and sendfile operations are not captured.

•   Container metadata is best-effort from cgroup path parsing.

•   Event drops may occur under extreme event rates.

EXIT STATUS
When tracing a launched command, procscope exits with the same exit code as the traced command. When using -p or -n, exits 0 on normal Ctrl-C termination.

FILES
Evidence bundles are written to the directory specified by --out. No persistent state files are created.

SEE ALSO
strace(1), bpftrace(8), bpftool(8)

BUGS
Report bugs at https://github.com/Mutasem-mk4/procscope/issues

AUTHOR
procscope contributors

LICENSE
MIT License