hyperdbg-rust-driver

Category: Development & Coding | Uploader: HyperDbg | Downloads: 0 | Version: v1.0（Latest）
HyperDbg Rust 驱动开发完整指南。包含 C++ 代码复刻、Rust 驱动开发、类型同步、编译验证等。在需要开发或维护 HyperDbg_rust 驱动时调用。
Changelog: Source: GitHub https://github.com/HyperDbg/gui
Directory Structure

Current level: tree/main/.trae/skills/hyperdbg-rust-driver/
📄 SKILL.md 21.9 KB
SKILL.md

---
name: "hyperdbg-rust-driver"
description: "HyperDbg Rust 驱动开发完整指南。包含 C++ 代码复刻、Rust 驱动开发、类型同步、编译验证等。在需要开发或维护 HyperDbg_rust 驱动时调用。"
---

# HyperDbg Rust 驱动开发完整指南

## ⚠️ 重要警告

**严禁直接使用 `cargo build` 命令！**

- 本项目使用 **EWDK (Enterprise Windows Driver Kit)** 进行编译
- 只能使用 PowerShell 构建脚本进行编译
- 当用户要求执行某个 `.ps1` 脚本时，**必须直接执行该脚本**

## ⚠️ 类型同步警告

**修改数据结构时必须更新生成器！**

| 修改类型 | 需要运行的命令 |
|----------|---------------|
| 修改 `types.go` | `go run ./cmd/rustgen/...` |
| 修改 `interfaces.go` | `go run ./cmd/rustgen/...` |
| 修改 `packet.go` | `go run ./cmd/rustgen/...` |

## 🔴 新增接口方法同步流程（重要！）

**当在 `interfaces.go` 中添加新方法时，必须按以下顺序操作：**

### 步骤 1: Go 端修改

```
1. debugger/interfaces.go  → 添加方法签名
2. debugger/types.go       → 添加需要的类型/常量（如 DebugState）
3. debugger/packet.go      → 添加方法实现
```

### 步骤 2: 运行生成器

```bash
go run ./cmd/rustgen/...
```

这会自动更新：
- `rust-driver/kd/src/generated/router.rs` → `DebuggerApi` trait
- `rust-driver/kd/src/generated/mod.rs` → 模块导出
- `cmd/mcp/mcp.go` → MCP 服务器

### 步骤 3: Rust 端实现

```
4. rust-driver/kd/src/hyperdbg_api.rs → 实现 trait 方法
5. rust-driver/kd/src/lib.rs          → 使用生成的常量（如需要）
```

### 步骤 4: 检查生成器是否需要更新

如果新方法需要新的 `Request` 字段，必须修改生成器：

**文件**: `cmd/rustgen/rustgen.go`

```go
// 在 generateRouter() 函数中找到 Request 结构体生成代码
// 添加新字段，例如：
buf.WriteString("    #[serde(skip_serializing_if = \"Option::is_none\")]\n")
buf.WriteString("    pub addr: Option<String>,\n")
```

### 完整示例：添加 `Initialize()` 方法

```go
// Step 1: interfaces.go
type Debugger interface {
    Initialize() error  // 新增
    // ...
}

// Step 2: types.go
const (
    StateInitialized DebugState = iota  // 新增
    StateRunning
    // ...
)

// Step 3: packet.go
func (p *Packet) Initialize() error {
    data := mylog.Check2(json.Marshal(map[string]string{"action": "initialize"}))
    resp := SendReceive[Empty](p, data)
    if resp == nil || !resp.Success {
        return fmt.Errorf("initialize failed: %s", resp.Message)
    }
    p.state.Store(int32(StateInitialized))
    return nil
}

// Step 4: 运行生成器
// go run ./cmd/rustgen/...

// Step 5: hyperdbg_api.rs
impl DebuggerApi for HyperDbgApi {
    fn initialize(&mut self, _req: &Request) -> Result<Empty, String> {
        if self.vmm_initialized {
            return Err(String::from("Already initialized"));
        }
        self.vmm_initialized = true;
        Ok(Empty {})
    }
    // ...
}
```

