Home

Awesome

Development of Il2CppInspector is suspended

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.

Il2CppInspector GUI

Main features

Tutorials and Guides

You can read more about how IL2CPP works in my series IL2CPP Reverse Engineering:

How IL2CPP works

Part 1: Hello World and the IL2CPP Toolchain

Part 2: Structural Overview & Finding The Metadata

Il2CppInspector guides

Il2CppInspector Plugin Development Wiki

How to create, use and debug IL2CPP DLL injection projects

Working with code in IL2CPP DLL injection projects

Using Il2CppInspector's type model to extract protobuf-net definitions (Case Study: Fall Guys)

Reverse engineering walkthroughs

Finding loaders for obfuscated global-metadata.dat files - explains how to find the loader, deobfuscation and/or decryption code for global-metadata.dat in almost any IL2CPP application

Enable loading of League of Legends: Wild Rift - covers XOR decryption, XOR string decryption, API export ROT decryption, data obfuscation of binary metadata

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

VMProtect control flow obfuscation in Honkai Impact - covers extrapolating the code path from a function with control flow flattening using x64dbg and the IDA decompiler

Reverse engineering Genshin Impact with PowerShell - covers writing a test harness to find a function in an obfuscated binary via brute-force attack / reverse fuzzing

Other features

File format and architecture support:

Nice to have:

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

Get all current plugins (optional):

../get-plugins.sh

For other operating systems supporting .NET Core, add -r xxx to the final command where xxx is a RID from https://docs.microsoft.com/en-us/dotnet/articles/core/rid-catalog

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:

System
Mono
Microsoft.Reflection
Microsoft.Win32
Internal.Runtime
Unity
UnityEditor
UnityEngine
UnityEngineInternal
AOT
JetBrains.Annotations

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:

You can specify the intra-file type ordering with the --sort switch:

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:

Example IDA C++ decompilation after applying Il2CppInspector (initialization code omitted for brevity):

Il2CppInspector annotated IDA project

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:

  1. From the Code Browser, choose File -> Parse C Source...

  2. 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.

  3. Ensure the Parse Options are set exactly as follows:

    -D_GHIDRA_

  4. Click Parse to Program and accept any warnings. This may take a long time to complete.

  5. Open the Script Manager and add the output folder you chose in Il2CppInspector as a script folder.

  6. 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).

  7. Click Refresh to make the script appear in Script Manager.

  8. Right-click the script and choose Run. This may take a while to complete.

Ghidra import help

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:

Il2CppInspector annotated Ghidra project

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:

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.

Il2CppInspector GUI

The following files are generated:

The above files contain all the data needed for dynamic analysis in a debugger.

In addition, the following files are generated for DLL injection:

For Visual Studio users, the following files are also generated:

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

  1. Use Il2CppInspector to create C++ scaffolding output for the executable binary of interest
  2. Load the generated solution (Il2CppDLL.sln) into Visual Studio
  3. Add the code you wish to execute in the Run() function in main.cpp
  4. Compile the project
  5. 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.cpp
void Run()
{
    // 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));
}

More detailed tutorials can be found here:

How to create, use and debug IL2CPP DLL injection projects

Working with code in IL2CPP DLL injection projects

Creating a Visual Studio C# code stubs solution

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.

Il2CppInspector Auto-generated Visual Studio solution

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:

Universal IL2CPP Build Utility

Three Powershell scripts are provided to enable easy building and testing of IL2CPP binaries:

Example uses:

./il2cpp.ps1

builds each C# source file ìnto a .NET assembly DLL, a C++ source folder and one IL2CPP binary per supported architecture

./il2cpp.ps1 MyFirstTest

builds MyFirstTest.cs into MyFirstTest.dll, creates a C++ source folder named MyFirstTest and an IL2CPP binary for each supported architecture

./il2cpp.ps1 MyFirstTest,MySecondTest 2019.3.1f1

builds MyFirstTest.cs and MySecondTest.cs into individual assembly DLLs, C++ source folders and IL2CPP binaries, using Unity 2019.3.1f1

./il2cpp.ps1 MyFirstTest,MySecondTest F:\Unity\Hub\Editor\2019.3.1f1

as above but specifies a custom path for your Unity installation.

The minimum supported Unity version is 2017.1.0f3.

To learn more about these features, see the section entitled Using Il2CppInspector to generate IL2CPP code in IL2CPP Reverse Engineering Part 1.

Using the APIs for programmatic analysis

NOTE: The Il2CppInspector APIs are also available as a NuGet package! (search: NoisyCowStudios.Il2CppInspector)

Il2CppInspector offers the following re-usable class library APIs:

Use these APIs to easily query IL2CPP types, create new output modules and integrate Il2CppInspector with your own static analysis applications.

