Hyperdbg Consistency Checker

HyperDbg Go/C++ Consistency Checker

This skill helps verify that Go implementations are consistent with the original C++ HyperDbg codebase.

When to Invoke

• User wants to compare Go test code with C++ implementation
• Debugging IOCTL structure mismatches
• Verifying struct layouts between Go and C++
• Checking if Go implementation follows C++ patterns
• Investigating BSOD crashes related to driver communication
• Fixing compilation errors after SDK bindgen regeneration
• Resolving type/field name differences between old code and new SDK

Directory Structure Mapping

Key Files to Compare

Go Implementation

• debugger/app/libhyperdbg.go - 应用层入口
• debugger/kernel_level/kd.go - 内核调试器
• debugger/kernel_level/kernel_listening.go - 内核监听
• debugger/user_level/ud.go - 用户态调试器
• debugger/user_level/user_listening.go - 用户态监听
• debugger/user_level/pe_parser.go - PE解析器
• debugger/core/debugger.go - 核心调试逻辑
• debugger/core/interpreter.go - 命令解释器
• debugger/core/steppings.go - 单步执行
• debugger/core/break_control.go - 断点控制
• debugger/communication/namedpipe.go - 命名管道
• debugger/communication/remote_connection.go - 远程连接
• debugger/communication/tcp.go - TCP通信
• debugger/communication/forwarding.go - 事件转发
• debugger/misc/assembler.go - 汇编器
• debugger/misc/disassembler.go - 反汇编器
• debugger/misc/callstack.go - 调用栈
• debugger/misc/pci_id.go - PCI ID数据库
• debugger/misc/readmem.go - 内存读取
• debugger/script_engine/script_engine.go - 脚本引擎
• debugger/script_engine/script_engine_wrapper.go - 脚本引擎包装器
• debugger/script_engine/symbol.go - 符号表
• debugger/transparency/transparency.go - 透明模式
• debugger/transparency/gaussian_rng.go - 高斯随机数
• debugger/driver_loader/install.go - 驱动安装
• debugger/common/common.go - 通用工具
• debugger/common/cpu.go - CPU相关
• debugger/common/list_spinlock.go - 链表和自旋锁
• debugger/export/types.go - 导出类型
• debugger/export/common_export.go - 导出通用函数
• debugger/commands/debugging/debugging_commands.go - 调试命令
• debugger/commands/extension/extension_commands.go - 扩展命令
• debugger/commands/meta/meta_commands.go - 元命令
• debugger/objects/objects.go - 对象管理
• debugger/rev/rev_ctrl.go - 逆向控制
• debugger/pdbex/ - PDB解析器(Go独有)
• debugger/debugger_test.go - 测试代码

C++ Implementation

• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/app/libhyperdbg.cpp - 应用层入口
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/kernel-level/kd.cpp - 内核调试器
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/kernel-level/kernel-listening.cpp - 内核监听
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/user-level/ud.cpp - 用户态调试器
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/user-level/user-listening.cpp - 用户态监听
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/user-level/pe-parser.cpp - PE解析器
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/core/debugger.cpp - 核心调试逻辑
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/core/interpreter.cpp - 命令解释器
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/core/steppings.cpp - 单步执行
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/core/break-control.cpp - 断点控制
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/communication/ - 通信模块
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/misc/ - 辅助模块
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/script-engine/ - 脚本引擎
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/transparency/ - 透明模式
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/driver-loader/install.cpp - 驱动安装
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/common/common.cpp - 通用工具
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/export/export.cpp - 导出函数
• HyperDbgUnified/HyperDbg/hyperdbg/libhyperdbg/code/debugger/commands/ - 命令模块
• HyperDbgUnified/HyperDbg/hyperdbg/hyperkd/code/driver/Ioctl.c - 内核IOCTL处理

Bindgen SDK Generator (2026-04-16 ✅ 已完成)

架构概述

Bindgen 是一个基于 modernc.org/cc/v4 C 解析器的自动代码生成器，将 HyperDbg C 头文件转换为 Go 类型绑定。

核心文件： debugger/bindgen/generate_test.go

