diff --git a/README.md b/README.md index 1251a30..05c2c14 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,10 @@ - **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. +Trace malware behavior, investigate suspicious binaries, and audit container workloads — without `strace` overhead or the complexity of system-wide EDR daemons.

- Latest Release @@ -25,260 +23,68 @@ Trace malware behavior, investigate suspicious binaries, and audit container wor Go Report Card
- CI Status License
- Powered by eBPF Latency Heuristics Enabled

-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. +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. -**Not designed for:** EDR, SIEM, Kubernetes-first monitoring, policy enforcement, or whole-system tracing. +**Designed for:** security research, malware triage, incident response, and deep debugging. +**Not designed for:** EDR, SIEM, or whole-system tracing. ## Quick Start [![Try it in the Browser](https://img.shields.io/badge/Try_in_Browser-Killercoda-23C13F?style=flat-square&logoColor=white)](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 +[Full Installation Guide](docs/install.md) | [Usage & Output Formats](docs/usage.md) -| 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 | +## Capabilities -> **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. +| Category | Events | Details | +|----------|--------|---------| +| **Process** | exec, fork, exit | [Support Matrix](docs/support-matrix.md) | +| **Files** | open, rename, unlink, chmod | [Support Matrix](docs/support-matrix.md) | +| **Network** | connect, accept, bind, listen | [Support Matrix](docs/support-matrix.md) | +| **Privileges** | setuid, setgid, ptrace | [Support Matrix](docs/support-matrix.md) | ## 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 -``` +- **Linux kernel 5.8+** with BTF support. +- **Root** privileges or specific eBPF capabilities. +- **Architectures:** amd64, arm64. -### Markdown Summary +See [Support Matrix](docs/support-matrix.md) for details. -Team-ready report with overview, process tree, event breakdown, file/network activity tables, notable events, and honest limitations. +## Why procscope? -## Configuration & Flags +- **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. +- **Low Overhead:** eBPF-powered observation with minimal performance impact. -| 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. +[Compare with Tracee, Tetragon, and strace](docs/comparison.md) ## 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/) +- [Architecture & Design](docs/architecture.md) +- [Security & Privacy Model](docs/security-model.md) +- [Installation Guide](docs/install.md) +- [Usage & Flags](docs/usage.md) +- [Packaging Status](docs/packaging.md) ## 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. +`procscope` is community-driven. See [CONTRIBUTING.md](CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) to get involved. ## License @@ -286,10 +92,4 @@ See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community participation guideli --- -## 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-* +Developed by [Mutasem Kharma (معتصم خرما)](https://github.com/Mutasem-mk4). diff --git a/docs/install.md b/docs/install.md new file mode 100644 index 0000000..5648fdf --- /dev/null +++ b/docs/install.md @@ -0,0 +1,54 @@ +# Installation Guide + +This guide covers the various ways to install `procscope`. + +> **Note:** Running `procscope` usually requires `sudo` (eBPF capabilities). + +## 1. Homebrew (Recommended) + +```bash +brew tap Mutasem-mk4/kharma +brew install procscope +``` + +## 2. Go Install (Requires Go 1.24+) + +```bash +go install github.com/Mutasem-mk4/procscope/cmd/procscope@latest +``` + +## 3. Direct Download + +Download the release asset that matches your architecture from: + +- [Latest Releases](https://github.com/Mutasem-mk4/procscope/releases/latest) + +Available assets include: +- Debian package (`.deb`) +- Linux tarballs for `amd64` and `arm64` + +## 4. Build from Source + +Ensure you have Go 1.24+ and `make` installed. + +```bash +git clone https://github.com/Mutasem-mk4/procscope.git +cd procscope +make build +sudo install -m755 bin/procscope /usr/local/bin/procscope +``` + +## 5. Native Package Managers + +`procscope` is becoming available in official repositories. + +**BlackArch Linux:** +```bash +sudo pacman -S procscope +``` + +**Kali Linux & Parrot OS:** +```bash +# Pending official inclusion; use the .deb package from releases in the meantime. +sudo dpkg -i procscope_*.deb +``` diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..423c81b --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,62 @@ +# Usage and Output Formats + +This document describes how to configure `procscope` and the various output formats it provides. + +## 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 | + +## 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.