Zero-overhead, zero-config eBPF process tracer for Linux.
Trace malware behavior, investigate suspicious binaries, and audit container workloads — without strace overhead or the complexity of system-wide EDR daemons like Falco or Tetragon.
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.
go install github.com/Mutasem-mk4/procscope/cmd/procscope@latest
procscope --version# 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 capabilities and blindspots.
- 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.
| Channel | Status |
|---|---|
| GitHub releases | Available |
go install |
Available |
| Homebrew (macOS/Linux) | Available via Mutasem-mk4/kharma tap |
| Arch / BlackArch package | Available in BlackArch |
| Debian / Kali / Parrot packages | Packaging metadata maintained in-tree; pending distro inclusion |
Note: Running procscope usually requires sudo (eBPF capabilities).
brew tap Mutasem-mk4/kharma
brew install procscopego install github.com/Mutasem-mk4/procscope/cmd/procscope@latestDownload the release asset that matches your architecture from:
Current release assets include:
- Debian package (
.deb) - Linux tarballs for
amd64andarm64
git clone https://github.com/Mutasem-mk4/procscope.git
cd procscope
make build
sudo install -m755 bin/procscope /usr/local/bin/procscopeThese commands are the target install experience after distro acceptance.
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
- Acceptance Risk Assessment
- Security Model
- Privacy Model
- Packaging Guide
- Distribution Submission Playbook
- Comparison
- Design Decisions
See CONTRIBUTING.md.
procscope is heavily community-driven; check issues labeled good-first-issue to get started quickly.
See SECURITY.md for reporting vulnerabilities.
See CODE_OF_CONDUCT.md for community participation guidelines.
procscope was developed by Mutasem Kharma (معتصم خرما), a Security Engineer and eBPF Specialist focused on building high-performance, offensive and defensive security tools for the modern cloud-native landscape. Mutasem specializes in low-level system observation, automated vulnerability research, and autonomous security agents.
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-