IntructionTracer

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

IntructionTracer

★ 12 Open GitHub ↗

x64dbg插件:用来记录指令流程

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# InstructionTracer

x64dbg 指令跟踪插件。从当前位置开始单步执行，自动记录用户模块中的每条指令，跳过系统 DLL，直到到达指定目标地址，并将执行路径保存到文本文件。

适用于逆向分析中需要还原「从 A 点到 B 点」之间实际执行了哪些指令的场景。

## 功能特性

- **单步跟踪**：从当前 EIP/RIP 开始，逐条执行指令
- **智能跳过系统模块**：进入 `ntdll.dll`、`kernel32.dll` 等系统 DLL 时自动 `StepOver`，不写入日志
- **记录用户模块指令**：在用户模块（如目标 exe、dll）中记录地址与反汇编文本
- **目标地址停止**：到达指定地址后自动结束跟踪并保存文件
- **手动停止**：支持 `TraceStop` 命令随时中止
- **支持 x86 / x64**：分别编译为 `.dp32` / `.dp64`

## 工作原理

```
TraceLog 启动
    ↓
StepInto 执行一条指令
    ↓
CBSTEPPED 回调触发
    ↓
┌─ 到达目标地址？ → 记录最后一条指令 → 结束
├─ 系统模块？     → StepOver 跳过
└─ 用户模块？     → 写入日志 → StepInto 继续
```

## 环境要求

