Content
# proc
Rust 编写的交互式 TUI 系统进程管理器。把 **进程管理 + 网络分析 + USB 占用 + 监控 + Docker + 安全评分 + 降频检测 + 磁盘 I/O + 终端录屏 + 告警 + SMART 磁盘健康 + per-process 网络流量 + DNS 查询日志 + 容器 exec** 融合到一个 TUI 中。**Windows-only 应用**（Windows 10 1809+ / Windows 11 x64，详见 [ADR-0022](docs/adr/0022-windows-only-platform.md)）。
> **v0.17.0（2026-07-10）— 5 主题大 cycle（性能 + 可观测性 + VT100 + record + 写操作）**：proc 历史上最大 cycle（~5540 行业务代码 + 测试 + ADR/doc），5 主题合并全交付——(1) **主题 A 性能优化**（TD-47 `parent_chain: Vec<(u32, Arc<str>)>` 零 heap alloc + TD-54 MCP handler 持久 `snapshot` 字段 1s tick refresh + TD-44 itoa + TD-45 bincode encoding 选项层 + TD-50 `proc_smart` deprecated）；(2) **主题 B 可观测性**（rmcp 0.11 `ResourceRoute` trait 暴露 3 资源 URI + SSE transport 结构化 stub + TD-52 sparkline `proc_metrics_history` tool 30s 历史采样）；(3) **主题 F VT100 replay**（`Vt100ToUiFrameConverter` 1:1 映射澄清 ADR-0028 misreading + 透明转码路径 + RAII 临时文件，VT100 录屏现享受 search / 倒放 / 书签全部能力）；(4) **record 暴露**（spawn `proc record --no-tui` 子进程 + `record_handle` 跨 tool call 保活 + `confirm: bool` 必传 gate，[ADR-0029](docs/adr/0029-record-exposure-and-confirm-mechanism.md) 翻盘 ADR-0025b）；(5) **USB release + docker-rm 写操作**（`proc_usb_release` 三步链路 kill + flush + eject + `proc_docker_rm` / `image_rm` / `volume_rm` bollard API）。MCP tool 总数 **39 → 46**（+7 tool）。cycle 7 stage 全交付（5 主题 + 4 份新 ADR 0026~0029 + REVIEW-v0.17 P0 0 / P1 2 / P2 8，不触发拆分）。详见 [CHANGELOG](CHANGELOG.md)。
> **v0.15.0（2026-07-06）— MCP 全功能暴露 cycle（查询类）**：把 proc 已落地但 MCP 未暴露的查询类能力全部透出给 LLM agent——(1) **MCP 模块骨架重构**（`handler.rs` 单文件 1156 行 → `handler/{mod, cli, inspect, metrics}.rs` 4 子 module，[ADR-0024](docs/adr/0024-mcp-handler-module-split.md)）；(2) **CLI 命令 9 tool 直接暴露**（`proc_flows` / `proc_throttle` / `proc_export` / `proc_docker_inspect` / `proc_docker_images` / `proc_docker_volumes` / `proc_docker_events` / `proc_monitor_add` / `proc_monitor_remove`）；(3) **详情页 6 Tab 合并 1 个 `proc_inspect(pid, tab=...)` tool**（[ADR-0023](docs/adr/0023-mcp-inspect-tool-merge.md)，schema 自描述，与 v0.7 既有 `proc_handles` 互补）；(4) **系统级 metrics 5 tool**（`proc_metrics_system` / `gpu` / `disk_io` / `smart` / `thermal`，让 agent 看到系统全貌）。MCP tool 总数 **17 → 32**（agent 视角最大价值缺口补完，写操作 + 录屏类留 v0.16）。cycle 4 stage 全交付（~1700 行业务代码 + 39 新集成测试 + REVIEW-v0.15 P0 0 / P1 3 / P2 5，TD-50~54 归档）。详见 [CHANGELOG](CHANGELOG.md)。
> **v0.14.0（2026-07-06）— 录屏回放 v2 cycle**：4 大能力补完录屏事后分析体验——(1) **文件格式 v3 按需加载**（解决长 session OOM：30 min × 1000 进程从 9s 启动 + 10 GB RAM 优化到 < 100ms + ~12 MB，PERF-BASELINE TD-45 闭环）+ `RecordingFooter` 元数据 + v1/v2 老文件 `.prec.idx` sidecar 兼容 + CLI `--info` 不开 TUI 输出元数据；(2) **书签系统**（`b` 录制时添加 / `B` 回放时打开面板 / `.bookmarks.json` sidecar 持久化）；(3) **时间轴搜索**（`/` 进入 FilterExpr 5 维度：`cpu > 80` / `mem > 500mb` / `name =~ /chrome/i` / `anomaly.severity = critical` / `timestamp > ...` + substring 模式 + `n`/`N` 跳转 + timeline `●` 高亮）；(4) **倒放**（`r` 切方向 + tick 双向分支 + timeline `▶`/`◀`/`⏸` 三态，倒放到首帧自动暂停与正向到末帧暂停对称）。cycle 5 stage 全交付（方案 A 完整 v2，~1750 行业务代码 + 127 新测试）；REVIEW-v0.14 P0 0 / P1 1 / P2 1，TD-49 归档（VT100 replay 无倒放/搜索 + 长录屏搜索遍历优化）。详见 [CHANGELOG](CHANGELOG.md)。
> **v0.13.0（2026-07-05）— 性能 baseline cycle**：建立 criterion benchmark suite（6 个 hot path × 多档 fixture = 25 数据点）+ 产出 [PERF-BASELINE 报告](docs/reviews/PERF-BASELINE-v0.13.md)。**用户拍板方案 c**：验证 proc 当前架构在 1000 进程规模下无显著性能瓶颈，跳过 stage 3+ 优化。cycle 全程**不动业务代码**（1115 passed / 0 failed / 3 ignored 基线不变）；4 个候选项（parent_chain Arc 重构 / tui format! 风暴 / record deserialize 加速 / command_palette fuzzy）归档 tech-debt [TD-44/45/46/47](docs/tech-debt.md) 留 v0.14+ cycle 评估（含 1 个侦察报告误读纠错）。
> **v0.12.0（2026-07-04）** Windows-only 平台定位 + UX polish cycle：**ADR-0022 锁定 Windows-only 决策**（移除全部 Linux/macOS 代码——src/ebpf/ 整模块 + src/psi.rs + nvtop / nethogs / unsupported.rs 删 + ~25 文件 cfg gate 清理）/ **签名验证完整度**（SignatureStatus 9 状态机加 Expired/UntrustedRoot/ChainError + TRUSTED_SIGNERS 扩到 24 vendor + 用户配置 `trusted_signers.toml`）/ **FilterExpr 修复**（`mem > 50%` 按总内存换算 silent bug + regex `\/` escape 让 CIDR / URL pattern 能写）/ **6 个 v0.11 REVIEW-13 P2 修复**（diag JSON 加 dns_collector / NetworkIn HashSet O(1) / R17 系统启动白名单 / R18 Downloads 去重 / property_at_index lifetime 修正 / MCP DNS 持久 collector）。全量回归 1115 tests passed / 0 failed。详见 [CHANGELOG](CHANGELOG.md)。
> **已知限制**：**Windows-only 平台**（v0.12 起 proc 转为 Windows-only，Linux / macOS 用户迁移路径 `git checkout v0.11.0`）；Win10 < 1809 admin 下 Schannel event 1793 不 fire；worker restart 3 次失败后仍永久死亡；DNS ETW 仅 Windows 管理员启用（非 admin 走 PowerShell fallback）。详见 [tech-debt](docs/tech-debt.md)。
> **v0.11.0（2026-07-01）** 安全 + 可靠性大版本：**Worker Restart 真正实装**（TD-4 清零，panic 后指数退避 5s/30s/5min 自动重启，3 次失败永久死亡）/ **DNS ETW 替代 PowerShell probe**（CPU 3-5% → < 0.5%，延迟 500ms-1s → < 50ms，PowerShell fallback 保留）/ **FilterExpr v2 网络字段**（`sni/dns_name/remote_addr/remote_port/bytes_out/bytes_in/source`）/ **进程签名验证 R16**（WinVerifyTrust 6 状态机 + BackgroundScorer 异步）/ **进程父子链 R17**（Office → shell / Browser → shell / ScriptInterpreter 三档扣分）/ **可疑启动路径 R18**（%TEMP% / %APPDATA% / Downloads + R16 协同扣分）。全量回归 1146 tests passed / 0 failed。详见 [CHANGELOG](CHANGELOG.md)。
> **已知限制**：Win10 < 1809 admin 下 Schannel event 1793 不 fire（延续 v0.10）；worker restart 3 次失败后仍永久死亡；DNS ETW 仅 Windows 管理员启用（非 admin 走 PowerShell fallback）；Linux ebpf 编译路径未在本机验证（TD-19 延续）。详见 [tech-debt](docs/tech-debt.md)。
> **v0.10.0（2026-06-28）** 跨平台 SNI 对齐：**Windows Schannel ETW SNI 落地**（手写 windows-rs ETW + TDH 动态 schema，event 1793 / TargetName 字段实测修订）/ **ProcessFlow.source 字段**（`Ebpf` / `Schannel` enum，跨平台在 ProcessFlow 数据结构统一）/ **R15 跨平台激活**（白名单同时检查 sni + dns_name）/ **`proc flows` 跨平台 CLI**（表格加「来源」列，JSON 自动加 source 字段）/ **REVIEW-11 P1 修复**（Schannel-only flow 退出感知 + spawn 失败句柄清理）。弥补 v0.7 阶段 8 eBPF 仅 Linux 的缺位。全量回归 959 tests passed / 0 failed。详见 [CHANGELOG](CHANGELOG.md)。
>
> **已知限制**：Win10 < 1809 admin 下 Schannel event 1793 不 fire（worker 启动成功但 UI 显示 0 条）；Linux ebpf 编译路径未在本机验证（v0.8.0 cycle stage 1 主动推迟，本 cycle 不依赖）。详见 [tech-debt TD-19 / TD-20](docs/tech-debt.md)。
> **v0.8.0（2026-06-28）** 小修一波清 + FilterExpr 扩展：**FilterExpr 全 view 支持**（Tree / AppGroup 视图按 `:` 也能用 `cpu > 5 AND name =~ /chrome/` 过滤）/ **错误信息中文化**（不再直出 nom 内部 `TakeWhile1`，改友好提示「缺少字段名/值」）/ **Linux CI 加固**（全量 `cargo test --release` + 测试 bin 数 ≥ 30 校验防 cfg-gate 静默 skip）/ **Linux stub 测试覆盖**（env/dlls/handles/memory 降级路径有早期告警）。全量回归 930 tests passed / 0 failed。详见 [CHANGELOG](CHANGELOG.md)。
> **v0.7.0（2026-06-28）** 新增三大主题：**生态卡位**（`proc mcp serve` LLM agent 接入 / shell 补全 / Ctrl+P 命令面板 / FilterExpr 表达式搜索 `cpu > 5 AND name =~ /chrome/`）/ **平台深度**（Linux PSI 监控 / Win11 EcoQoS 切换 / Win ETW per-process 磁盘 IO / Linux eBPF flow graph）/ **架构债清理**（App 拆 5 个 panel controller）。全量回归 910 tests passed / 0 failed。详见 [CHANGELOG](CHANGELOG.md)。
## 功能
`proc` 把 **进程管理 + 网络分析 + 安全评分 + 资源监控 + USB 占用 + 进程守护 + Docker + 终端录屏 + 告警** 融合到一个 TUI 中，所有面板共享一份系统快照（`SysinfoRegistry` 全局单例），后台 worker 体系（`SnapshotWorker<T>` / `LightWorker` / `HeavyWorker` / `BackgroundScorer`）保证主线程 50ms tick 不阻塞。
### 6 大主面板
| 面板 | 切换 | 能力 |
|---|---|---|
| 进程列表 | `1` | 按 CPU / 内存 / PID / 名称 / 安全分 / 磁盘读 / 磁盘写 / **网络收 / 网络发** 9 字段排序（持久化到 `ui.toml`），模糊搜索，多选批量终止，`v` 切应用分组视图（按 `.exe` 聚合，CPU/内存/进程数三字段）<sup>v0.5.0</sup> |
| 进程树 | `2` | 父子层级展开/折叠，孤儿 / 僵尸 / 残存进程检测，`o` 一键选孤儿、`z` 一键选僵尸 |
| 端口/网络 | `3` | 按端口 / 按进程 / 按远程三种视图；6 种异常模式自动告警（CLOSE_WAIT 堆积、TIME_WAIT 异常、远程地址爆炸等）；网络诊断工具箱 Ping / DNS 反查 / Whois / Traceroute / 端口探测；**`D` 切换 DNS 查询日志子视图**<sup>v0.5.0</sup>；**TCP 传输质量摘要**（重传率 / RST 率告警）<sup>v0.5.0</sup> |
| USB 助手 | `4` | 句柄占用检测（`filelocksmith`）+ 风险分级（Safe / Warning / Critical）+ 缓存刷新 + 安全弹出引导 + 持续监测模式 |
| 监控 | `5` | 按 PID / 端口 / 命令三种 Target；`NotifyOnly` 或 `AutoRestart` 指数退避策略；Critical 告警推 Toast |
| Docker | `6` | 容器列表 + 实时事件流 + 健康检查 + 资源统计；**容器内进程（top）/ 日志模式（logs）/ 镜像 / 卷视图**<sup>v0.5.0</sup>；**`e` exec 进容器嵌入式 PTY**<sup>v0.5.0</sup>；支持命名管道 / TCP 双连接；事件流 `sync_channel(64)` 背压 |
### Process Inspector<sup>v0.5.0</sup>
Press `Enter` on a process list/tree to enter the details page, with 6 tabs at the top to switch between inspection views:
| Tab | Content | Data Source |
|---|---|---|
| **Summary** | Classification / Parent Process / CPU / Memory / Disk / Runtime / exe / cmd / cwd / Port Summary / Network Summary / Security Score / Risk Factors / **Priority + affinity**<sup>v0.5.0</sup> | sysinfo + `port_map` |
| **Environment** | Process environment variable list (KEY=VALUE), `/` case-insensitive search filter, `↑↓ PgUp PgDn Home End` scrolling | Win: PEB walk (`NtQueryInformationProcess` + `ReadProcessMemory`)；Linux: `/proc/<pid>/environ` |
| **Network** | All listening and connections of this PID + **Recent 5 DNS queries**<sup>v0.5.0</sup>: Protocol / Local / Remote / Status / Process Name | Reuse `port_map::find_ports_by_pid` |
| **DLL** | Loaded modules (Windows DLL / Linux `.so`), sorted by path letters, `/` search; table columns: Path / Base Address / Size | Win: `CreateToolhelp32Snapshot`；Linux: Parse `/proc/<pid>/maps` and merge r-xp / r--p / rw-p multi-segment mappings |
| **Handles**<sup>v0.5.0</sup> | All handles opened by the process: File / RegistryKey / Event / Semaphore / Mutant / Section / Process / Thread / Token；**`Ctrl+F` search within handles** | Win: `NtQuerySystemInformation` + `DuplicateHandle` + `NtQueryObject`；Linux: `/proc/<pid>/fd` |
| **Memory Mapping**<sup>v0.5.0</sup> | VirtualQueryEx / `/proc/<pid>/maps` memory regions: Base Address / Size / Status / Protection / Mapping File Name | Win: `VirtualQueryEx`；Linux: `/proc/<pid>/maps` |
For non-Win/Linux platforms like macOS, the Environment / DLL / Handles / Memory tabs display a "Not supported on this platform" message. Within the details page, press `F5` to force re-collect data (replacing `r` from v0.6.0 onwards, with `r` showing deprecation), `y` to copy process information to the clipboard (similar to vim's yank, replacing `c` from v0.6.0 onwards), `v` to toggle secret masking for the Env tab (forced masking during screen recording), `/` for search, `Tab/Shift+Tab` to switch tabs, `+` / `-` to adjust priority, and `Esc` to exit search and then exit the page.
### Security Scoring
Each process comes with a **0-100 score** (100 = secure), based on **18 independent checks** (expanded to 18 checks from v0.11.0 onwards, including R16 signature verification, R17 parent-child chain, and R18 suspicious path checks, in conjunction with existing v0.6 path checks; see [ADR-0021](docs/adr/0021-process-signature-verification.md) and [CONTEXT.md](CONTEXT.md) for R16/R17/R18):
- **Signature** Authenticode digital signature
- **Parent-Child Chain** Parent process chain integrity (e.g., `explorer.exe → chrome.exe` is reasonable)
- **Path** Executable file path legitimacy (e.g., `C:\Windows\System32\` vs. temporary directory)
- **Command Line** Suspicious patterns (encoding base64, hidden windows, suspicious parameters, etc., 20+ patterns)
- **Network Behavior** Connection count / remote address / listening port anomalies
- **Name Impersonation** `scvhost.exe` / `chr0me.exe` etc., homoglyph attacks
- **Resource Anomalies** CPU / memory peaks
- **Child Process Explosion** Deriving many child processes within a short time
- **Privilege Escalation** Requesting overly high privileges
- **svchost Integrity** System service host integrity
- **DLL Loading** Loaded DLL legitimacy
- **Token Privileges** Token privilege audit
- **Reputation Cache** File SHA256 reputation (streaming hash + 64MB limit to prevent OOM)
Press `S` (uppercase) to sort by security score, with suspicious processes listed first; the **Summary tab** in the details page displays all risk factors and deductions. The background scoring thread (`BackgroundScorer`) asynchronously calculates scores via a channel, without blocking the UI; cache key `{pid}:{start_time}:{exe}` prevents PID reuse string data.
### System Resource Monitoring (Sidebar)
- **Throttle Detection** Real-time identification of CPU throttling causes (thermal / power / idle), displayed as `⚠THERMAL` / `⚠POWER` on the sidebar (Win32 `CallNtPowerInformation`)
- **per-core Frequency + Temperature**<sup>v0.5.0</sup> Independent display of current frequency + temperature for each core; color grading (< 70°C green / 70-79 yellow / 80-89 orange / ≥ 90 red); Linux uses `/sys/devices/system/cpu/cpufreq` + hwmon, Windows uses `CallNtPowerInformation`
- **Disk I/O** Independent read/write rates for each disk + per-process I/O rates (`(pid, start_time)` key to prevent PID reuse string data)
- **GPU** Multi-vendor support: Windows DXGI + NVML (NVIDIA enrichment: temperature / video memory / power / utilization) + PDH utilization; **Linux uses nvtop subprocess to cover AMD / Intel / NVIDIA**<sup>v0.5.0</sup>
- **SMART Disk Health Badge**<sup>v0.5.0</sup> Sidebar displays `✓` (Ok) / `⚠` (Warning) / `✗` (Failing) / `-` (Unknown) for each mount point
- **Sidebar Others** CPU/memory/swap usage + sparkline graph (30-second history), network card IP, uptime
### AMD / Intel GPU Support (Multi-vendor)<sup>v0.5.0</sup>
Phase 6 introduces the `GpuProvider` trait abstraction with multiple implementations:
| Provider | Platform | Coverage |
|---|---|---|
| `NvmlProvider` | Windows | DXGI (VRAM for all vendors) + NVML (NVIDIA enrichment) + PDH utilization |
| `NvtopProvider` | Linux | nvtop subprocess JSON output, covering AMD / Intel / NVIDIA vendors |
`detect_providers()` returns an active list based on feature flags + platform + binary availability. Linux users can enable AMD/Intel temperature / video memory / utilization monitoring after installing `nvtop`. Windows AMD/Intel are included in the 0.6.0+ roadmap.
### Per-process Network Traffic<sup>v0.5.0</sup>
Process list adds **Network In / Network Out** columns (bytes/second), collected every 1 second. `NetFlowCollector` trait + multiple implementations:
| Implementation | Platform | Path |
|---|---|---|
| `IphelperCollector` | Windows | IP Helper (`GetTcpTable2` + `GetPerTcpConnectionEStats` + netstat2 PID join, **does not use ETW**) |
| `NethogsCollector` | Linux | nethogs subprocess parsing |
CLI `proc ls --sort net_recv --limit 10` sorts by traffic; within TUI, press `←→` to switch sorting fields and select the network column.
### DNS Query Log<sup>v0.5.0</sup>
Exclusive to Windows platform.<sup>v0.11.0</sup> **Primary path uses ETW** (handwritten windows-rs `Microsoft-Windows-DNS-Client` real-time session, event 3008/3010 + TDH dynamic schema parsing, latency < 50ms + 100% integrity); if ETW startup fails, **falls back to PowerShell** (spawn long-running `powershell.exe` subprocess subscribing to `Microsoft-Windows-DNS-Client/Operational` channel event 3010). Both are abstracted by the `DnsLogCollector` trait, with reader threads / ETW callbacks parsing events + sysinfo PID name lookup + `sync_channel(1000)` pushing to the main thread. Drain every 500ms, main thread cap=1000 FIFO. See [ADR-0020](docs/adr/0020-dns-etw-provider.md) for details.
- **Within TUI**: press `D` (uppercase) to activate the DNS sub-view, displaying recent DNS query lists
- **Details Page Network Tab**: displays the last 5 DNS queries for the PID at the bottom
- **CLI**: `proc dns --tail` streams new events
- **Anomaly Rule R9**: new PID initiates DNS queries and is not in the whitelist → Warning
**How to know which collector is in use?** Run `proc diag`, and the last line `dns_collector: <kind>` reflects the actual type (`etw` / `powershell` / `none`). When reporting "DNS log data missing" bugs, include this line.
**Privacy Commitment**: DNS query records are **never persisted** to disk, only retaining recent 1000 entries in memory; `record/frame.rs` serialization type does not contain `DnsQuery`.
### v0.6.0 Security Hardening
Phase 2 introduces 4 independent security mechanisms (see [SECURITY.md](SECURITY.md) and [ADR-0008](docs/adr/0008-self-mitigation-policy.md)):
| Mechanism | Effect |
|---|---|
| **self-mitigation** | Earliest call to `apply_self_mitigations()` at startup, applying 5 protections to itself via `SetProcessMitigationPolicy`: DEP (Permanent) / ASLR (HighEntropy) / ProhibitDynamicCode / DisableExtensionPoints / **ImageLoad (NoRemote + NoLow + PreferSystem32)**. **Does not enable ProcessSignaturePolicy** (would cause nvml-wrapper unsigned native dependency to fail) |
| **env masking** | Details page Env tab defaults to mask display `{first 2 chars}***(original length B)`; secret pattern matches 12 keywords (KEY/TOKEN/SECRET/PASSWORD/PASSWD/PWD/CREDENTIAL/PRIVATE/AUTH/API/DSN/CONNECTION_STRING) + `DATABASE_URL` special case + `*_AUTHORIZATION` suffix. Press `v` to toggle reveal, **forced masking during screen recording** |
| **screen recording protection** | User actively presses `R` to trigger screen recording, first prompting confirmation (warning will capture all screen content including DNS domain / process cmd), press `y` to confirm / `n` to cancel |
| **restricted spawn** | When elevated, spawn PowerShell DNS subprocesses first call `CreateRestrictedToken` + `DISABLE_MAX_PRIVILEGE` to strip inherited `SeDebugPrivilege`, preventing subprocess hijacking and credential theft. **Only applies to DNS spawn** (docker exec / nvtop do not apply due to their need for privileged tokens) |
### v0.6.0 Observability
Phase 3 introduces a complete diagnostic chain:
- **Log rotation**: `tracing-appender::RollingFileAppender::daily` one file per day `~/.config/proc/proc.logYYYY-MM-DD`, automatically cleaning up logs older than 7 days (no truncation at startup).
- **Crash report**: upon panic, write to `~/.config/proc/crashes/crash-{YYYYMMDD-HHMMSS}.txt` (main thread panic) or `crash-worker-{name}-{ts}.txt` (worker thread panic), containing timestamp + proc version + panic info + `Backtrace::force_capture()`. **Does not upload anywhere**, users can attach manually when reporting bugs.
- **Worker metrics**: each worker records `poll_count / poll_total_us / poll_max_us / channel_full_count / last_error` (atomic), main thread aggregates and outputs to `proc diag`.
- **`proc diag` subcommand**: JSON outputs all worker avg/max/polls/drops metrics, facilitating bug reports with attachments. `?` help page Workers section also displays a simplified version (with `✓` / `⚠` health badges).
- **Worker crash banner**: worker threads use `catch_unwind` to package the body, upon panic, notify the main thread via `crash_tx`, and render a red banner at the top of the TUI; press `D` to clear.
### v0.6.0 Performance Optimization
Phase 4 replaces all `format!` String allocations in `ProcessInfo` with Arc:
| Field | Old Type | New Type | Benefit |
|---|---|---|---|
| `name` | `String` | `Arc<str>` | heavy worker single allocation, clone uses atomic counting |
| `cmd` | `Vec<String>` | `Arc<[String]>` | same as above |
| `exe` / `cwd` / `user_id` | `Option<String>` | `Option<Arc<str>>` | same as above |
| `status` | `String` (`format!("{:?}", sysinfo::ProcessStatus)`) | `ProcessStatus` Copy enum (13 variants) | zero allocation, aligned with sysinfo 0.34.2 real naming |
| `name_lower` | (always `to_lowercase` during search) | `Arc<str>` precomputed | search hot path no longer rebuilds for each keystroke |
| `query_lower` | (always `to_lowercase` during keystrokes) | `SearchState` cache | same as above |
With 500 processes × 1.5s recollection, heap allocation reduces by 90%+; search box character input cumulative latency drops from ~50ms to μs.
### TCP Transmission Quality<sup>v0.5.0</sup>
`TcpStats` expands 4 transmission quality fields:
| Field | Data Source |
|---|---|
| `retransmitted_segs` | Win `GetTcpStatisticsEx2` / Linux `/proc/net/snmp` |
| `reset_segs` | same as above |
| `failed_connections` | same as above |
| `out_segs` | same as above |
CLI `proc port --stats` outputs TCP quality summary; within TUI, anomaly rules:
- **R7**: retransmission rate > 5% → Warning
- **R8**: RST rate > 2% → Warning
### SMART Disk Health<sup>v0.5.0</sup>
Cross-platform SMART data collection:
| Platform | Primary Path | Fallback |
|---|---|---|
| Linux / macOS | `smartctl --json --attributes <device>` subprocess | — |
| Windows | `smartctl` subprocess | WMI `MSStorageDriver_FailurePredictStatus` (aggregated status) |
`SmartData` structure: device / model / serial / temperature / health (4 levels: Ok / Warning / Failing / Unknown) / attributes. CLI `proc smart [device]` outputs; TUI sidebar disk badges.
30s poll cycle (`SmartWorker` independent worker, decoupled from `LightWorker`), shutdown + join upon drop.
### Docker Enhancement<sup>v0.5.0</sup>
Phase 3 expands Docker panel from "container list + event stream" to lazydocker level:
- **Container processes** (`t` to docker top view, CLI `proc docker top <name>`): reuse `bollard::top_processes`
- **Log mode** (`l` to log view, CLI `proc docker logs <name> [--follow] [--tail N]`): independent `LogsWorker` tokio runtime + `sync_channel(64)` backpressure + 5000-line ring buffer + follow mode
- **Image view** (`Tab` to Images, CLI `proc docker images`): local image list + `in_use()` determination + double `d` confirmation for deletion (CLI `proc docker image-rm <id> [--force]` )
- **Volume view** (`Tab` to Volumes, CLI `proc docker volumes`): volume list + in_use reverse check + double `d` confirmation for deletion (CLI `proc docker volume-rm <name> [--force]` )
- **docker-compose thin wrapper** (CLI `proc docker compose up -d` etc., forward to docker-compose)
- **Event stream** (CLI `proc docker events`)
### Container exec (Embedded PTY) <sup>v0.5.0</sup>
Phase 9 introduced `AppMode::ContainerExec`: from DockerPanel, select a container and press `e` to enter embedded PTY mode. Local `portable-pty` spawns `docker exec -it <container> <shell>` subprocess; docker CLI handles all daemon communication (named pipe / TCP / unix socket) + remote PTY allocation; `vt100` crate parses ANSI byte stream feeding `ratatui` rendering.
| Key | Behavior |
|---|---|
| `e` (Docker panel) | Enter exec mode (infer default shell by image: alpine→`/bin/sh`, ubuntu/debian→`/bin/bash`, others fall back to `/bin/sh`) |
| Normal ANSI keys | Pass-through (Enter=`\r` / Tab=`\t` / Backspace=`\x7f` / arrow keys=`\x1b[A/B/C/D` / Ctrl+C=`\x03` / Ctrl+D=`\x04` / Ctrl+\\=`\x1c`) |
| `Ctrl+D` / `exit` / `Ctrl+\` / subprocess exit | Automatically switch back to DockerPanel + prompt "Container xxx has exited" |
CLI `proc docker exec <container> [cmd...]` directly spawns `docker exec -it` passing stdio (CLI user terminal = remote PTY).
### Process Guarding and Alerts
**Monitoring** (panel `5`): monitor target processes by PID / port / command; `NotifyOnly` only notifies, `AutoRestart { max_retries, base_backoff, max_backoff }` exponentially backs off and automatically restarts; watchdog subprocess can be cleanly shut down by Ctrl+C (`try_wait()` polling).
**Alerts**: configurable threshold rules (CPU / memory / disk / network / connections / temperature / frequency 7 metrics, 6 comparison operators), continuous hits trigger anti-bouncing, state machine `Pending → Firing → Resolved`, automatically graded Info / Warning / Critical, Critical pushes Toast. Default rules work without configuration; custom rules are placed in `~/.config/proc/alerts.toml`:
```toml
[[rule]]
metric = "CpuUsage"
op = "GT"
threshold = 90.0
consecutive_hits = 3
severity = "Warning"
```
### Terminal Recording Playback
Complete VT100 terminal recording (v2 format, preserving RGB color - v1 old version fades, deprecated):
- `proc record` starts recording (press `R` in TUI to toggle), status bar shows REC indicator
- During recording, press `b` to mark bookmarks (since v0.14): inline input label, Enter submits / Esc cancels / empty label defaults to "Bookmark #N"
- `proc replay <file>.prec` playback: play/pause, frame-by-frame `←→`, speed `0.5× / 1× / 2× / 4×`, `Shift+←→` jump 10 frames
- During playback, press `B` (Shift+B) to open bookmarks panel (since v0.14): Up/Down selects · Enter jumps to bookmark frame · `e` edits label · `d` deletes · substring search · Esc closes
- During playback, press `/` to enter timeline search (since v0.14): 5 dimension FilterExpr (`cpu > 80` / `mem > 500mb` / `name =~ /chrome/i` / `anomaly.severity = critical` / `timestamp > 1234567890`) + substring mode; hit frame positions `●` highlighted in timeline; `n` / `N` jumps to next / previous hit frame; Enter submits / Esc cancels input state then `n` / `N` still jumps
- During playback, press `r` to toggle play/pause direction (since v0.14): reverse playback speed gears same as forward (Half / Normal / Double / Quad), timeline icon `▶` / `◀` / `⏸` reflects direction + playback state, reverse playback to first frame automatically pauses (symmetric with forward playback to last frame pause)
- `proc replay <file>.prec --info` (since v0.14) displays recording metadata (duration / frame count / anomaly events / max CPU/mem) without opening TUI
- Bookmarks persist to `<file>.prec.bookmarks.json` sidecar (decoupled from recording file body, can be shared / deleted separately)
- Ctrl+C exits gracefully, ensuring recording file is properly flushed (global `shutdown` module unified signal)
- Timestamp format `MM-DD HH:MM:SS`, aligned with operation logs
### CLI Subcommands
Not just TUI - command line directly consumes the same collection layer:
| Subcommand | Purpose |
|---|---|
| `proc ls --sort cpu --limit 20` | Process list (sort: cpu/mem/name/pid/disk_read/disk_write/net_sent/net_recv) |
| `proc tree` | Process tree |
| `proc port 8080 [--kill] [--stats]` | Port occupancy query / termination / TCP quality summary |
| `proc kill <pid> [--force]` | Terminate single process / force terminate process tree |
| `proc pkill <name> [--force --dry-run]` | Batch terminate by name (exact match, case-insensitive) |
| `proc eject <drive> [--find-locks]` | USB occupancy analysis / detailed handle list |
| `proc who <path>`<sup>v0.5.0</sup> | Reverse query "who occupies this file / directory" |
| `proc handles [--pid N] [--file path]`<sup>v0.5.0</sup> | Enumerate all handles of specified PID / reverse query PID list occupying specified path |
| `proc priority <pid> [--set normal]`<sup>v0.5.0</sup> | Query / set priority (idle/belownormal/normal/abovenormal/high/realtime) |
| `proc affinity <pid> [--set 0xFF]`<sup>v0.5.0</sup> | Query / set CPU affinity mask |
| `proc throttle <pid> on\|off`<sup>v0.7.0</sup> | Windows 11 EcoQoS / Efficiency Mode toggle (🍃 marker maintained by HeavyWorker batch query) |
| `proc smart [device]`<sup>v0.5.0</sup> | SMART disk health (omitting device lists all disks) |
| `proc dns [--tail]`<sup>v0.5.0</sup> | DNS query log (only Windows, memory-only) |
| `proc flows [--limit N] [--json]`<sup>v0.7.0 · cross-platform v0.10.0</sup> | ProcessFlow list (Linux uses eBPF connect+DNS association, Windows admin uses Schannel ETW SNI; table contains "source" column; ADR-0016 + ADR-0018) |
| `proc diag`<sup>v0.6.0</sup> | worker metrics JSON output (avg/max/polls/drops), attach to bug report |
| `proc monitor --add --pid N` / `--remove ID` | Monitor management (by `--pid` / `--port` / `--command`) |
| `proc record` / `proc replay <file>` | VT100 recording |
| `proc export --format json\|csv [-o file] [--sort] [--limit]` | Process data export (including ISO-8601 local timestamp) |
| `proc docker ps / inspect / top / logs / images / volumes / image-rm / volume-rm / compose / events / exec`<sup>v0.5.0</sup> | Docker 11 subcommands |
| `proc mcp serve`<sup>v0.7.0</sup> | Start MCP server (stdio transport, default), expose above 32 subcommands / detail page Tabs / system metrics / recording v2 / USB status as `proc_*` MCP tools for Claude Desktop / Cursor etc. LLM agent calls (v0.7 lands 17 tools, v0.15 expands to 32 tools, v0.16 expands to 39 tools, v0.17 expands to 46 tools) |
| `proc mcp serve --transport sse --port 8080`<sup>v0.17.0</sup> | Start MCP server (SSE transport, **current structural stub**, full implementation postponed to v0.18+ cycle — see ADR-0027; agent temporarily uses stdio + polling via `resources/read` or `proc_metrics_history` instead) |
### MCP Server (LLM Agent Access)<sup>v0.7.0 · expanded v0.15.0 · expanded v0.16.0 · expanded v0.17.0 · expanded v0.18.0</sup>
`proc mcp serve` exposes proc's process / network / DNS / Docker / detail page Tabs / system metrics / recording v2 / USB status / record exposure / USB release / docker-rm write operation capabilities as [MCP](https://modelcontextprotocol.io/) tools, allowing Claude Code / Cursor / Windsurf etc. clients to call directly. See [`docs/adr/0009-mcp-server.md`](docs/adr/0009-mcp-server.md) (v0.7 design) + [`docs/adr/0023-mcp-inspect-tool-merge.md`](docs/adr/0023-mcp-inspect-tool-merge.md) (v0.15 detail page 6 Tab merge) + [`docs/adr/0024-mcp-handler-module-split.md`](docs/adr/0024-mcp-handler-module-split.md) (v0.15 module split) + [`docs/adr/0025a-mcp-replay-search-agent-schema.md`](docs/adr/0025a-mcp-replay-search-agent-schema.md) (v0.16 replay_search schema) + [`docs/adr/0025b-mcp-record-not-exposed.md`](docs/adr/0025b-mcp-record-not-exposed.md) (v0.16 record non-exposure decision, v0.17 ADR-0029 overturned) + [`docs/adr/0026-mcp-handler-persistent-fields.md`](docs/adr/0026-mcp-handler-persistent-fields.md) (v0.17 MCP handler persistent fields) + [`docs/adr/0027-resource-subscribe-and-sse-transport.md`](docs/adr/0027-resource-subscribe-and-sse-transport.md) (v0.17 Resource subscribe + SSE transport, v0.18 expanded §5 subscribe-push lifecycle) + [`docs/adr/0028-vt100-to-uiframe-converter.md`](docs/adr/0028-vt100-to-uiframe-converter.md) (v0.17 VT100 conversion) + [`docs/adr/0029-record-exposure-and-confirm-mechanism.md`](docs/adr/0029-record-exposure-and-confirm-mechanism.md) (v0.17 record exposure + confirm mechanism, v0.18 expanded §6 record auto-stop).
**Claude Desktop configuration** (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`; Windows: `%APPDATA%\Claude\claude_desktop_config.json`):
```json
{
"mcpServers": {
"proc": {
"command": "proc",
"args": ["mcp", "serve"]
}
}
}
```
**Cursor / Windsurf configuration** (project `.cursor/mcp.json` or global): same schema, replace `command` with proc's absolute path (e.g., `C:\Users\YOU\.cargo\bin\proc.exe`).
**Manual debugging**: `npx mcp-inspector proc mcp serve` view schema and try calling in browser.
**Available tools** (**46 tools**, v0.7 lands 17 + v0.15 adds 15 + v0.16 adds 7 + v0.17 adds 7):
##### Category 0 — v0.7 existing 17 tools (list view)
| Tool | Corresponding CLI | Returns JSON |
|---|---|---|
| `proc_ls` | `proc ls` | `{ ok, sort, count, processes[] }` |
| `proc_tree` | `proc tree` | `{ ok, roots[] }` (recursive) |
| `proc_port` | `proc port` | `{ ok, count, ports[] }` |
| `proc_kill` | `proc kill` | `{ ok, pid, result }` |
| `proc_pkill` | `proc pkill` | `{ ok, total, killed, failed, results[] }` |
| `proc_eject` | `proc eject` | `{ ok, devices[] | locks[] }` |
| `proc_who` | `proc who` | `{ ok, count, lockers[] }` |
| `proc_handles` | `proc handles --pid` | `{ ok, count, handles[] }` |
| `proc_priority` | `proc priority` | `{ ok, pid, action, priority }` |
| `proc_affinity` | `proc affinity` | `{ ok, pid, action, affinity_mask }` |
| `proc_smart` | `proc smart` | `{ ok, disks[] | disk }` |
| `proc_dns` | `proc dns` | `{ ok, count, queries[] }` (drain once, non-tail) |
| `proc_diag` | `proc diag --json` | `{ ok, workers[] }` |
| `proc_monitor_list` | Monitor configuration snapshot | `{ ok, count, monitors[] }` |
| `proc_docker_ps` | `proc docker ps` | `{ ok, count, containers[] }` |
| `proc_docker_top` | `proc docker top` | `{ ok, count, processes[] }` |
| `proc_docker_logs` | `proc docker logs` | `{ ok, count, lines[] }` (non-follow) |
##### Category 1 — v0.15 adds 9 tools (direct CLI command exposure)
| Tool | Corresponding CLI | Returns JSON |
|---|---|---|
| `proc_flows` | `proc flows` | `{ ok, count, flows[], worker }` (Schannel ETW worker unavailable → `worker: "unavailable"`)|
| `proc_throttle` | `proc throttle` | `{ ok, pid, ecoqos_state }` (Windows 11 EcoQoS) |
| `proc_export` | `proc export` | `{ ok, format, payload }` (json / csv) |
| `proc_docker_inspect` | `proc docker inspect` | `{ ok, container, health_detail, stats }` |
| `proc_docker_images` | `proc docker images` | `{ ok, count, images[] }` (including in_use reverse query) |
| `proc_docker_volumes` | `proc docker volumes` | `{ ok, count, volumes[] }` (including in_use reverse query) |
| `proc_docker_events` | `proc docker events` | `{ ok, count, events[], note }` (500ms short timeout drain, non-follow) |
| `proc_monitor_add` | `proc monitor --add` | `{ ok, id, target_kind, target, restart_policy }` (`dry_run=false` default, consistent with `proc_kill`; `dry_run=true` opt-in returns preview) |
| `proc_monitor_remove` | `proc monitor --remove` | `{ ok, id, removed }` |
##### Category 2 — New 1 tool in v0.15 (Details page 6 Tab merge)
| Tool | Input parameters | Returns JSON (by tab branch) |
|---|---|---|
| `proc_inspect` | `pid, tab=summary\|env\|network\|dlls\|memory_map\|handles, reveal=false` | `summary`: Complete ProcessInfo + parent_chain + signature_status + risk_factors (Details page view returns complete cmd/exe/cwd true value) / `env`: env_vars[] (secret 12 keyword default mask, `reveal=true` opt-in display true value) / `network`: listening[] + established[] + dns_recent[] / `dlls`: dlls[] (path/base_addr/size) / `memory_map`: regions[] (base_addr/size/state/protection/name) / `handles`: Same schema as `proc_handles` |
##### Category 4 — New 5 tools in v0.15 (System-level metrics)
| Tool | Returns JSON |
|---|---|
| `proc_metrics_system` | `{ ok, cpu_usage_pct, memory, swap, system_disk, uptime_secs, processes_count, network_interfaces[], tcp_stats, cpu_temp_c, gpu_temp_c }` (No 30s sparkline history — TD-52 v0.16+ candidate) |
| `proc_metrics_gpu` | `{ ok, gpus[], providers[] }` (providers marked nvml/dxgi/pdh data source; no GPU → `gpus: [], note`) |
| `proc_metrics_disk_io` | `{ ok, total, per_disk[], disks[] }` (`device=Some` only filters per_disk) |
| `proc_metrics_smart` | `device=None` → aggregated (disks[] summary, same as sidebar) / `device=Some` → detailed attributes (same schema as `proc_smart`) |
| `proc_metrics_thermal` | `{ ok, per_core_freq_mhz[], per_core_temp_c[], throttle, reason }` (throttle null + reason="Unavailable" fallback non-Windows) |
##### Category 5 — New 7 tools in v0.16 (Screen recording v2 + Operation)
**Category 5a — Replay (2 tools, Screen recording metadata / content query)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_replay_info` | `file_path: String` (.prec extension, v3 UiFrame / VT100 automatic distribution) | `format: "uiframe"` path: `{ ok, format, version, hostname, start_time, end_time, duration_secs, frame_count, anomaly_count, event_count, max_cpu, max_mem, has_bookmarks_sidecar, path, size_bytes }` / `format: "vt100"` path: `{ ok, format, version, start_time, frame_count, start_ms, end_ms, duration_secs, width, height, has_bookmarks_sidecar, path, size_bytes }` |
| `proc_replay_search` | `file_path: String, query: String, limit: Option<usize>` (query prefix `:` use FilterExpr 5 dimensions timestamp/cpu/mem/name/anomaly.severity / otherwise substring match process name; limit default 100, truncated=true agent can secondary adjust improve limit) | `{ ok, query, match_count, returned, truncated, limit, matches: [{ frame_idx, timestamp, cpu_usage, memory_used, matched_processes[], anomaly_severity }] }` (VT100 screen recording does not support search return `ok:false`) |
**Category 5b — Bookmarks CRUD (4 tools, operate `.prec.bookmarks.json` sidecar)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_bookmarks_list` | `file_path: String` | `{ ok, count, sidecar_present, source_healthy, bookmarks[] }` (double field three-state distinguish: no sidecar / fresh sidecar / stale sidecar) |
| `proc_bookmarks_add` | `file_path: String, frame_idx: usize, label: Option<String>, dry_run: Option<bool>` | `{ ok, dry_run, action: "add", id, frame_idx, label, timestamp_secs, sidecar_written }` (label=None/empty → default "Bookmark #N"; frame_idx out of bounds → `ok:false`; `dry_run=false` default, same as `proc_kill`) |
| `proc_bookmarks_edit` | `file_path: String, id: u64, label: String, dry_run: Option<bool>` | `{ ok, dry_run, action: "edit", id, old_label, new_label, sidecar_written }` (id does not exist → `ok:false`; keep old_label let agent see diff) |
| `proc_bookmarks_delete` | `file_path: String, id: u64, dry_run: Option<bool>` | `{ ok, dry_run, action: "delete", id, frame_idx, label, sidecar_written }` (id does not exist → `ok:false`; keep frame_idx + label let agent know what was deleted) |
**Category 5c — USB status (1 tool, user pain point "kill process don't know if succeeded")**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_eject_status` | `drive: String` ("E" / "E:" / "E:\\" all accepted, same as `proc_eject` normalize) | `{ ok, drive, device, ejectable, lock_count, locks[], suggestion }` (suggestion 4 levels: `eject_now` lock_count=0 can eject directly / `kill_locks` lock_count>0 need kill first / `unknown_drive` drive character invalid / `unavailable` non-Windows or scan failed; agent use `proc_eject_status → proc_kill → proc_eject_status` three-step feedback loop) |
##### Category 6 — New 6 tools in v0.17 (Observability + record exposure + USB release + docker-rm write operation)
**Category 6a — Observability sparkline (1 tool, TD-52 30s history sampling)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_metrics_history` | `metric: "cpu"\|"memory"\|"swap", seconds: Option<u8>` (default 30s, upper limit 30 due to `system_history` field 30s cap) | `{ ok, metric, seconds, count, samples: [{ ts, value }] }` ordered oldest → newest (empty history return count=0 + samples=[] worker warm-up period / Default path / no-default-features build) |
**Category 6b — Record exposure (2 tools, spawn subprocess + confirm gate, ADR-0029)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_record_start` | `confirm: bool` (must pass true to confirm screen recording risk — capture screen all content including DNS domain / process cmd) / `file_path: String` / `duration_secs: Option<u64>` (optional, v0.18+ really auto-stop — Some(N) spawn subprocess pass `--duration N` flag, subprocess timer thread sleep N secs then call `shutdown::request()` trigger clean exit) | `{ ok, action: "start", file_path, started_at, expected_duration_secs, pid, log_path }` (confirm=false → ok=false + error; record_handle already has child → ok=false + error "Screen recording is in progress") |
| `proc_record_stop` | `file_path: String` (must match `proc_record_start` file_path) | `{ ok, action: "stop", file_path, size_bytes, frame_count, duration_secs, killed, exit_code?, metadata_warning? }` (no screen recording in progress → ok=false + error; kill child + wait 10s timeout strong wait + read .prec metadata; metadata_warning field expose when .prec damaged) |
**Category 6c — USB release three-step process (1 tool, kill + flush + eject, ADR-0029)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_usb_release` | `confirm: bool` (must pass) / `drive: String` ("E" / "E:" / "E:\\" all accepted, same as `proc_eject_status` normalize) / `kill_pids: Vec<u32>` (agent usually get from `proc_eject_status` locks[].pid) / `dry_run: Option<bool>` (default false, true skip execution return simulation) | `{ ok, dry_run, action: "release", drive, killed_pids: [{ pid, result: "Killed"\|"AlreadyGone"\|"AccessDenied"\|"Failed"\|"Error", error? }], flushed: bool, ejected: bool, warnings: [...] }` (flush failed still try eject, warnings array accumulate three-step diagnosis) |
**Category 6d — Docker-rm write operation (3 tools, bollard API, ADR-0029)**
| Tool | Input parameters | Returns JSON |
|---|---|---|
| `proc_docker_rm` | `confirm: bool` (must pass) / `container_id: String` / `force: Option<bool>` (default false) / `volumes: Option<bool>` (default false, also delete associated anonymous volume) | `{ ok, container_id, removed: bool, force, volumes }` (Docker not running → ok=false + error) |
| `proc_docker_image_rm` | `confirm: bool` (must pass) / `image_id: String` / `force: Option<bool>` / `prune_children: Option<bool>` (currently not distinguish, bollard API limit, warning field expose) | `{ ok, image_id, removed: bool, force, warning? }` |
| `proc_docker_volume_rm` | `confirm: bool` (must pass, data permanently lost irreversible) / `volume_name: String` / `force: Option<bool>` | `{ ok, volume_name, removed: bool, force }` |
##### Resource subscribe + SSE transport（v0.17.0 · 扩 v0.18.0）
**Resource subscribe**（rmcp 0.11 `ResourceRoute` trait，ADR-0027）：`ProcMcpHandler` exposes 3 resource URIs, client polls for snapshot via `resources/read` (v0.17) and subscribes for incremental updates via `resources/subscribe` (v0.18 stage 2):
| URI | Returns JSON |
|---|---|
| `proc://metrics/system` | Same schema as `proc_metrics_system` tool (drain persistent `snapshot` field, fallback to new) |
| `proc://processes/list` | Same schema as `proc_ls --sort cpu --limit 50` (top 50 by cpu_usage) |
| `proc://docker/events` | Same schema as `proc_docker_events` tool (recent 50 events, 500ms short timeout drain) |
**subscribe-push worker lifecycle**（v0.18.0，ADR-0027 §关键设计点 5）：`SubscribePushWorker` holds a registry of `subscribers: Arc<Mutex<HashMap<String, Peer<RoleServer>>>>`. When a client calls `resources/subscribe { uri }`, a push task is lazily spawned (1s tick, traversing and calling `peer.notify_resource_updated`). The peer is automatically removed from the registry when disconnected. **stdio transport single client assumption** (single client per URI); SSE transport multi-client support is planned for v0.19+ cycle, upgrading to `HashMap<String, Vec<Peer>>`.
**SSE transport** (`proc mcp serve --transport sse --port 8080`, ADR-0027): v0.17 structural stub, full implementation postponed to v0.19+ cycle. Reasons: (1) rmcp 0.11 `streamable_http_server` module requires Cargo feature `transport-streamable-http-server-tower` and additional dependencies; (2) current `run_mcp_serve` uses `tokio::runtime::Builder::new_current_thread()` (avoiding blocking with DockerMonitor), while SSE server requires multi-client concurrency and `new_multi_thread()` runtime refactoring; (3) SSE multi-client subscribe-push registry upgrade (`HashMap<String, Peer>` → `HashMap<String, Vec<Peer>>`). **Workaround**: use stdio transport (default) + client-side `resources/subscribe` with v0.18 stage 2 subscribe-push worker lifecycle.
**Field trimming**: `proc_ls` excludes `exe` / `cwd` / `user_id` to avoid sensitive path leaks (list view, see ADR-0009); `proc_inspect(summary)` shows detailed view with full cmd/exe/cwd (agent actively queries single process = agreed to show real values, complementary to list view, see ADR-0023); `proc_inspect(env)` masks secrets by default (12 keywords, same contract as v0.6 env_reveal, `reveal=true` opt-in); write operations (`proc_kill` / `proc_pkill` / `proc_monitor_add` / `proc_monitor_remove` / `proc_bookmarks_add` / `proc_bookmarks_edit` / `proc_bookmarks_delete`) have `dry_run=false` by default (consistent with v0.7 contract, `dry_run=true` opt-in); **irreversible destructive operations** (`proc_record_start` / `proc_usb_release` / `proc_docker_rm` / `proc_docker_image_rm` / `proc_docker_volume_rm`) require `confirm: bool` (ADR-0029 decision 5, complementary to `dry_run`).
### Themes and Persistence
**10 built-in themes**: Dark / Catppuccin / Dracula / Gruvbox / One Dark / Rose Pine / Nord / Solarized / Tokyo Night / Light. Press `t` to cycle through themes, selected theme is persisted to `~/.config/proc/theme.txt`.
**User preferences persistence**: process list sorting fields and first-run guidance flag are written to `~/.config/proc/ui.toml`.
**First run**: if `ui.toml` is missing, display a one-time guidance prompt "Press `?` to view shortcuts". After pressing `?`, write `first_run=false` to disk, and the prompt won't appear on next startup.
## Installation
```bash
# Method 1: cargo binstall (5 seconds, precompiled, recommended)
cargo install cargo-binstall
cargo binstall proc
# Method 2: build from source (5 minutes)
git clone https://github.com/Alfroul/proc.git
cd proc
cargo build --release
./target/release/proc
# Method 3: Windows package managers (v0.6.0+)
winget install Alfroul.proc
scoop install proc
```
### Shell Completions (v0.7.0+)
```bash
# Generate completion scripts to stdout and redirect to shell completion directories.
proc completions --shell bash > ~/.bash_completion.d/proc
proc completions --shell zsh > ~/.zsh/completions/_proc
proc completions --shell fish > ~/.config/fish/completions/proc.fish
proc completions --shell powershell > $PROFILE
```
Release artifacts also include pre-generated completion files (in the `completions/` directory), which are deployed by scoop/winget installations.
Alternatively, install using `cargo install --path .`.
## Shortcuts
Press `?` in TUI to view the complete list (grouped and scrollable).
| Key | Function |
|---|---|
| `1-6` | Switch panels |
| **`Ctrl+P`**<sup>v0.7.0</sup> | **Command panel** (fuzzy search commands: kill / port panel / theme / sort by cpu / ..., ~40 items, replacing memorized keybindings) |
| `v` | Toggle process view (list ↔ grouped) |
| `t` | Cycle themes (persistent) |
| `?` | Help page |
| `↑↓` / `PgUp PgDn` | Move / page |
| `Enter` | Details / expand / collapse |
| `Space` | Multi-select |
| `/` | Search |
| `←→` | Cycle sorting fields (persistent) |
| `S` | Jump to security sorting |
| `k` / `K` | Terminate / force-terminate process tree |
| `A` | Alert popup |
| `R` (uppercase) | VT100 recording toggle |
| `Shift+←→` | Replay: jump 10 frames |
| **`Tab` / `Shift+Tab`** | Switch Inspector Tab in details page (summary / environment / network / DLL / handles / memory)<sup>v0.5.0</sup> |
| **`+` / `-`**<sup>v0.5.0</sup> | Adjust process priority in Summary Tab (Idle ↔ Realtime 6 levels) |
| **`F5`**<sup>v0.6.0</sup> | Force refresh Inspector data in details page (replacing 'r', aligned with Mission Center / htop; old 'r' shows deprecation warning) |
| **`y`**<sup>v0.6.0</sup> | Copy process info to clipboard in details page (vim yank, replacing 'c'; old 'c' shows deprecation) |
| **`v`**<sup>v0.6.0</sup> | Toggle secret masking in Env Tab (forced mask in recording) |
| **`Ctrl+F`**<sup>v0.5.0</sup> | Search filter in handles / memory Tab |
| **`D` (uppercase)**<sup>v0.5.0</sup> | Port panel: switch DNS query log subview |
| **`e`**<sup>v0.5.0</sup> | Docker panel: exec into container (embedded PTY) |
| **`l`**<sup>v0.5.0</sup> | Docker panel: enter container log view |
| **`t`**<sup>v0.5.0</sup> | Docker panel: view container processes (docker top) |
| **`Tab` (Docker panel)**<sup>v0.5.0</sup> | Switch Containers / Images / Volumes views |
| `r` (details page) | Re-collect Inspector data (environment / network / modules / handles / memory) |
| `q` / `Esc` | Quit / clear search (first Esc only clears search, second Esc returns to list) |
> **v0.6.0 keybinding changes**: details page `r` → **`F5`** (refresh, aligned with Mission Center / htop), `c` → **`y`** (vim yank), added `v` to toggle secret masking; Docker panel `r` → **`Shift+R`** (restart / refresh image or volume). Old `r` / `c` show deprecation warnings during v0.6.0 compatibility period, removed in v0.7.0.
In details page, `k` / `w` keep original semantics (terminate / add monitoring). Additional shortcuts are available in each panel, hinted at the bottom status bar.
## Command Line
```bash
proc # Launch TUI
proc ls --sort cpu --limit 20 # List processes
proc ls --sort net_recv --limit 10 # Sort by download rate
proc tree # Process tree
proc port 8080 # View occupying process
proc port 8080 --kill # Terminate occupying process
proc port --stats # TCP transmission quality summary
proc kill 1234 # Terminate process
proc kill 1234 --force # Force-terminate process tree
proc pkill chrome.exe # Terminate by name
proc pkill chrome.exe --force --dry-run # Force + dry-run
proc eject E: # Detect E: drive occupation
proc eject E: --find-locks # Detailed handle list
proc who Cargo.toml # Find who occupies this file
proc handles --pid 1234 # Enumerate PID 1234 handles
proc handles --file Cargo.toml # Find occupying PIDs
proc priority 1234 # Query PID 1234 priority
proc priority 1234 --set high # Set to High
proc affinity 1234 # Query affinity mask
proc affinity 1234 --set 0xFF # Set to 0xFF (first 8 cores)
proc smart # List disks + health
proc smart /dev/sda # View /dev/sda SMART details
proc smart '\\.\PhysicalDrive0' # Windows physical disk 0
proc dns --tail # Stream new DNS events (Windows only)
proc diag # Output worker metrics JSON (append to bug report)
proc monitor --add --pid 1234 # Monitor PID
proc monitor --add --port 8080 # Monitor port
proc monitor --add --command "cargo run" # Monitor and auto-restart
proc monitor --remove 1 # Remove monitoring (by ID)
proc record # Launch TUI and record
proc replay recording.prec # Replay
proc export --format json --limit 20 # Export JSON to stdout
proc export --format csv -o procs.csv --sort mem # Export CSV to file
# Docker 11 subcommands
proc docker ps # Container list (default)
proc docker inspect <name> # Container details
proc docker top <name> # Container processes
proc docker logs <name> # Output logs
proc docker logs <name> --follow --tail 100 # Follow mode + last 100 lines
proc docker images # Local images
proc docker volumes # Volume list
proc docker image-rm <id> # Remove image (double confirmation)
proc docker image-rm <id> --force # Force remove (even if in_use)
proc docker volume-rm <name> # Remove volume
proc docker compose up -d # Forward to docker-compose
proc docker events # Listen to event stream (Ctrl+C to stop)
proc docker exec <container> # Exec into container (infer shell)
proc docker exec <container> bash -lc "env" # Exec specific command
```
## Platform Support
**Windows-only since v0.12.0** (see [ADR-0022](docs/adr/0022-windows-only-platform.md)). Windows 10 1809+ / Windows 11 x64. Migration path for Linux / macOS users: `git checkout v0.11.0` (last release with Linux code).
**Release CI covers only 1 target** (v0.12.0+): `x86_64-pc-windows-msvc`. Install with `cargo binstall proc` / `winget install Alfroul.proc` / `scoop install proc` (Linux / macOS binstall / winget / scoop packages are no longer published, see [ADR-0022](docs/adr/0022-windows-only-platform.md)).
| Feature | Windows 10 1809+ / Windows 11 x64 |
|---|---|
| Process List / Tree | ✅ |
| Process Categorization (User/System/Service) | ✅ Win32 |
| Security Rating (Signing) | ✅ WinVerifyTrust R16<sup>v0.11.0</sup> + 9 state machine<sup>v0.12.0</sup> + trusted_signers.toml<sup>v0.12.0</sup> |
| USB Assistant | ✅ |
| Throttling Detection | ✅ |
| Per-core Frequency<sup>v0.5.0</sup> | ✅ CallNtPowerInformation |
| Per-core Temperature<sup>v0.5.0</sup> | ✅ ACPI |
| Per-disk I/O Rate | ✅ |
| Per-process Disk I/O | ✅ sysinfo (IO Performance Counters) |
| **Per-process Disk I/O (ETW High Precision)**<sup>v0.7.0</sup> | ✅ NT Kernel Logger + DiskIo TypeGroup1 (Admin; non-admin degraded to sysinfo) |
| **GPU (Multi-vendor)**<sup>v0.5.0</sup> | ✅ NVIDIA via NVML + DXGI / PDH utilization |
| **SMART Disk Health**<sup>v0.5.0</sup> | ✅ smartctl + WMI fallback |
| **Per-process Network Traffic**<sup>v0.5.0</sup> | ✅ IP Helper |
| **DNS Query Log**<sup>v0.5.0 · v0.11.0 ETW</sup> | ✅ ETW (default) / PowerShell (fallback, admin decides `proc diag` to see `dns_collector`) |
| **TCP Transmission Quality**<sup>v0.5.0</sup> | ✅ GetTcpStatisticsEx2 |
| **Process Handle Tab**<sup>v0.5.0</sup> | ✅ NtQuerySystemInformation |
| **Memory Map Tab**<sup>v0.5.0</sup> | ✅ VirtualQueryEx |
| **Process Priority / Affinity**<sup>v0.5.0</sup> | ✅ SetPriorityClass / SetProcessAffinityMask |
| **Windows 11 EcoQoS Toggle**<sup>v0.7.0</sup> | ✅ SetProcessInformation(ProcessPowerThrottling) + Process List 🍃 marking |
| **Schannel ETW TLS SNI**<sup>v0.10.0</sup> | ✅ `Microsoft-Windows-Schannel-Events` ETW event 1793 (Win10 1809+ Admin + TDH dynamic schema) |
| **File Locksmith (who)**<sup>v0.5.0</sup> | ✅ filelocksmith |
| **v0.6.0 Security Hardening** (self-mitigation / env mask / restricted spawn) | ✅ |
| **v0.6.0 Observability** (log rotate / crash report / worker metrics) | ✅ |
| **Docker** (ps/inspect/top/logs/images/volumes/exec) | ✅ |
| Process-level Bandwidth (EStats) | ✅ |
| Toast Notifications | ✅ |
| Network Diagnostics | ✅ |
| Screen Recording / Alerts / Monitoring | ✅ |
## FAQ
**Do I need administrator privileges?** No, basic functionality does not require administrator privileges. Administrator privileges are required to enable process-level bandwidth monitoring (EStats), terminate certain system processes, and complete handle enumeration. Non-administrator users will automatically be downgraded.
**Why was Linux/macOS support removed in v0.12?**<sup>v0.12.0</sup> See [ADR-0022](docs/adr/0022-windows-only-platform.md) for details. The short reasons are: (1) **Maintenance cost** - Linux eBPF flow graph (ADR-0016) + Linux PSI monitoring (ADR-0013) + Linux nvtop GPU + Linux nethogs network traffic, these "Linux killer features" require a Linux real machine environment for continuous verification, and the developers are mainly working on Windows, making the Linux path long-standing "not verified on this machine" (TD-19) become a debt black hole; (2) **Focus** - the core value of proc is on the Windows platform depth (WinVerifyTrust / ETW / Schannel / EcoQoS / NT Kernel Logger / Win32 API), focusing on Windows to make the Windows experience optimal; (3) **Simplify** - Cargo.toml removes libc / aya / aya-log and other Linux dependencies, CI / release only runs 1 target (previously 5), and the toolchain simplifies to make iteration faster. Linux/macOS users who need v0.12+ new features (such as trusted_signers / mem% fixes / 9 state machines) are welcome to fork.
**What should Linux/macOS users do?**<sup>v0.12.0</sup> Three options: (1) **Stay at v0.11.0** - `git checkout v0.11.0` or download v0.11.0 binary from [releases](https://github.com/Alfroul/proc/releases); v0.11.0 is the last release that includes Linux code, with complete eBPF / PSI / nvtop / nethogs paths. (2) **Fork and continue Linux maintenance** - proc is under the MIT license, and community forks are welcome to maintain the Linux branch. (3) **Alternative solutions** - Linux recommends [btop](https://github.com/aristocratos/btop) (TUI) / [htop](https://htop.dev/) (TUI) / [sysdig](https://sysdig.com/) (eBPF); macOS recommends [Activity Monitor](https://support.apple.com/guide/mac-help/mchlp2529/mac) (built-in) / [iStat Menus](https://bjango.com/mac/istatmenus/). See ADR-0022 migration path for details.
**Why doesn't GPU information display?**
- Windows: only displays NVIDIA (via NVML), other graphics cards use DXGI to display VRAM (utilization/temp/power only for NVIDIA)
- Linux: install `nvtop` to enable AMD / Intel / NVIDIA full-fledged monitoring
- macOS: not supported yet
**Where is DNS log recorded?** **Never persisted**. Only the last 1000 entries are kept in memory, and they are lost when proc exits. This is a privacy design. If you need long-term recording, use the Windows Event Viewer to export the `Microsoft-Windows-DNS-Client/Operational` channel.
**What's the difference between container exec and direct `docker exec`?** TUI presses `e` to enter the embedded PTY view (`portable-pty` + `vt100` crate), ANSI rendering is done within ratatui; CLI `proc docker exec` directly passes stdio, equivalent to `docker exec -it`. Both underlying spawn `docker exec -it <container> <shell>` subprocesses, and docker CLI handles all daemon communication.
**What if smartctl is not installed?** Windows installs smartctl, and proc automatically uses it; if not installed, it falls back to WMI `MSStorageDriver_FailurePredictStatus` (only predicts failure aggregation status, without detailed attributes).
**What does recording the screen leak?**<sup>v0.6.0</sup> Screen recording (VT100 recording) captures all screen content, including DNS domain / process cmd / env true values (if reveal is open). Starting from v0.6.0, pressing `R` to trigger screen recording **first pops up a confirmation dialog** (press `y` to confirm / `n` to cancel), and forces Env Tab to use mask mode during recording (even if `env_reveal=true` is also forced to mask). The recording file is stored in `~/.config/proc/recordings/*.prec`, **never automatically uploaded**.
**What mitigation strategies are enabled by self-mitigation?**<sup>v0.6.0</sup> 5 strategies: DEP (Permanent) / ASLR (HighEntropy) / ProhibitDynamicCode / DisableExtensionPoints / **ImageLoad (NoRemote + NoLow + PreferSystem32)**. **ProcessSignaturePolicy is not enabled** (it would make nvml-wrapper unsigned native dependencies fail). See [ADR-0008](docs/adr/0008-self-mitigation-policy.md) for details. You can verify in Process Explorer → Properties → Image File → Mitigation flags.
**Where is the crash report located?**<sup>v0.6.0</sup> Under `~/.config/proc/crashes/`: main thread panic → `crash-{YYYYMMDD-HHMMSS}.txt`; worker thread panic → `crash-worker-{name}-{ts}.txt`. Files contain timestamp + proc version + panic info + `Backtrace::force_capture()`. When reporting bugs, attach the corresponding file.
**Why doesn't the log get overwritten?**<sup>v0.6.0</sup> Before v0.5.0, `File::create` truncates and overwrites old logs, and the last part is lost before crashing. Starting from v0.6.0, `tracing-appender::RollingFileAppender::daily` is used, with a new file `proc.logYYYY-MM-DD` each day, and automatically cleans up logs from 7 days ago.
**How to enable eBPF flow graph?**<sup>v0.7.0 · removed in v0.12</sup> ~~Only on Linux platform, need to compile yourself~~. **Starting from v0.12, Windows-only, eBPF flow graph path has been removed** (ADR-0022) - `src/ebpf/` module deleted, Cargo.toml `ebpf` feature flag removed. Linux users' migration path: `git checkout v0.11.0` still uses the old eBPF path (see ADR-0016, Status changed to Superseded by ADR-0022). Windows users use [ADR-0018 Schannel ETW TLS SNI](docs/adr/0018-windows-schannel-sni.md) path instead - port panel press `F` to enter Flow sub-view, CLI uses `proc flows`.
**What permissions does eBPF require?**<sup>v0.7.0 · removed in v0.12</sup> ~~root or `CAP_BPF` + `CAP_PERFMON` capability, kernel ≥ 5.10~~. **Starting from v0.12, Windows-only, eBPF path has been removed** (see previous "How to enable eBPF flow graph" and [ADR-0022](docs/adr/0022-windows-only-platform.md)).
**How to trigger R15 security scoring (external behavior)?**<sup>v0.7.0</sup> Default is not enabled. Need to explicitly create `~/.config/proc/sni_whitelist.txt` (one allowed domain per line, `#` for comments), R15 is activated. Two conditions trigger (either deduct 30 points): dns_name not in whitelist / ≥ 50 different IPs within 10s (port scanning feature). An empty file means "all dns_name are not in whitelist" (user assumes responsibility). See [ADR-0016](docs/adr/0016-ebpf-flow-graph.md#securityrule-r15-外联行为评分) for details.
**What do the 🔒 / ⚠️ / ❓ icons next to the process name mean?**<sup>v0.11.0</sup> Signature status markers (ADR-0021): 🔒 Trusted (signature chain traced back to Microsoft / known CA) / ⚠️ Unsigned or Revoked (no signature / signature revoked) / ❓ Unknown (verification failed / non-admin run). `Pending` (default value within 1-2 heavy refreshes after startup) and `Signed` (signed but not trusted CA) do not display emojis to avoid column width fluctuations. Inspector Summary Tab displays complete status (e.g., "Signature: Trusted Signature (Microsoft/known CA)"). CLI uses `proc ls --filter 'security_score < 80'` to filter out processes with deductions. See [ADR-0021](docs/adr/0021-process-signature-verification.md) for details.
**proc shows my application as ⚠️ (unsigned), but I have a signature?**<sup>v0.11.0 · improved in v0.12.1</sup> Three steps to troubleshoot: (1) Is proc running as administrator? **Non-elevated `verify_signature` directly returns Unknown (does not call `WinVerifyTrust`)**, starting from v0.12.1, the process list does not display any emojis (Unknown and Pending / Signed are empty strings), and the Inspector Summary Tab shows "Unknown (need administrator privileges)" status - restart proc as administrator to activate WinVerifyTrust real verification; (2) Is the signature chain complete? Missing intermediate certificates may cause `WinVerifyTrust` to return `TRUST_E_SUBJECT_NOT_SIGNED` or chain breakage errors (falling into Unknown / ChainError); (3) Are you using `.cat` file signature? Drivers and system components use `.cat` associated signatures, `WinVerifyTrust` directly verifies `.exe` and returns Unsigned - this is a known limitation, leaving it for future debt. Run `proc ls --json | jq '.[] | select(.signature_status=="Unsigned")'` to get the complete list, then use `sigcheck /a your.exe` (Sysinternals) to cross-verify.
**How to use Windows Flow graph?**<sup>v0.10.0</sup> Windows admin automatically enables Schannel ETW worker (no feature flag required): start proc → port panel press `F` to switch to Flow sub-view → curl / browser triggers TLS handshake → see SNI list. CLI uses `proc flows` for the same display, `proc flows --json` outputs with `"source": "schannel"` field. Non-admin / Win10 < 1809 / x86 process → worker fails to start / does not fire, UI displays degradation prompts. See [ADR-0018](docs/adr/0018-windows-schannel-sni.md) for details.
**What if Windows users see 0 items in Flow sub-view?**<sup>v0.10.0</sup> Three steps to troubleshoot: (1) Check Windows version with `winver`, need Win10 1809+ (build 17763+) / Win11; (2) Run proc as administrator (non-admin worker fails to start); (3) Trigger TLS handshake and wait 1-2s (Schannel event 1793 fires when DeleteSecurityContext, connection closes instantly). Still 0 items? Run `proc diag` to see `schannel_etw` worker line's `poll_count` - if it grows but SNI is empty, it means the callback received the event but TDH parsing failed, please attach `~/.config/proc/logs/proc.log` to report issues.
**proc shows R17 suspicious parent-child chain hits, but my Word/Excel startup cmd is legitimate?**<sup>v0.11.0</sup> R17 is a "typical macro attack chain" heuristic detection - deductions do not represent malware, but just match the attack pattern. Three steps to troubleshoot: (1) Inspector Summary Tab top red warning below has a complete chain (`WINWORD.EXE → cmd.exe`), verify if it's your expected script; (2) enter details page to see `Command line:` field (`proc inspect <pid>` same), confirm cmd parameters are expected script paths instead of base64 / encoded payload; (3) if indeed legitimate and want to eliminate warnings, currently R17 built-in patterns do not support whitelisting (v0.11.0 will add), but can configure custom rules in `~/.config/proc/lineage_rules.toml` to replace default detection - for example, reduce the weight to 5:
```toml
# Note: built-in OfficeToShell/BrowserToShell/ScriptInterpreter still deduct 35/25/15,
# here only for appending custom rules (cannot override built-in weight).
[[rule]]
name = "my_editor_to_shell"
parent_pattern = "(?i)my_editor"
child_pattern = "(?i)(cmd|powershell)"
weight = 5
```
See [tech-debt](docs/tech-debt.md) (R17 built-in pattern whitelisting to be added).
**proc shows R18 hits (`suspicious_path_*` / `[⚠ suspicious location]`), but my portable app is in AppData?**<sup>v0.11.0</sup> R18 is a "malware common startup location" heuristic detection - `%TEMP%` / `%APPDATA%` / `%LOCALAPPDATA%` / `%USERPROFILE%\Downloads` are user-writable directories, and legitimate portable apps are indeed placed in these locations. Three steps to troubleshoot: (1) check if the process also hits R16 (unsigned) - Inspector Summary Tab top has "unsigned + suspicious path collaborative hit (strong double signal)" warning, strongly suggest scanning for viruses; signed applications (🔒 / empty emoji) are usually legitimate. (2) when portable apps need to be placed in AppData, can configure custom rules in `~/.config/proc/path_rules.toml` to accept the path (although cannot directly whitelist built-in kind, but can confirm the weight is expected):
```toml
# Custom suspicious directories (will not affect built-in Temp/AppData/LocalAppData/Downloads judgments)
[[suspicious_dir]]
name = "my_portable_app"
path = "%USERPROFILE%\\my_portable" # supports %VAR% / ${VAR} / $VAR placeholders
weight = 5 # default 25
reason = "portable app residual path"
```
(3) R18 and v0.6 path_check (**叠加扣分**) - Temp path will simultaneously deduct 25 (temp_dir) + 20 (suspicious_path_temp) + collaborative 10 = 55 points (unsigned). This is a surgical design: retain v0.6 path_check unchanged, R18 as an independent entry adds deductions (same as R17 + v0.7 office_spawning_shell processing mode). If only accept single deduction, refer to [CONTEXT.md](CONTEXT.md) R18 section to understand scoring logic.
**What if the worker crashes?**<sup>v0.6.0 · v0.11.0 auto-restart</sup> TUI top renders red banner (`[worker name] panicked: <message>`), press `D` to clear. Meanwhile, crash report is written to `crashes/crash-worker-*.txt`. **v0.11.0 auto-thermal recovery**: worker panic then exponential backoff (5s / 30s / 5min) auto respawn; 3 failures lead to permanent death and proc restart (`WorkerManager::restart` implementation, TD-4 zero). Banner has three states (restarting / restarted / permanent failure). See [ADR-0019](docs/adr/0019-worker-restart-policy.md) for details.
**Why is my DNS log delayed or missed?**<sup>v0.11.0</sup> v0.11 defaults to ETW (CPU < 0.5%, delay < 50ms), but administrator privileges are hard requirements - non-admin automatically downgrades to PowerShell probe (v0.5.0 path remains). Run `proc diag`, the last `dns_collector: <kind>` line reflects the actual type (`etw` / `powershell` / `none`). If it's `powershell` and you want to use ETW, run proc as administrator. Linux / macOS does not have DNS-Client ETW provider, and DNS log functionality is not available.
**Why does FilterExpr `cpu > 5` filter out all flows in Flow sub-view (`F` enter)?**<sup>v0.11.0</sup> v0.11 stage 8 REVIEW-13 P1-2 fix - Flow view uses `apply_network` evaluation context, process fields (cpu/mem/name...) in this ctx is always false (no ProcessInfo), users write and filter out all flows. CLI `proc flows --filter 'cpu > 5'` prints warn prompt "Flow fields: sni/dns_name/remote_addr/remote_port/bytes_out/bytes_in/source, see ADR-0011" + exit 1; TUI same UX gap left TD archive (need deeper state machine coordination). Flow view correct syntax: `sni =~ /google\.com$/` / `remote_port = 443` / `source = schannel` / `dns_name in ("a.com", "b.com")`.
# R16 / R17 / R18 Trigger Conditions
<sup>v0.11.0</sup> Three-level scoring rules:
- **R16 Signature** (Step 1 access, ADR-0021): Each process `.exe` goes through `WinVerifyTrust` 6 states - Unsigned deduct 20 / Revoked deduct 35 / Signed (signed but not trusted CA) deduct 10 / Unknown (verification failed / non-admin) deduct 5 (only Windows) / Trusted / Pending no deduction.
- **R17 Suspicious Parent-Child Chain** (Step 17): `OfficeToShell` (Word/Excel/PowerPoint → cmd/powershell/wscript) deduct 35; `BrowserToShell` (Chrome/Edge/Firefox → cmd/powershell) deduct 25; `ScriptInterpreter` (wscript/cscript/mshta direct run) deduct 15. Custom rules can be added in `~/.config/proc/lineage_rules.toml`.
- **R18 Suspicious Launch Path** (Step 18): `%TEMP%` deduct 20 / `%APPDATA%` / `%LOCALAPPDATA%` / `%USERPROFILE%\Downloads` each deduct 15; with R16 collaboration (Unsigned/Revoked + suspicious path simultaneously hit) additional deduction 10. System directories (Program Files / Windows / System32) whitelist no deduction. Custom directories can be added in `~/.config/proc/path_rules.toml`.
- Cross-rule **叠加扣分** (surgical principle - keep v0.6 path_check / v0.7 office_spawning_shell unchanged, R17/R18 as independent entries superposition): typical macro attack mode `unsigned + temporary directory + Word → cmd` can accumulate deduction to 100+.
## R16 State Machine 9 Variants
<sup>v0.12.0</sup> v0.12 phase 3 TD-26 expands `WinVerifyTrust` HRESULT state machine, from v0.11 6 variants to 9 variants:
- `Trusted` / `Pending`: no deduction (trusted CA or not yet triggered verification)
- `Signed`: deduct 10 (signed but not trusted CA)
- `ChainError`: deduct 10 (certificate chain broken / name mismatch / signature invalid - incomplete verification)
- `Expired` / `UntrustedRoot`: each deduct 15 (certificate expired / untrusted root, once trusted but problematic)
- `Unsigned`: deduct 20 (no signature)
- `Revoked`: deduct 35 (signature revoked, once trusted but revoked by CA)
- `Unknown`: deduct 5 (Windows non-admin downgrade / verification API error)
Badge display: 🔒 Trusted / ⚠️ Unsigned / Revoked / Expired / UntrustedRoot / ❓ ChainError / empty Pending / Signed / Unknown (v0.12.1: Unknown changed from ❓ to empty string to avoid non-admin full-screen noise). See [ADR-0021](docs/adr/0021-process-signature-verification.md) for details.
## proc Displays Adobe / Docker / Cisco Processes as ⚠️ or Deduct Points (Signed), but Trusted Signers Configured Still Not Upgraded to 🔒?
<sup>v0.12.0</sup> v0.12 phase 3 TD-27 implementation, three-step troubleshooting:
(1) **CompanyName field value**: `trusted_signers.toml` matches FileVersion Information's `CompanyName` (not X.509 certificate subject CN). Use `sigcheck /a your.exe` (Sysinternals) or PowerShell `(Get-Item your.exe).VersionInfo.CompanyName` to view the actual value.
(2) **regex case sensitivity**: user `vendor_pattern` default case-sensitive - add `(?i)` prefix for case-insensitive (e.g., `(?i)^adobe`). Built-in 24 vendor list (v0.12 expansion) includes Adobe / Cisco / Oracle / VMWare / Docker / Red Hat / Apache / Python / GitHub / Electron / AMD, etc., zero-configuration effective.
(3) **configuration file location + format**: `~/.config/proc/trusted_signers.toml` (Windows = `C:\Users\{user}\.config\proc\trusted_signers.toml`), format `[[signer]] name / vendor_pattern / reason(optional)`, TOML parsing failure / regex compilation failure will **silently degrade to empty** - check `~/.config/proc/proc.log` for `trusted_signers rule「xxx」vendor_pattern regex compilation failed` warning. Example:
```toml
[[signer]]
name = "my_company"
vendor_pattern = "(?i)^MyCompany" # (?i) makes matching case-insensitive
reason = "internal application"
```
## Terminal Exception?
Exit and execute `reset` to restore.
## How to Write FilterExpr CIDR / URL / Regex Containing `/`?
<sup>v0.12.0</sup> v0.12 phase 4 TD-28 supports `\/` escape. Examples: `remote_addr =~ /192\.168\.1\.0\/24/` (CIDR) / `sni =~ /https:\/\/example\.com/` (URL) / `cmd =~ /C:\/Users\/admin/` (Windows path). Parser converts `\/` to single `/` (regex crate does not accept `\/` as valid escape), other `\X` (e.g., `\.` `\d` `\w`) remains unchanged for regex interpretation. Old expressions (without `\/`) behavior remains unchanged.
## FilterExpr `mem > 5%` Hits Almost All Processes?
<sup>v0.12.0</sup> v0.12 phase 4 TD-30 fixes silent bug - v0.11 before `mem > 5%` literal interpreted as `mem_bytes > 5.0` (byte value directly compared with percentage), almost all processes hit. After fixing, `mem + %` calculated as `mem / total_memory * 100` compared with percentage literal (e.g., `mem > 50%` on 16GB system equivalent to `mem > 8GB`). `cpu > 5%` and `cpu > 5` remain equivalent (cpu itself is 0-100 scale); `disk_read > 5%` / `net_sent > 5%` and other byte fields without natural divisor retain legacy behavior (surgical: not adding disk_total / net_total fields in EvalCtx). total_memory in test scenarios (panel_with_procs passing 0) falls back to legacy behavior to avoid division by zero.
## Configuration File Location?
`~/.config/proc/` directory: `theme.txt` (theme index), `ui.toml` (sorting preference), `alerts.toml` (alert rules), `proc.logYYYY-MM-DD` (running log, daily rotate retaining 7 days), `crashes/` (panic crash report), `recordings/` (default recording path).
## How to View Detailed Logs?
Logs written to `~/.config/proc/proc.logYYYY-MM-DD` by default (daily rotate, retaining 7 days). Use `RUST_LOG` to adjust level:
```bash
RUST_LOG=proc=debug proc # debug level
RUST_LOG=proc::security=trace proc # only security module trace
RUST_LOG=proc::port_map=debug proc ls # CLI subcommands also take effect
```
Default level is `info` when `RUST_LOG` is not set.
## How to Report Worker Performance Issues?
<sup>v0.6.0</sup> Run `proc diag` to output all worker metrics JSON (avg_us/max_us/polls/drops/last_error), attach to bug report. In TUI, press `?` to enter help page and view simplified version (with `✓` / `⚠` health badges).
## Benchmark
v0.13.0 and later, the repository includes criterion benchmark suite (6 hot paths: search / sorting / heavy refresh / TUI rendering / screen recording serialization / FilterExpr apply). Run locally:
```bash
cargo bench # run all 6 benchmarks
cargo bench --bench bench_refresh_heavy # run a single benchmark
```
Output in `target/criterion/<name>/<fixture>/new/estimates.json` (including mean / median / stddev). **Not running on CI** - criterion on GitHub Actions shared runner has large fluctuations, only run locally.
Current baseline figures (13th Gen Intel i7-13700HX / Win11 / Rust 1.95.0) see [`docs/reviews/PERF-BASELINE-v0.13.md`](docs/reviews/PERF-BASELINE-v0.13.md). **Core conclusion**: proc current architecture has no significant performance bottleneck under 1000 process scale; only mean > 5 ms hot path (parent_chain 16.5 ms @ 1000 processes) in worker independent thread does not block UI frame budget. Report "lag" with `cargo bench` figures can significantly reduce positioning cost.
## License
MIT (repository root directory LICENSE file)
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available