pranshuparmar/witr

## 1. 目的 **witr** 的存在是为了回答一个单一的问题： 当某个事物在系统上运行时，无论它是一个进程、一个服务，还是绑定到某个端口的东西，总有其原因。这个原因通常是间接的、不明显的，或者分布在多个层级中，例如 supervisor、容器、服务或 shell。 现有的工具（`ps`、`top`、`lsof`、`ss`、`systemctl`、`docker ps`）公开了状态和元数据。它们展示了正在运行的是*什么*，但需要用户在不同工具的输出之间手动关联，以推断*为什么*运行。 **witr** 让这种因果关系变得明确。 它在单一的、人类可读的输出或**交互式 TUI 仪表板**中，解释了**运行中的事物从何而来**、**它是如何启动的**，以及**此刻是何种系统链在负责它的存在**。 ## 2. 安装 witr 以单一静态二进制文件的形式分发，支持 Linux、macOS、FreeBSD 和 Windows。 witr 还在多种操作系统和生态系统中独立打包和维护。[Repology](https://repology.org/project/witr/versions) 上提供了最新的打包状态概览。请注意，由于独立的审查和验证过程，社区包可能会落后于 GitHub 发布版。 ### 2.1 快速安装 #### Unix (Linux, macOS 和 FreeBSD) ``` curl -fsSL https://raw.githubusercontent.com/pranshuparmar/witr/main/install.sh | bash ```

脚本详情

该脚本将： - 检测您的操作系统（`linux`、`darwin` 或 `freebsd`） - 检测您的 CPU 架构（`amd64` 或 `arm64`） - 下载最新发布的二进制文件和 man page - 将其安装到 `/usr/local/bin/witr` - 将 man page 安装到 `/usr/local/share/man/man1/witr.1` - 传递 INSTALL_PREFIX 以覆盖默认安装路径

#### Windows (PowerShell) ``` irm https://raw.githubusercontent.com/pranshuparmar/witr/main/install.ps1 | iex ```

脚本详情

该脚本将： - 下载最新版本 并校验 checksum。 - 将 `witr.exe` 解压到 `%LocalAppData%\witr\bin`。 - 将 bin 目录添加到您的用户 `PATH` 中。

### 2.2 包管理器

Homebrew (macOS & Linux)

