wstrace

用 Rust 编写的高性能零驱动 Windows 系统与 API 监控工具。

面向 Windows 的现代 strace 与实时 Process Monitor。使用原生 Rust 构建，无需任何内核驱动，具备实时终端用户界面（TUI）以及用于无头诊断的无缓冲流式输出。

---

架构常见问题

为什么零内核驱动？

第三方内核驱动（.sys）存在系统崩溃（BSOD）风险，会扩大攻击面，并且需要驱动签名豁免，而企业环境禁止此类豁免。wstrace 100% 运行在用户态，使用非侵入式 Win32 调试 API 和原生 Windows ETW 接口。

为什么不需要管理员提权？

标准用户账户可以通过 wstrace run <binary> 运行并跟踪任意目标。派生的子进程直接继承调试句柄（PROCESS_ALL_ACCESS），无需 UAC 提示。模块、线程、套接字和 I/O 的遥测完全依赖非特权 Win32 API。

如果存在提权，为什么它仍然是一种优势？

提权是加速器，而非门槛：

• 标准用户（默认）： 对 run、attach（用户会话）、子进程（-C）、交互式 TUI 和流式输出提供完整跟踪。
• 管理员： 解锁系统级内核 ETW 和跨会话检查（wstrace all），以监控后台操作系统服务和系统守护进程。

---

安装

1. PowerShell 一行命令（无需克隆）

在 PowerShell 中运行，自动将最新版本安装到 $HOME\.local\bin 并将其添加到用户 PATH：

irm https://raw.githubusercontent.com/gilnett/wstrace/main/packaging/install.ps1 | iex

2. Scoop 包管理器

通过个人 bucket 安装：

scoop bucket add gilnett https://github.com/gilnett/scoop-bucket
scoop install wstrace

或直接通过 URL 安装：

scoop install https://raw.githubusercontent.com/gilnett/wstrace/main/packaging/scoop/wstrace.json

3. 独立二进制文件（GitHub Releases）

从 GitHub Releases 下载预编译的独立二进制文件。

4. Cargo（从源码安装）

直接从 GitHub 安装：

cargo install --git https://github.com/gilnett/wstrace.git

或从克隆的仓库本地构建：

cargo build --release

生成的二进制文件位于 target\release\wstrace.exe。

4. 包管理器（Winget 与 Scoop）

[!NOTE] Winget 和 Scoop 清单会与已发布的 GitHub Releases 自动同步。

Windows 包管理器（Winget）

[!NOTE] 官方软件包提交目前正在 microsoft/winget-pkgs 上接受审核与验证。一旦获得社区版主批准并合并，即可直接通过以下方式安装：

winget install gilnett.wstrace

Scoop

scoop install .\packaging\scoop\wstrace.json

快速开始与用法

1. 验证

确认 wstrace 在当前 shell 中可访问：

wstrace --version

2. 跟踪应用程序（交互式 TUI）

启动目标可执行文件并实时获取 Win32 和系统遥测数据：

wstrace run <executable_path> [-- <arguments>...]

TUI 键盘控制

按键	操作	描述
Ctrl+C	复制选中项	将高亮的事件详情复制到 Windows 剪贴板。
Ctrl+A	全部复制	将所有当前筛选的事件复制到 Windows 剪贴板。
Ctrl+E / Space	暂停 / 恢复	冻结事件视图，同时不丢弃传入的遥测数据。
Ctrl+X	清空缓冲区	从显示缓冲区中清空当前事件列表。
Tab	类别循环	筛选事件：ALL -> FILE -> REG -> NET -> PROC。
f	仅显示失败项	将视图限制为失败的操作（例如访问被拒绝、未找到）。
Up / Down	导航	选择一个事件进行深入检查。
q / Esc	退出	干净地终止跟踪会话。

3. 跟踪全系统范围的所有活动

实时监控全系统范围内的活动进程、新生成的进程、退出的进程以及已加载的模块：

wstrace all

4. 附加到正在运行的进程

通过 PID 或二进制名称附加到现有进程，无需重启该进程：

# Attach by PID
wstrace attach -p <PID>

