knewstimek/veh-debugger
GitHub: knewstimek/veh-debugger
一款基于VEH的Windows调试器，通过DAP与MCP协议实现反调试绕过、AI原生控制与跨进程调试，解决传统WinDbg等工具的单一附加限制。
Stars: 4 | Forks: 0
# VSCode 的 VEH Debugger
**简体中文** | [English](README.en.md)
基于 Windows VEH (Vectored Exception Handler) 的调试器。全面支持 DAP (Debug Adapter Protocol)。
## 为什么选择 VEH Debugger？
### 有利于绕过反调试
由于不使用 Windows Debug API（`NtSetInformationThread`、`IsDebuggerPresent` 等），因此可以保持 `PEB.BeingDebugged = 0` 的状态。能够自然地绕过 **Themida、VMProtect** 等基于 PEB/NtQuery 的反调试检测。但是，针对检查 VEH 本身的保护机制（如 EAC 等内核级反作弊）可能会被检测到。
### 🤝 可与现有调试器同时使用
使用 Windows Debug API 的调试器（x64dbg、WinDbg、Visual Studio 等）每个进程只能附加一个，而 VEH Debugger **可以与 Windows 调试器同时附加到同一个进程中。** 你可以在使用内核调试器或其他用户态调试器进行分析的同时，使用 VEH Debugger 辅助设置断点/监控内存。
### 🤖 原生支持 AI 代理
内置 MCP (Model Context Protocol) 工具服务器，使 **Claude、Cursor、Windsurf、Codex** 等 AI 代理可以直接控制调试器。你可以使用自然语言下达调试指令，例如“在这个函数下个断点，然后帮我看看 RAX 的值”。
### 🖥️ 集成 VSCode 环境
无需单独的调试器 GUI，**所有操作都在 VSCode 调试面板中完成。** 反汇编视图、寄存器查询/修改、内存读写，甚至是硬件断点，全部在 VSCode 内搞定。
## 特性
- **基于 VEH**：使用 VEH 代替 Windows Debug API，有利于绕过反调试
- **全面支持 DAP**：可在所有兼容 DAP 的客户端中使用，如 VSCode、MCP debug 工具等
- **MCP 工具服务器**：提供 36 个工具，供 AI 代理（Claude、Codex 等）直接控制调试器
- **TCP 模式**：通过 `--tcp --port=PORT` 支持远程调试/MCP 集成
- **远程访问**：通过 `--remote` / `--bind=0.0.0.0` 实现跨 VM/网络的调试
- **支持 32/64 位**：可调试 x86/x64 进程（需单独构建 32 位 DLL）
- **软件断点**：INT3 (0xCC) 补丁
- **硬件断点**：DR0~DR3（监控内存读取/写入 = Find What Writes/Accesses）
- **PDB 符号支持**：源文件/行号映射，通过函数名设置断点
- **反汇编**：Zydis x86/x64 反汇编程序（默认）+ 内置轻量级解码器（后备）
- **内存读写**：支持 DAP readMemory/writeMemory
- **MT (静态 CRT) 构建**：DLL 注入时无 vcruntime 依赖
## 架构
```
VSCode / DAP Client Claude / AI Agent
↕ DAP (stdin/stdout or TCP) ↕ MCP (stdin/stdout, JSON-RPC 2.0)
veh-debug-adapter.exe veh-mcp-server.exe
↕ Named Pipe IPC ↕ Named Pipe IPC
└──────── veh-debugger.dll (타겟 프로세스 내부) ────────┘
```
### 组件说明
| 组件 | 作用 |
|---------|------|
| `veh-debugger.dll` (`vcruntime_net.dll`) | 注入到目标进程。负责注册 VEH 处理程序、管理断点、查询线程/堆栈/内存 |
| `veh-debug-adapter.exe` | DAP 协议服务器。负责 DLL 注入、Named Pipe 通信、处理 JSON-RPC |
| `veh-mcp-server.exe` | MCP 工具服务器。允许 AI 代理通过 36 个工具直接控制调试器 |
| VSCode Extension | 定义 launch.json 架构，设置适配器路径（最小化包装器） |
## 构建
### 环境要求
- Windows 10+ x64
- CMake 3.20+
- Visual Studio 2022 (MSVC)
- Node.js 18+（用于 VSCode 扩展，可选）
### C++ 构建（64 位）
```
cmake -B build -G "Visual Studio 17 2022" -A x64
cmake --build build --config Release
```
输出产物：
- `build/bin/Release/veh-debug-adapter.exe` — DAP 适配器
- `build/bin/Release/veh-mcp-server.exe` — MCP 工具服务器
- `build/bin/Release/vcruntime_net.dll` — VEH 调试器 DLL（伪装名称）
### C++ 构建（32 位 DLL）
调试 32 位进程时需要：
```
cmake -B build32 -G "Visual Studio 17 2022" -A Win32
cmake --build build32 --config Release --target veh-debugger
# 输出: build32/bin/Release/vcruntime_net32.dll
# 复制到 build/bin/Release/ 使用
copy build32\bin\Release\vcruntime_net32.dll build\bin\Release\
```
### 构建 VSCode 扩展
```
cd extension
npm install
npm run compile
```
## 用法
### 1. 在 VSCode 中使用 (stdio 模式)
添加到 `.vscode/launch.json`：
**启动进程**
```
{
"type": "veh",
"request": "launch",
"name": "VEH Debug - Launch",
"program": "C:/path/to/target.exe",
"args": ["arg1", "arg2"],
"stopOnEntry": true
}
```
- `program`：要调试的可执行文件路径
- `args`：运行参数（可选）
- `stopOnEntry`：是否在入口点暂停
- `runAsInvoker`：以当前权限运行，不弹出 UAC 权限提升提示（默认：false）
**附加到正在运行的进程**
```
{
"type": "veh",
"request": "attach",
"name": "VEH Debug - Attach",
"processId": 1234
}
```
- `processId`：目标进程 PID（可在任务管理器中查看）
### 2. TCP 模式（本地）
将适配器作为独立进程运行后，DAP 客户端通过 TCP 连接：
```
veh-debug-adapter.exe --tcp --port=4711
```
默认仅绑定到 `127.0.0.1`，因此只能在本地访问。
### 3. TCP 远程模式（VM/网络）
在 VM 内部或远程机器上运行，从主机/外部连接：
```
# 在目标机器上运行 (0.0.0.0 绑定)
veh-debug-adapter.exe --tcp --port=4711 --remote
# 或
veh-debug-adapter.exe --tcp --port=4711 --bind=0.0.0.0
```
从外部使用 DAP 客户端连接到 `<目标机器IP>:4711`。
**安全警告**：`--remote` 会绑定到所有网络接口。请仅在可信网络中使用，或通过防火墙限制访问。
### 4. MCP debug 工具集成 (DAP over TCP)
```
# 以 TCP 模式运行 adapter
veh-debug-adapter.exe --tcp --port=4711
# 在 MCP debug 工具中建立 TCP 连接
debug(operation: "launch", address: "localhost:4711", ...)
```
### 5. MCP 工具服务器（直接由 AI 代理控制）
这是一个独立的 MCP 服务器，允许不了解 DAP 协议的 AI 代理像调用函数一样控制调试器。
**自动安装（推荐）**
```
# 一次性安装到所有 agent
veh-mcp-server.exe --install
# 仅安装到特定 agent
veh-mcp-server.exe --install claude-code
veh-mcp-server.exe --install cursor
# 卸载
veh-mcp-server.exe --uninstall
```
支持的代理：`claude-code`, `claude-desktop`, `cursor`, `windsurf`, `codex`
会自动检测自身的绝对路径，并注册到各个代理的配置文件中。
| 代理 | 配置文件 | 格式 |
|---------|----------|------|
| Claude Code | `~/.claude/settings.json` | JSON (`mcpServers`) |
| Claude Desktop | `%APPDATA%/Claude/claude_desktop_config.json` | JSON (`mcpServers`) |
| Cursor | `~/.cursor/mcp.json` | JSON (`mcpServers`) |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`) |
| Codex CLI | `~/.codex/config.toml` | TOML (`mcp_servers`) |
**手动安装**（直接编辑配置文件）
Claude Code / Claude Desktop / Cursor / Windsurf (JSON 格式):
```
{
"mcpServers": {
"veh-debugger": {
"command": "C:/path/to/veh-mcp-server.exe",
"args": ["--log=veh-mcp.log"]
}
}
}
```
Codex CLI (TOML 格式):
```
[mcp_servers.veh-debugger]
command = "C:/path/to/veh-mcp-server.exe"
args = ["--log=veh-mcp.log"]
enabled = true
```
配置完成后，重启代理/IDE 即可生效。
**MCP 工具列表（36个）**
| 工具 | 参数 | 描述 |
|------|------|------|
| `veh_attach` | `pid` | 向进程注入 DLL + 连接管道 |
| `veh_launch` | `program, args?, stopOnEntry?` | 创建进程 + 注入 |
| `veh_detach` | - | 分离调试器 |
| `veh_set_breakpoint` | `address, condition?, hitCondition?, logMessage?, action?` | 软件 BP。通过 `action` 在命中时自动执行 (veh_batch 格式) |
| `veh_remove_breakpoint` | `id` | 移除软件 BP |
| `veh_set_source_breakpoint` | `source, line, condition?, hitCondition?, logMessage?` | 源文件+行号 BP (需要 PDB；对于未加载的模块，状态会设为 `pending`，待模块加载后自动绑定) |
| `veh_set_function_breakpoint` | `name, condition?, hitCondition?, logMessage?` | 函数名 BP (需要 PDB；对于未加载的模块，状态会设为 `pending`，待模块加载后自动绑定) |
| `veh_list_breakpoints` | - | 查询活跃的 SW/HW BP 列表 |
| `veh_set_data_breakpoint` | `address, type, size` | HW BP (write/readwrite/execute) |
| `veh_remove_data_breakpoint` | `id` | 移除 HW BP |
| `veh_continue` | `threadId?, wait?, timeout?, pass_exception?, ignore_exceptions?` | 继续执行。可通过 `ignore_exceptions=[0x80000003]` 仅将特定异常传递给 SEH |
| `veh_step_in` | `threadId` | Step Into |
| `veh_step_over` | `threadId` | Step Over |
| `veh_step_out` | `threadId` | Step Out |
| `veh_pause` | `threadId?` | 暂停 |
| `veh_threads` | - | 线程列表 |
| `veh_stack_trace` | `threadId, maxFrames?` | 堆栈跟踪 |
| `veh_registers` | `threadId` | 查询寄存器 |
| `veh_set_register` | `threadId, name, value` | 修改寄存器值 |
| `veh_evaluate` | `expression, threadId` | 计算寄存器/内存/指针/段表达式 (`[reg+offset]`, `gs:[0x60]` 等) |
| `veh_read_memory` | `address, size` | 读取内存 (hex) |
| `veh_write_memory` | `address, data` 或 `patches` | 写入内存。支持批量：`patches=[{address,data},...]` |
| `veh_dump_memory` | `address, size, output_path` | 将内存转储为二进制文件 (最大 64MB) |
| `veh_allocate_memory` | `size?, protection?` | 在目标进程中分配内存 (VirtualAlloc) |
| `veh_free_memory` | `address` | 释放已分配的内存 (VirtualFree) |
| `veh_execute_shellcode` | `shellcode, timeout_ms?` | 执行 shellcode (分配 RWX 内存 + 复制 + 创建线程 + 等待 + 释放) |
| `veh_modules` | - | 模块列表 |
| `veh_disassemble` | `address, count?` | 反汇编 (Zydis) |
| `veh_exception_info` | - | 查询最后的异常信息 |
| `veh_trace_register` | `threadId, register, mode?, value?, max_steps?` | 跟踪寄存器变化 (DLL 内部单步循环，IPC 开销为 0) |
| `veh_trace_memory` | `address, size?, timeout_ms?` | 跟踪内存写入 (使用临时 HW BP 快速检测) |
| `veh_resolve_imports` | `threadId, addresses, max_steps?, follow_exceptions?, system_only?, target_modules?` | 批量解析混淆的 import (thunk -> DLL 单步跟踪，最多 2000 个) |
| `veh_batch` | `steps` | 批量执行多条指令 (可使用 `$N` 引用结果，支持 if/loop/for_each 控制流) |
| `veh_trace_callers` | `address, duration_sec?` | 函数调用者性能分析 (自动 resume -> 收集 N 秒内的 caller -> 自动 pause)。返回每个唯一 caller 的命中次数。x64: 使用 RtlVirtualUnwind (准确)。x86: 使用 [ESP] (仅在函数入口点准确) |
| `veh_trace_calls` | `addresses, duration_sec?, resolve?, system_only?` | 监控 call/jmp 指令在运行时的跳转目标。在 call 指令处设置 BP 并运行 N 秒，收集实际目标地址 + API 名称。`resolve=true`: 在自然的调用上下文中跟踪 thunk/trampoline，直至追踪到最终 API (应对基于异常的混淆)。`system_only=true`: 仅返回系统 DLL 目标。适用于还原加壳二进制文件的 IAT。 |
### 命令行选项
**veh-mcp-server.exe**
| 选项 | 描述 |
|------|------|
| `--install [AGENT]` | 将 MCP 服务器注册到 AI 代理配置中 (全部或指定代理) |
| `--uninstall [AGENT]` | 从 AI 代理配置中移除 MCP 服务器 |
| `--log=FILE` | 日志文件路径 |
| `--log-level=LEVEL` | 日志级别：debug, info, warn, error |
| `--help` | 输出帮助信息 |
**veh-debug-adapter.exe**
| 选项 | 描述 |
|------|------|
| `--tcp` | TCP 传输模式 (默认: stdin/stdout) |
| `--port=PORT` | TCP 端口号 (默认: 4711) |
| `--remote` | 绑定到 0.0.0.0 (允许远程连接) |
|--bind=0.0.0.0` | 与 `--remote` 相同 |
| `--log=FILE` | 日志文件路径 |
| `--log-level=LEVEL` | 日志级别：debug, info, warn, error (默认: info) |
| `--help` | 输出帮助信息 |
## 功能详情
### 断点
**软件断点 (INT3)**
- `setBreakpoints` — 基于源文件:行号 (需要 PDB)
- `setFunctionBreakpoints` — 基于函数名 (需要 PDB)
- `setInstructionBreakpoints` — 基于地址 (无需 PDB)
**硬件断点 (DR0~DR3)**
- `setDataBreakpoints` — 监控内存地址的读取/写入
- 原理与 Cheat Engine 的 "Find out what writes/accesses to this address" 相同
- 最多同时监控 4 个 (受 CPU 硬件限制)
- 监控大小：1/2/4/8 字节
### PDB 符号支持
如果存在目标进程的 PDB 文件：
- 可根据源文件名 + 行号设置断点
- 可根据函数名设置断点
- 在堆栈跟踪中显示函数名/源文件/行号
即使没有 PDB，依然可以进行基于地址的调试。
### 单步执行
| 命令 | 行为 |
|------|------|
| `next` (F10) | Step Over — 执行一行/一条指令 (跳过函数调用) |
| `stepIn` (F11) | Step Into — 进入函数内部 |
| `stepOut` (Shift+F11) | Step Out — 运行直到当前函数结束 |
### 启动进程调试
类似于 Windows 调试器中的“边运行边调试”功能。同时支持 DAP (`launch` 请求) 和 MCP (`veh_launch`)。
执行顺序：
1. `CreateProcess` + `CREATE_SUSPENDED` — 以暂停状态创建进程
2. DLL 注入 — 注册 VEH 处理程序，启动 Named Pipe 服务器
3. 如果 `stopOnEntry=true` 则在入口点保持暂停，如果为 `false` 则通过 `ResumeThread` 继续执行
如果要附加到已经在运行的进程，请使用 `attach` / `veh_attach`。
### DLL 注入
支持 4 种注入方式（自动选择）：
1. **CreateRemoteThread** — 默认方式
2. **NtCreateThreadEx** — 应对受保护的进程
3. **Thread Hijacking** — 劫持现有线程
4. **QueueUserAPC** — APC 队列方式
### 内存与反汇编
- `readMemory` / `writeMemory` — 读写任意内存
- `disassemble` — x86/x64 反汇编
- **Zydis 后端**（默认）：显示完整的操作数 (`mov rax, qword ptr [rbp-0x10]`)
- **Simple 后端**（后备）：仅显示助记符 (`mov`, `call` — 无外部依赖)
- 通过 `IDisassembler` 接口进行抽象，使用 `CreateDisassembler()` 工厂生成
- `evaluate` — 计算内存地址表达式
## 支持的 DAP 命令完整列表
| 类别 | 命令 |
|---------|------|
| 生命周期 | initialize, launch, attach, disconnect, terminate |
| 断点 | setBreakpoints, setFunctionBreakpoints, setExceptionBreakpoints, setInstructionBreakpoints, setDataBreakpoints, dataBreakpointInfo |
| 执行控制 | configurationDone, continue, next, stepIn, stepOut, pause |
| 状态查询 | threads, stackTrace, scopes, variables, evaluate |
| 内存/反汇编 | readMemory, writeMemory, disassemble |
| 其他 | modules, loadedSources, exceptionInfo, completions, source, cancel, gotoTargets |
## 项目结构
```
├── CMakeLists.txt # 루트 CMake (MT 정적 CRT)
├── src/
│ ├── dll/ # VEH 디버거 DLL
│ │ ├── dllmain.cpp # DLL 진입점
│ │ ├── veh_handler.* # VEH 예외 핸들러
│ │ ├── breakpoint.* # 소프트웨어 BP 관리
│ │ ├── hw_breakpoint.* # 하드웨어 BP (DR0~DR3)
│ │ ├── memory.* # 메모리 읽기/쓰기
│ │ ├── threads.* # 스레드 열거/제어
│ │ ├── stack_walk.* # 스택 워킹 (DbgHelp)
│ │ └── pipe_server.* # Named Pipe IPC 서버
│ ├── adapter/ # DAP 어댑터 EXE
│ │ ├── main.cpp # 진입점 (모드 파싱)
│ │ ├── dap_server.* # DAP 프로토콜 핸들러
│ │ ├── dap_types.h # DAP 타입 정의
│ │ ├── transport.* # stdin/stdout & TCP 전송
│ │ ├── injector.* # DLL 인젝션 (4가지 방식)
│ │ ├── pipe_client.* # Named Pipe IPC 클라이언트
│ │ ├── disassembler.h # IDisassembler 인터페이스
│ │ ├── disassembler.cpp # SimpleDisassembler (내장 경량 디코더)
│ │ └── zydis_disassembler.cpp # ZydisDisassembler (Zydis v4 기반)
│ ├── mcp/ # MCP 도구 서버
│ │ ├── main.cpp # 진입점 (--install, --log 등)
│ │ ├── mcp_server.* # MCP 프로토콜 + 26개 도구 구현
│ │ └── installer.* # 에이전트별 자동 설치/제거
│ └── common/ # 공유 코드
│ ├── ipc_protocol.h # IPC 명령/응답 정의
│ └── logger.h # 로깅 유틸리티
├── third_party/ # 외부 라이브러리
│ └── nlohmann/json.hpp # JSON 파서 (MIT)
│ # Zydis v4.1 (vendored in third_party/)
└── extension/ # VSCode 익스텐션
├── package.json
├── tsconfig.json
└── src/extension.ts
```
## 常见问题排查
### DLL 注入失败
- 尝试以管理员身份运行 VSCode/适配器
- 检查目标进程的位数 (32/64) — 必须与 DLL 位数匹配
- 检查杀毒软件是否阻止了注入
### 管道连接超时
- 默认超时时间为 7 秒。在较慢的系统上，加载 DLL 可能需要一些时间
- 通过日志文件查看进度：`--log=debug.log --log-level=debug`
### 断点未生效
- 确认 PDB 文件是否与目标 EXE 位于同一目录下
- 如果没有 PDB，则只能使用基于地址的 BP (`setInstructionBreakpoints`)
- 硬件 BP 最多限制为 4 个
### 无法建立远程连接
- 检查是否使用了 `--remote` 或 `--bind=0.0.0.0` 选项
- 检查防火墙是否开放了相应端口
- 确认虚拟机的网络适配器是否处于桥接模式
## 依赖项
| 库 | 用途 | 许可证 |
|-----------|------|---------|
| [nlohmann/json](https://github.com/nlohmann/json) | JSON 解析 (header-only) | MIT |
| [Zydis v4.1](https://github.com/zyantific/zydis) | x86/x64 反汇编 (包含在 third_party 中) | MIT |
## 许可证
MIT License
标签：AI编程辅助, DAP协议, MCP, VEH, Windows调试器, 云资产清单, 反调试绕过, 字典攻击, 逆向工程