Il2CppDumper技术指南：解析Unity二进制文件的逆向工程工具

基础认知

工具定位

Il2CppDumper是一款针对Unity应用的逆向工程工具，用于解析IL2CPP编译后的二进制文件与元数据，提取类型定义、方法信息和数据结构。支持Windows、Linux、macOS多平台运行，需.NET Framework 4.7.2或更高版本环境。

核心能力

• 解析多种可执行文件格式（PE/ELF/Mach-O/WASM）
• 提取元数据(Metadata)中的类型定义与继承关系
• 生成伪DLL文件与结构体定义
• 支持主流逆向工具集成（IDA Pro/Ghidra/Binary Ninja）

**元数据(Metadata)**：IL2CPP编译过程中生成的包含类型、方法、字段等信息的二进制数据文件，通常命名为global-metadata.dat

快速上手指南

环境准备

1. 安装.NET SDK 5.0或更高版本
2. 克隆代码仓库：git clone https://gitcode.com/gh_mirrors/il/Il2CppDumper
3. 编译项目：cd Il2CppDumper && dotnet build Il2CppDumper.sln

基本使用流程

1. 准备目标文件：

   • 可执行文件（如libil2cpp.so、GameAssembly.dll）
   • 元数据文件（global-metadata.dat）

2. 执行基础解析：dotnet Il2CppDumper.dll <可执行文件路径> <元数据文件路径> <输出目录>

版本兼容性矩阵

功能	Windows	Linux	macOS	最低Unity版本
PE解析	✅	❌	❌	5.3
ELF解析	❌	✅	❌	5.3
Mach-O解析	❌	❌	✅	5.5
WASM解析	✅	✅	✅	2018.1
伪DLL生成	✅	✅	✅	5.3

场景驱动

场景一：Android游戏二进制分析

问题描述：需要分析Android平台Unity游戏的libil2cpp.so文件，提取类结构与方法信息。

操作步骤：

1. 准备文件：将libil2cpp.so和global-metadata.dat复制到工作目录
2. 执行解析命令：dotnet Il2CppDumper.dll libil2cpp.so global-metadata.dat output
3. 查看输出结果：检查output目录下的dump.cs和DummyDll文件夹

效果对比：

• 原始二进制：无法直接查看类结构与方法签名
• 解析后输出：获得可读的C#类定义与方法声明，可用于静态分析

场景二：IDA Pro集成分析

问题描述：需要在IDA Pro中加载IL2CPP结构信息，辅助逆向分析过程。

操作步骤：

1. 生成IDA脚本：dotnet Il2CppDumper.dll --gen-ida <可执行文件> <元数据文件> ida_script.py
2. 在IDA Pro中加载脚本：File > Script file... > 选择ida_script.py
3. 应用类型信息：等待脚本执行完成，IDA视图将显示解析后的类型名称

效果对比：

• 未集成前：函数名为sub_xxxx，无法识别类型信息
• 集成后：函数名与参数类型被还原，调用关系清晰可见

场景三：WebAssembly模块解析

问题描述：需要分析Unity WebGL构建输出的wasm模块中的IL2CPP结构。

操作步骤：

1. 提取文件：从构建输出中获取UnityLoader.js和.wasm文件
2. 执行专门解析：dotnet Il2CppDumper.dll --wasm <wasm文件> <元数据文件> wasm_output
3. 生成结构定义：cd wasm_output && dotnet run --project StructGenerator

效果对比：

• 原始wasm：字节码格式难以直接分析
• 解析后：获得C风格结构体定义与函数声明，可用于安全审计

场景四：版本差异比较

问题描述：需要比较同一游戏不同版本间的代码结构变化。

操作步骤：

1. 分别解析两个版本： dotnet Il2CppDumper.dll v1/libil2cpp.so v1/global-metadata.dat v1_output dotnet Il2CppDumper.dll v2/libil2cpp.so v2/global-metadata.dat v2_output
2. 使用diff工具比较输出：diff -r v1_output/dump.cs v2_output/dump.cs

效果对比：

• 直接比较二进制：难以发现逻辑变化
• 比较解析结果：可清晰识别类、方法的新增、删除与修改

深度配置

基础配置

通过编辑<安装目录>/config.json文件进行基础配置：