## 模块可见性问题

**生成器中的模块声明必须正确设置可见性！**

```go
// 错误 ❌ - 外部无法访问
buf.WriteString("mod ioctl;\n")

// 正确 ✅ - 外部可以访问
buf.WriteString("pub mod ioctl;\n")
```

**位置**: `cmd/rustgen/rustgen.go` 的 `generateMod()` 函数

## 源代码位置

| 组件 | C++ 源码 | Rust 实现 |
|------|---------|----------|
| hyperhv | `doc/cpp/HyperDbgUnified/HyperDbg/hyperdbg/hyperhv` | `rust-driver/kd/src/hyperkd/hyperhv` |
| hyperkd | `doc/cpp/HyperDbgUnified/HyperDbg/hyperdbg/hyperkd` | `rust-driver/kd/src/hyperkd` |

## 文件结构

```
HyperDbg_rust/
├── cmd/
│   ├── mcp/
│   │   └── mcp.go              # MCP 服务器 (自动生成)
│   └── rustgen/
│       ├── main.go             # 代码生成器入口
│       ├── rustgen.go          # Rust 类型生成
│       ├── wdkgen.go           # WDK 绑定验证
│       └── mcpgen.go           # MCP 服务器生成
│
├── debugger/
│   ├── interfaces.go           # Debugger 接口定义
│   ├── types.go                # 类型定义
│   ├── packet.go               # 通信协议
│   └── event_*.go              # 事件类型定义
│
└── rust-driver/
    └── kd/                     # 主驱动 crate
        ├── Cargo.toml
        ├── build.ps1           # 构建脚本
        └── src/
            ├── lib.rs          # 驱动入口
            ├── kd.rs           # 内核调试器
            ├── ud.rs           # 用户调试器
            ├── hyperdbg_api.rs # API 实现
            │
            ├── generated/      # 自动生成目录
            │   ├── mod.rs
            │   ├── common.rs
            │   ├── register.rs
            │   ├── event_*.rs  # 事件类型 (22个文件)
            │   ├── router.rs   # API 路由器
            │   ├── emit.rs     # 事件发射器
            │   ├── ioctl.rs    # IOCTL 代码
            │   ├── hook_db.rs  # Hook 数据库
            │   ├── hook_types.rs
            │   ├── hook_args.rs
            │   ├── ept_hook.rs
            │   ├── inline_hook.rs
            │   ├── ntddk.rs    # WDK 函数导出
            │   ├── types.rs    # WDK 类型
            │   └── constants.rs # WDK 常量
            │
            ├── go_script/      # Go 脚本引擎
            │   ├── parser/     # Go 解析器
            │   ├── analyzer.rs
            │   ├── executor.rs
            │   └── generator.rs
            │
            ├── hyperkd/        # 调试器核心
            │   ├── hyperhv/    # Hypervisor 实现
            │   │   ├── vmm/    # VMX/EPT 核心
            │   │   ├── hooks/  # Hook 机制
            │   │   ├── memory/ # 内存管理
            │   │   ├── processor/ # 处理器管理
            │   │   └── interface/ # 接口层
            │   ├── debugger.rs
            │   ├── commands.rs
            │   └── network.rs
            │
            ├── net/            # WSK HTTP Server
            │   ├── http.rs
            │   ├── json.rs
            │   └── util.rs
            │
            ├── framework/      # 驱动框架
            │   ├── device.rs
            │   ├── ioctl.rs
            │   └── utils.rs
            │
            ├── logger/         # 日志模块
            │   └── debug_logger.rs
            │
            ├── disassembler/   # 反汇编器
            └── pdbex/          # PDB 解析器
```

---

# 第一部分：C++ 代码复刻

## 复刻流程

### Phase 1: 核心头文件处理

1. **State.h** - 核心状态定义
   - `VIRTUAL_MACHINE_STATE` -> `Vcpu`
   - `VMX_CONTEXT` -> `VmxContext`
   - `EPT_STATE` -> `EptState`

