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 13.1 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` | `cd cmd/rustgen && go run .` |
| 修改 `interfaces.go` | `cd cmd/rustgen && go run .` |
| 修改 `packet.go` | `cd cmd/rustgen && go run .` |

## 源代码位置

| 组件 | 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)]` |

---

# 第四部分：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文件>
  - 结构体: <数量>
  - 函数: <数量>
  - 常量: <数量>
  - 编译状态: <通过/失败>
```
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
hyperdbg-rust-driver

Directory Structure

SKILL.md

Report

Notice