您可以在 macOS 或 Linux 上使用 [Homebrew](https://brew.sh/) 安装 **witr**： ``` brew install witr ```

Conda (macOS, Linux & Windows)

您可以在 macOS、Linux 和 Windows 上使用 [conda](https://docs.conda.io/en/latest/)、[mamba](https://mamba.readthedocs.io/en/latest/) 或 [pixi](https://pixi.prefix.dev/latest/) 安装 **witr**： ``` conda install -c conda-forge witr # 或者使用 mamba mamba install -c conda-forge witr # 或者使用 pixi pixi global install witr ```

Arch Linux (AUR)

在 Arch Linux 及其衍生版上，可以通过 [AUR 包](https://aur.archlinux.org/packages/witr-bin) 安装： ``` yay -S witr-bin # 或者使用 paru paru -S witr-bin # 或者使用你偏好的 AUR helper ```

Winget (Windows)

您可以通过 [winget](https://learn.microsoft.com/en-us/windows/package-manager/winget/) 安装 **witr**： ``` winget install -e --id PranshuParmar.witr ```

NPM (Cross-platform)

您可以使用 [npm](https://www.npmjs.com/package/@pranshuparmar/witr) 安装 **witr**： ``` npm install -g @pranshuparmar/witr ```

FreeBSD Ports

您可以在 FreeBSD 上通过 [FreshPorts port](https://www.freshports.org/sysutils/witr/) 安装 **witr**： ``` pkg install witr # 或 pkg install sysutils/witr ``` 或者从 Ports 构建： ``` cd /usr/ports/sysutils/witr/ make install clean ```

Chocolatey (Windows)

您可以使用 [Chocolatey](https://community.chocolatey.org) 安装 **witr**： ``` choco install witr ```

Scoop (Windows)

您可以使用 [Scoop](https://scoop.sh) 安装 **witr**： ``` scoop install main/witr ```

AOSC OS

您可以从 [AOSC OS 仓库](https://packages.aosc.io/packages/witr) 安装 **witr**： ``` oma install witr ```

GNU Guix

您可以从 [GNU Guix 仓库](https://packages.guix.gnu.org/packages/witr/) 安装 **witr**： ``` guix install witr ```

Uniget (Linux)

您可以使用 [uniget](https://uniget.dev/) 安装 **witr**： ``` uniget install witr ```

Aqua (macOS, Linux & Windows)

您可以使用 [aqua](https://aquaproj.github.io/) 安装 **witr**： ``` # 添加 package aqua g -i pranshuparmar/witr # 安装 package aqua i pranshuparmar/witr ```

Brioche (Linux)

您可以使用 [brioche](https://brioche.dev/) 安装 **witr**： ``` brioche install -r witr ```

预构建包 (deb, rpm, apk)

**witr** 为主流 Linux 发行版提供原生包。您可以从 [GitHub 发布页面](https://github.com/pranshuparmar/witr/releases/latest) 下载最新的 `.deb`、`.rpm` 或 `.apk` 包。 - 使用 `curl` 的通用下载命令： # 请将 curl -LO https://github.com/pranshuparmar/witr/releases/latest/download/ - **Debian/Ubuntu (.deb):** sudo dpkg -i ./witr-*.deb # 或者，使用 apt 来解决依赖问题： sudo apt install ./witr-*.deb - **Fedora/RHEL/CentOS (.rpm):** sudo rpm -i ./witr-*.rpm - **Alpine Linux (.apk):** sudo apk add --allow-untrusted ./witr-*.apk

### 2.3 源码与手动安装

Go (跨平台)

您可以直接从源码安装最新版本： ``` go install github.com/pranshuparmar/witr/cmd/witr@latest ``` 这会将 `witr` 二进制文件放置在您的 `$GOPATH/bin` 或 `$HOME/go/bin` 目录中。请确保此目录在您的 `PATH` 中。

手动安装

如果您倾向于手动安装，请按照适用于您平台的以下简单步骤操作： **Unix (Linux, macOS, FreeBSD)** ``` # 1. 确定 OS 和 Architecture OS=$(uname -s | tr '[:upper:]' '[:lower:]') ARCH=$(uname -m) [ "$ARCH" = "x86_64" ] && ARCH="amd64" [ "$ARCH" = "aarch64" ] && ARCH="arm64" # 2. 下载 binary curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/witr-${OS}-${ARCH}" -o witr # 3. 验证 checksum（可选） curl -fsSL "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -o SHA256SUMS grep "witr-${OS}-${ARCH}" SHA256SUMS | (sha256sum -c - 2>/dev/null || shasum -a 256 -c - 2>/dev/null) rm SHA256SUMS # 4. 重命名并安装 chmod +x witr sudo mkdir -p /usr/local/bin sudo mv witr /usr/local/bin/witr # 5. 安装 man page（可选） sudo mkdir -p /usr/local/share/man/man1 sudo curl -fsSL https://github.com/pranshuparmar/witr/releases/latest/download/witr.1 -o /usr/local/share/man/man1/witr.1 ``` **Windows (PowerShell)** ``` # 1. 确定 Architecture if ($env:PROCESSOR_ARCHITECTURE -eq "AMD64") { $ZipName = "witr-windows-amd64.zip" } elseif ($env:PROCESSOR_ARCHITECTURE -eq "ARM64") { $ZipName = "witr-windows-arm64.zip" } else { Write-Error "Unsupported architecture: $($env:PROCESSOR_ARCHITECTURE)" exit 1 } # 2. 下载 zip Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/$ZipName" -OutFile "witr.zip" # 3. 解压 binary Expand-Archive -Path "witr.zip" -DestinationPath "." -Force # 4. 验证 checksum（可选） Invoke-WebRequest -Uri "https://github.com/pranshuparmar/witr/releases/latest/download/SHA256SUMS" -OutFile "SHA256SUMS" $hash = Get-FileHash -Algorithm SHA256 .\witr.zip $expected = Select-String -Path .\SHA256SUMS -Pattern $ZipName if ($expected -and $hash.Hash.ToLower() -eq $expected.Line.Split(' ')[0]) { Write-Host "Checksum OK" } else { Write-Host "Checksum Mismatch" } # 5. 安装到本地 bin 目录 $InstallDir = "$env:LocalAppData\witr\bin" New-Item -ItemType Directory -Path $InstallDir -Force | Out-Null Move-Item .\witr.exe $InstallDir\witr.exe -Force # 6. 添加到 User Path（永久生效） $UserPath = [Environment]::GetEnvironmentVariable("Path", "User") if ($UserPath -notlike "*$InstallDir*") { [Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User") $env:Path += ";$InstallDir" Write-Host "Added to Path. You may need to restart PowerShell." } # 7. 清理 Remove-Item witr.zip Remove-Item SHA256SUMS ```

### 2.4 免安装运行

Nix Flake

如果您使用 Nix，可以从源码构建 **witr** 并在不安装的情况下运行： ``` nix run github:pranshuparmar/witr -- --help ```

Pixi

如果您使用 [pixi](https://pixi.prefix.dev/latest/)，可以在 Linux 或 macOS 上免安装运行： ``` pixi exec witr --help ```

### 2.5 其他操作

验证安装

``` witr --version man witr ```

Shell 自动补全

`witr` 支持所有参数的 Tab 补全。要启用它，请将相应的行添加到您的 shell 配置中： **Bash** ``` echo 'eval "$(witr completion bash)"' >> ~/.bashrc source ~/.bashrc ``` **Zsh** ``` echo 'eval "$(witr completion zsh)"' >> ~/.zshrc source ~/.zshrc ``` **Fish** ``` witr completion fish | source # 要使其永久生效： witr completion fish > ~/.config/fish/completions/witr.fish ``` **PowerShell** ``` witr completion powershell | Out-String | Invoke-Expression # 要使其永久生效，请将上述行添加到你的 $PROFILE 中 ```

卸载

如果您通过包管理器（Homebrew、Conda 等）安装，请使用相应的卸载命令（例如 `brew uninstall witr`）。 要彻底移除通过脚本/手动安装的 **witr**： **Unix (Linux, macOS, FreeBSD)** ``` sudo rm -f /usr/local/bin/witr sudo rm -f /usr/local/share/man/man1/witr.1 ``` **Windows** ``` Remove-Item -Recurse -Force "$env:LocalAppData\witr" ```

## 3. 交互模式 (TUI) 不带任何参数或使用 `-i` 参数运行 `witr` 会启动**交互模式 (TUI)**。这提供了一个基于终端的实时仪表板，用于探索进程和端口。 ### 核心功能： - **实时进程列表**：实时查看所有正在运行的进程，支持排序和过滤。 - **端口视图**：探索开放端口，并立即查看持有这些端口的进程。 - **进程详情**：深入某个特定进程，查看其完整的祖先树、子进程、环境变量、工作目录等。 - **进程操作**：直接从 UI 发送信号（Kill、Terminate、Pause、Resume）或 Renice 进程。 - **鼠标支持**：使用鼠标进行导航、排序列和点击行。 ## 4. 参数与选项 ``` --env show environment variables for the process -x, --exact use exact name matching (no substring search) -f, --file strings file path(s) to find process for (repeatable) -h, --help help for witr -i, --interactive interactive mode (TUI) --json show result as JSON --no-color disable colorized output -p, --pid strings pid(s) to look up (repeatable) -o, --port strings port(s) to look up (repeatable) -s, --short show only ancestry -t, --tree show only ancestry as a tree --verbose show extended process information -v, --version version for witr --warnings show only warnings ``` 位置参数（不带参数标志）将被视为进程或服务名称。可以传递多个名称。默认情况下，名称匹配使用子串匹配（模糊搜索）。使用 `--exact` 仅匹配具有确切名称的进程。 所有的目标参数（`--pid`、`--port`、`--file`）都是可重复的，并且可以相互混合使用，也可以与位置名称参数混合使用。当提供多个目标时，结果将按顺序显示并带有标签分隔符。所有输出模式（标准、简短、树状、JSON、env、warnings、verbose）均支持多输入。 如果未提供参数或相关参数（`--pid`、`--port`、`--file`），或者显式使用了 `--interactive` 参数，则会启动 TUI。 ## 5. 示例输出 ### 5.1 基于名称的查询 ``` witr node ``` ``` Target : node Process : node (pid 14233) User : pm2 Command : node index.js Started : 2 days ago (Mon 2025-02-02 11:42:10 +05:30) Restarts : 1 Why It Exists : systemd (pid 1) → pm2 (pid 5034) → node (pid 14233) Source : pm2 Working Dir : /opt/apps/expense-manager Git Repo : expense-manager (main) Listening : 127.0.0.1:5001 ``` ### 5.2 简短输出 ``` witr --port 5000 --short ``` ``` systemd (pid 1) → PM2 v5.3.1: God (pid 1481580) → python (pid 1482060) ``` ### 5.3 树状输出 ``` witr --pid 143895 --tree ``` ``` systemd (pid 1) └─ init-systemd(Ub (pid 2) └─ SessionLeader (pid 143858) └─ Relay(143860) (pid 143859) └─ bash (pid 143860) └─ sh (pid 143886) └─ node (pid 143895) ├─ node (pid 143930) ├─ node (pid 144189) └─ node (pid 144234) ``` 注意：_树状视图包含子进程（最多 10 个）并会高亮显示目标进程_。 ### 5.4 多重匹配 ``` witr ng ``` ``` Multiple matching processes found: [1] nginx (pid 2311) nginx -g daemon off; [2] nginx (pid 24891) nginx -g daemon off; [3] ngrok (pid 14233) ngrok http 5000 Re-run with: witr --pid ``` 为了避免子串匹配并仅查找具有确切名称的进程，请使用 `--exact` 参数： ``` witr nginx -x ``` ### 5.5 基于文件的查询 ``` witr --file /var/lib/dpkg/lock ``` 解释保持文件打开的进程。 ### 5.6 多输入 ``` witr nginx --port 5432 --pid 1234 ``` ``` ----- [name: nginx] ----- Target : nginx Process : nginx (pid 2311) ... ----- [port: 5432] ----- Target : postgres Process : postgres (pid 891) ... ----- [pid: 1234] ----- Target : node Process : node (pid 1234) ... ``` 所有的目标参数都是可重复的并且可以混合使用。结果将按您输入的顺序显示。所有的输出模式（`--short`、`--tree`、`--json`、`--env`、`--warnings`、`--verbose`）均支持多输入。 ## 6. 平台支持 - **Linux** (x86_64, arm64) - 完整功能支持 (`/proc`)。 - **macOS** (x86_64, arm64) - 使用 `ps`、`lsof`、`sysctl`、`pgrep`。 - **Windows** (x86_64, arm64) - 使用 `Get-CimInstance`、`tasklist`、`netstat`。 - **FreeBSD** (x86_64, arm64) - 使用 `procstat`、`ps`、`lsof`。 ### 5.1 功能兼容性矩阵 | 功能 | Linux | macOS | Windows | FreeBSD | 备注 | |---------|:-----:|:-----:|:-------:|:-------:|-------| | **进程选择** | | 按名称 | ✅ | ✅ | ✅ | ✅ | | | 按 PID | ✅ | ✅ | ✅ | ✅ | | | 按端口 | ✅ | ✅ | ✅ | ✅ | | | 按文件 | ✅ | ✅ | ❌ | ✅ | | | 多/混合输入 | ✅ | ✅ | ✅ | ✅ | 可重复的参数，混合类型。 | | 精确匹配 | ✅ | ✅ | ✅ | ✅ | | | 完整命令行 | ✅ | ✅ | ✅ | ✅ | | | 进程启动时间 | ✅ | ✅ | ✅ ✅ | | | 工作目录 | ✅ | ✅ | ✅ | ✅ | | | 环境变量 | ✅ | ⚠️ | ❌ | ✅ | macOS：由于 SIP 限制，仅部分支持。 | | **网络** | | 监听端口 | ✅ | ✅ | ✅ | ✅ | | | 绑定地址 | ✅ | ✅ | ✅ | ✅ | | | 端口 → PID 解析 | ✅ | ✅ | ✅ | ✅ | | | **服务检测** | | 服务管理器 | ✅ | ✅ | ✅ | ✅ | Linux: systemd，macOS: launchd，Windows: Services，FreeBSD: rc.d | | 服务描述 | ✅ | ✅ | ✅ | ✅ | Linux: `Description`，macOS: `Comment`，Windows: `Display Name`，FreeBSD: `rc` 标头 | | 配置源 | ✅ | ✅ | ✅ | ✅ | Linux: Unit 文件，macOS: Plist，Windows: 注册表键，FreeBSD: Rc 脚本 | | Supervisor | ✅ | ✅ | ✅ | ✅ | | | 容器 | ✅ | ✅ | ✅ | ✅ | Docker (包含 Compose 映射)，Podman，K8s (Kubepods)，Containerd。macOS/Linux 上的 Colima。FreeBSD 上的 Jails。 | | SSH 会话检测 | ✅ | ✅ | ✅ | ✅ | 检测远程 IP 和终端。 | | tmux/screen 检测 | ✅ | ✅ | ❌ | ✅ | 在来源中显示会话名称。 | | 计划任务检测 | ✅ | ✅ | ❌ | ❌ | Linux: systemd 定时器，macOS: launchd 间隔/日历。 | | Snap/Flatpak 检测 | ✅ | ❌ | ❌ | ❌ | | | **健康与诊断** | | CPU 使用率检测 | ✅ | ✅ | ✅ | ✅ | | | 内存使用率检测 | ✅ | ✅ | ✅ | ✅ | | | 健康状态检测 | ✅ | ✅ | ✅ | ✅ | | | 打开的文件/句柄 | ✅ | ✅ | ⚠️ | ✅ | Windows：仅显示数量。 | | 已删除的二进制文件检测 | ✅ | ✅ | ✅ | ✅ | 如果可执行文件丢失则发出警告。 | | Capability 警告 | ✅ | ❌ | ❌ | ❌ | 对非 root 进程的危险 capability 发出警告。 | | **上下文** | | Git 仓库/分支检测 | ✅ | ✅ | ✅ | ✅ | | | **交互模式 (TUI)** | | 进程仪表板 | ✅ | ✅ | ✅ | ✅ | | | 端口仪表板 | ✅ | ✅ | ✅ | ✅ | | | 进程详情 | ✅ | ✅ | ✅ | ✅ | | | 进程操作 | ✅ | ✅ | ❌ | ✅ | | **图例：** ✅ 完全支持 | ⚠️ 部分/有限支持 | ❌ 不可用 ### 5.2 权限说明 #### Linux/FreeBSD witr 会检查系统目录，这可能需要提升权限。 如果您没有看到预期的信息，请尝试使用 sudo 运行 witr： ``` sudo witr [your arguments] ``` #### macOS 在 macOS 上，witr 使用 `ps`、`lsof` 和 `launchctl` 来收集进程信息。某些操作可能需要提升权限： ``` sudo witr [your arguments] ``` 注意：由于 macOS 的系统完整性保护 (SIP)，某些系统进程详情即使使用 sudo 也可能无法访问。 #### Windows 在 Windows 上，witr 使用 `Get-CimInstance`、`tasklist` 和 `netstat`。要查看其他用户或系统服务拥有的进程详情，您必须以**管理员**身份运行终端。 ``` # 在 Administrator PowerShell 中运行 .\witr.exe [your arguments] ``` ## 7. 目标 ### 主要目标 - 解释**为什么存在某个进程**，而不仅仅是它存在 - 减少调试和中断期间的认知时间 - 开箱即用，零配置 - 安全、只读且非破坏性 - 优先考虑清晰度而非完整性 ### 非目标 - 不是一个监控工具 - 不是一个性能分析器 - 不能替代 systemd/docker 工具 - 不是一个修复或自动解决问题的工具 ## 8. 核心概念 witr 将**一切视为一个进程问题**。 端口、服务、容器和命令最终都会映射到 **PID**。一旦确定了 PID，witr 就会构建一条因果链来解释_为什么那个 PID 会存在_。 在其核心，witr 回答了： 1. 什么正在运行？ 2. 它是如何启动的？ 3. 是什么使它保持运行？ 4. 它属于什么上下文？ ## 9. 输出行为 ### 9.1 输出原则 - 默认单屏显示（尽力而为） - 确定性的顺序 - 叙述式的解释 - 尽力检测并明确指出不确定性 ### 9.2 退出码 witr 返回有意义的退出码，可用于脚本、CI 流水线和监控： | 代码 | 含义 | |------|---------| | 0 | 干净：找到进程，无警告 | | 1 | 警告：找到进程，但有一个或多个警告 | | 2 | 未找到：没有匹配的进程或服务 | | 3 | 权限拒绝：权限不足 | | 4 | 无效输入：参数错误或匹配不明确 | #### 示例用法： ``` witr nginx --short case $? in 0) echo "All clear" ;; 1) echo "Warnings detected" ;; 2) echo "Process not running" ;; 3) echo "Need elevated privileges" ;; 4) echo "Invalid input or ambiguous match" ;; esac ``` ### 9.3 标准输出部分 #### 目标 用户询问的内容。 #### 进程 可执行文件、PID、用户、命令、启动时间和重启次数。 #### 为什么存在 展示进程如何产生的因果祖先链。 这是 witr 的核心价值。 #### 来源 负责启动或监管进程的主要系统（尽力而为）。 示例： - 带有定时器触发服务的时间表信息的 systemd unit (Linux) - 带有时间表/触发器详情的 launchd 服务 (macOS) - SSH 会话（带有远程 IP 和终端） - docker 容器 - pm2 - cron - 交互式 shell（检测 tmux/screen 会话） - Snap/Flatpak 沙箱 (Linux) 仅选择**一个主要来源**。 #### 上下文 (尽力而为) - 工作目录 - Git 仓库名称和分支 - 容器名称 / 镜像 (docker、podman、kubernetes、colima、containerd) - 公有与私有绑定 #### 警告 非阻碍性的观察结果，例如： - 进程以 root 身份运行 - 非 root 进程上具有危险的 Linux capabilities (CAP_SYS_ADMIN 等) - 进程正在公共接口 (0.0.0.0 / ::) 上监听 - 已多次重启（仅在超过阈值时警告） - 进程占用高内存 (>1GB RSS) - 进程已运行超过 90 天 - 已删除的二进制文件，库注入指示符 (LD_PRELOAD、DYLD_*) ## 10. 成功标准 如果满足以下条件，witr 就是成功的： - 用户可以在几秒钟内回答“它为什么在运行？” - 它减少了对多种工具的依赖 - 输出在压力下也可以理解 - 用户在事件发生时信任它 ## 11. 赞助者 特别感谢支持 **witr** 的人们 ❤️

标签：Awesome, EVTX分析, FreeBSD, Go, Mr. Robot, Ruby工具, TUI, witr, 威胁情报, 开发者工具, 开源, 排查工具, 无线安全, 日志审计, 端口查询, 系统管理, 终端用户界面, 网络连接, 运维工具, 运行状态, 进程分析