2. **Ept.h** - EPT 结构定义
   - `EPT_PML4_ENTRY` -> `EptPml4Entry`
   - `EPT_PML3_ENTRY` -> `EptPdpEntry`
   - `EPT_PML2_ENTRY` -> `EptPdEntry`
   - `EPT_PML1_ENTRY` -> `EptPtEntry`

3. **Vmx.h** - VMX 结构定义
   - 所有 VMCS 字段常量
   - 所有 MSR 常量
   - 所有控制位常量

### Phase 2: 实现文件处理

1. **Ept.c** -> `ept.rs`
2. **EptHook.c** -> `ept_hook.rs`
3. **Mtf.c** -> `mtf.rs`
4. **Vmexit.c** -> `vmexit.rs`

## 数据结构映射规则

| C++ 类型 | Rust 类型 |
|---------|----------|
| `UINT8` | `u8` |
| `UINT16` | `u16` |
| `UINT32` | `u32` |
| `UINT64` | `u64` |
| `SIZE_T` | `usize` |
| `BOOLEAN` | `bool` |
| `PVOID` | `*mut c_void` |
| `CHAR[]` | `[u8; N]` |

### 结构体映射示例

```rust
// C++
typedef struct _EPT_PML1_ENTRY {
    UINT64 ReadAccess : 1;
    UINT64 WriteAccess : 1;
    UINT64 ExecuteAccess : 1;
    UINT64 MemoryType : 3;
    UINT64 PageFrameNumber : 40;
} EPT_PML1_ENTRY;

// Rust
#[repr(C, packed)]
pub struct EptPtEntry {
    pub value: u64,
}

impl EptPtEntry {
    pub fn read_access(&self) -> bool { (self.value & 1) != 0 }
    pub fn set_read_access(&mut self, v: bool) {
        if v { self.value |= 1; } else { self.value &= !1; }
    }
}
```

---

# 第二部分：WDK 绑定

## 🔴 强制阅读 WDK 绑定文件

**写任何模块之前，必须先阅读以下文件：**

```
rust-driver/kd/src/generated/ntddk.rs      # 所有内核函数 (1251个)
rust-driver/kd/src/generated/types.rs      # 所有类型定义 (7317个)
rust-driver/kd/src/generated/constants.rs  # 所有常量 (5348个)
```

## WDK-SYS 关键函数签名

### IRP 相关函数

```rust
pub fn IoAllocateIrp(StackSize: CCHAR, ChargeQuota: BOOLEAN) -> PIRP;
pub fn IoFreeIrp(Irp: PIRP);
pub fn IoAllocateMdl(VirtualAddress: PVOID, Length: ULONG, ...) -> PMDL;
pub fn IoFreeMdl(Mdl: PMDL);
```

### 事件相关函数

```rust
pub fn KeInitializeEvent(Event: PRKEVENT, Type: EVENT_TYPE, State: BOOLEAN);
pub fn KeSetEvent(Event: PRKEVENT, Increment: KPRIORITY, Wait: BOOLEAN) -> LONG;
pub fn KeWaitForSingleObject(Object: PVOID, WaitReason: KWAIT_REASON, ...) -> NTSTATUS;
```

## 枚举类型使用

**枚举类型是 `i32` 类型别名，必须通过模块路径访问常量！**

```rust
// 错误用法 ❌
use wdk_sys::EVENT_TYPE;
EVENT_TYPE::SynchronizationEvent  // 编译错误！

// 正确用法 ✅
use wdk_sys::_EVENT_TYPE;
_EVENT_TYPE::SynchronizationEvent  // 正确！
```

---

# 第三部分：Rust 生成器同步

当 Go 端的类型定义或接口发生变化时，需要同步更新 Rust 生成器生成的代码。

## 同步步骤

1. **运行 Rust 生成器**
   ```bash
   cd HyperDbg_rust/cmd/rustgen
   go run .
   ```

2. **检查编译**
   ```bash
   cd HyperDbg_rust/rust-driver/kd
   cargo check
   ```