To utilize Il2CppInspector in your own projects, add a reference to Il2CppInspector.Common.dll.

Include the following using directives:

See the source code for further details or the tutorials above.

Using plugins

Plugins should be placed in the plugins folder in the same folder as Il2CppInspector.exe. Each plugin should be placed into its own sub-folder with any dependencies or configuration files needed.

From the GUI you can enable and disable plugins, change the execution order and configure individual plugin settings via the Manage plugins... button.

From the CLI you can specify which plugins and settings to use as follows.

For one plugin:

Il2CppInspector.exe --plugins "myplugin --firstOption value1 --secondOption value2"

For multiple plugins:

Il2CppInspector.exe --plugins "plugin1 --option1 ..." "plugin2 --option2 ..." ...

Plugins will be executed in the order specified.

Core plugins (those that are part of Il2CppInspector's base functionality) are always enabled when using the CLI, but can be disabled in the GUI.

When using the CLI, core plugins always execute first by default. You can force the core plugins to execute in a different order by specifying their names in the desired execution order. For example:

Il2CppInspector.exe --plugins "analytics --output foo.csv"

will run the core plugins first then the analytics example plugin, but:

Il2CppInspector.exe --plugins "analytics --output foo.csv" "xor"

will cause the xor core plugin to run after analytics.

For help on a specific plugin, specify the plugin name with no arguments:

Il2CppInspector.exe --plugins myplugin

To get more plugins, click Get Plugins in the Manage Plugins window in the GUI, visit the Il2CppInspectorPlugins repository or use the get-plugins.ps1 or get-plugins.sh scripts to update to the latest plugin releases.

Il2CppInspector Plugins

Creating plugins

Plugins let you extend the functionality of Il2CppInspector. For example you can pre and post-process metadata and binaries to enable inspection of IL2CPP applications that Il2CppInspector cannot handle automatically.

Plugin support is currently experimental and has limited functionality.

Details on how to create your own plugins can be found in the Il2CppInspector Plugin Development Wiki.

You can find out more about plugins, and browse the source code of current plugins and examples in the Il2CppInspectorPlugins repository.

Extending Il2CppInspector's Python output to support other targets

The current version of Il2CppInspector can output Python scripts targeting the IDA and Ghidra disassemblers.

When Il2CppInspector generates such a script, it generates a concatenation of a shared block of code (Outputs/ScriptResources/shared-main.py) which parses the JSON metadata and dispatches it to a set of implementation-specific functions to be processed, and a block of code specific to the target application which implements these functions (a file from Outputs/ScriptResources/Targets).

If you would like to add support for a new target application, create a new Python script in Outputs/ScriptResources/Targets with the nane <target-name-without-whitespace>.py and implement the following functions:

Refer to the source code of IDA.py and Ghidra.py for examples.

When you add a new target and re-compile Il2CppInspector:

If you develop an API for a target that you think might be useful to others, please feel free to submit a PR with the code!

Version support

Unity versionIL2CPP versionSupport
4.6.1+First releaseUnsupported
5.2.x15Unsupported
5.3.0-5.3.116Working
5.3.219Working
5.3.3-5.3.420Working
5.3.5-5.4.621Working
5.5.0-5.5.622Working
5.6.0-5.6.723Working
2017.1.0-2018.2.2124Working
2018.3.0-2018.4.x24.1Working
2019.1.0-2019.3.624.2Working
2019.3.7-2019.4.1424.3Working
2019.4.15-2019.4.2024.4Working
2019.4.21-2019.4.x24.5Working
2020.1.0-2020.1.1024.3Working
2020.1.11-2020.1.1724.4Working
2020.2.0-2020.2.327Working
2020.2.4-2020.3.x27.1Working
2021.1.0-2021.1.x27.2Partial

Please refer to the companion repository https://github.com/nneonneo/Il2CppVersions if you would like to track the changes between each IL2CPP release version.

Problems

If you have files that don't work or are in an unsupported format, please open a new issue on GitHub and attach a sample with details on the file format, and I'll try to add support. Include both the IL2CPP binary and global-metadata.dat in your submission.

Please check the binary file in a disassembler to ensure that it is a plain IL2CPP binary before filing an issue. Il2CppInspector is not intended to handle packed, encrypted or obfuscated IL2CPP files.

Support

If you found Il2CppInspector useful, you can really help support the project by making a small donation at http://paypal.me/djkaty!

You can also donate with bitcoin: 3FoRUqUXgYj8NY8sMQfhX6vv9LqR3e2kzz

Much love! - Katy

Acknowledgements

Thanks to the following major contributors!

This project uses:

Thanks to the following individuals whose code and research helped me develop this tool:

The following books and documents were also very helpful:

Pizza spinner animation in the GUI made by Chris Gannon - https://gannon.tv/

License

This software is licensed under AGPLv3.