Frida Gadget

Overview

• What it is: A shared library (FridaGadget.dylib / libgadget.so) loaded into a target process for instrumentation.
• When to use: When the Injected mode (i.e., frida CLI / frida.attach()) is not viable — e.g., jailed iOS, non-debuggable Android, or restricted environments.
• Activation: Gadget starts when the dynamic linker executes its constructor function (before main()).

Loading Methods

Binary Naming

• The Gadget binary can be renamed to anything (useful for anti-detection bypass).
• The config file must match the binary name with a .config extension.
  • Example: FridaGadget.dylib → FridaGadget.config

Config File

• Encoding: UTF-8
• Format: JSON object
• Location: Same directory as the Gadget binary (with matching name + .config extension)

Root-Level Keys

code_signing Details

• "optional": Frida assumes it can modify code in memory and run unsigned code (default for most platforms).
• "required": Required to run on jailed iOS without a debugger attached. Side effect: Interceptor API becomes unavailable. To use Interceptor on jailed iOS, attach a debugger before Gadget loads — the relaxed code-signing state persists even after detaching.

Platform-Specific Notes

Android (non-debuggable apps)

The package manager only copies files from /lib if they match:

• Name starts with lib
• Name ends with .so
• Name is gdbserver

Workaround: Rename config file to comply with .so suffix rule.

lib/
└── arm64-v8a/
    ├── libgadget.config.so   ← config file renamed with .so suffix
    └── libgadget.so

iOS (Xcode)

Xcode typically places FridaGadget.dylib inside a Frameworks/ subdirectory. Gadget will also search the parent directory of Frameworks/ for the config file. This means the config can sit next to the app binary:

MyApp.app/
├── MyApp                    ← app binary
├── FridaGadget.config       ← config can live here
└── Frameworks/
    └── FridaGadget.dylib

Interaction Types

1. Listen (Default)

Gadget exposes a frida-server-compatible interface. Existing CLI tools (frida, frida-trace, etc.) work without modification.

• Process list: Contains only one entry — Gadget
• App identifier: Always re.frida.Gadget
• Default behavior: Constructor blocks until you attach() or call resume() after spawn() → attach() → instrument.

Default config:

1{
2  "interaction": {
3    "type": "listen",
4    "address": "127.0.0.1",
5    "port": 27042,
6    "on_port_conflict": "fail",
7    "on_load": "wait"
8  }
9}

All supported keys:

2. Connect

Gadget connects outbound to a running frida-portal, joining its process cluster. The portal’s control interface (same protocol as frida-server) lets controllers enumerate_processes() and attach() remotely.

• Blocking behavior: Only blocks if spawn-gating is enabled (Device.enable_spawn_gating()). Otherwise proceeds after joining the portal cluster.

Default config:

1{
2  "interaction": {
3    "type": "connect",
4    "address": "127.0.0.1",
5    "port": 27052
6  }
7}

All supported keys:

Advanced: For custom authentication, per-node ACLs, and app-specific protocol messages, instantiate PortalService programmatically instead of using the frida-portal CLI.

3. Script

Loads a single JavaScript file from the filesystem before the program’s entrypoint. Fully autonomous — no external Frida client needed.

Minimal config:

1{
2  "interaction": {
3    "type": "script",
4    "path": "/home/user/explore.js"
5  }
6}

Script skeleton with lifecycle hooks:

 1rpc.exports = {
 2  init(stage, parameters) {
 3    // stage: "early" (first load) or "late" (reload)
 4    // parameters: object from config, or {}
 5    console.log('[init]', stage, JSON.stringify(parameters));
 6
 7    Interceptor.attach(Module.getGlobalExportByName('open'), {
 8      onEnter(args) {
 9        const path = args[0].readUtf8String();
10        console.log('open("' + path + '")');
11      }
12    });
13  },
14  dispose() {
15    // Called when script is unloaded (process exit, Gadget unload, or reload)
16    console.log('[dispose]');
17  }
18};

Lifecycle behavior:

• init(stage, parameters) is called before program entrypoint. Gadget waits for it to return (supports returning a Promise for async work — e.g., Socket.connect()).
• stage values:
  • "early": Gadget was just loaded for the first time
  • "late": Script is being reloaded from disk
• dispose() is called on unload. Optional.
• rpc.exports is optional entirely — only needed if lifecycle awareness is required.
• Debugging: console.log(), console.warn(), console.error() → stdout/stderr.

All supported keys:

4. ScriptDirectory

Loads multiple scripts from a directory. Each script is treated as a plugin. Optional per-script filtering limits which processes load each script — useful for system-wide instrumentation with per-app targeting.

Minimal config:

1{
2  "interaction": {
3    "type": "script-directory",
4    "path": "/usr/local/frida/scripts"
5  }
6}

All supported keys:

Per-script config file (e.g., twitter.js → twitter.config):

Example — macOS Twitter tweak:

/usr/local/frida/scripts/twitter.js:

 1const { TMTheme } = ObjC.classes;
 2
 3rpc.exports = {
 4  init(stage, parameters) {
 5    ObjC.schedule(ObjC.mainQueue, () => {
 6      TMTheme.switchToTheme_(TMTheme.darkTheme());
 7    });
 8  },
 9  dispose() {
10    ObjC.schedule(ObjC.mainQueue, () => {
11      TMTheme.switchToTheme_(TMTheme.lightTheme());
12    });
13  }
14};

/usr/local/frida/scripts/twitter.config:

1{
2  "filter": {
3    "executables": ["Twitter"],
4    "bundles": ["com.twitter.twitter-mac"],
5    "objc_classes": ["Twitter"]
6  }
7}

Filter is OR-logic: script loads if executable name is Twitter or bundle ID is com.twitter.twitter-mac or an ObjC class named Twitter is loaded. For stability, prefer filtering on bundle ID. Use objc_classes as a fallback for apps without bundle IDs.

Quick Reference: Interaction Type Comparison

Related

• Frida Modes — overview of Injected, Embedded (Gadget), and Preloaded modes
• JavaScript API: rpc — rpc.exports reference
• JavaScript API: Socket.connect() — async socket API usable in init()
• frida-trace — CLI tool that works with Listen mode
• insert_dylib — tool for patching dylibs to load Gadget