frida-il2cpp-bridge

frida-il2cpp-bridge

A Frida module to dump, trace or hijack any Il2Cpp application at runtime, without needing the global-metadata.dat file.

Features

• Dump classes, methods, fields and so on
• Trace, intercept and replace method calls
• Mess around with the C# runtime
• Il2Cpp structs and global metadata (almost) free

Compatibility

Unity version

It should work for any Unity version in the range 5.3.0 - 6000.3.x.

Platforms

Android, Linux, Windows, iOS, macOS are supported. However, only Android and Linux are “tested”: expect breakage if you are using another platform.

CLI

Starting from version 0.10.0, a frida-il2cpp-bridge Python executable is included alongside the NPM package installation. This executable wraps the frida command and adds IL2CPP specific features. To invoke it, simply run:

npx frida-il2cpp-bridge --help

or

npm exec frida-il2cpp-bridge -- --help

Dumping

Use the dump subcommand to dump an application:

$ npm exec frida-il2cpp-bridge -- dump --help
usage: frida-il2cpp-bridge [args ...] dump [-h] [--out-dir OUT_DIR] [--cs-output {none,stdout,flat,tree}] [--no-namespaces] [--flatten-nested-classes]
                                           [--keep-implicit-base-classes] [--enums-as-structs] [--no-type-keywords] [--actual-constructor-names]
                                           [--indentation-size INDENTATION_SIZE]

options:
  -h, --help            show this help message and exit
  --out-dir OUT_DIR     where to save the dump (defaults to current working dir)
  --cs-output {none,stdout,flat,tree}
                        style of C# output (defaults to tree)
                        -   none: do nothing;
                        - stdout: print to console;
                        -   flat: one single file (dump.cs);
                        -   tree: directory structure having one file per assembly.
  --no-namespaces       do not emit namespace blocks, and prepend namespace name in class declarations
                        (without flag)          --no-namespaces
                        namespace Foo           class Foo.Bar
                        {                       {
                            class Bar               ...
                            {                   }
                                ...
                            }
                        }
  --flatten-nested-classes
                        write nested classes at the same level of their inclosing classes, and prepend enclosing class name in their declarations
                        (without flag)          --flatten-nested-classes
                        class Foo               class Foo
                        {                       {
                            ...                     ...
                                                }
                            class Bar
                            {                   class Foo.Bar
                                ...             {
                            }                       ...
                        }                       }
  --keep-implicit-base-classes
                        write implicit base classes (class -> System.Object, struct -> System.ValueType, enum -> System.Enum) in class declarations
                        (without flag)          --keep-implicit-base-classes
                        class Foo               class Foo : System.Object
                        {                       {
                        }                       }
                        
                        struct Bar              struct Bar : System.ValueType
                        {                       {
                        }                       }
                        
                        enum Baz                enum Baz : System.Enum
                        {                       {
                        }                       }
  --enums-as-structs    write enum class declarations as structs
                        (without flag)          --enums-as-structs
                        enum Foo                struct Foo
                        {                       {
                            First = 0,              int value__; // 0x10
                            Second = 1,             static Foo First = 0;
                        }                           static Foo Second = 1;
                                                }
  --no-type-keywords    use fully qualified names for builtin types instead of their keywords
                        (without flag)          --no-type-keywords
                        class Foo               class Foo
                        {                       {
                            int a;                  System.Int32 a;
                        
                            void B(string c);       System.Void B(System.String c);
                        }                       }
  --actual-constructor-names
                        write actual constructors names
                        (without flag)          --no-type-keywords
                        class Foo               class Foo
                        {                       {
                            static Foo();           static void .cctor();
                        
                            Foo();                  void .ctor();
                        }                       }
  --indentation-size INDENTATION_SIZE
                        indentation size (defaults to 4)

Example:

npm exec frida-il2cpp-bridge -- -f com.example.application dump --out-dir dumps

Output:

Spawning `com.example.application`...
IL2CPP module loaded in 1.13s (id=com.example.application, version=1.12.8, unity version=2019.3.0f1)
Dumping mscorlib: 2872 of 2872 classes
Dumping GameAssembly: 32 of 32 classes
Collected 2904 classes in 4.76s
Dump saved to dumps/com.example.application/1.12.8

Testing

Over the time, it was realized that some testing was necessary, as supporting many Unity version makes introducing regressions or faulty features easy. Though it’s far from being complete and bullet-proof, there’s a minimal testing setup contributors can get advantage of to test their changes.
In order to test frida-il2cpp-bridge, a IL2CPP application is needed (of course). Here are some very useful resources:

• IL2CPP toolchain
• Scripting

Commands (local)

Unity editors (so IL2CPP toolchains) will be downloaded and extracted automatically.

Prerequisites

1. Only Linux (x86_64) is currently supported;
2. Make sure to have clang and make installed.

Build IL2CPP assembly (GameAssembly.so) for a specific Unity version only

make assembly UNITY_VERSION=6000.3.10f1

Run test on each assembly

make test

Commands (Docker)

Currently, testing-related commands for Linux (x86_64) are provided, however there’s a Dockerfile so that it’s possible to create a container on any OS or arch (a virtualization system/emulator might be required).

Prerequisites

1. Docker (or similar);
2. Emulator/virtualization (optional).

Build Docker image for a specific Unity version

make image UNITY_VERSION=2023.2.20f1

This creates a Docker image tagged as frida-il2cpp-bridge-playground:2023.2.20f1 having roughly the following content:

~/
└── build/
    ├── 2023.2.20f1/
    │   └── out
    │       ├── Data
    │       │   ├── Metadata
    │       │   │  └── global-metadata.dat
    │       │   ├── Resources
    │       │   │  └── mscorlib.dll-resources.dat
    │       └── GameAssembly.so
    └── host

As you can see, it only contains artifacts (and frida-server, of course). However, multi stage Docker builds are used so that you can stop at any step:

# Just get the Unity editor in it
docker build \
  --platform linux/amd64 \
  --build-arg UNITY_VERSION=2023.2.20f1 \
  --target unity-editor \
  -t unity:2023.2.20f1 \
  test

Run tests on each Docker image

make testd

Limitations

• Image build for 2021.2.0f1 is currently broken.

Acknowledgements

Thanks to meme and knobse for helping and getting me into this, and to djkaty and nneonneo for providing the Il2Cpp API.

Problems?

Discussions and Wiki are both active. Use them!