It is with great regret that I have to announce that development work on Il2CppInspector has been halted for the foreseeable future.
The reason for this is that due to health and changes in my personal life, I simply do not have time to commit to working on the project anymore. This is very frustrating for me but there is little I can really do about it.
Please feel free to fork the project and make improvements! You can also continue to post issues as I would like to have a compendium of bugs and problems saved in case that I or someone else does have the opportunity to get back to working on this. Please note though, that I won't be responding to issues or PRs going forward for the foreseeable future.
If you need IL2CPP tooling, I recommend my friend and colleague's excellent project Cpp2IL which is a work-in-progress tool to convert IL2CPP binaries directly back into IL code which can be easily viewed in dnSpy etc. This is a mammoth task so please do go and support his work on this amazing project!
Happy hacking,
Katy.
Il2CppInspector 2021.1
Il2CppInspector helps you to reverse engineer IL2CPP applications, providing the most complete analysis currently available.
Main features
Output IL2CPP type definitions, metadata and method pointers as C# stub code
Create .NET assembly shim DLLs containing the IL2CPP application structure and metadata for use in decompilers such as ILSpy, dnSpy, Unity asset loading with AssetStudio or managed proxy generation with Il2CppAssemblyUnhollower
Create C++ scaffolding for all types, methods, function pointers and API functions in an IL2CPP application for use in x64dbg, Cydia Substrate etc.
Three major APIs for use in your own custom static analysis projects for querying low level binary metadata, the .NET type model and the whole C++ application. These are also available as a NuGet Package.
Plugin SDK allows you to create custom plugins to extend Il2CppInspector's capabilities
Defeats certain types of obfuscation
Most types of packed PE files (Windows DLLs)
ROT encryption of API export names
Beebyte symbol obfuscation via automated differential analysis (requires Beebyte Deobfuscator plugin and an earlier unobfuscated IL2CPP or Mono version of the title)
Enable loading of Honkai Impact (3 parts) - covers finding functions in an image, data obfuscation of global-metadata.dat, IDA decompiler techniques, how to write a plugin
Also supports single and split APK (Android), AAB (Android App Bundle), XAPK, Zip and decrypted IPA (iOS) application package files as input
Supports ELF files created from memory dumps
Supports Linux process maps + corresponding .bin files - such as those produced by GameGuardian - without the need to manually extract the IL2CPP binary
32-bit and 64-bit support for all file formats
Supports ARMv7, Thumb-2, ARMv8 (A64), x86 and x64 architectures regardless of file format
Supports applications created with Unity 5.3.0 onwards (full IL2CPP version table below)
Nice to have:
Support for assemblies, classes, methods, constructors, fields, properties, enumerations, events, interfaces, structs, pointers, references, attributes, nested types, generic types, generic methods, generic constraints, default field values and default method parameter values
Partition C# code output by namespace, assembly, class, full tree or single file; sort by index or type name; output flat or nested folder hierarchy. Each file includes the necessary using directives. Scope and type name conflicts are resolved automatically to produce code that compiles.
API function export processing for PE, ELF, Mach-O and SELF (PRX) binaries
Symbol table processing and name demangling for ELF and Mach-O binaries
Relocation processing for ELF binaries
Automatically defeats certain basic obfuscation methods
Test chassis for automated integration testing of IL2CPP binaries
Class library targets .NET Core 3.1. Built with Visual Studio 2019.
NOTE: Il2CppInspector is not a decompiler. It can provide you with the structure of an application and function addresses for every method so that you can easily jump straight to methods of interest in your disassembler. It does not attempt to recover the entire source code of the application.
Build instructions
git clone --recursive https://github.com/djkaty/Il2CppInspector
cd Il2CppInspector
Windows
Build the CLI and Windows GUI versions:
dotnet publish -c Release
Get all current plugins (optional):
powershell -f get-plugins.ps1
Mac OS X
Build the CLI version:
cd Il2CppInspector.CLI
dotnet publish -r osx-x64 -c Release
Get all current plugins (optional):
../get-plugins.sh
Linux
Build the CLI version:
cd Il2CppInspector.CLI
dotnet publish -r linux-x64 -c Release
The output binary for command-line usage is placed in Il2CppInspector/Il2CppInspector.CLI/bin/Release/netcoreapp3.0/[win|osx|linux]-x64/publish/Il2CppInspector.exe.
The output binary for Windows GUI is placed in Il2CppInspector/Il2CppInspector.GUI/bin/Release/netcoreapp3.1/[win|osx|linux]-x64/publish/Il2CppInspector.exe.
The plugins folder should be placed in the same folder as Il2CppInspector.exe.
Command-line Usage
Run Il2CppInspector.exe at the command prompt.
File format and architecture are automatically detected.
All outputs are generated by default. To generate only specific outputs, use the --select-outputs switch in combination with the output selection switches.
-i, --bin (Default: libil2cpp.so) IL2CPP binary, APK, AAB, XAPK, IPA, Zip or Linux process map text input file(s) (single file or comma-separated list for split APKs)
-m, --metadata (Default: global-metadata.dat) IL2CPP metadata file input (ignored for APK/AAB/XAPK/IPA/Zip)
--image-base For ELF memory dumps, the image base address in hex (ignored for standard ELF files and other file formats)
--select-outputs Only generate outputs specified on the command line (use --cs-out, --py-out, --cpp-out, --json-out, --dll-out to select outputs). If not specified, all outputs are generated
-c, --cs-out (Default: types.cs) C# output file (when using single-file layout) or path (when using per namespace, assembly or class layout)
-p, --py-out (Default: il2cpp.py) Python script output file
-h, --cpp-out (Default: cpp) C++ scaffolding / DLL injection project output path
-o, --json-out (Default: metadata.json) JSON metadata output file
-d, --dll-out (Default: dll) .NET assembly shim DLLs output path
--metadata-out IL2CPP metadata file output (for extracted or decrypted metadata; ignored otherwise)
--binary-out IL2CPP binary file output (for extracted or decrypted binaries; ignored otherwise; suffixes will be appended for multiple files)
-e, --exclude-namespaces (Default: System Mono Microsoft.Reflection Microsoft.Win32 Internal.Runtime Unity UnityEditor UnityEngine UnityEngineInternal AOT JetBrains.Annotations) Comma-separated list of namespaces to suppress in C# output, or 'none' to include all namespaces
-l, --layout (Default: single) Partitioning of C# output ('single' = single file, 'namespace' = one file per namespace in folders, 'assembly' = one file per assembly, 'class' = one file per class in namespace folders, 'tree' = one file per class in assembly and
namespace folders)
-s, --sort (Default: index) Sort order of type definitions in C# output ('index' = by type definition index, 'name' = by type name). No effect when using file-per-class or tree layout
-f, --flatten Flatten the namespace hierarchy into a single folder rather than using per-namespace subfolders. Only used when layout is per-namespace or per-class. Ignored for tree layout
-n, --suppress-metadata Diff tidying: suppress method pointers, field offsets and type indices from C# output. Useful for comparing two versions of a binary for changes with a diff tool
--suppress-dll-metadata Diff tidying: suppress method pointers, field offsets and type indices attributes from DLL output. Useful for comparing two versions of a binary for changes
-k, --must-compile Compilation tidying: try really hard to make code that compiles. Suppress generation of code for items with CompilerGenerated attribute. Comment out attributes without parameterless constructors or all-optional constructor arguments. Don't emit
add/remove/raise on events. Specify AttributeTargets.All on classes with AttributeUsage attribute. Force auto-properties to have get accessors. Force regular properties to have bodies. Suppress global::Locale classes. Generate dummy parameterless
base constructors and ref return fields.
--separate-attributes Place assembly-level attributes in their own AssemblyInfo.cs files. Only used when layout is per-assembly or tree
-j, --project Create a Visual Studio solution and projects. Implies --layout tree, --must-compile and --separate-attributes
--cpp-compiler (Default: BinaryFormat) Compiler to target for C++ output (MSVC or GCC); selects based on binary executable type by default
-t, --script-target (Default: IDA) Application to target for Python script output (IDA or Ghidra) - case-sensitive
--unity-path (Default: C:\Program Files\Unity\Hub\Editor\*) Path to Unity editor (when using --project). Wildcards select last matching folder in alphanumeric order
--unity-assemblies (Default: C:\Program Files\Unity\Hub\Editor\*\Editor\Data\Resources\PackageManager\ProjectTemplates\libcache\com.unity.template.3d-*\ScriptAssemblies) Path to Unity script assemblies (when using --project). Wildcards select last matching folder in
alphanumeric order
--unity-version Version of Unity used to create the input files, if known. Used to enhance Python, C++ and JSON output. If not specified, a close match will be inferred automatically.
--unity-version-from-asset A Unity asset file used to determine the exact Unity version. Overrides --unity-version.
--plugins Specify options for plugins. Enclose each plugin's configuration in quotes as follows: --plugins "pluginone --option1 value1 --option2 value2" "plugintwo --option...". Use --plugins <name> to get help on a specific plugin
--help Display this help screen.
--version Display version information.
File format considerations
Apple Universal Binaries and APKs/XAPKs with binaries for multiple architectures: when using the CLI, multiple output files will be generated, with each filename besides the first suffixed by the index of the image in the binary. Unsupported images will be skipped.
IPA packages: the executable must be decrypted first. Encrypted executable binaries are not supported.
Split APK packages: when using the CLI, specify a list of APK files with a comma between each filename.
ELF binaries created from memory dumps: specify the image base (in hex) using --image-base. If the supplied image base is incorrect, the application may crash.
GameGuardian dumps (and other Linux process map dumps): you can use a *-maps.txt file in place of an IL2CPP binary. Il2CppInspector will scan the folder containing the maps file for matching .bin files and reassemble and rebase libil2cpp.so automatically. You therefore don't need to create the file manually or provide an image base address when using this kind of dump. For this to work, neither the text file nor any of the binary files must be renamed, and all must be in the same folder.
Packed PE files (DLLs): WARNING: Loading a packed PE file will cause the DLL's entry point and initialization functions to execute. Do not load malicious DLLs and never run Il2CppInspector as an administrator when handling packed PE files. USE AT YOUR OWN RISK.
Creating C# prototypes
Il2CppInspector can create C# code stub files with pointer metadata to allow you to explore the IL2CPP binary in an easy-to-read format.
Specify the -c switch to choose the C# output file or path.
To exclude types from certain namespaces from being generated in the C# source file output, provide a comma-separated list of case-sensitive namespaces in --exclude-namespaces. The following namespaces will be excluded if no argument is specified:
Providing an argument to --exclude-namespaces will override the default list. To output all namespaces, use --exclude-namespaces=none. This only applies to C# prototypes output.
You can specify the output layout with the --layout switch:
single - all types in a single file
namespace - one namespace per file (each file will be given the namespace name)
assembly - one assembly per file (each file will be given the assembly name)
class - one class per file
tree - one class per file in a tree-like folder structure with top-level assembly folders and second-level namespace folders
You can specify the intra-file type ordering with the --sort switch:
index - sort by type definition index as found in the IL2CPP metadata
name - sort alphabetically by type name
This switch has no effect when using class or tree layout.
The --flatten switch allows you to flatten a hierarchy of nested namespaces when layout is class or namespace, ie. a series of sub-folders System/IO/Compression will instead be a single top-level sub-folder System.IO.Compression.
The --suppress-metadata switch allows you to suppress the output of comments including method pointers, field offsets and type indices. This is useful when you want to diff the changes between two versions of an application to see only which types have changed.
The --seperate-attributes switch directs Il2CppInspector to put assembly-level attributes in their own AssemblyInfo.cs files rather than at the top of the first file generated for each assembly, when layout is assembly or tree.
Adding metadata to your IDA workflow
Simply run Il2CppInspector with the -p switch to choose the IDA script output file. Load your binary file into IDA, press Alt+F7 and select the generated script. Observe the Output Window while IDA analyzes the file - this may take a long time.
Three files are generated by Il2CppInspector for IDAPython: the Python script itself, a JSON metadata file and a C++ type header file (this is cpp/appdata/il2cpp-types.h by default if you used the CLI, or il2cpp.h if you used the GUI). These files must be present for the script to run successfully.
If you know which version of Unity the binary was compiled with, you can improve the output by specifying this with --unity-version, for example --unity-version 2019.3.1f1. You can also supply any asset file from the application to detect the Unity version with --unity-version-from-asset. Otherwise Il2CppInspector will make an educated guess based on the contents of the binary.
Il2CppInspector generates the following data for IDA projects:
Type declarations for all IL2CPP internal types
Type declarations for every type in the IL2CPP application including generic instances
Addresses for every known type
Names for all regular .NET methods
Names for all constructed generic methods
Names and typed signatures for all IL2CPP custom attributes generator functions
Names, .NET argument type lists and typed signatures for all IL2CPP runtime invoker functions for both regular and constructed generic methods (per-signature Method.Invoke endpoints)
Function boundaries for all of the above
Comments at each function entry point with .NET method signatures for all of the above
Names and type declarations for all of the following IL metadata references: Type, TypeInfo, MethodDef, FieldInfo, StringLiteral, MethodRef (this includes all generic class and method instantiation metadata)
Comments for all IL string literal metadata pointers containing the value of the string
Names and types for some IL2CPP-specific data structures and functions
Names and typed signatures for all IL2CPP API functions that could be identified
Example IDA C++ decompilation after applying Il2CppInspector (initialization code omitted for brevity):
Adding metadata to your Ghidra workflow
Run Il2CppInspector with the -p switch to choose the Ghidra script output file, and -t Ghidra (case-sensitive) to specify Ghidra as the script type you wish to produce.
Three files are generated by Il2CppInspector for Ghidra: the Python script itself, a JSON metadata file and a C++ type header file. These files must be present for the script to run successfully.
If you know which version of Unity the binary was compiled with, you can improve the output by specifying this with --unity-version, for example --unity-version 2019.3.1f1. You can also supply any asset file from the application to detect the Unity version with --unity-version-from-asset. Otherwise Il2CppInspector will make an educated guess based on the contents of the binary.
NOTE: For best results, choose No when Ghidra asks if you would like to perform auto-analysis when the binary is first loaded. If you receive a Conflicting data exists at address error when running the script below, re-load the binary into the project and choose No at the auto-analysis prompt.
NOTE: To significantly speed up analysis for ELF files, set the image base to zero (0x00000000) in the load options for the binary. For compatibility reasons, executing the Ghidra Python script on an ELF file will change the file's image base to zero for you if necessary, however if the current image base is non-zero this may take a very long time to complete. Other file formats will retain the same image base.
To import metadata into an existing Ghidra project:
From the Code Browser, choose File -> Parse C Source...
Create a new profile and add the generated C++ type header file. This is cpp/appdata/il2cpp-types.h by default if you used the CLI, or il2cpp.h if you used the GUI.
Ensure the Parse Options are set exactly as follows:
-D_GHIDRA_
Click Parse to Program and accept any warnings. This may take a long time to complete.
Open the Script Manager and add the output folder you chose in Il2CppInspector as a script folder.
If you have used scripts from Il2CppInspector for other binaries, ensure the Python files are named differently, or disable use of the previous script folder(s).
Click Refresh to make the script appear in Script Manager.
Right-click the script and choose Run. This may take a while to complete.
Il2CppInspector generates identical data for Ghidra projects as it does for IDA - see the above section for details.
Example Ghidra C++ decompilation after applying Il2CppInspector:
Creating C++ scaffolding or a DLL injection project
Il2CppInspector generates a series of C++ source files which you can use in a variety of ways, for example:
with a tool like x64dbg to analyze the memory of the application at runtime
with a tool like Cydia Substrate (MSHookFunction) for accessing types, methods and IL2CPP API functions
to run custom code via DLL injection on Windows (see below)
Run Il2CppInspector with the -h switch to choose the C++ output folder.
If you know which version of Unity the binary was compiled with, you can improve the output by specifying this with --unity-version, for example --unity-version 2019.3.1f1. You can also supply any asset file from the application to detect the Unity version with --unity-version-from-asset. Otherwise Il2CppInspector will make an educated guess based on the contents of the binary.
You can target which C++ compiler you wish to use the output files with: specify --cpp-compiler MSVC for Visual Studio and --cpp-compiler GCC for gcc or clang.
Il2CppInspector performs automatic name conflict resolution to avoid the use of pre-defined symbols and keywords in C++, and to handle re-definition of same-named symbols in the application.
Some IL2CPP binary files contain only a partial set of API exports, or none at all. For these cases, Il2CppInspector will build scaffolding using only the available exports to ensure that the project compiles successfully.
The following files are generated:
appdata - this folder contains project-agnostic binary-specific declarations:
ilc2pp-types.h:
Type declarations for all internal IL2CPP types (a minimal version of the Unity headers)
Type declarations for every type used in the application including all arrays, enums, concrete generic type instances and inferred usages from metadata.
Boxed versions for types where applicable
VTables for every type
il2cpp-functions.h:
The function pointer signature and offset from the image base address to every C#-equivalent method
The offset from the image base address to every method information class (MethodInfo **)
il2cpp-types-ptr.h:
The offset from the image base address to every type information class (Il2CppClass **)
il2cpp-api-functions.h:
The function pointer signature to every IL2CPP API function (copied directly from Unity for the version used to compile the binary). Functions not found in the binary's export list will be elided
il2cpp-api-functions-ptr.h:
The offset from the image base address to every IL2CPP API function export (functions starting with il2cpp_)
il2cpp-metadata-version.h:
A #define for the IL2CPP version used by the target binary
The above files contain all the data needed for dynamic analysis in a debugger.
In addition, the following files are generated for DLL injection:
framework - project-agnostic binary-agnostic boilerplate code and scaffolding:
dllmain.cpp:
Provides a DLL injection stub which calls init_il2cpp() (see below) and starts Run() (see below) in a new thread
helpers.cpp and helpers.h:
Provides various helper functions. See the comments in helpers.h for details.
il2cpp-init.cpp, il2cpp-init.h and il2cpp-appdata.h:
Provides the void init_il2cpp() function which uses all of the above headers to generate usable function pointers and class pointers that are mapped to the correct places in the in-memory image at runtime
pch-il2cpp.cpp and pch-il2cpp.h:
Provides the necessary scaffolding to enable pre-compiled headers (PCH) for all of the headers in the appdata folder
user - project-specific binary-agnostic user code which you can modify as desired:
main.cpp and main.h:
Contains a stub Run() function which denotes the entry point for your custom injected code. The function executes in a new thread and therefore does not block DllMain.
This is the only folder whose files you should edit.
For Visual Studio users, the following files are also generated:
IL2CppDLL.vcxproj, Il2CppDLL.vcxproj.filters and Il2CppDLL.sln:
The project and solution files for a DLL injection project. The first time you load the solution into Visual Studio, you will be asked to re-target the platform SDK and C++ toolchain. Accept the default suggestions. WARNING: Compilation may fail if you don't do this.
The default main.cpp includes commented code to allow you to write to a log or open a new console using the functions from helpers.h. To specify a log file target in your source code, use extern const LPCWSTR LOG_FILE = L"my_log_file.txt".
Tip: When a new version of the target application is released, you can re-output the C++ scaffolding project in-place. The appdata and framework folders will be overwritten but the user folder and project/solution files will not be changed. This makes it easy to update your project when the target application has been updated!
Compatibility: It is recommended to use Visual Studio 2019 (MSVC++ Build Tools v142 or later). The scaffolding projects have been tested with Visual Studio 2019 and Visual Studio 2017 (MSVC++ Build Tools v141), however some helper code is omitted when using Visual Studio 2017 in order to enable compilation to succeed.
DLL Injection workflow
Use Il2CppInspector to create C++ scaffolding output for the executable binary of interest
Load the generated solution (Il2CppDLL.sln) into Visual Studio
Add the code you wish to execute in the Run() function in main.cpp
Compile the project
Use a DLL injection tool such as Cheat Engine or RemoteDLL to inject the compiled DLL into the IL2CPP application at runtime
You have access to all of the C#-equivalent types and methods in the application, plus all of the available IL2CPP API functions. No additional function pointer or type declarations are required.
Example (create a Vector3 and log its y co-ordinate to a file):
// in main.cppvoidRun()
{
// Vector3 example// (Call an IL2CPP API function)
Vector3__Boxed* myVector3 = (Vector3__Boxed*) il2cpp_object_new((Il2CppClass*) *Vector3__TypeInfo);
// (Call an instance constructor)Vector3__ctor(myVector3, 1.0f, 2.0f, 3.0f, NULL);
// (Access an instance field)il2cppi_log_write(to_string(myVector3->fields.y));
}
Il2CppInspector can create a complete Visual Studio workspace with a solution (.sln) file, project (.csproj) files and assembly-namespace-class tree-like folder structure. Each project creates a single assembly.
Use the --project switch to generate a solution workspace.
In order for Il2CppInspector to be able to create .csproj files which contain the correct Unity assembly references, you must provide the path to an installed Unity editor and a project template or ScriptAssemblies folder of an existing Unity project.
NOTE: The default settings will select the latest installed version of Unity and the latest installed version of the default 3D project template, if they have been installed in the default location.
Typical Unity editor location (specified with --unity-path): C:\Program Files\Unity\Hub\Editor\20xx.y.z
Typical Unity project template location (specified with --unity-assemblies): C:\Program Files\Unity\Hub\Editor\20xx.y.z\Editor\Data\Resources\PackageManager\ProjectTemplates\libcache\<name-of-template>
Typical Unity script assemblies location in existing project (specified with --unity-aseemblies): X:\MyProject\Library\ScriptAssemblies
Replace x, y and z with your Unity version number. Replace <name-of-template> with the desired template.
NOTE: You can use the asterisk wildcard (*) one or more times when specifying these paths. Il2CppInspector will select the last matching folder in alphanumeric order. This is useful if you have multiple side-by-side Unity installs and wish to always select the latest version or template.
In the event that the assembly references are not correctly resolved the first time you load a solution, simply close and re-open the solution to force them to be resolved.
Generating JSON metadata
Il2CppInspector can create a JSON file containing various metadata about the application.
Use the -o switch to specify the JSON output path.
The output schema is as follows:
addressMap (object)
An address map of all IL2CPP-related content in binary
methodDefinitions (array)
The virtual address, binary symbol, C++ function signature and .NET method signature of every .NET-equivalent method in the binary
constructedGenericMethods (array)
The virtual address, binary symbol, C++ function signature and .NET method signature of every .NET-equivalent concrete generic method in the binary
customAttributesGenerators (array)
The virtual address, name and C++ function signature of every custom attributes generator function in the binary
methodInvokers (array)
The virtual address, name and C++ function signature of every Method.Invoke thunk function in the binary
stringLiterals (array)
For Unity versions lower than 5.3.2: the ordinal, name and text of every stri
请发表评论