isia21/hook-mod-base
GitHub: isia21/hook-mod-base
一个模块化的 C++ DLL 模板，为游戏逆向工程和 modding 提供面向对象的 hook 管理架构，并集成 IDA Pro 符号解析与可视化内存映射工具链。
Stars: 0 | Forks: 0
# HookModBase — 模块化 C++ DLL Modding SDK 模板
[English](#english) | [Русский](#русский) | [视觉展示](#visual-showcase)
## English
**HookModBase** 是一个轻量级、结构化的 C++ DLL 模板，专为逆向工程、调试和游戏 modding 设计。
与原始的 hooking 库不同，本项目专注于**软件架构**——提供一个干净、面向对象的框架，将多个 hook 子系统组织成模块化的类，而不是杂乱的单个文件。
### 逆向工程工作流
此 SDK 搭建了**静态分析** (IDA Pro) 和**动态执行** (注入的 DLL) 之间的桥梁：
1. **注入 DLL：** DLL 初始化并在游戏文件夹中生成诊断文件。
2. **检查内存：** 打开 `hook_memory_map.html` 以准确查看您已接管了哪些代码区域。
3. **同步 IDA：** 在您的 IDA 数据库中运行 `ida_sync_map.py`。您的工作区将立即反映出 DLL 的更改（橙色 = Hooks，绿色 = NOP Caves，青色 = VTables）。
4. **分析孤儿：** 使用生成的 IDC 脚本查找“孤儿”函数（在您的 hooks 之后不再被调用的代码块），帮助您找到更多 code caves 的空间。
### 主要特性
* **模块化架构 (`IHookModule` & `HookManager`)：** 通过将 mod 功能（例如 `InputHook`, `GraphicsHook`）分离为具有标准化生命周期的独立类，鼓励编写整洁的代码。
* **安全的内存回滚 (`HookTracker`)：** 自动跟踪被覆盖的字节，并在 DLL 卸载期间严格按照后进先出 (LIFO) 顺序恢复原始代码，从而最大限度地减少进程崩溃。
* **IDA Pro 符号解析器 (`SymbolResolver`)：** 从 IDA Pro 导入标准的 TAB 分隔导出列表，以便在调试日志中自动将原始虚拟地址解析为命名函数。
* **可视化树形诊断：** 使用树状图形 (`|-`, `\_`) 将详细的 hooking 结构（包含 NOP 区域和父级调用点）记录到 `OutputDebugString`。
* **干净的内存包装器 (`MemoryEx`)：** 使用 `uintptr_t` 实现类型安全的内存操作，以确保在 x86 和 x64 平台之间的兼容性。
* **可视化内存映射 (HTML/BMP/JSON)：** 自动生成进程内存的交互式、高分辨率映射。直接在浏览器中通过缩放和工具提示可视化原始代码、hook 条目、NOP caves 和 VTable 覆盖。
* **IDA Pro 实时同步 (Python/IDC)：** 动态生成同步脚本。在 IDA Pro 中运行它们可立即根据 DLL 的实时状态为 hook 的函数着色、应用 NOP patch 并添加注释。
* **安全的海量日志支持：** 完全重写了使用堆分配的 `std::string` 的日志引擎。安全地处理来自 `SymbolResolver` 的大量转储（xrefs, 树），而不会导致游戏线程 Stack Overflows。
### 技术限制与注意事项
为了保持代码库的轻量化和高度可读性，做出了以下设计权衡：
1. **无 Length Disassembler Engine (LDE)：** SDK 不会自动即时计算 inline hooks 的指令长度。开发者有责任指定正确的指令边界或使用 NOP 填充剩余空间。
2. **无运行时 Trampoline 生成器：** 本项目专为完整的函数劫持（替换）或直接调用点 patching 而设计。要内联调用原始函数，您必须手动处理汇编 stub，或者在 `MemoryEx` 实现中集成像 *MinHook* 或 *Microsoft Detours* 这样的低级引擎。
### 仓库结构
```
├── HookModBase.sln # MSBuild Solution
├── HookModBase/ # DLL Project (Dynamic Library)
│ ├── include/ # SDK Header files
│ ├── src/ # Core SDK Implementation
│ ├── example/ # TestAppHook module implementation
│ └── dllmain.cpp # DLL entry point and thread setup
└── TargetApp/ # Test EXE Project (Console Mock Engine)
└── main.cpp # Hook target loop
```
### 快速开始
1. 在 Visual Studio 中打开 `HookModBase.sln`（配置为 **Release | x86**）。
2. 构建解决方案。
3. 导航至包含以下内容的输出目录：
- TargetApp.exe
- HookModBase.dll
- ida_exports.txt (输入符号)
- hook_memory_map.html (交互式视图)
- ida_sync_map.py / .idc (IDA 同步脚本)
4. 运行 `TargetApp.exe`。您将看到 2 帧的原始输出，此后 DLL 中的后台线程将成功 hook 执行流。
#### 创建自定义模块：
```
#include "IHookModule.h"
#include "MemoryEx.h"
#include "Utils.h"
class MyModModule : public IHookModule
{
public:
const char* GetName() const override { return "MyModModule"; }
bool Init() override {
uintptr_t base = reinterpret_cast(GetModuleHandle(nullptr));
// Setup an inline Jmp hook
m_tracker.InstallHook(
base + 0x1140,
HookType::Jmp,
reinterpret_cast(MyDetour),
"TargetClass::TargetMethod"
);
return true;
}
void Shutdown() override {
m_tracker.RestoreAll(); // Safely rolls back changes
}
};
```
## Русский
**HookModBase** — это легковесный, структурированный шаблон C++ DLL, разработанный для задач реверс-инжиниринга, отладки и создания игровых модификаций.
В отличие от низкоуровневых библиотек перехвата, этот проект сфокусирован на **архитектуре программного кода**. Он предоставляет объектно-ориентированную структуру для разделения различных подсистем хуков на изолированные модули, предотвращая накопление хаотичного кода в одной точке входа.
### 逆向工程过程
Этот SDK создает «мостик» между **Статическим анализом** (IDA Pro) и **Динамическим выполнением** (Инжектированная DLL):
1. **Инжект DLL:** При запуске DLL инициализирует модули и создает диагностические файлы в папке игры.
2. **Анализ карты:** Откройте `hook_memory_map.html`, чтобы увидеть, какие именно области кода вы взяли под контроль.
3. **Синхронизация IDA:** Запустите `ida_sync_map.py` в вашей базе IDA. Рабочее пространство мгновенно окрасится: Оранжевый = Хуки, Зеленый = NOP-пещеры, Циановый = VTable.
4. **Поиск «сирот»:** Используйте IDC-скрипт для поиска функций-сирот (блоков кода, на которые больше нет ссылок после ваших хуков), чтобы найти место под новые Code Caves.
### 核心功能
* **Модульная архитектура (`IHookModule` и `HookManager`):** Позволяет разносить функционал мода (например, работу с вводом `InputHook`, графикой `GraphicsHook`) по независимым классам со стандартизированным жизненным циклом.
* **Безопасный откат памяти (`HookTracker`):** Автоматически отслеживает измененные байты и восстанавливает оригинальный код в строгом порядке LIFO (Last-In-First-Out) при выгрузке DLL, предотвращая падение целевого процесса.
* **Разрешение символов IDA Pro (`SymbolResolver`):** Импортирует текстовые файлы экспорта функций из IDA Pro (разделенные табуляцией) для автоматического преобразования адресов памяти в осмысленные имена функций в логах отладки.
* **Наглядная древовидная диагностика:** Выводит подробную структуру установленных хуков и затертых NOP-регионов в `OutputDebugString` в виде наглядного дерева с использованием символов псевдографики (`|-`, `\_`).
* **Безопасная работа с памятью (`MemoryEx`):** Использует строго типизированные указатели `uintptr_t`, исключая срез адресов и обеспечивая переносимость кода.
* **Визуальное картирование памяти (HTML/BMP/JSON):** Автоматически генерирует интерактивную карту памяти процесса. Позволяет видеть оригинальный код, точки входа хуков, NOP-пещеры и подмены VTable прямо в браузере с поддержкой зума и всплывающих подсказок.
* **Синхронизация с IDA Pro (Python/IDC):** Генерирует готовые скрипты «на лету». Запустите их в IDA, чтобы мгновенно раскрасить базу, применить NOP-патчи и добавить комментарии, соответствующие реальному состоянию вашей DLL.
* **Поддержка гигантских логов:** Полностью переработанный движок логирования с выделением памяти в куче (`std::string`). Безопасно обрабатывает огромные дампы от `SymbolResolver` (xrefs, деревья вызовов), исключая риск переполнения стека игровых потоков.
### 技术限制
Для сохранения простоты чтения и легковесности кода были приняты следующие архитектурные компромиссы:
1. **Отсутствие дизассемблера длин (LDE):** Шаблон не вычисляет размер инструкций на лету. Разработчик должен самостоятельно контролировать границы изменяемых инструкций или забивать оставшееся место NOP-командами.
2. **Отсутствие генератора трамплинов во время выполнения:** Проект ориентирован на полное замещение логики (hijacking) или патчинг адресов вызова (call-site). Для вызова оригинальной функции изнутри хука разработчику потребуется реализовать ассемблерный мост вручную или интегрировать решение класса *MinHook* / *Microsoft Detours* на уровне `MemoryEx`.
### 仓库结构
```
├── HookModBase.sln # Файл решения MSBuild (Visual Studio)
├── HookModBase/ # Проект DLL (Динамическая библиотека)
│ ├── include/ # Заголовочные файлы SDK
│ ├── src/ # Исходный код ядра SDK
│ ├── example/ # Реализация тестового модуля TestAppHook
│ └── dllmain.cpp # Точка входа DLL и запуск рабочего потока
└── TargetApp/ # Тестовый проект EXE (Консольное приложение)
└── main.cpp # Имитация игрового цикла
```
### 快速开始
1. Откройте файл `HookModBase.sln` в Visual Studio (рекомендуется конфигурация **Release | x86**).
2. Соберите решение (Build Solution).
3. Перейдите в каталог сборки, содержащий:
- TargetApp.exe
- HookModBase.dll
- ida_exports.txt (Входящие символы)
- hook_memory_map.html (Интерактивная карта)
- ida_sync_map.py / .idc (Скрипты синхронизации для IDA)
4. Запустите `TargetApp.exe`. Первые два кадра выполнится оригинальный код, после чего фоновый поток DLL применит хуки и перехватит выполнение.
#### 自定义 module 创建示例：
```
#include "IHookModule.h"
#include "MemoryEx.h"
#include "Utils.h"
class MyModModule : public IHookModule
{
public:
const char* GetName() const override { return "MyModModule"; }
bool Init() override {
uintptr_t base = reinterpret_cast(GetModuleHandle(nullptr));
// Установка стандартного inline-перехода (Jmp Hook)
m_tracker.InstallHook(
base + 0x1140,
HookType::Jmp,
reinterpret_cast(MyDetour),
"TargetClass::TargetMethod"
);
return true;
}
void Shutdown() override {
m_tracker.RestoreAll(); // Безопасно восстанавливает оригинальные байты
}
};
```
## visual-showcase
## 📊 视觉展示：大规模检测工具 / Визуальный обзор: Инструментарий экстремального масштаба
标签：API Hook, C++, Homebrew安装, IDA Pro, 云资产清单, 内存调试, 动态链接库, 多模态安全, 数据擦除, 游戏模组, 逆向工具, 逆向工程