参数	默认值	范围	说明
DumpMethod	true	true/false	控制是否输出方法信息
GenerateDummyDll	true	true/false	是否生成伪DLL文件
MakeFunction	false	true/false	是否生成函数定义
OutputFormat	"cs"	"cs"/"h"/"json"	输出文件格式
SearchMethod	"auto"	"auto"/"symbol"/"manual"	方法搜索模式

配置示例：

{
  "DumpMethod": true,
  "GenerateDummyDll": true,
  "OutputFormat": "cs",
  "SearchMethod": "auto"
}

高级调优

修改<安装目录>/Utils/SearchSection.cs文件调整搜索算法：

1. 调整搜索窗口大小：修改const int WindowSize = 0x1000;值
2. 优化内存使用：设置MaxSearchDepth参数控制递归深度
3. 并行处理配置：修改ParallelOptions.MaxDegreeOfParallelism控制并发数

风险提示：调整搜索参数可能导致解析速度变慢或内存占用增加，建议逐步调整并测试效果。

扩展开发

通过继承基础类扩展新功能：

1. 添加新文件格式支持：

   • 继承<安装目录>/ExecutableFormats/ElfBase.cs
   • 实现抽象方法ParseHeader()和FindTextSection()

2. 开发自定义输出模块：

   • 创建新类继承<安装目录>/Outputs/StructGenerator.cs
   • 重写Generate()方法实现自定义格式输出

3. 集成新逆向工具：

   • 参考<安装目录>/ida.py编写新工具脚本
   • 实现export_to_tool()接口处理数据转换

常见故障排除

1. 元数据解析失败

症状：提示"Metadata file is invalid" 解决方案：

• 检查文件完整性：确保global-metadata.dat未损坏
• 验证版本匹配：确认元数据与可执行文件来自同一构建
• 更新工具版本：使用最新版Il2CppDumper尝试解析

2. 解析速度过慢

症状：处理大型文件时耗时超过30分钟 解决方案：

• 增加内存分配：export DOTNET_GCHeapHardLimit=4GB
• 限制输出范围：使用--filter参数指定需要解析的命名空间
• 分阶段处理：先使用--quick模式生成基础结构，再针对性解析

3. Dummy DLL生成失败

症状：输出目录中缺少DummyDll文件夹 解决方案：

• 检查依赖：确保安装.NET SDK而非仅运行时
• 清理缓存：删除obj和bin目录后重新编译
• 手动生成：运行dotnet run --project DummyAssemblyGenerator

4. IDA脚本加载错误

症状：IDA中执行脚本提示"import error" 解决方案：

• 安装Python依赖：pip install six
• 检查IDA Python版本：确保使用Python 3.x环境
• 更新脚本：使用--gen-ida-py3参数生成Python 3兼容脚本

5. WASM解析不完整

症状：输出文件缺少部分类型定义 解决方案：

• 启用详细日志：添加--log-level debug参数查看解析过程
• 手动指定内存段：使用--wasm-memory-base 0x10000设置基地址
• 提供Unity版本：使用--unity-version 2020.3指定精确版本

技术限制与替代方案

已知限制

1. IL代码还原：无法完全还原原始C#代码逻辑，仅能提供方法签名与结构信息
2. 混淆处理：对重度混淆的元数据识别率下降，可能导致部分类型无法解析
3. 泛型支持：复杂泛型类型的解析可能存在错误

替代方案建议

1. 代码逻辑还原：配合dnSpy等.NET反编译工具分析生成的Dummy DLL
2. 混淆处理：先使用de4dot等工具进行预处理，再使用Il2CppDumper解析
3. 复杂类型分析：结合Ghidra的IL2CPP分析插件进行交叉验证

性能优化建议

• 64位系统：始终使用64位版本工具处理大型文件
• 内存配置：确保系统内存不少于8GB，推荐16GB以上
• 磁盘空间：预留至少10GB临时空间用于处理大型项目

参考文献

1. Unity Technologies. "IL2CPP Internals" [2021]
2. reverseengineering.stackexchange.com. "IL2CPP Reverse Engineering Guide" [2022]
3. Il2CppDumper GitHub Wiki. "Advanced Configuration Options" [2023]
4. "Practical Reverse Engineering" by Bruce Dang et al. [Wiley, 2014]
5. "Reverse Engineering for Beginners" by Dennis Yurichev [2017]