Mutasem-mk4/procscope

# procscope **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. ## 快速开始 ``` # 跟踪命令 sudo procscope -- ./suspicious-binary # 附加到正在运行的进程 sudo procscope -p 1234 # 保存证据包 + Markdown 报告 sudo procscope --out case-001 --summary report.md -- ./installer.sh # 以 JSONL 格式流式传输事件 sudo procscope --jsonl events.jsonl -- ./tool ``` ## procscope 观察内容 | 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 | ## 要求 - **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). ### 1. 直接下载（推荐） 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.deb ``` **For 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/ ``` ### 2. Go 安装（源码） 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@latest ``` ### 3. 原生包管理器（待上游集成） We are actively tracking upstream approvals for major distributions. Once merged: **BlackArch Linux:** ``` sudo pacman -S procscope ``` **Kali Linux & Parrot OS:** ``` sudo apt update && sudo apt install procscope ``` ## 输出格式 ### 实时时间线 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 事件流 Machine-readable, one event per line: ``` procscope --jsonl events.jsonl -- ./command ``` ### 证据包 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 摘要 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](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](docs/comparison.md) for honest, detailed comparison. ## 文档 - [Building from Source](BUILDING.md) - [Architecture](docs/architecture.md) - [Support Matrix](docs/support-matrix.md) - [Security Model](docs/security-model.md) - [Privacy Model](docs/privacy-model.md) - [Packaging Guide](docs/packaging.md) - [Comparison](docs/comparison.md) - [Design Decisions](docs/design-decisions/) ## 贡献 See [CONTRIBUTING.md](CONTRIBUTING.md). ## 安全 See [SECURITY.md](SECURITY.md) for reporting vulnerabilities. ## 许可 [MIT](LICENSE) **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?*

标签：DAST, Docker镜像, Go, Ruby工具, Web截图, 云资产清单, 命名空间, 安全调试, 客户端加密, 容器安全, 开源安全工具, 恶意软件分析, 文件活动, 日志审计, 特权转换, 网络连接, 调试, 运行时取证, 进程生命周期, 进程追踪, 逆向工程, 逆向工程平台