README
¶
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
Contributing
procscope is community-driven. See CONTRIBUTING.md and CODE_OF_CONDUCT.md to get involved.
Star History
License
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.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
procscope
command
procscope — Process-scoped runtime investigator for Linux.
|
procscope — Process-scoped runtime investigator for Linux. |
|
internal
|
|
|
caps
Package caps provides runtime capability and privilege detection for procscope.
|
Package caps provides runtime capability and privilege detection for procscope. |
|
cli
Package cli implements the procscope command-line interface.
|
Package cli implements the procscope command-line interface. |
|
events
Package events defines the procscope event schema for runtime observations.
|
Package events defines the procscope event schema for runtime observations. |
|
output
Package output provides event rendering for procscope investigations.
|
Package output provides event rendering for procscope investigations. |
|
process
Package process provides process tree tracking, command launching, and PID attachment for procscope investigations.
|
Package process provides process tree tracking, command launching, and PID attachment for procscope investigations. |
|
redact
Package redact provides safe-default redaction controls for procscope output.
|
Package redact provides safe-default redaction controls for procscope output. |
|
tracer
Package tracer manages eBPF program loading, attachment, and event reading for procscope runtime investigations.
|
Package tracer manages eBPF program loading, attachment, and event reading for procscope runtime investigations. |
|
version
Package version provides build-time version information for procscope.
|
Package version provides build-time version information for procscope. |