3. **修复生成器（如有警告或错误）**
   - 如果出现 "unused import" 警告，在生成器中添加 `#![allow(unused_imports)]`
   - 如果出现类型找不到错误，检查是否需要 `use super::*;`
   - 生成器文件：`HyperDbg_rust/cmd/rustgen/wdkgen.go`

## 生成器关键代码位置

| 函数 | 文件 | 作用 |
|------|------|------|
| `GenerateRustTypes()` | rustgen.go | 类型生成入口 |
| `generateTypesSplit()` | rustgen.go | 类型生成 |
| `generateHandlersSplit()` | rustgen.go | 处理器生成 |
| `GenerateBindgen()` | wdkgen.go | WDK 绑定验证 |
| `GenerateHookDatabase()` | wdkgen.go | Hook 数据库生成 |
| `GenerateMCP()` | mcpgen.go | MCP 服务器生成 |

## 常见问题

| 问题 | 解决方案 |
|------|---------|
| 未使用的导入警告 | 添加 `#![allow(unused_imports)]` 属性 |
| 类型找不到错误 | 确保 `use super::*;` 存在 |
| 函数签名冲突 | 添加 `#![allow(clashing_extern_declarations)]` |
| 函数转整数警告 | 添加 `#![allow(warnings)]` |
| `module is private` 错误 | 在生成器中将 `mod xxx` 改为 `pub mod xxx` |
| trait 方法未实现 | 在 `hyperdbg_api.rs` 中添加对应方法 |
| `undefined: StateXxx` 错误 | 在 `types.go` 中添加 DebugState 常量 |

## 🔴 编译验证流程

**每次修改后必须验证编译通过！**

```bash
# 1. 运行生成器
go run ./cmd/rustgen/...

# 2. 编译驱动
powershell -ExecutionPolicy Bypass -File "rust-driver/kd/build.ps1"

# 3. 运行测试（如有）
go test ./...
```

## 🔴 使用生成的 IOCTL 常量

**在 `lib.rs` 中使用生成的 IOCTL 常量，而不是硬编码数字！**

```rust
// 错误 ❌ - 硬编码数字
match control_code {
    0x800 => { ... }
    0x900 => { ... }
}

// 正确 ✅ - 使用生成的常量
use crate::generated::ioctl::*;

match control_code {
    IOCTL_INTERNAL_DRIVER_INITIALIZE => { ... }
    IOCTL_INTERNAL_KERNEL_DEBUGGER_INITIALIZE => { ... }
}
```

**IOCTL 常量文件**: `rust-driver/kd/src/generated/ioctl.rs`

---

# 第四部分：WSK 网络编程

## 参考项目

| 项目 | 路径 | 说明 |
|------|------|------|
| KSOCKET | `todo/参考价值/KSOCKET-master/` | Berkeley Socket API 风格的 WSK 封装 |
| DriverUtil | `todo/参考价值/代码+课件/DriverUtil/` | EPT Hook 和 WSK Socket 实现 |

## WSK 核心实现模式

```rust
// 异步上下文结构
struct Context {
    event: KEVENT,  // 使用 KEVENT 类型 (24字节)
    irp: PIRP,
}

// 完成回调 - 必须返回 STATUS_MORE_PROCESSING_REQUIRED
unsafe extern "C" fn wsk_completion_routine(
    _device: PDEVICE_OBJECT,
    _irp: PIRP,
    context: PVOID,
) -> NTSTATUS {
    if !context.is_null() {
        KeSetEvent(context as PRKEVENT, 0, false as BOOLEAN);
    }
    STATUS_MORE_PROCESSING_REQUIRED  // 关键！
}

// 初始化异步上下文
impl Context {
    fn new() -> Result<Self, SocketError> {
        unsafe {
            let irp = IoAllocateIrp(1, false as BOOLEAN);
            let mut ctx = Context {
                event: core::mem::zeroed(),
                irp,
            };
            KeInitializeEvent(
                &raw mut ctx.event as PRKEVENT, 
                _EVENT_TYPE::SynchronizationEvent, 
                false as BOOLEAN
            );
            Ok(ctx)
        }
    }

    fn wait_for_completion(&mut self) -> NTSTATUS {
        unsafe {
            let _ = KeWaitForSingleObject(
                &raw mut self.event as PVOID,
                _KWAIT_REASON::Executive,
                KERNEL_MODE,
                false as BOOLEAN,
                ptr::null::<LARGE_INTEGER>() as PLARGE_INTEGER,
            );
            (*self.irp).IoStatus.__bindgen_anon_1.Status
        }
    }
}
```

