vladimiracunadev-create/rootcause-windows-inspector

``` ╔═══════════════════════════════════════════════════════════════════════════════════╗ ║ ║ ║ ██████╗ ██████╗ ██████╗ ████████╗ ██████╗ █████╗ ██╗ ██╗███████╗███████╗ ║ ║ ██╔══██╗██╔═══██╗██╔═══██╗╚══██╔══╝██╔════╝ ██╔══██╗██║ ██║██╔════╝██╔════╝ ║ ║ ██████╔╝██║ ██║██║ ██║ ██║ ██║ ███████║██║ ██║███████╗█████╗ ║ ║ ██╔══██╗██║ ██║██║ ██║ ██║ ██║ ██╔══██║██║ ██║╚════██║██╔══╝ ║ ║ ██║ ██║╚██████╔╝╚██████╔╝ ██║ ╚██████╗ ██║ ██║╚██████╔╝███████║███████╗ ║ ║ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═════╝╚══════╝╚══════╝ ║ ║ ║ ║ W I N D O W S I N S P E C T O R ║ ║ Forensic diagnostics · Built in Rust · v0.13.0 ║ ╚═══════════════════════════════════════════════════════════════════════════════════╝ ``` [](https://github.com/vladimiracunadev-create/rootcause-windows-inspector/actions/workflows/ci.yml) [](LICENSE) [](https://www.rust-lang.org/) [](docs/REQUIREMENTS.md) [](docs/ROADMAP.md) 🌐 **[产品页面 →](https://vladimiracunadev-create.github.io/rootcause-windows-inspector/)** **RootCause** 是一款用 **Rust** 编写的 **Windows** 桌面软件，旨在解决一个实际问题：当出现磁盘占用 100%、`%TEMP%` 异常增长、整体运行缓慢、内存消耗过高或无法解释的网络活动等症状时，清晰地揭示**究竟是哪个进程、文件夹、服务、连接或 ETL 跟踪**导致了系统性能下降。 它不打算成为一个“神奇的清理工具”。它的目标是**解释导致问题的主要原因**，保留证据，并在轻量级观察不足以解决问题时，提供一条通向更高精度的专业路径。 ## ⚡ 快速开始 ``` # 检查环境 (Rust, WPR, Inno Setup) .\scripts\verify-environment.ps1 # 编译 cargo build --release # 运行（某些功能需要管理员权限） .\target\release\rootcause.exe ``` ## 🔍 解决的问题 Windows 在单一视图中无法很好回答的具体问题： | 问题 | RootCause 如何提供帮助 | |---|---| | 现在是哪个进程占用了磁盘？ | I/O 增量最高的进程 Top 排行 + 趋势 sparkline | | 哪个临时文件夹增长了？增长了多少？ | 扫描 `%TEMP%`、`SoftwareDistribution`、`DeliveryOptimization` | | 是来自 Windows Update、BITS 还是 SysMain？ | 进程 + 活动服务的关联分析 | | 哪个可执行文件保持着与公网 IP 的连接？ | 网络表格 + 从 UI 进行 IP 封锁 | | 如何在不增加额外负担的情况下捕获证据？ | 集成 WPR/ETW，无需离开应用即可生成 ETL 摘要 | ## 🛡️ 运行机制 ### 1 · 轻量级操作模式 主要模式。低消耗，适用于频繁观察。 - 🟢🟡🔴 系统状态通用信号灯 - 📊 实时的 CPU · RAM · I/O sparkline - 🔝 具有严重程度和评分的占用最高进程 Top - 🌡️ 各区间内的 CPU / RAM / 写入 / 读取压力 - 🗂️ 扫描 `TEMP` 和 Windows Update 缓存 - 🌐 各进程的活动连接及其与公网 IP 的关联 - 📜 最近的系统事件和相关的服务 - 🗃️ 导出 JSON · 带有 A 与 B 对比功能的 SQLite 历史记录 - ⚡ 按进程过滤严重程度 (Critical / Warning / Normal) - 🔔 出现 Critical 进程时的 toast 通知 - ⌨️ 快捷键：`F5` 刷新 · `Ctrl+E` 导出 · `Ctrl+1…9` 切换 tab - 🖥️ 计算机硬件信息：OS、CPU、核心数、频率、RAM - ◫ Autostart tab：Run 注册表 (HKCU/HKLM) 和 Startup 文件夹（包含严重程度和磁盘验证）— 检测与已知基线的变化 (NUEVA/MODIFICADA/ELIMINADA) 并生成 `persistence-change` 告警 - ⚙️ Windows 服务变更检测（通过 CLI `rootcause services` + 事件中的 `service-change` 告警；它不是 GUI 的一个 tab）：监控每个服务的 `StartMode` + 二进制文件路径与已知基线的对比 (NUEVA/MODIFICADA/ELIMINADA) — 捕获新服务、二进制文件劫持或启动模式更改（例如：禁用 Defender） - 💻 完整的 CLI：在控制台使用 `rootcause --help` 查看所有命令 ### 2 · ETW/WPR 精度模式 适用于轻量级观察不足的情况。 - 从 UI 启动 / 停止 / 取消 WPR 捕获 - 记录问题的人工上下文 - 无需离开应用，使用 `tracerpt` 汇总最新的 ETL - 活动的 ETW 提供程序可视化进度条 - 为后续使用 WPA 进行深入分析提供清晰路径 ## 安全、弹性和演进 RootCause 的演进不仅是为了诊断性能下降和故障，还包括检测与未授权活动相符的异常信号，并强化 Agent 自身的弹性。 这些方向已经正式确立为产品的动态文档，而不是零散的笔记： - [`REQ-SEC-001 - 异常行为检测与可能的恶意活动`](docs/requirements/REQ-SEC-001-deteccion-comportamiento-anomalo.md)：定义了基于启发式算法、信号关联、技术证据和针对可疑进程、异常消耗、异常传出连接、持久性机制和可疑执行路径的缓解建议的演进方向。 - [`REQ-SEC-002 - RootCause Agent 自保护和弹性`](docs/requirements/REQ-SEC-002-autoproteccion-y-resiliencia.md)：已具备初步基础，包括本地心跳、异常关闭检测、配置完整性证据、建议的退避策略以及在 GUI/CLI 中的可见暴露。 - [`需求永久记录`](docs/requirements/README.md)：集中了状态、优先级和技术路线图的可追溯性。 - [`异常行为检测模块 (V1)`](docs/MODULO_DETECCION_ANOMALIAS.md)：描述了已经集成到仓库中的初步实现，包括本地启发式算法、简单关联、汇总的事件、配置以及在 GUI/CLI 中可见的输出。 当前仓库的实现： - REQ-SEC-001 已经具备集成的初步 V1 版本，可检测持续的 CPU 异常、内存增长、激进的写入操作、异常的传出流量、可疑路径、基础持久性机制、快速重生、重复脚本以及信号关联。 - 当前的输出显示严重程度、评分、涉及的进程、原因假设、汇总的证据和建议的缓解措施。 - REQ-SEC-002 进入到一个初步且务实的实现：本地心跳、异常关闭后的恢复、基本的配置监控以及可见的 Agent 状态；目前不承诺无懈可击或服务级别的持久守护进程。 务实的定位： - RootCause 可演进而检测与恶意或未授权活动相符的信号，但并不旨在取代专业的防病毒或 EDR 解决方案。 - RootCause 还必须考虑其自身 Agent 的弹性，因为诊断工具在实际场景中可能会成为被篡改的目标。 ## 🗂️ 产品版本 | 模式 | 类型 | 状态 | 如何使用 | 是否包含在 `release-windows` 中？ | |---|---|---|---|---| | **GUI Desktop** | 核心主版本 | 生产环境 | 安装程序 / 便携版 | 是 | | **CLI-only** | 备用核心版本 | 生产环境 | `--no-default-features` | 是 | | **PowerShell module** | 适配器 | 生产环境 | `Import-Module RootCause` | 是 | | **VS Code Extension** | 适配器 | 生产环境 | `code --install-extension` | 是 | | **Tray icon** | 运行时扩展 | 骨架 | 未来 Feature `tray` | 否 | | **Windows Service** | 运行时扩展 | 骨架 | 未来 Feature `service` | 否 | | **RootCause Demo** | 分发配置 | 可选 | 独立的演示安装包 | 默认不包含 | `PowerShell module` 和 `VS Code Extension` 复用 `rootcause.exe`；它们不是该产品的替代引擎。 ``` # CLI-only 版本（约 4 MB，无图形界面） cargo build --release --no-default-features # 完整 GUI 版本（约 18 MB，默认） cargo build --release ``` ### 主版本的官方交付物 | 文件 | 内容 | |---|---| | `RootCause-Setup.exe` | 应用程序主安装程序 | | `RootCause-Portable.zip` | 主构建版本（GUI + CLI）的便携版 | | `RootCause-CLI-Portable.zip` | CLI-only 版本的便携版 | | `RootCause.psm1` | PowerShell 模块 | | `RootCause-VSCode-Extension.vsix` | VS Code 扩展 | | `SHA256SUMS.txt` | 完整性哈希值 | 各模式快速安装指南： - `RootCause-Setup.exe`：安装后从控制台使用 GUI 或 `rootcause`。 - `RootCause-Portable.zip`：解压并运行 `rootcause.exe`（包含 GUI + CLI 的主构建版本）。 - `RootCause-CLI-Portable.zip`：解压并从控制台运行 `rootcause.exe`。 - `RootCause.psm1`：要求已安装 `rootcause.exe` 或其在 `PATH` 中可用。 - `RootCause-VSCode-Extension.vsix`：要求已安装 `rootcause.exe` 或能在 `rootcause.executablePath` 中进行配置。 目录的权威来源：[`docs/CATALOGO_PRODUCTO.md`](docs/CATALOGO_PRODUCTO.md)。 ## 📦 Windows 包管理器 ``` # Scoop scoop install rootcause # Winget winget install VladimirAcuna.RootCause # Chocolatey choco install rootcause-windows-inspector ``` Manifests 位于 `packaging/distribution/` · PowerShell 模块位于 `packaging/powershell/`。 ## 📁 仓库交付状态 ### ✅ 包含 - 完整的 Rust 源代码 - 使用 `eframe/egui` 的原生 GUI（feature 为 `gui`，默认开启） - 通过 feature flags 实现的 CLI-only 版本 (`--no-default-features`) - PowerShell 模块 (`RootCause.psm1`) — 9 个原生 cmdlets - 分发 Manifests：Scoop, Winget, Chocolatey - 带有状态栏、警报和诊断面板的 VS Code 扩展 - 有文档说明的骨架：Tray icon 和 Windows Service - 验证、构建、打包和分析 ETL 的脚本 - 关于架构、要求、操作和 CI 的详尽文档 - 集成在界面中的 WPR/ETW 精度模式 - SQLite 历史记录（最近 1000 行）+ 自动备份至 JSON - 采用 JSON 格式 (`rootcause-config.json`) 的操作配置，具有安全的默认设置 - 具有本地心跳、检测之前异常关闭以及基本配置完整性的 Agent 健康状况监控 - 汇总的异常事件记录 + SQLite 中的操作审计 - 通过 API 进行可选且解耦的 AI 适配器，默认关闭 - 兼容企业部署的静默安装程序 (`/VERYSILENT /SUPPRESSMSGBOXES`) ### ❌ 不包含 - 预编译的 `.exe` - 数字签名 - 内核驱动 - 相当于 WPA 的完整解析器 ## 🗂️ 界面部分 | Tab | 描述 | |---|---| | **Overview** | 全局信号灯 + sparkline + 计算机特性 | | **Procesos** | 带有严重程度过滤的表格 + 进程 command line | | **Conexiones** | 每个进程的活动连接 + IP 封锁 | | **Temporales** | Windows 缓存 (TEMP, SoftwareDistribution 等) | | **ETW / WPR** | WPR 捕获 + ETL 跟踪摘要 | | **Servicios** | wuauserv、BITS、DoSvc、SysMain + 最近事件 | | **Autostart** | Run/RunOnce 注册表、Startup 文件夹和计划任务 + 变更检测与基线对比 | | **Historial** | SQLite 快照 + 带有增量的 A 与 B 对比 | | **Acerca** | 版本、作者、GitHub、快捷键、硬件 | ## 🔬 已实现的功能

系统观察

- 全局 CPU · 已用 / 总内存 - 各区间的网络活动 · 各区间的总 I/O - 通用信号灯 · 趋势 sparkline (环形缓冲区 60 个样本)

高占用进程

- 名称 · PID · 可执行文件路径 · Command line - 区间内的 CPU · RAM · 读取 / 写入 - 严重程度和评分 · 类别 · 简要说明 - 按严重程度进行交互式过滤

关键的临时文件和缓存

- `%TEMP%` · `C:\Windows\Temp` - `C:\Windows\SoftwareDistribution\Download` - `C:\ProgramData\Microsoft\Windows\DeliveryOptimization\Cache`

网络和连接

- 通过 `netstat` 获取活动连接 · 与 PID 关联 - 关注公网 IP · 由防火墙控制的封锁

历史记录和证据

- SQLite 历史记录：保留最多 1000 行；Historial tab 显示并比较最近 60 次捕获 - 带有 CPU / RAM / I/O / 警报增量的 A 与 B 对比 - 持久化的汇总事件，包含可能的原因和相关的证据 - 本地操作审计（`kill`、`block-ip`、`stop-service`、`accept-persistence-baseline`、`accept-service-baseline`、WPR、可选的 IA） - 导出 JSON · ETL 跟踪文件夹和分析

受控干预

- 结束未受进程 · 封锁远程 IP - 暂时停止服务（`BITS`、`DoSvc`、`SysMain`、`wuauserv`） - 启动 / 停止 / 取消 WPR 捕获 - 汇总最新捕获的 ETL - 手动操作受本地配置控制并在 SQLite 中进行审计

配置和可选的 AI

- `rootcause config show` · `rootcause config init` - `rootcause-config.json` 中的进程和临时文件的阈值 - `rootcause status --json` 和 `rootcause history --json` 用于集成 - `rootcause incidents` 用于查看持久化记录的性能下降 - `rootcause ai explain-latest` 仅在启用 IA 时丰富最近的事件 - 如果 IA 失败或未配置，RootCause 将继续正常运行

异常行为检测 (V1)

- 针对持续 CPU、内存增长、激进写入和异常传出流量的本地启发式算法 - 可疑路径、可配置的可靠基线以及可疑的父子进程关系 - Run/RunOnce/Startup 中的基础持久性和相关的安全服务，与已知基线进行对比并对变更进行分类 (NUEVA/MODIFICADA/ELIMINADA)，从而发出 `persistence-change` 异常 - 针对 Windows 服务（`StartMode` + 二进制路径）的监控，与已知基线进行对比，使用相同的分类 (NUEVA/MODIFICADA/ELIMINADA) 发出 `service-change` 异常 - 简单的信号关联，包含评分、严重程度、原因假设和建议的缓解措施 - 在 GUI、CLI、导出的 JSON 和持久化的历史记录中展示主要事件 - 务实的定位：作为可观察性和诊断的补充；不能替代防病毒软件或 EDR

## 🚀 自动化验证 本仓库包含在 GitHub Actions 中可见的验证： - **`ci.yml`** — 在 `windows-latest` 上进行格式化、lint、测试和发布构建 - **`release-windows.yml`** — 便携版 ZIP、Inno 安装程序和 SHA-256 哈希值 - 使用 `scripts/ci-local.ps1` 进行本地 CI 复制 - 完整指南见 [`docs/CI_GITHUB.md`](docs/CI_GITHUB.md) ## 📦 打包 ``` # 完整 release 和 artifacts 流程 .\scripts\release-product.ps1 -VerifyEnvironment # 完整流程 + push/tag/release .\scripts\release-product.ps1 -VerifyEnvironment -Publish # 静默安装（企业） RootCause-Setup.exe /VERYSILENT /SUPPRESSMSGBOXES /NORESTART ``` 也可从 shell 中使用： ``` ./scripts/release-product.sh -VerifyEnvironment ./scripts/release-product.sh -VerifyEnvironment -Publish ``` 完整详情 → [`docs/PACKAGING_WINDOWS.md`](docs/PACKAGING_WINDOWS.md) ## 📐 仓库结构 ``` rootcause-windows-inspector/ ├── Cargo.toml ← versión, features (gui / cli-only), dependencias ├── README.md ├── LICENSE ← Apache 2.0 ├── SECURITY.md ├── docs/ ← 25+ documentos de arquitectura, operación y producto ├── landing/ ← Landing page (servida por GitHub Pages desde este repo) ├── packaging/ │ ├── windows/ ← Inno Setup .iss (instalador GUI) │ ├── powershell/ ← RootCause.psm1 (módulo PowerShell, 9 cmdlets) │ ├── chocolatey/ ← rootcause.nuspec + chocolateyInstall.ps1 │ └── distribution/ │ ├── scoop/ ← rootcause.json (manifest Scoop) │ └── winget/ ← rootcause.yaml (manifest Winget) ├── vscode-extension/ ← Extensión VS Code (TypeScript, status bar, alertas) │ ├── package.json │ ├── tsconfig.json │ └── src/extension.ts ├── scripts/ ← build, verify, package, wpr, etl └── src/ ├── main.rs ← entrada: despacha CLI o GUI según args + feature guards ├── cli.rs ← CLI completa (--help, status, snapshot, wpr, kill…) ├── config.rs ← configuración operativa y defaults seguros ├── meta.rs ← constantes del producto (versión, autor, links) ├── app.rs ← UI completa (tabs, sparklines, historial, filtros) ├── models.rs ← structs compartidos + incidentes + auditoría ├── bin/ │ └── rootcause-service.rs ← skeleton Windows Service └── services/ ├── ai.rs ← adaptador IA opcional por API ├── inspector.rs ← orquestador principal + get_hardware_info() ├── persistence.rs← SQLite + snapshots + incidentes + audit trail ├── rules.rs ← rule engine ligero y correlación de incidentes ├── tray.rs ← skeleton tray icon (activa con feature `tray`) ├── windows.rs ← PowerShell, WPR, toast, cmdlines ├── network.rs ← netstat + clasificación ├── temp_scan.rs ← temporales y cachés └── etl.rs ← análisis dumpfile.xml ``` ## 📚 推荐阅读路径 | 角色 | 文档 | |---|---| | 🧑‍💻 开发者 | [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) · [`docs/RUST_PARA_ROOTCAUSE.md`](docs/RUST_PARA_ROOTCAUSE.md) | | 👤 最终用户 | [`docs/MANUAL_PARA_NOVATOS.md`](docs/MANUAL_PARA_NOVATOS.md) · [`docs/OPERACION.md`](docs/OPERACION.md) | | 🏢 招聘人员 | [`docs/RECLUTADORES.md`](docs/RECLUTADORES.md) · [`docs/REPOSITORIO_ANALISIS.md`](docs/REPOSITORIO_ANALISIS.md) | | 🔬 架构 | [`docs/ARQUITECTURA_ESCALABILIDAD.md`](docs/ARQUITECTURA_ESCALABILIDAD.md) · [`docs/ARQUITECTURA_EVOLUTIVA.md`](docs/ARQUITECTURA_EVOLUTIVA.md) | | 🛡️ 演进和弹性 | [`docs/requirements/README.md`](docs/requirements/README.md) · [`docs/ROADMAP.md`](docs/ROADMAP.md) | | 📋 Release | [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) · [`docs/ROADMAP.md`](docs/ROADMAP.md) | | 📑 全部内容 | [`docs/INDEX.md`](docs/INDEX.md) | ## 🤖 通过 API 可选的 AI RootCause 不需要 AI 即可检测缓慢、持久化证据、进行通知或通过 CLI/GUI 运行。 最低限度的激活： ``` rootcause config init $env:ROOTCAUSE_AI_API_KEY="tu_api_key" rootcause config show rootcause ai explain-latest ``` 有效的配置存在于 `rootcause-config.json` 中。要启用 IA，您必须设置 `ai.enabled = true` 并定义 `ai.endpoint`。 如果 AI 提供商出现故障： - 捕获将继续工作 - 不会丢失警报 - 已持久化的事件将被保留 - 错误将被记录在审计中 ## 🔗 公共分发（演示） 如果您想要一个与主配置文件分开的评估公共发行版，请使用 **RootCause Demo** 作为替代的分发配置： - [`docs/DEMO_PUBLICA.md`](docs/DEMO_PUBLICA.md) - [`docs/GUIA_DE_USO_PREVIA.md`](docs/GUIA_DE_USO_PREVIA.md) - [`docs/LIMITACIONES_DEMO.md`](docs/LIMITACIONES_DEMO.md) - [`docs/POLITICA_DE_PRIVACIDAD_LOCAL.md`](docs/POLITICA_DE_PRIVACIDAD_LOCAL.md) ## ⚠️ 务实的限制说明 - 不提供预编译或已签名的二进制文件 - ETL 摘要 **无法替代 WPA** 进行精细的时间点切换或符号分析 - TEMP 扫描有目的地进行了限制；不会索引整个磁盘 - `netstat` 不等同于 IDS 或完整的网络取证 - 停止服务或进程只是权宜之计，不是通用的解决方案 ## 🗺️ 名称和品牌 **RootCause** 是本仓库当前的工作名称。建议在正式发布前评估其他替代方案。初步审查见 [`docs/NOMBRES_PRODUCTO.md`](docs/NOMBRES_PRODUCTO.md)。 ## 📄 许可证 Apache 2.0 — 见 [`LICENSE`](LICENSE) 和 [`docs/LICENCIA_Y_DECISION.md`](docs/LICENCIA_Y_DECISION.md)。 ## ✍️ 作者 Vladimir Acuña · [@vladimiracunadev-create](https://github.com/vladimiracunadev-create)

标签：AI合规, ETW, Rust, Windows 调试器, 可视化界面, 性能监控, 数字取证, 网络流量审计, 自动化脚本, 诊断工具, 通知系统