Modes

Overview

Frida instruments programs via Gum (C core) + GumJS (JavaScript runtime wrapping Gum). Instrumentation scripts run inside the target process with full access to Gum APIs: function hooking, library/export enumeration, memory read/write, memory pattern scanning.

Three modes address different deployment constraints:

Mode 1: Injected

When to use: Default mode. Target process is accessible (not jailed). You want to spawn, attach, or hijack a process at runtime.

How it works:

• frida-core packages GumJS into a shared library and injects it into the target
• Provides a two-way communication channel to scripts
• Scripts can be loaded, communicated with, and unloaded dynamically

Additional capabilities via frida-core:

• Enumerate installed apps
• Enumerate running processes
• Enumerate connected devices

Remote device support (iOS / Android):

• frida-server runs as a daemon on the device
• Exposes frida-core over TCP
• Default listen address: localhost:27042

Tooling: All standard Frida CLI tools (frida, frida-trace, frida-ps, etc.) use this mode by default.

Mode 2: Embedded (Gadget)

When to use: Injected mode is unavailable — e.g., jailed iOS, non-debuggable Android, or environments without a running frida-server.

How it works:

• Embed frida-gadget (a shared library) directly into the target application
• Gadget initializes via its constructor function at dynamic-linker load time
• After loading, interact with it using existing Frida tools (e.g., frida-trace)

Ways to embed Gadget:

• Modify the program’s source code
• Patch the binary or one of its libraries (e.g., using insert_dylib)
• Use dynamic linker preloading: LD_PRELOAD (Linux) or DYLD_INSERT_LIBRARIES (macOS/iOS)

Naming:

• The Gadget binary can be named anything (useful to bypass anti-Frida detection on name)
• Config file must share the same base name as the binary, with .config extension
  • Example: FridaGadget.dylib → FridaGadget.config

Platform-specific notes:

Config file format: UTF-8 JSON with root object. Top-level keys:

Gadget Interaction Types

Listen (default)

Gadget exposes a frida-server-compatible TCP interface. Process list contains only the single Gadget process (re.frida.Gadget / name Gadget).

Constructor blocks until attach() or resume() is called (enabling early instrumentation). Override with "on_load": "resume" to skip blocking.

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}

Config keys:

Connect

Gadget connects outward to a running frida-portal and joins its cluster. Useful for managed/fleet scenarios. Constructor blocks only if spawn-gating is enabled (Device.enable_spawn_gating()).

Default config:

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

Config keys:

Note: For custom authentication, per-node ACLs, or application-specific protocol messages, instantiate PortalService programmatically instead of using the frida-portal CLI.

Script

Fully autonomous mode. Loads and executes a single JavaScript file from the filesystem before the program’s entrypoint runs. No external tooling required.

Minimal config:

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

Script skeleton with optional 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 on script unload (process exit, Gadget unload, or reload)
16    console.log('[dispose]');
17  }
18};

Lifecycle details:

• init() is called before the program’s entrypoint; Gadget waits for it to return (supports returning a Promise)
• dispose() is optional cleanup hook
• console.log/warn/error write to stdout/stderr

path resolution rules:

• Absolute paths are used directly
• Relative paths are resolved relative to the Gadget binary location
• On iOS, relative paths first check the app’s Documents directory (supports iTunes file sharing / AFC updates for debuggable apps)

Config keys:

ScriptDirectory

Loads multiple scripts from a directory. Useful for system-wide instrumentation or plugin-style tweaks. Each script can optionally have a .config sidecar for filtering and parameters.

Minimal config:

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

Config keys:

Per-script sidecar config (<scriptname>.config):

Example: twitter.js + twitter.config for macOS Twitter app:

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 any criterion matches.

Mode 3: Preloaded

Concept: Analogous to LD_PRELOAD (Linux) / DYLD_INSERT_LIBRARIES (macOS) — but for JavaScript. Uses frida-gadget in autonomous (Script or ScriptDirectory) mode loaded via the dynamic linker.

Implementation: Same as Embedded mode, but specifically configured to use the script or script-directory interaction with no external controller. Gadget is injected via LD_PRELOAD/DYLD_INSERT_LIBRARIES and runs scripts from the filesystem automatically.

Key difference from Embedded Listen/Connect: No frida-server or frida-portal is needed at runtime.

Decision Guide

Is the target process accessible (not jailed, can attach/spawn)?
├── Yes → Use Injected mode (frida-server + standard tools)
└── No → Need to embed frida-gadget
    ├── Want remote interactive control?
    │   ├── Direct connection → Listen interaction (Gadget as server)
    │   └── Fleet/portal scenario → Connect interaction (Gadget connects to portal)
    └── Want fully autonomous (no external tooling)?
        ├── Single script → Script interaction
        └── Multiple scripts / plugin system → ScriptDirectory interaction

Related References

• Gadget full docs: /docs/gadget/
• JavaScript API (rpc.exports, Interceptor, Module, Socket): /docs/javascript-api/
• frida-trace CLI: /docs/frida-trace/