procscope — eBPF Process Tracer for Linux by Mutasem Kharma (معتصم خرما)

Process-scoped eBPF runtime investigation for Linux. Trace malware behavior, investigate suspicious binaries, and audit container workloads using a command or PID as the investigation scope.

Launch a command under observation — or attach to an existing process — and see what it actually does at runtime: process lifecycle, file activity, network connections, privilege transitions, and more.

Designed for: security research, malware triage, incident response, and deep debugging. Not designed for: EDR, SIEM, or whole-system tracing.

Quick Start

Build from source (Go 1.26.8+)

git clone https://github.com/Mutasem-mk4/procscope.git
cd procscope
make build
sudo ./bin/procscope -- /bin/true

Full Installation Guide | Usage & Output Formats

Capture and read an investigation

sudo procscope --out case-001 --summary report.md -- /bin/true
sudo less report.md
sudo less case-001/process-tree.txt

Evidence files are private and normally owned by root when tracing with sudo. See Reading and exporting evidence for creating a private copy without changing the original permissions.

Features & Capabilities

Category	Events	Details
Process	exec, fork, exit	Support Matrix
Files	open, rename, unlink, chmod	Support Matrix
Network	connect, accept, bind, listen	Support Matrix
Privileges	setuid, setgid, ptrace	Support Matrix

Tech Stack & Requirements

• Build from source: Go 1.26.8+
• Observation: eBPF (CO-RE)
• Linux kernel 5.8+ with BTF support.
• Root privileges or specific eBPF capabilities.
• Architectures: amd64, arm64.

See Support Matrix for details.

Why procscope?

• Zero Config: No complex policies or yaml files.
• Focused: Automatically follows forks but stays scoped to your target tree.
• Evidence Ready: Generates structured evidence bundles and Markdown reports for IR teams.
• Tracing limits: eBPF observation has overhead and may lose events; measure on your workload.

Compare with Tracee, Tetragon, and strace

Documentation

• Architecture & Design
• Security & Privacy Model
• Installation Guide
• Usage & Flags
• Packaging Status

Contributing

procscope is community-driven. See CONTRIBUTING.md and CODE_OF_CONDUCT.md to get involved.

Star History

License

MIT

---

Developed by Mutasem Kharma (معتصم خرما).

Building from a clean checkout

Use make build with Go 1.26.8 or newer, clang with BPF support, llvm, and libbpf development headers installed. The Makefile generates the embedded BPF object from source if missing or stale. Direct go build needs that object first. For Debian builds, prepare dependencies with make source-dist and build from the resulting archive. Debian rules use vendor mode with network access disabled.

JSON stream integrity

When --json or --jsonl - sends events to stdout, the traced command's stdout is redirected to stderr. This keeps the event stream valid JSONL even when the command prints. Combining --pid and --name, or using nonpositive --max-args / --max-path, fails before tracing starts.

Network connect events describe observed attempts, not proof of a completed connection. Event loss and tracing overhead depend on workload and kernel behavior; no zero-overhead or lossless-capture guarantee is made.