Update README.md
This commit is contained in:
Katy Coe
73
README.md
73
README.md
@@ -1,4 +1,4 @@
|
||||
# Il2CppInspector 2020.2
|
||||
# Il2CppInspector 2020.2.1 beta
|
||||
|
||||
Il2CppInspector helps you to reverse engineer IL2CPP applications, providing the most complete analysis currently available.
|
||||
|
||||
@@ -41,7 +41,7 @@ You can read more about IL2CPP in my series [IL2CPP Reverse Engineering](https:/
|
||||
File format and architecture support:
|
||||
|
||||
* Supports ELF (Android .so), PE (Windows .exe), Mach-O (Apple iOS/Mac), Universal Binary (Fat Mach-O) and FSELF (PlayStation 4 .prx/.sprx) file formats
|
||||
* Also supports APK (Android) and decrypted IPA (iOS) application package files as input
|
||||
* Also supports single and split APK (Android) and decrypted IPA (iOS) application package files as input
|
||||
* 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)
|
||||
@@ -109,7 +109,7 @@ Run `Il2CppInspector.exe` at the command prompt.
|
||||
File format and architecture are automatically detected.
|
||||
|
||||
```
|
||||
-i, --bin (Default: libil2cpp.so) IL2CPP binary, APK or IPA input file
|
||||
-i, --bin (Default: libil2cpp.so) IL2CPP binary, APK or IPA 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/IPA)
|
||||
|
||||
@@ -160,6 +160,8 @@ For Apple Universal Binaries and APKs with binaries for multiple architectures,
|
||||
|
||||
For IPA packages, the executable must be decrypted first. Encrypted executable binaries are not supported.
|
||||
|
||||
For split APK packages, specify a list of APK files with a space between each filename.
|
||||
|
||||
### 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.
|
||||
@@ -241,6 +243,10 @@ Three files are generated by Il2CppInspector for Ghidra: the Python script itsel
|
||||
|
||||
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`. 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..._
|
||||
@@ -255,14 +261,10 @@ To import metadata into an existing Ghidra project:
|
||||
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.
|
||||
|
||||
**NOTE:** If you receive a `Conflicting data exists at address` error when running the script, re-load the binary into the project but choose No when Ghidra asks if you would like to perform auto-analysis.
|
||||
|
||||
|
||||
|
||||
Il2CppInspector generates identical data for Ghidra projects as it does for IDA - see the above section for details.
|
||||
|
||||
**NOTE**: For compatibility reasons, executing the Ghidra Python script on an ELF file will reset the file's image base to zero (`0x00000000`). Other file formats will retain the same image base.
|
||||
|
||||
Example Ghidra C++ decompilation after applying Il2CppInspector:
|
||||
|
||||
|
||||
@@ -308,6 +310,9 @@ The following files are generated:
|
||||
- `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:
|
||||
@@ -317,7 +322,7 @@ In addition, the following files are generated for DLL injection:
|
||||
- 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 basic logging and other helper functions. See the comments in `helpers.h` for details.
|
||||
- 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
|
||||
@@ -338,6 +343,8 @@ 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!
|
||||
|
||||
#### DLL Injection workflow
|
||||
|
||||
1. Use Il2CppInspector to create C++ scaffolding output for the executable binary of interest
|
||||
@@ -357,13 +364,13 @@ void Run()
|
||||
// Vector3 example
|
||||
|
||||
// (Call an IL2CPP API function)
|
||||
Vector3__Boxed* myVector3 = (Vector3__Boxed*) il2cpp_object_new(Vector3__TypeInfo);
|
||||
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)
|
||||
LogWrite(to_string(myVector3->fields.y));
|
||||
il2cppi_log_write(to_string(myVector3->fields.y));
|
||||
}
|
||||
```
|
||||
|
||||
@@ -431,7 +438,10 @@ The output schema is as follows:
|
||||
The virtual addresses of the start of every known function in the binary, including all of those above plus any others detected but not included in the above categories
|
||||
|
||||
- `typeMetadata` (array)
|
||||
The virtual address, name and C++ type name of key metadata items in the binary. This includes `Il2CppCodeRegistration` and `Il2CppMetadataRegistration`, and depending on the binary version may also include `Il2CppCodeGenModule **` and a pointer to each `Il2CppCodeGenModule`
|
||||
The virtual address, name and C++ type name of key metadata items in the binary. This includes `Il2CppCodeRegistration` and `Il2CppMetadataRegistration`, and depending on the binary version may also include a pointer to each `Il2CppCodeGenModule`
|
||||
|
||||
- `arrayMetadata` (array)
|
||||
The virtual address, name, C++ type name and size of key metadata arrays in the binary
|
||||
|
||||
- `functionMetadata` (array)
|
||||
The virtual address, name and C++ function signature of key metadata functions in the binary. Depending on how the binary was analyzed by Il2CppInspector, this may include `il2cpp_codegen_register`.
|
||||
@@ -447,14 +457,43 @@ The output schema is as follows:
|
||||
|
||||
### Generating IL2CPP binaries without a Unity project
|
||||
|
||||
Two Powershell scripts are provided to enable easy testing and debugging:
|
||||
Three Powershell scripts are provided to enable easy building and testing of IL2CPP binaries:
|
||||
|
||||
* `generate-binaries.ps1` compiles every C# source file in `TestSources` as a separate assembly and outputs them to `TestAssemblies`. It then takes every assembly in `TestAssemblies` and compiles each one as a separate IL2CPP project for each of these architectures: Windows x86 standalone, Windows x64 standalone, Android ARMv7 (32-bit) and Android ARMv8-A (64-bit). These are placed into the `TestBinaries`folder. It then calls `generate-tests.ps1`.
|
||||
* `generate-tests.ps1` generates a file called `Tests.cs` in the `Il2CppTests` project, containing one test per IL2CPP project in `TestBinaries`. This file will be compiled by the `Il2CppTests`project. You will then be able to see one test per IL2CPP project in Visual Studio's Test Explorer.
|
||||
* `il2cpp.ps1` is the main workhorse and compiles each specified C# source file in `TestSources` (or all of them if none supplied) as a separate assembly, and outputs them to `TestAssemblies`. It then takes every specified assembly in `TestAssemblies` and compiles each one as a separate IL2CPP project for each of these architectures: Windows x86 standalone, Windows x64 standalone, Android ARMv7 (32-bit) and Android ARMv8-A (64-bit). These are placed into the `TestBinaries` folder. The C++ source code for each build is placed into the `TestCpp` folder. It then calls `generate-tests.ps1`.
|
||||
|
||||
The auto-generated tests generate a file in the test IL2CPP binary's folder called `test-result.cs` and compares it (whitespace-insensitive) with the corresponding project name `cs` file in `TestExpectedResults`. In this way, you can check for files with known structure that the analysis is being performed correctly, or step through the analysis of specific binaries in the debugger without having to change the project's command-line arguments.
|
||||
Specify a comma-separated list of source files (without the `.cs` extension) to process as the first argument (or `-assemblies`).
|
||||
|
||||
To learn more about this feature, see the section entitled **Using Il2CppInspector to generate IL2CPP code** in [IL2CPP Reverse Engineering Part 1](https://katyscode.wordpress.com/2020/06/24/il2cpp-part-1/).
|
||||
You can optionally specify a Unity version or Unity install path with the 2nd argument (or `-unityVersion`). If none is supplied, the latest installed Unity version will be used. You can also specify wildcards, eg. `2019*` will use the latest installed version of Unity 2019, `2018.3*` will use the latest installed version of Unity 2018.3 etc. Use Unity Hub to install the desired versions.
|
||||
|
||||
Therefore with one command you can generate an assembly DLL, C++ source code and IL2CPP binary for each architecture for any given list of source files, one set of outputs per source file, for a specified version of Unity.
|
||||
|
||||
* `generate-tests.ps1` generates a file called `Tests.cs` in the `Il2CppTests` project, containing one test per IL2CPP project in `TestBinaries`. This file will be compiled by the `Il2CppTests` project. You will then be able to see one test per IL2CPP project in Visual Studio's Test Explorer.
|
||||
|
||||
The auto-generated tests generate C#, JSON and C header files in the test IL2CPP binary's folder in `TestBinaries` (each filename prefixed with `test`) and compares them (whitespace-insensitive) with the corresponding project name files in `TestExpectedResults`. In this way, you can check for files with known structure that the analysis is being performed correctly, or step through the analysis of specific binaries in the debugger without having to change the project's command-line arguments.
|
||||
|
||||
* `update-expected-results.ps1` copies all of the output test results from `TestBinaries` into `TestExpectedResults`, therefore updating the files that will be used to verify correct test results.
|
||||
|
||||
Example uses:
|
||||
|
||||
`./il2cpp.ps1`
|
||||
|
||||
builds each C# source file <20>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](https://katyscode.wordpress.com/2020/06/24/il2cpp-part-1/).
|
||||
|
||||
### Using the APIs for programmatic analysis
|
||||
|
||||
@@ -521,7 +560,7 @@ Unity version | IL2CPP version | Support
|
||||
2018.3.x-2018.4.x | 24.1 | Working
|
||||
2019.1.x-2019.3.6 | 24.2 | Working
|
||||
2019.3.7-2020.1.x | 24.3 | Working
|
||||
2020.2.0 (alpha) | 27 | Working
|
||||
2020.2.0 (beta) | 27 | Working
|
||||
|
||||
Please refer to the companion repository https://github.com/nneonneo/Il2CppVersions if you would like to track the changes between each IL2CPP release version.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user