## WSK Socket 类型标志

```c
#define WSK_FLAG_BASIC_SOCKET        0x00000000  // 基本套接字
#define WSK_FLAG_LISTEN_SOCKET       0x00000001  // 监听套接字 (TCP Server)
#define WSK_FLAG_DATAGRAM_SOCKET     0x00000002  // 数据报套接字 (UDP)
#define WSK_FLAG_CONNECTION_SOCKET   0x00000004  // 连接套接字 (TCP Client)
```

---

# 第五部分：Go 脚本引擎

## 概述

项目包含一个完整的 Go 脚本解析器，用于在内核中执行 Go 代码片段进行 Hook 操作。

## 文件结构

```
go_script/
├── parser/           # Go 解析器 (从 goscript 移植)
│   ├── ast.rs       # AST 节点定义
│   ├── scanner.rs   # 词法分析器
│   ├── parser.rs    # 语法分析器
│   ├── token.rs     # Token 定义
│   └── ...
├── analyzer.rs       # AST 分析器
├── executor.rs       # 脚本执行器
├── generator.rs      # Rust 代码生成器
└── mod.rs           # 模块入口
```

## Hook 安装流程

```
Go 代码 → Parser → AST → Analyzer → HookOperations → Executor → WDK API
    │                                                    │
    │  install_hook_script()                             │
    │  ├── parse_go_code()                               │
    │  ├── analyze_go_code()                             │
    │  ├── lookup_api_address()                          │
    │  └── install_ept_hook() / install_inline_hook()    │
    │                                                    │
    └────────────────────────────────────────────────────┘
```

---

# 第六部分：验证清单

## 每个文件完成后检查

- [ ] 所有结构体字段完整
- [ ] 所有函数签名正确
- [ ] 所有常量值正确
- [ ] 编译无错误
- [ ] 使用 WDK 绑定而非手动声明

## 禁止修改的文件

- `rust-driver/kd/src/generated/*.rs` - 自动生成的文件
- `cmd/mcp/mcp.go` - 自动生成的 MCP 服务器

## 编译命令

```powershell
# 编译主驱动
cd d:\ux\examples\hypedbg\HyperDbg_rust\rust-driver\kd
powershell -ExecutionPolicy Bypass -File build.ps1

# 检查编译（不生成驱动）
cargo check
```

---

# 第七部分：错误处理

遇到问题时：

1. 检查类型是否匹配
2. 检查生命周期是否正确
3. 检查 unsafe 块是否正确
4. 检查模块导入是否正确
5. 参考 C++ 原始实现
6. 检查 WDK 绑定文件中的函数签名

## 输出格式

每完成一个文件，报告：
```
✓ 完成: <C++文件> -> <Rust文件>
  - 结构体: <数量>
  - 函数: <数量>
  - 常量: <数量>
  - 编译状态: <通过/失败>
```

---

# 第八部分：实战案例 - 添加新接口方法

## 背景

本次案例展示了如何添加 6 个新接口方法到 HyperDbg 项目：

- `Initialize()`
- `Terminate()`
- `StartNetworkServer(addr string)`
- `StopNetworkServer()`
- `KernelDebuggerInitialize()`
- `KernelDebuggerUninitialize()`

## 遇到的问题

### 问题 1: 模块可见性错误

```
error[E0603]: module `ioctl` is private
   --> src\lib.rs:410:27
    |
410 |     use crate::generated::ioctl::*;
    |                           ^^^^^ private module
```

