# winbintool

**Repository Path**: yuliqing16/winbintool

## Basic Information

- **Project Name**: winbintool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-22
- **Last Updated**: 2026-04-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# winbintool

`winbintool` 是一个 Windows 进程工具，提供 REPL 和一次性 `--cmd` 执行模式，支持附加到本机进程、读写内存、枚举模块和线程、查看进程信息、执行函数调用，并在需要时自动加载 `winbintool_agent.dll`。

它目前以 x64 控制器为主，同时配套 x86 helper，用于处理跨位数场景和保持同一套命令体验。

## 能做什么

- 附加到当前进程或指定 PID
- 读写远程进程内存
- 查看模块、线程、内存区域和进程状态
- 运行表达式、变量、指针和地址相关命令
- 做内存搜索、扫描、观察和差异检查
- 调用目标进程中的函数
- 通过 agent 执行更依赖进程上下文的操作

## 目录结构

```text
src/main.cpp            CLI 入口
src/app/                命令解析、REPL、会话逻辑
src/win/                Windows 相关过程、内存和 agent 通信
src/agent/              注入式 DLL agent
include/wbt/            公共头文件
tests/test_winbintool.cpp  测试程序
docs/harness/           agent 交互约定和稳定输出规范
scripts/                构建和发布脚本
```

## 构建

```powershell
cmake -S . -B build
cmake --build build --config Debug
ctest --test-dir build -C Debug --output-on-failure
```

如果需要 x86 helper，再建一个 Win32 tree：

```powershell
cmake -S . -B build-win32 -A Win32
cmake --build build-win32 --config Debug --target winbintool_helper
```

如果你是直接用 MSVC 命令行，请先确保 shell 已初始化到 `x86` 环境，再配置 Win32 tree。

## 发布

使用 `scripts/publish.ps1` 生成可分发目录：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/publish.ps1 -Configuration Release
```

默认输出结构：

```text
publish\Release\x64\winbintool.exe
publish\Release\x64\winbintool_agent.dll
publish\Release\x86\winbintool_helper.exe
```

脚本会把运行所需的 VC 运行库一起复制到对应架构目录。控制器会先找同目录下的 helper，再尝试 `..\x86\winbintool_helper.exe`，所以发布后的 `x64` 目录可以直接启动。

## 快速开始

查看帮助：

```powershell
.\build\Debug\winbintool.exe --help
```

在当前进程里跑一个最小自检：

```powershell
.\build\Debug\winbintool.exe attach <pid> --cmd smoke
```

附加到指定 PID：

```powershell
.\build\Debug\winbintool.exe attach <pid> --cmd status
```

如果 helper 不在默认位置，可以显式指定：

```powershell
$env:WBT_HELPER_PATH = "D:\path\to\winbintool_helper.exe"
```

## 命令速查

### 基础模式

- `help [topic]`
- `attach <pid>`
- `detach`
- `quit` / `exit`

### 进程信息

- `pid`
- `status`
- `procinfo`
- `maps`
- `limits`
- `fds` (handle count + file handle paths)
- `ns`
- `net`
- `tree`
- `modules`
- `threads`
- `heap`
- `sections`

### 符号和地址

- `where`
- `info`
- `check`
- `symbols`
- `functions`
- `exports`
- `imports`
- `got`
- `plt`
- `source`
- `lineinfo`

### 内存操作

- `d <address> <size>` / `db` / `read`
- `write <address> <byte> [byte...]` / `w` / `w32` / `w64`
- `watch <address> <size>`
- `watch_status`
- `find <address> <size> <byte...>`
- `findstr <address> <size> <text...>`
- `findptr <value>`
- `xrefs <value>`
- `scan <address> <size> <byte...>`

### 执行和诊断

- `call <address> [arg...]`
- `disasm <address> <size>`
- `telescope <address> [depth]`
- `bt`
- `json`
- `ping`
- `smoke`

## 表达式写法

- `123`、`0x7b`、`7b` 都会被当成数字处理
- `name` 会先按变量或符号解析
- `&name` 会打印地址
- `name=value` 会写入变量
- `call`、`where`、`check`、`source`、`lineinfo` 这类命令都能直接吃表达式

## 测试

```powershell
ctest --test-dir build -C Release --output-on-failure
```

常用自检命令：

```powershell
.\build\Release\winbintool.exe attach <pid> --cmd ping
.\build\Release\winbintool.exe attach <pid> --cmd smoke
```

## 注意事项

- 这个工具只适合授权的本机调试和分析场景
- 发布包里必须同时有 `winbintool.exe`、`winbintool_agent.dll` 和 `winbintool_helper.exe`
- `smoke` 主要用于验证控制器、agent 和 helper 的基本链路
- `WBT_HELPER_PATH` 可以覆盖自动查找逻辑