frida-gadget is a tool for patching Android applications to integrate the Frida Gadget.This tool automates the process of downloading the Frida gadget library and injecting the
loadLibrary code into the main activity.
pip install frida-gadget --upgradeYou should install
apktool and add it to your PATH environment variable.# Install Apktool on macOS
brew install apktool
# Add Apktool to your PATH environment variable
export PATH=$PATH:$HOME/.brew/binFor other operating systems, such as
Windows, you can refer to the Install Guide.$ frida-gadget --help
Usage: cli.py [OPTIONS] APK_PATH
Patch an APK with the Frida gadget library
Options:
--arch TEXT Specify the target architecture of the device. (options: arm64, x86_64, arm, x86)
--config TEXT Specify the Frida configuration file.
--js TEXT Specify the Frida gadget JavaScript file.
--js-delay INTEGER Specify seconds to wait before executing the JavaScript file.
--force-manifest Force modify AndroidManifest.xml even if it already has required permissions.
--custom-gadget-name TEXT Specify a custom name for the Frida gadget.
--no-res Skip decoding resources.
--main-activity TEXT Specify the main activity if known.
--sign Automatically sign the APK using uber-apk-signer.
--skip-decompile Skip the decompilation step.
--skip-recompile Skip the recompilation step.
--use-aapt2 Use aapt2 instead of aapt for resource processing.
--decompile-opts TEXT Specify additional options for apktool decompile.
--recompile-opts TEXT Specify additional options for apktool recompile.
--apktool-path TEXT Specify the path or command to run apktool.
--frida-version TEXT Specify the Frida version to use.
--ks TEXT The keystore file. If not provided, will use debug keystore.
--ks-alias TEXT The alias of the used key in the keystore.
--ks-key-pass TEXT The password for the key.
--ks-pass TEXT The password for the keystore.
--version Show the version and exit.
--help Show this message and exit.Simply provide the APK file with the target architecture.
$ frida-gadget target.apk --sign
[INFO] Auto-detected frida version: 16.1.3
[INFO] APK: '[REDACTED]/demo-apk/target.apk'
[INFO] Auto-detected architecture via ADB: arm64-v8a # Alternatively, specify the architecture with --arch arm64
[INFO] Gadget Architecture(--arch): arm64(default)
[DEBUG] Decompiling the target APK using apktool
[DEBUG] Downloading the frida gadget library for arm64
[DEBUG] Checking internet permission and extractNativeLibs settings
[DEBUG] Adding 'android.permission.INTERNET' permission to AndroidManifest.xml
[DEBUG] Searching for the main activity in the smali files
[DEBUG] Found the main activity at '[REDACTED]/frida-gadget/tests/demo-apk/target/smali/com/google/mediap/apps/target/MainActivity.smali'
[DEBUG] Locating the onCreate method and injecting the loadLibrary code
[DEBUG] Recompiling the new APK using apktool
...
[INFO] APK signing finished: ./target/dist/target-aligned-debugSigned.apk (72.78 MiB)You can also use this tool with Docker. Here's how to use it:
1. First, pull the Docker image:
docker pull ksg97031/frida-gadget2. Mount your local directory containing the APK file to the container:
docker run -v $(pwd):/workspace/mount ksg97031/frida-gadget /workspace/mount/your-app.apk --arch arm64 --signNote: Replace
your-app.apk with your actual APK filename. The patched APK will be created in the same directory as your original APK.For example, if your APK is named
example.apk:docker run -v $(pwd):/workspace/mount ksg97031/frida-gadget /workspace/mount/example.apk --arch arm64 --sign
# The patched APK will be located at ./example/dist/example.apkThe tool automatically detects the device architecture when an ADB device is connected. You can also manually specify the architecture using the
--arch option.To determine your device's architecture, connect your device and run the following command:
adb shell getprop ro.product.cpu.abiThis command will output the architecture of your device, such as
arm64-v8a, armeabi-v7a, x86, x86_64 or multi-arch.Example of automatic detection:
$ frida-gadget target.apk --sign
[INFO] Auto-detected architecture via ADB: arm64-v8aExample of manual specification:
$ frida-gadget target.apk --arch arm64 --sign
[INFO] Gadget Architecture(--arch): arm64The following table shows the minimum Frida version required for different Android versions:
(Note: This information may not be completely accurate)
| Android Version | Minimum Frida Version | Notes |
|---|---|---|
| Android 5.x ~ 7.x (Lollipop~Nougat) | Frida 14.2+ | Support for older Android versions was improved in Frida 12.6. Frida 14.2 includes fixes for libc detection errors and restored Houdini (translator) support. Latest Frida (16.x) continues to support Android 5~7. |
| Android 8.0 ~ 8.1 (Oreo) | Frida 12.6.6+ | Java API issues like Java.choose were resolved in Frida 12.6.3+. Java integration issues on 32-bit ARM devices were fixed in Frida 12.6.6. Frida 14.x and newer versions work stably on Oreo. |
| Android 9.0 (Pie) | Frida 12.7+ | Frida was extensively tested on Pixel 3 (Android 9). Frida 12.x ~ 15.x versions work stably on AOSP-based Android 9. Latest Frida 16.x also supports Android 9. (For emulators, Google-provided Android 9 images for arm/arm64 are recommended.) |
| Android 10 (Q) | Frida 14.2+ | While there were no major changes specific to Android 10, Frida 14.2+ is recommended for overall stability. Frida 14.2 includes various compatibility improvements for both pre and post Android 10 versions. Latest Frida 15.x and 16.x versions work without issues on Android 10. |
| Android 11 (R) | Frida 14.2+ | Frida 14.2 includes modifications to address ART changes and ARM->x86 translation in Android 11. Frida 14.2 or higher is recommended for Android 11. Frida 15.x~16.x fully support Android 11. (May have separate issues on custom ROMs like Samsung.) |
| Android 12 (S) | Frida 15.0+ | Official support for Android 12 was first added in Frida 15.0. Initial 15.0 version had minor compatibility issues, but Frida 15.1.23 includes several stability improvements for Android 12. Frida 15.1.23 or higher (preferably 15.2 or latest 16.x) is recommended for Android 12 devices. |
| Android 13 (T) | Frida 15.1.23+ | Preliminary support for Android 13 was introduced in Frida 15.1.23, and support matured in Frida 16.x versions. Minimum Frida 15.1.23 is required for Android 13 devices, but using the latest Frida 16 version is recommended (includes fixes for Android 13's internal behavior changes). |
| Android 14 (UpsideDownCake) | Frida 16.2.0+ | Due to ART structure changes in Android 14, initial Frida 16.0~16.1 versions had issues with Java hooking, but Frida 16.2.0 improved hooking support for Android 14. Frida 16.2 or higher is recommended for Android 14 (Frida 16.2 added support for Android 14's new ART entrypoints). |
You can observe the main activity to see the injected
loadLibrary code.Additionally, the Frida gadget library will be present in your APK.
$ unzip -l [REDACTED]/demo-apk/target/dist/target.apk | grep libfrida-gadget
21133848 09-15-2021 02:28 lib/arm64-v8a/libfrida-gadget-16.1.3-android-arm64.soIf the main activity is not automatically detected, you can specify it manually using the
--main-activity option:$ frida-gadget target.apk --main-activity com.example.MainActivity --no-res --sign1. Download the @akabe1/frida-multiple-unpinning script.
2. Inject the script into the target application using the
--js flag.frida-gadget target.apk --js frida-multiple-unpinning.js --sign --no-res3. Run the injected application on your device or emulator.
4. Observe the network traffic using a proxy tool such as Burp Suite or Caido.
Note: If the app crashes, try adding
--js-delay 2 to delay script execution:frida-gadget target.apk --js frida-multiple-unpinning.js --js-delay 2 --sign --no-resThis gives the app time to initialize before applying hooks.
You can also specify a custom Frida version using
--frida-version:frida-gadget target.apk --js frida-multiple-unpinning.js --frida-version 16.1.3 --sign --no-resThis is useful when you need to use a specific Frida version for compatibility reasons.
You can specify a custom apktool path or command using the
--apktool-path option.For example, you can use a script or a specific jar file:
$ frida-gadget target.apk --apktool-path ./tools/apktool.bat --sign # Windows
$ frida-gadget target.apk --apktool-path "java -Xmx16g -jar ~/Download/apktool.jar" --sign # Java with 16GB memoryYou can also specify custom options for apktool decompile and recompile using the
--decompile-opts and --recompile-opts options.For example, you can pass additional flags to apktool:
$ frida-gadget target.apk --decompile-opts "--only-main-classes --no-res" --recompile-opts "--force-all" --sign