**原因**: 生成器中 `ioctl` 模块声明为 `mod ioctl` 而非 `pub mod ioctl`

**解决**: 修改 `cmd/rustgen/rustgen.go`

```go
// 修改前
buf.WriteString("mod ioctl;\n")

// 修改后
buf.WriteString("pub mod ioctl;\n")
```

### 问题 2: Trait 方法未实现

```
error[E0046]: not all trait items implemented, missing: `initialize`, `terminate`, ...
```

**原因**: 生成器自动在 `DebuggerApi` trait 中添加了新方法，但 `hyperdbg_api.rs` 未实现

**解决**: 在 `hyperdbg_api.rs` 中添加实现

```rust
impl DebuggerApi for HyperDbgApi {
    fn initialize(&mut self, _req: &Request) -> Result<Empty, String> {
        // 实现代码
    }
    // ... 其他方法
}
```

### 问题 3: 未定义的状态常量

```
debugger\packet.go:623:22: undefined: StateInitialized
```

**原因**: `types.go` 中缺少 `StateInitialized` 常量

**解决**: 在 `types.go` 中添加

```go
const (
    StateInitialized DebugState = iota  // 新增
    StateRunning
    StatePaused
    StateStepping
    StateTerminated
)
```

### 问题 4: Request 缺少字段

```
error: no field `addr` on type `Request`
```

**原因**: 新方法 `StartNetworkServer(addr string)` 需要 `addr` 字段，但生成器未生成

**解决**: 修改 `cmd/rustgen/rustgen.go`

```go
// 在 Request 结构体生成代码中添加
buf.WriteString("    #[serde(skip_serializing_if = \"Option::is_none\")]\n")
buf.WriteString("    pub addr: Option<String>,\n")
```

## 完整操作流程

```
┌─────────────────────────────────────────────────────────────┐
│  Step 1: Go 端修改                                          │
│  ├── debugger/interfaces.go  → 添加 6 个方法签名            │
│  ├── debugger/types.go       → 添加 StateInitialized        │
│  └── debugger/packet.go      → 添加 6 个方法实现            │
├─────────────────────────────────────────────────────────────┤
│  Step 2: 修改生成器                                         │
│  └── cmd/rustgen/rustgen.go                                 │
│      ├── pub mod ioctl (模块可见性)                         │
│      └── addr: Option<String> (Request 字段)                │
├─────────────────────────────────────────────────────────────┤
│  Step 3: 运行生成器                                         │
│  └── go run ./cmd/rustgen/...                               │
│      → 生成 27 个 Rust 文件                                 │
│      → 生成 MCP 服务器 (45 个方法)                          │
├─────────────────────────────────────────────────────────────┤
│  Step 4: Rust 端实现                                        │
│  ├── hyperdbg_api.rs → 实现 6 个 trait 方法                 │
│  └── lib.rs          → 使用 IOCTL 常量替换硬编码            │
├─────────────────────────────────────────────────────────────┤
│  Step 5: 编译验证                                           │
│  └── powershell -ExecutionPolicy Bypass -File build.ps1     │
│      → 编译成功！                                           │
└─────────────────────────────────────────────────────────────┘
```

## 关键文件对照表

| Go 文件 | Rust 文件 | 说明 |
|---------|----------|------|
| `interfaces.go` | `generated/router.rs` | 接口 → Trait |
| `types.go` | `generated/common.rs` | 类型定义 |
| `packet.go` | `hyperdbg_api.rs` | 实现 |
| - | `generated/ioctl.rs` | IOCTL 常量 |

## 经验总结

1. **生成器是核心** - 所有类型同步都通过生成器完成
2. **模块可见性很重要** - 需要外部使用的模块必须声明为 `pub`
3. **Request 字段要同步** - 新方法需要新字段时，必须更新生成器
4. **编译验证不可少** - 每次修改后都要运行编译验证
5. **使用生成的常量** - 不要硬编码 IOCTL 数字，使用生成的常量
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
hyperdbg-rust-driver

Directory Structure

SKILL.md

Report

Notice
