wstrace

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

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

---

安装

PowerShell 脚本

powershell -ExecutionPolicy Bypass -File .\packaging\install.ps1

将 wstrace.exe 安装到 $HOME\.local\bin，并将该目录注册到用户 PATH 环境变量中。

Windows 包管理器（Winget）

winget install gilnett.wstrace

Scoop

scoop install packaging/scoop/wstrace.json

Cargo（从源码构建）

cargo install --path .

预编译二进制文件

直接使用 Rust 工具链编译：

cargo build --release

生成的独立可执行文件位于 target\release\wstrace.exe。

---

使用指南

验证

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

wstrace --version

---

交互式 TUI 模式

启动目标应用程序并显示实时事件表：

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	退出	干净地终止跟踪会话。

---

附加到正在运行的进程

通过进程标识符（PID）或二进制名称附加到现有进程，而无需重新启动它：

# Attach by PID
wstrace attach -p <PID>

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

---

子进程跟踪（-C / --children）

跟踪目标进程并递归监控由其生成的所有子进程：

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

---

路径过滤（--include 和 --exclude）

隔离相关操作或抑制操作系统噪声：

# Include only operations matching a substring
wstrace --include "<substring>" run <executable_path>

# Exclude operations matching a substring
wstrace --exclude "<substring>" run <executable_path>

---

无头流模式（-m stream）

将实时事件直接写入 stdout，并带有 ANSI 颜色代码，用于日志记录或 CI/CD 流水线：

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

---

结构化 JSON 导出（--export-json）

在终止时将所有捕获的会话事件导出到格式化的 JSON 文件：

wstrace --export-json <output_file.json> run <executable_path>

---

剪贴板导出（--copy / --to-clipboard）

退出时自动将所有捕获的会话事件直接复制到 Windows 剪贴板：

wstrace --copy run <executable_path>

---

架构与兼容性

• 核心引擎： 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