Process-scoped runtime investigator for Linux.
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, namespace changes, and more.
Designed for: security research, malware triage, reverse engineering support, incident response, and deep debugging.
Not designed for: EDR, SIEM, Kubernetes-first monitoring, policy enforcement, or whole-system tracing.
# Trace a command
sudo procscope -- ./suspicious-binary
# Attach to a running process
sudo procscope -p 1234
# Save evidence bundle + Markdown report
sudo procscope --out case-001 --summary report.md -- ./installer.sh
# Stream events as JSONL
sudo procscope --jsonl events.jsonl -- ./tool| Category | Events | Confidence |
|---|---|---|
| Process lifecycle | exec, fork/clone, exit (with codes) | Exact |
| File activity | open, rename, unlink, chmod, chown | Best-effort |
| Network activity | connect, accept, bind, listen (IP:port) | Best-effort |
| Privilege transitions | setuid, setgid, ptrace | Exact / Best-effort |
| Namespace changes | setns, unshare | Best-effort |
| Mount operations | mount | Best-effort |
Honesty note: procscope does NOT claim to capture all process activity. See docs/support-matrix.md for exact details on what is observed, what is missed, and why.
- Linux kernel 5.8+ with BTF (
CONFIG_DEBUG_INFO_BTF=y) - Root or
CAP_BPF+CAP_PERFMON+CAP_SYS_RESOURCE - Architectures: amd64, arm64
procscope will detect missing capabilities at startup and provide actionable guidance.
Note: Running procscope usually requires sudo (eBPF capabilities).
You can directly download the pre-compiled .deb package or static binary straight from our automated GitHub pipelines:
For Debian / Kali / Parrot OS:
wget https://github.com/Mutasem-mk4/procscope/releases/latest/download/procscope_0.1.4_linux_amd64.deb
sudo dpkg -i procscope_0.1.4_linux_amd64.debFor other Linux Distros (Static Binary):
wget https://github.com/Mutasem-mk4/procscope/releases/latest/download/procscope_0.1.4_linux_amd64.tar.gz
tar -xvf procscope_0.1.4_linux_amd64.tar.gz
sudo mv procscope /usr/local/bin/If you have Go 1.22+ installed, you can natively compile and install the tool to your Go bin path effortlessly:
go install github.com/Mutasem-mk4/procscope/cmd/procscope@latestWe are actively tracking upstream approvals for major distributions. Once merged:
BlackArch Linux:
sudo pacman -S procscopeKali Linux & Parrot OS:
sudo apt update && sudo apt install procscopeCompact, color-coded terminal output during investigation:
TIME PID COMM EVENT DETAILS
[+ 0ms] 1234 suspicious process.exec /tmp/suspicious-binary
[+ 12ms] 1234 suspicious file.open /etc/passwd [read]
[+ 15ms] 1234 suspicious net.connect ipv4 → 93.184.216.34:443
[+ 18ms] ! 1234 suspicious priv.setuid uid 1000 → 0
[+ 20ms] 1235 sh process.exec /bin/sh
[+ 25ms] 1235 sh process.exit exit_code=0
[+ 30ms] 1234 suspicious process.exit exit_code=0
Machine-readable, one event per line:
procscope --jsonl events.jsonl -- ./commandStructured directory for incident response:
case-001/
├── 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
Team-ready report with overview, process tree, event breakdown, file/network activity tables, notable events, and honest limitations.
| Flag | Short | Description | Default |
|---|---|---|---|
--pid |
-p |
Attach to existing PID | — |
--name |
-n |
Attach by process name | — |
--out |
-o |
Evidence bundle directory | — |
--jsonl |
JSONL output file | — | |
--summary |
Markdown summary file | — | |
--no-color |
Disable ANSI colors | false | |
--quiet |
-q |
Suppress live timeline | false |
--max-args |
Max argv elements | 64 | |
--max-path |
Max path string length | 4096 | |
--skip-checks |
Skip privilege checks | false |
- No environment dumping — env vars are not captured by default
- No secret capture — payload/body content is not traced
- Bounded lengths — arguments and paths are truncated at configurable limits
- Pattern-based redaction — values matching
password,token,secret, etc. are redacted
┌───────────────────────────────────────┐
│ CLI (cobra) │
├──────────┬────────────┬───────────────┤
│ Launcher │ Attacher │ Cap Check │
├──────────┴────────────┴───────────────┤
│ Event Correlator │
│ (process tree, investigation ID) │
├───────────────────────────────────────┤
│ eBPF Tracer Manager │
│ (load, attach, ring buffer read) │
├───────────────────────────────────────┤
│ eBPF Programs (kernel) │
│ tracepoints: sched, syscalls, etc. │
├───────────────────────────────────────┤
│ Output Layer │
│ timeline │ JSON │ bundle │ summary │
└───────────────────────────────────────┘
See docs/architecture.md for detailed design.
| Feature | procscope | Tracee | Tetragon | Inspektor Gadget | strace |
|---|---|---|---|---|---|
| Focus | Process-scoped investigation | Runtime security | K8s observability | K8s debugging | Syscall tracing |
| Scope | Single process tree | System-wide | System/pod-wide | System/pod-wide | Single process |
| Setup | Zero config | Policy config | CRDs | kubectl | Zero config |
| Evidence bundle | ✓ | ✗ | ✗ | ✗ | ✗ |
| Markdown report | ✓ | ✗ | ✗ | ✗ | ✗ |
| Process tree | ✓ auto-follows forks | ✓ | ✓ | ✓ | -f flag |
| K8s-native | ✗ | ✓ | ✓ | ✓ | ✗ |
| Policy engine | ✗ | ✓ | ✓ | ✗ | ✗ |
See docs/comparison.md for honest, detailed comparison.
- Building from Source
- Architecture
- Support Matrix
- Security Model
- Privacy Model
- Packaging Guide
- Comparison
- Design Decisions
See CONTRIBUTING.md.
See SECURITY.md for reporting vulnerabilities.
procscope is a process-first local investigator. It is not an EDR, not a SIEM, and not a policy engine. It is designed to answer one question well: what did this process actually do?