# Attach by process name
wstrace attach -n <process_name.exe>

5. 无头流模式（CI/CD 与日志记录）

将实时事件直接写入 stdout，并带有 ANSI 颜色代码：

wstrace -m stream [-d <seconds>] run <executable_path>

完整手册与高级选项： 有关高级路径过滤（--include / --exclude）、子进程跟踪（-C）、JSON 报告（--export-json）、剪贴板导出（--copy）以及脚本选项，请参阅 CLI 参考手册 或运行 wstrace --help。

---

架构与兼容性

• 核心引擎： Rust（2021 Edition）
• 安装程序与部署： PowerShell（packaging/install.ps1）
• 终端 UI： Ratatui + Crossterm
• 遥测数据采集： Win32 API（ToolHelp32Snapshot、OpenProcess、VirtualQueryEx）与 Windows 事件跟踪（ETW）。
• 目标架构：
  • x86_64-pc-windows-msvc（Intel / AMD 64 位）
  • aarch64-pc-windows-msvc（Qualcomm Snapdragon X / Windows on ARM）

---

企业合规与机构治理

wstrace 专为满足高安全性企业环境（银行、国防、医疗保健和关键基础设施）中部署的严格机构要求而设计：

1. 零云端数据泄露（气隙隔离与主权独立）

wstrace 100% 离线且独立运行。它不维护任何远程服务器，不发起任何遥测或分析，也不执行任何出站网络调用。实时跟踪期间观察到的任何敏感数据（API 令牌、文件路径、凭据、内存内容）严格限制在本地 RAM 中，绝不会离开工作站。

2. 零内核驱动（零 Ring-0 足迹）

与安装第三方 .sys 内核驱动的传统跟踪工具不同——后者会引入系统崩溃风险（蓝屏死机 / BSOD）和 ring-0 后门攻击面——wstrace 以零内核驱动方式运行。它完全依赖非侵入式的用户态 Win32 调试和原生 Windows 内核 ETW 消费者接口。

3. 严格的本地访问控制与会话隔离

跟踪遥测数据严格受限于 Windows 用户会话和强制完整性控制（MIC）边界。非特权用户会话无法访问或检查更高完整性的进程，除非显式提升管理员权限，严格遵守最小权限原则。

4. 法规与标准对齐

• SOC 2 Type II 与 ISO/IEC 27001 对齐： 完整的数据主权、零外部数据外泄，以及可审计的构建来源。
• GDPR（RGPD）与 CCPA 合规： 隐私设计 架构。零个人数据收集、画像、跟踪或商业化。
• 欧盟网络弹性法案（CRA）就绪： 有记录的安全披露政策（SECURITY.md）、通过 Dependabot 进行的自动化 CVE 依赖扫描，以及第三方许可证审计清单（THIRD_PARTY_LICENSES.md）。
• OWASP 规则 #1 合规： 代码库和版本控制历史中零硬编码密钥、凭据或私有 API 密钥。

---

许可证与知识产权治理

• 软件许可证： 依据 GNU General Public License v3.0（GPL-3.0-or-later）授权。
• 贡献者许可协议（CLA）： 所有外部贡献均受 CONTRIBUTING.md 中所述条款约束，确保统一的版权所有权，并保护企业收购（M&A）和商业双许可权利。

---

致谢与第三方鸣谢

wstrace 自豪地构建于 Rust 开源生态系统之上，并感谢以下基础库：

• Ratatui（MIT）—— 现代终端用户界面（TUI）布局与渲染引擎。
• Crossterm（MIT）—— 跨平台终端操作与原始输入控制。
• windows-sys（MIT / Apache-2.0）—— 官方 Microsoft Win32 和内核 ETW API 绑定。

有关完整的许可证声明和条款，请参阅 THIRD_PARTY_LICENSES.md。

---

支持与赞助

如果你觉得 wstrace 对你的 Windows 工程、安全审计或性能调试有帮助，可以通过 GitHub Sponsors 或 Ko-fi 支持开发：

• GitHub Sponsors： https://github.com/sponsors/gilnett
• Ko-fi： https://ko-fi.com/gilnet