https://github.com/Mutasem-mk4/procscope
Zero-overhead eBPF process tracer for Linux malware triage and incident response. Traces syscalls, network, and file events per-process without strace overhead.
https://github.com/Mutasem-mk4/procscope
bpf cli container-security ebpf forensics golang incident-response kali-linux kubernetes-security linux-security malware-analysis monitoring observability process-monitoring reverse-engineering runtime-security security-tools threat-detection threat-hunting tracing
Last synced: 4 days ago
JSON representation
Zero-overhead eBPF process tracer for Linux malware triage and incident response. Traces syscalls, network, and file events per-process without strace overhead.
- Host: GitHub
- URL: https://github.com/Mutasem-mk4/procscope
- Owner: Mutasem-mk4
- License: mit
- Created: 2026-04-16T23:49:10.000Z (15 days ago)
- Default Branch: master
- Last Pushed: 2026-04-27T14:41:03.000Z (4 days ago)
- Last Synced: 2026-04-27T16:25:45.569Z (4 days ago)
- Topics: bpf, cli, container-security, ebpf, forensics, golang, incident-response, kali-linux, kubernetes-security, linux-security, malware-analysis, monitoring, observability, process-monitoring, reverse-engineering, runtime-security, security-tools, threat-detection, threat-hunting, tracing
- Language: C
- Homepage: https://killercoda.com/mutasem04/scenario/procscope-scenario
- Size: 27.4 MB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: docs/support-matrix.md
Awesome Lists containing this project
- fucking-awesome-go - procscope - Process-scoped runtime investigator using eBPF to trace process lifecycle, file activity, and network connections. (Security / HTTP Clients)
- awesome-go - procscope - Process-scoped runtime investigator using eBPF to trace process lifecycle, file activity, and network connections. (Security / HTTP Clients)
README
# procscope — eBPF Process Tracer for Linux by Mutasem Kharma (معتصم خرما)
**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.
## Quick Start
[](https://killercoda.com/mutasem04/scenario/procscope-scenario)
### 1-Minute Install (Go 1.24+)
```bash
go install github.com/Mutasem-mk4/procscope/cmd/procscope@latest
procscope --version
```
```bash
# 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
```
## What procscope Observes
| 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](docs/support-matrix.md) for exact details on capabilities and blindspots.
## Requirements
- **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.
## Packaging Status
| 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 |
## Installation
Note: Running procscope usually requires `sudo` (eBPF capabilities).
### 1. Homebrew (Recommended)
```bash
brew tap Mutasem-mk4/kharma
brew install procscope
```
### 2. Go Install
```bash
go install github.com/Mutasem-mk4/procscope/cmd/procscope@latest
```
### 2. Direct Download
Download the release asset that matches your architecture from:
- https://github.com/Mutasem-mk4/procscope/releases/latest
Current release assets include:
- Debian package (`.deb`)
- Linux tarballs for `amd64` and `arm64`
### 3. Build from Source
```bash
git clone https://github.com/Mutasem-mk4/procscope.git
cd procscope
make build
sudo install -m755 bin/procscope /usr/local/bin/procscope
```
### 4. Native Package Managers
These commands are the target install experience after distro acceptance.
**BlackArch Linux:**
```bash
sudo pacman -S procscope
```
**Kali Linux & Parrot OS:**
```bash
sudo apt update && sudo apt install procscope
```
## Output Formats
### Live Timeline
Compact, 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
```
### JSONL Event Stream
Machine-readable, one event per line:
```bash
procscope --jsonl events.jsonl -- ./command
```
### Evidence Bundle
Structured 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
```
### Markdown Summary
Team-ready report with overview, process tree, event breakdown, file/network activity tables, notable events, and honest limitations.
## Configuration & Flags
| 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 |
## Safe Defaults
- **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
## Architecture
```
┌───────────────────────────────────────┐
│ 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](docs/architecture.md) for detailed design.
## Comparison with Other Tools
| 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](docs/comparison.md) for honest, detailed comparison.
## Documentation
- [Building from Source](BUILDING.md)
- [Architecture](docs/architecture.md)
- [Support Matrix](docs/support-matrix.md)
- [Acceptance Risk Assessment](docs/acceptance-risk.md)
- [Security Model](docs/security-model.md)
- [Privacy Model](docs/privacy-model.md)
- [Packaging Guide](docs/packaging.md)
- [Distribution Submission Playbook](docs/packaging-submission-playbook.md)
- [Comparison](docs/comparison.md)
- [Design Decisions](docs/design-decisions/)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md).
`procscope` is heavily community-driven; check issues labeled `good-first-issue` to get started quickly.
## Security
See [SECURITY.md](SECURITY.md) for reporting vulnerabilities.
## Community
See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community participation guidelines.
## License
[MIT](LICENSE)
---
## About the Author
**procscope** was developed by [Mutasem Kharma (معتصم خرما)](https://github.com/Mutasem-mk4), 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-*