输入： debugger/bindgen/SDK/headers/*.h (13个头文件)

输出： debugger/sdk/*.go (12个Go绑定文件)

BindgenConfig 多目标配置

type BindgenConfig struct {
    Name        string
    HeadersDir  string
    OutputDir   string
    PackageName string
    HeaderOrder []string
}

当前激活配置：

• sdk — 输入: SDK/headers/, 输出: ../sdk/, 包名: sdk

待激活配置（已注释）：

• header — 输入: HyperDbgUnified/.../header/, 输出: ../header/, 包名: header（因C++语法问题暂未启用）

头文件 → Go文件映射

核心生成机制

1. 全局去重 (Global Deduplication)

使用 safemap.M 有序Map确保跨头文件的类型唯一性：

type Result struct {
    Structs  *safemap.M[string, structInfo]
    Enums    *safemap.M[string, enumInfo]
    Typedefs *safemap.M[string, typedefInfo]
    Macros   *safemap.M[string, macroConstInfo]
    FnMacros *safemap.M[string, macroConstInfo]
}

2. N-ary Tree 结构体解析

嵌套匿名结构体通过递归提取为独立类型：

func generateStructFields(t *cc.StructType, structGoName string, isPacked bool) (fields, methods string, innerTypes []structInfo)
func generateStructFieldsInnerTypes(t *cc.StructType, structGoName string, forcePacked bool) []structInfo

• 有tag的嵌套结构体 → 提取为独立 innerType
• 递归处理多层嵌套
• 生成 getter/setter 方法访问嵌套字段

3. 预制结构体 (Prebuilt Structs)

SDK头文件中引用但未定义的外部类型，手动注入：

type prebuiltStruct struct {
    goName, cName, source, originalSource string
    fields                                string
    lineNo                                int
}

已注入的预制结构体：

• source 字段：分配到哪个输出文件（如 Constants.h）
• originalSource 字段：实际来源路径（用于注释追踪）

4. 统一类型映射

func mapPredefinedType(kind cc.Kind, fallback string) string

5. 枚举生成策略

• 连续值从0开始 → 使用 iota
• 连续值从N开始 → 显式赋值（如 = 1, = 2, ...）
• 非连续值 → 逐个显式赋值
• 每个枚举自动生成 String() 方法

运行 Bindgen

cd c:\Users\Admin\Desktop\hypedbg\debugger
go test -run TestGenerate -v -count=1 ./bindgen/

验证编译

cd c:\Users\Admin\Desktop\hypedbg\debugger
go test -run TestFixError -v -count=1

gen → sdk 迁移 (2026-04-16 ✅ 已完成)

迁移概述

将所有 Go 代码从旧的 bindgen/gen 包迁移到新生成的 sdk 包。

已迁移文件

已删除

• debugger/bindgen/gen/ — 整个目录已删除

SDK 差异修复模式 (2026-04-16)

当 TestFixError 编译失败时，遵循以下修复流程：

核心原则：以绑定的SDK为准

名字不同就去检查C++头文件和SDK生成的Go文件，理解正确的名称。

常见差异类型与修复方法

1. 常量名差异

问题： 旧代码使用的常量名与SDK生成的不一致。

修复方法： 检查 bindgen/SDK/headers/ 对应头文件，找到正确的C枚举名，然后查看SDK生成的Go常量名。

2. 结构体字段名差异

问题： 结构体字段名与SDK生成的不一致。

修复方法： 查看 sdk/*.go 中对应结构体的字段定义。

3. 类型不存在

问题： 旧代码引用了SDK中不存在的类型。

修复方法：

1. 搜索 bindgen/SDK/headers/ 找到C头文件中的对应定义
2. 搜索 sdk/*.go 找到SDK生成的实际类型名
3. 如果确实不存在，考虑添加 prebuiltStruct 或使用匿名结构体

4. 字段不存在

问题： 旧代码访问了结构体中不存在的字段。

修复方法： 检查C头文件确认字段是否真的存在。如果C头文件也没有该字段，则删除引用。

5. bool vs uint8 类型不匹配

问题： BOOLEAN 现在映射为 bool 而非 uint8。

修复方法：

• 0 → false, 1 → true
• == 0 → !, != 0 → 直接bool
• 移除 func() uint8 { if x { return 1 }; return 0 }() 闭包
• uint8(x) → 直接使用bool值

6. int8 vs byte 类型不匹配

问题： char 映射为 int8，但 []byte 与 []int8 不能直接 copy。

修复方法：

// []byte → []int8
for i := range srcBytes {
    dstInt8[i] = int8(srcBytes[i])
}

// []int8 → string
byteSlice := make([]byte, len(int8Slice))
for i, v := range int8Slice {
    byteSlice[i] = byte(v)
}
s := string(byteSlice)

7. 枚举类型转换

问题： 从 binary.LittleEndian.Uint32() 读取的 uint32 需要显式转换为枚举类型。

修复方法：

// 错误
packet.TypeOfAction = binary.LittleEndian.Uint32(payload[8:12])

// 正确
packet.TypeOfAction = sdk.DEBUGGER_MODIFY_EVENTS_TYPE(binary.LittleEndian.Uint32(payload[8:12]))

8. 枚举值从非0开始

问题： 生成器默认使用 iota（从0开始），但C枚举值可能从1或其他值开始。

修复方法： 手动修正生成的枚举常量值，匹配C头文件定义。

示例： DEBUGGER_REMOTE_PACKET_TYPE 在 Connection.h:160 中从1开始：

// 错误 (iota从0开始)
DebuggerRemotePacketTypeDebuggerToDebuggeeExecuteOnVmxRoot DEBUGGER_REMOTE_PACKET_TYPE = iota

// 正确 (显式赋值)
DebuggerRemotePacketTypeDebuggerToDebuggeeExecuteOnVmxRoot DEBUGGER_REMOTE_PACKET_TYPE = 1

修复流程

1. 运行 go test -run TestFixError -v -count=1
2. 读取错误信息，定位文件和行号
3. 检查 sdk/*.go 中对应类型的实际定义
4. 检查 bindgen/SDK/headers/*.h 中C头文件的原始定义
5. 按照上述模式修复
6. 重新运行测试验证

ShowErrorMessage 迁移

旧代码使用 ShowErrorMessage(errorCode)，SDK中没有此函数。替换为：

// 旧
ShowErrorMessage(errorCode)

// 新
fmt.Println(sdk.DebuggerErrorCode(errorCode).String())

Common Issues to Check

1. Struct Layout Mismatches

Compare struct definitions between Go and C++, ensuring:

• Field order matches exactly
• Padding is explicit in Go ([N]byte padding fields)
• Total struct size matches (unsafe.Sizeof in Go vs sizeof in C++)

2. IOCTL Code Consistency

Verify IOCTL codes match between Go and C++:

注意： 所有IOCTL常量现在由bindgen自动从 Ioctls.h 生成到 sdk/Ioctls.go，以SDK生成的值为准。

3. Package Naming Convention

C++ uses hyphens in directory names, Go uses underscores:

• kernel-level/ → kernel_level/ (package: kernel_level)
• user-level/ → user_level/ (package: user_level)
• script-engine/ → script_engine/ (package: scriptengine)
• driver-loader/ → driver_loader/ (package: driver_loader)

4. BSOD Analysis

For Bugcheck 0xD1 (DRIVER_IRQL_NOT_LESS_OR_EQUAL):

• Check if VMX state is corrupted during unload
• Verify IOCTL sequence is correct
• Ensure Token is properly passed for all operations
• Check if event loop is stopped before VMM unload

Completion Progress

See COMPLETION_PROGRESS.md for detailed function-by-function comparison.

Priority Areas Needing Work

1. export/ — 57→11 functions (19% complete)
2. commands/ — 279→111 functions (40% complete) ✅ 核心命令已实现IOCTL通信
3. app/ — 15→6 functions (40% complete)
4. common/ — 38→23 functions (61% complete)
5. script-engine/ — 41→32 functions (78% complete)

Historical Implementation Records

Core IOCTL Communication Layer (2026-04-12)

File: debugger/core/debugger.go

已完成以下核心 IOCTL 通信方法的实现：

回调函数消除规则 (2026-04-12)

装逼回调函数模式（必须禁止）：

❌ 错误模式 - 回调传递：

func CommandXxxRequest(callbackFunc func(...) ..., params ...) ... {
    return callbackFunc(params...)
}

✅ 正确模式 - 直接IOCTL通信：

func CommandXxxRequest(dc *core.DebuggerCore, params ...) ... {
    input := make([]byte, size)
    binary.LittleEndian.PutUint32(input[0:4], param)
    success, _, err := dc.SendIoctlRequest(core.DebuggerIoctlRequest{
        Code:    core.IoctlXxx,
        Input:   input,
        Output:  output,
        InSize:  size,
        OutSize: size,
    })
    if !success || err != nil {
        return fmt.Errorf("operation failed: %v", err)
    }
    return nil
}

关键原则：

1. 所有命令函数必须接受 *core.DebuggerCore 作为第一个参数
2. 绝对禁止使用回调函数作为参数
3. 每个命令必须直接调用IOCTL或核心方法
4. 错误处理必须返回具体的error信息，不能简单转发

断点命令修复规则 (2026-04-12)

断点修改结构体 (DEBUGGEE_BP_LIST_OR_MODIFY_PACKET)：

请求类型常量：

任务完成状态 (2026-04-16)

✅ 已完成

1. Bindgen SDK 生成器 — 基于 modernc.org/cc/v4 的C头文件→Go绑定自动生成器

   • 全局去重、N-ary树结构体解析、预制结构体、统一类型映射
   • 12个Go绑定文件从13个C头文件自动生成
   • 运行: go test -run TestGenerate -v -count=1 ./bindgen/

2. gen → sdk 迁移 — 所有10个文件从 bindgen/gen 迁移到 sdk 包

   • 100+ 代码引用从 gen. 替换为 sdk.
   • bindgen/gen/ 目录已删除
   • 所有类型差异已修复，TestFixError 通过

3. 核心模块重构 — core/debugger.go 使用SDK生成的结构体和枚举

   • IOCTL控制码从SDK调用
   • 所有通信发包逻辑已实现

4. 命令模块重构 — commands/ 下的所有文件使用SDK绑定

   • 消除了回调函数模式
   • 直接调用core方法

🔄 进行中

1. header 包绑定 — libhyperdbg/header 的C++语法过滤
   • isCppLine() 和 preprocessHeader() 已实现
   • 因C++语法复杂性暂未启用（配置已注释）

📋 待完成

1. export/ — 57→11 functions (19% complete)
2. app/ — 15→6 functions (40% complete)
3. common/ — 38→23 functions (61% complete)
4. script-engine/ — 41→32 functions (78% complete)
5. 枚举值修正 — 生成器对非0起始枚举默认使用iota，需手动修正或改进生成器

Verification Steps

1. Compare struct sizes:

   fmt.Printf("Struct size: %d\n", unsafe.Sizeof(SomeStruct{}))
   

2. Serialize and compare bytes:

   • Serialize Go struct to bytes
   • Compare with C++ struct serialized bytes
   • Check for padding/alignment issues

3. Trace IOCTL calls:

   • Log all IOCTL calls in Go
   • Compare with expected C++ behavior
   • Verify parameters match

4. Check kernel logs:

   • Use WinDbg to trace kernel execution
   • Compare with expected code path

5. Run bindgen and verify:

   # 重新生成SDK绑定
   go test -run TestGenerate -v -count=1 ./bindgen/
   # 验证编译通过
   go test -run TestFixError -v -count=1
   

Type Mapping Rules (2026-04-13)

BOOLEAN Type Mapping

C++ BOOLEAN (Windows type) → Go bool

重要规则：

1. C++ 的 BOOLEAN 是 1 字节的 unsigned char 类型，与 Go 的 bool 大小相同（都是 1 字节）
2. 在结构体中使用 bool 时必须添加显式填充：如果字段后需要对齐到 4 字节边界，需要添加 [3]byte 填充
3. 不要使用 uint8 替代 bool：Go 的 bool 在内存布局上与 C++ 的 BOOLEAN 完全兼容

示例：

// C++ 结构体:
// typedef struct _DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS {
//     BOOLEAN IsStartingNewProcess;      // offset 0, size 1
//     // 3 bytes padding
//     UINT32 ProcessId;                  // offset 4, size 4
// } DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS;

// Go 实现:
type DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS struct {
    IsStartingNewProcess bool    // 1 byte
    _                    [3]byte // 显式填充
    ProcessId            uint32  // 4 bytes
}

Struct Padding Guidelines

1. 始终使用显式填充字段 ([N]byte) 而不是依赖 Go 编译器自动填充
2. 填充大小计算：
   • 如果下一个字段是 uint32/int32，当前字段是 1 字节类型（如 bool），则需要填充 3 字节
   • 如果下一个字段是 uint64/int64，当前字段是 4 字节类型，则需要填充 4 字节
3. 保持字段顺序与 C++ 一致：不要重新排列字段以优化填充

Source Comments Standard

所有 SDK 包中的结构体和枚举都必须包含 Source 注释：

// Source: HyperDbg/libhyperdbg/code/debugger/RequestStructures.h -> _STRUCT_NAME
type STRUCT_NAME struct {
    ...
}

// Source: HyperDbg/libhyperdbg/code/debugger/Events.h:160 -> _ENUM_NAME
type ENUM_NAME uint32

const (
    EnumValue1 ENUM_NAME = 1
    EnumValue2 ENUM_NAME = 2
)

注释格式要求：

• 格式：// Source: <C++头文件路径> -> <C++结构体/枚举名> 或 // Source: <C++头文件路径>:行号 -> <C++结构体/枚举名>
• 路径相对于 HyperDbg 源码根目录
• 使用下划线前缀的 C++ 名称（如 _DEBUGGER_ATTACH_DETACH_USER_MODE_PROCESS）
• 预制结构体额外包含 originalSource 字段追踪实际来源

char → int8 映射

C++ char → Go int8（非 byte/uint8）

C 的 char 是有符号的，映射为 Go 的 int8。当需要与 []byte 交互时，需要显式转换：

// int8数组 → string
byteSlice := make([]byte, len(int8Arr))
for i, v := range int8Arr {
    byteSlice[i] = byte(v)
}
s := string(byteSlice)

// []byte → int8数组
for i := range srcBytes {
    dstInt8[i] = int8(srcBytes[i])
}

Source: HyperDbg/gui — distributed by TomeVault.