- Windows 10/11
- [x64dbg](https://x64dbg.com/)（用于加载插件）
- Visual Studio 2022（含 C++ 工作负载）或 Build Tools
- CMake 3.8+
- Ninja（可选，CMake Presets 默认使用）

## 快速开始

### 1. 获取链接库

首次构建前，需要将 x64dbg SDK 的 `.lib` 文件放入 `InstructionTracer/pluginsdk/` 目录。

运行项目自带的下载脚本：

```powershell
powershell -ExecutionPolicy Bypass -File cmake\fetch-x64dbg-libs.ps1
```

脚本会从 x64dbg 官方快照包中提取以下文件：

- `x64dbg.lib` / `x64bridge.lib`（64 位）
- `x32dbg.lib` / `x32bridge.lib`（32 位）

也可手动从 [x64dbg Plugins Wiki](https://github.com/x64dbg/x64dbg/wiki/Plugins) 获取开发包后复制到该目录。

### 2. 编译

在 **Visual Studio 开发者命令行** 或已配置好 MSVC 环境的终端中执行：

```powershell
# 64 位 Debug（常用）
cmake --preset x64-debug
cmake --build out/build/x64-debug

# 64 位 Release
cmake --preset x64-release
cmake --build out/build/x64-release

# 32 位 Debug
cmake --preset x86-debug
cmake --build out/build/x86-debug
```

编译产物路径：

| 预设 | 输出文件 |
|------|----------|
| x64-debug / x64-release | `out/build/<preset>/InstructionTracer/InstructionTracer.dp64` |
| x86-debug / x86-release | `out/build/<preset>/InstructionTracer/InstructionTracer.dp32` |

也可在 Visual Studio 中直接打开项目文件夹，选择对应 CMake 预设后构建。

### 3. 安装插件

将编译好的插件复制到 x64dbg 的 `plugins` 目录：

```
# 64 位 x64dbg
<x64dbg目录>\release\x64\plugins\InstructionTracer.dp64

# 32 位 x32dbg
<x64dbg目录>\release\x32\plugins\InstructionTracer.dp32
```

重启 x64dbg，在日志窗口应看到加载成功提示。

## 使用方法

**前提**：已附加或启动目标进程，程序处于暂停状态。

### 开始跟踪

在 x64dbg 命令栏输入（参数用**逗号**分隔）：

```
TraceLog <目标地址>, <日志文件路径>
```

示例：

```
TraceLog 0x401500, C:\trace.txt
TraceLog game.exe+0x1234, D:\logs\path.txt
```

执行后插件会：

1. 解析目标地址
2. 创建/覆盖日志文件
3. 从当前位置开始 `StepInto`
4. 在用户模块中逐条记录指令，直到到达目标地址

### 停止跟踪

```
TraceStop
```

### 日志格式

每行一条指令，格式为 `地址  反汇编`：

```
0x0000000000401000  mov eax, 1
0x0000000000401005  add eax, ebx
0x0000000000401007  call game.401200
```

## 命令参考

| 命令 | 说明 | 示例 |
|------|------|------|
| `TraceLog` | 开始指令跟踪 | `TraceLog 0x401500, C:\trace.txt` |
| `TraceStop` | 停止当前跟踪 | `TraceStop` |

> **注意**：x64dbg 命令参数以逗号 `,` 分隔，不是空格。文件路径若包含空格，请确保逗号只用于分隔「地址」和「路径」两段参数。

## 项目结构

```
InstructionTracer/
├── README.md
├── CMakeLists.txt              # 顶层 CMake
├── CMakePresets.json           # 构建预设（x64/x86, Debug/Release）
├── cmake/
│   └── fetch-x64dbg-libs.ps1   # 下载 x64dbg 链接库脚本
└── InstructionTracer/
    ├── CMakeLists.txt          # 插件构建配置
    ├── pluginmain.h            # SDK 宏定义（dputs、PLUG_EXPORT 等）
    ├── pluginmain.cpp          # 插件导出入口（pluginit/plugstop/plugsetup）
    ├── plugin.h                # 业务函数声明
    ├── plugin.cpp              # 核心跟踪逻辑
    └── pluginsdk/              # x64dbg SDK 头文件与链接库
```

## 技术说明

### 插件架构

项目遵循 [x64dbg PluginTemplate](https://github.com/x64dbg/PluginTemplate) 的分层结构：

- **框架层**（`pluginmain.*`）：处理 x64dbg 要求的 DLL 导出、SDK 版本信息、日志宏
- **业务层**（`plugin.*`）：实现 `TraceLog` / `TraceStop` 命令与 `CBSTEPPED` 步进回调

### 关键 API

| API | 用途 |
|-----|------|
| `_plugin_registercommand` | 注册自定义命令 |
| `DbgEval` | 解析地址表达式 |
| `DbgValFromString` | 读取 `cip`、`mod.system(cip)` 等表达式 |
| `DbgCmdExecDirect` | 同步执行 `StepInto` / `StepOver` |
| `DbgDisasmAt` | 获取当前地址反汇编文本 |

### 编码

x64dbg 日志 API 要求 **UTF-8** 字符串。项目在 MSVC 下启用了 `/utf-8` 编译选项，确保中文日志正常显示。

## 常见问题

**Q: 插件加载后没有命令？**  
A: 命令仅在调试状态下可用。请先附加或启动目标进程。

**Q: 日志中文乱码？**  
A: 请使用最新编译的版本（已包含 `/utf-8` 选项），并确保源文件以 UTF-8 保存。

**Q: 跟踪很慢？**  
A: 单步跟踪本身较慢，这是预期行为。系统 DLL 已自动跳过以减少无关记录。

**Q: 目标地址永远到不了？**  
A: 使用 `TraceStop` 手动停止，或检查目标地址是否在可达的执行路径上。

**Q: 编译提示缺少 `.lib`？**  
A: 运行 `cmake\fetch-x64dbg-libs.ps1` 或手动将链接库放入 `InstructionTracer/pluginsdk/`。

## 参考资源

- [x64dbg 插件开发文档](https://help.x64dbg.com/en/latest/developers/plugins/index.html)
- [x64dbg 表达式语法](https://help.x64dbg.com/en/latest/introduction/Expressions.html)
- [PluginTemplate 官方模板](https://github.com/x64dbg/PluginTemplate)

## License

MIT

IntructionTracer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README