Frida JavaScript API

Source: frida/frida-website (_i18n/en/_docs/javascript-api.md) Runtime: QuickJS (default) or V8 (Script.runtime) TypeScript bindings: npm install @types/frida-gum + clone frida-agent-example

Runtime Information

Frida

Script

Process, Thread, Module, Memory

Process

Thread

Objects returned by Process.enumerateThreads():

1// Backtrace example in Interceptor
2Interceptor.attach(Module.getGlobalExportByName('open'), {
3  onEnter(args) {
4    console.log(Thread.backtrace(this.context, Backtracer.ACCURATE)
5      .map(DebugSymbol.fromAddress).join('\n'));
6  }
7});

Module

Objects returned by Module.load() and Process.enumerateModules():

Symbol type values:

• Mach-O: unknown, section, undefined, absolute, prebound-undefined, indirect
• ELF: unknown, section, object, function, file, common, tls

ModuleMap

1const map = new ModuleMap([filter]);  // filter: (Module) => boolean

Memory

1// patchCode example: make get_lives_left() return 9000
2const getLivesLeft = Process.getModuleByName('game-engine.so').getExportByName('get_lives_left');
3Memory.patchCode(getLivesLeft, 64, code => {
4  const cw = new X86Writer(code, { pc: getLivesLeft });
5  cw.putMovRegU32('eax', 9000);
6  cw.putRet();
7  cw.flush();
8});

MemoryAccessMonitor

CModule

Compile C source code to machine code in memory. Useful for hot Interceptor/Stalker callbacks.

1new CModule(code[, symbols, options])

• code: C source string or ArrayBuffer (precompiled shared library)
• symbols: object mapping names to NativePointer values (memory blocks, NativeCallbacks)
• options.toolchain: "internal" (TinyCC, always available, unoptimized) | "external" (system toolchain) | "any" (default)
• Global C functions exported as NativePointer properties
• Writable globals must be extern and passed via symbols
• Lifecycle hooks: void init(void), void finalize(void)
• dispose(): eagerly unmap

1const cm = new CModule(`
2#include <stdio.h>
3void hello(void) { printf("Hello from CModule\\n"); }
4`);
5const hello = new NativeFunction(cm.hello, 'void', []);
6hello();

CModule.builtins: object with defines and headers available during compilation (arch/version-specific).

RustModule

1new RustModule(code[, symbols, options])

• code: Rust source string
• symbols: extern C symbols exposed to Rust
• options.dependencies: array of Cargo dependency strings (e.g. ['base64 = "0.22.1"'])
• Public #[no_mangle] extern "C" functions exported as NativePointer properties

ApiResolver

1const resolver = new ApiResolver(type);
2// type: "module" | "swift" | "objc"

• "module": always available; resolves exports, imports, sections
• "swift": requires Swift runtime; check Swift.available
• "objc": requires ObjC runtime; check ObjC.available

Lazy-loads data on creation. Reuse instance for batch queries; recreate for fresh data.

1resolver.enumerateMatches(query)  // returns [{name, address, size?}]

Query syntax:

• Module: "exports:*!open*", "imports:libc.so!*", "sections:*!*text*"
• ObjC: "-[NSURL* *HTTP*]"
• Swift: "functions:*CoreDevice!*RemoteDevice*"

Suffix /i for case-insensitive matching.

DebugSymbol

Kernel

Requires Kernel.available === true before use.

Data Types, Function and Callback

Int64 / UInt64

1const v = new Int64(v)   // or int64(v)
2const v = new UInt64(v)  // or uint64(v)
3// v: number or decimal/hex string ("0x1234")

NativePointer

1const p = new NativePointer(s)  // or ptr(s)
2// s: decimal or "0x..." hex string
3NULL  // shorthand for ptr("0")

Arithmetic:

Pointer Authentication (AArch64 PAC):

Read/Write:

All read/write methods throw JS exception on inaccessible memory (except readVolatile/writeVolatile).

ArrayBuffer

NativeFunction

1new NativeFunction(address, returnType, argTypes[, abi])
2new NativeFunction(address, returnType, argTypes[, options])

Supported types: void, pointer, int, uint, long, ulong, char, uchar, size_t, ssize_t, float, double, int8–int64, uint8–uint64, bool

Structs by value: use array of field types: ['int', 'int', 'int']. Nestable. C++ classes with vtables: first field is pointer to vtable.

Supported ABIs:

Options object:

Variadic functions: add '...' between fixed and variadic args in argTypes.

NativeCallback

1new NativeCallback(func, returnType, argTypes[, abi])

Creates a native-callable JS function. Returns a NativePointer. When used with Interceptor.replace(), func receives this bound to the same invocation object as Interceptor.attach().

SystemFunction

1new SystemFunction(address, returnType, argTypes[, abi|options])

Like NativeFunction but return value is { value, errno } (UNIX) or { value, lastError } (Windows).

Network

Socket

SocketListener

All methods async (return Promise).

SocketConnection

Inherits from IOStream. All methods async.

File and Stream

File

IOStream / InputStream / OutputStream

All methods async (return Promise).

IOStream:

• input: InputStream
• output: OutputStream
• close(): close both streams

InputStream:

• close(), read(size) → ArrayBuffer (empty = EOF), readAll(size) → ArrayBuffer (exact size, rejects on premature EOF with partialData)

OutputStream:

• close(), write(data) → number of bytes written, writeAll(data) (rejects with partialSize), writeMemoryRegion(address, size) → bytes written

Platform-specific Streams

Database

SqliteDatabase

SqliteStatement

1const db = SqliteDatabase.open('/path/to/people.db');
2const smt = db.prepare('SELECT name FROM people WHERE age = ?');
3smt.bindInteger(1, 42);
4let row;
5while ((row = smt.step()) !== null) console.log(row[0]);
6smt.reset();

Instrumentation

Interceptor

callbacks object:

Both callbacks can also be NativePointer values pointing to C functions (from CModule) with signatures:

• void onEnter(GumInvocationContext *ic)
• void onLeave(GumInvocationContext *ic)

this inside callbacks:

this is thread-local per invocation — use it to pass data between onEnter and onLeave.

Performance notes:

• Omit unused callbacks (onEnter/onLeave) — each adds overhead (~6µs for onEnter alone, ~11µs for both on iPhone 5S)
• For hot functions, implement callbacks in C via CModule
• Batch multiple values into a single send() call for high-frequency hooks

 1// Basic attach
 2Interceptor.attach(Module.getGlobalExportByName('read'), {
 3  onEnter(args) {
 4    this.fd = args[0].toInt32();
 5    this.buf = args[1];
 6    this.count = args[2].toInt32();
 7  },
 8  onLeave(retval) {
 9    const n = retval.toInt32();
10    if (n > 0) console.log(hexdump(this.buf, { length: n }));
11  }
12});
13
14// Replace function
15const openPtr = Module.getGlobalExportByName('open');
16const open = new NativeFunction(openPtr, 'int', ['pointer', 'int']);
17Interceptor.replace(openPtr, new NativeCallback((pathPtr, flags) => {
18  console.log('Opening:', pathPtr.readUtf8String());
19  return open(pathPtr, flags);
20}, 'int', ['pointer', 'int']));

Stalker

Per-thread code tracing engine. Instruments basic blocks by copying them to RWX slabs.

follow() options:

 1Stalker.follow(threadId, {
 2  events: {
 3    call: true,    // CALL instructions
 4    ret: false,    // RET instructions
 5    exec: false,   // all instructions (high volume)
 6    block: false,  // block executed (coarse)
 7    compile: false // block compiled (coverage)
 8  },
 9  // Choose ONE of:
10  onReceive(events) { /* raw GumEvent binary blob */ },
11  onCallSummary(summary) { /* { address: callCount } */ },
12
13  // Optional transformer (rewrite basic blocks):
14  transform(iterator) {
15    let insn;
16    while ((insn = iterator.next()) !== null) {
17      // inspect insn.mnemonic, insn.address, etc.
18      iterator.keep(); // emit instruction (drop by not calling keep())
19    }
20  },
21  // C transformer for performance:
22  // transform: cm.transform,
23  // onEvent: cm.process,
24  // data: ptr(1337)
25});

Performance: Use onCallSummary instead of onReceive when only call counts are needed. Use CModule for transform/onEvent callbacks in hot paths.

ObjC

Frida 17+: No longer bundled in GumJS. Install: npm install frida-objc-bridge and import ObjC from 'frida-objc-bridge'. REPL and frida-trace still include it automatically.

Prerequisite: check ObjC.available before using any ObjC API.

ObjC.Object special properties:

 1// Hook ObjC method
 2const { NSSound } = ObjC.classes;
 3Interceptor.attach(NSSound.play.implementation, {
 4  onEnter() { send('[NSSound play]'); }
 5});
 6
 7// Replace implementation
 8const oldImpl = NSSound.play.implementation;
 9NSSound.play.implementation = ObjC.implement(NSSound.play, (handle, sel) => {
10  return oldImpl(handle, sel);
11});
12
13// Intercept block argument
14Interceptor.attach(someMethod, {
15  onEnter(args) {
16    const block = new ObjC.Block(args[4]);
17    const orig = block.implementation;
18    block.implementation = (err, val) => {
19      console.log('block called', err, val);
20      return orig(err, val);
21    };
22  }
23});

Java

Frida 17+: No longer bundled. Install: npm install frida-java-bridge and import Java from 'frida-java-bridge'. REPL and frida-trace still include it automatically.

Prerequisite: check Java.available before using any Java API.

Method flag constants: ACC_PUBLIC, ACC_PRIVATE, ACC_PROTECTED, ACC_STATIC, ACC_FINAL, ACC_SYNCHRONIZED, ACC_NATIVE, ACC_ABSTRACT, etc.

 1// Hook Android method
 2Java.perform(() => {
 3  const Activity = Java.use('android.app.Activity');
 4  Activity.onResume.implementation = function() {
 5    send('onResume called');
 6    this.onResume();
 7  };
 8});
 9
10// SSL pinning bypass pattern
11Java.perform(() => {
12  const X509TrustManager = Java.use('javax.net.ssl.X509TrustManager');
13  const MyTM = Java.registerClass({
14    name: 'com.example.MyTM',
15    implements: [X509TrustManager],
16    methods: {
17      checkClientTrusted(chain, authType) {},
18      checkServerTrusted(chain, authType) {},
19      getAcceptedIssuers() { return []; }
20    }
21  });
22});

CPU Instruction

Instruction

1const insn = Instruction.parse(target);  // target: NativePointer

Fields: address, next (NativePointer to next insn), size, mnemonic, opStr, operands, regsRead, regsWritten, groups, toString()

On 32-bit ARM: LSB=0 for ARM, 1 for Thumb.

Writer Classes

All writers share this interface:

X86Writer — also: putCallAddressWithArguments, putCallReg, putJmpAddress, putJmpReg, putJccShortLabel, putJccNearLabel, putMovRegReg, putMovRegU32, putMovRegU64, putAddRegImm, putSubRegImm, putPushReg, putPopReg, putRet, putLeave, putCmpRegI32, putTestRegReg, putXchgRegRegPtr, putLockXaddRegPtrReg, putFxsaveRegPtr, putU8, putS8

ArmWriter — also: putBImm, putBLabel, putBlImm, putBlxImm, putBxReg, putLdrRegAddress, putLdrRegU32, putStrRegReg, putMovRegReg, putAddRegRegImm, putSubRegRegImm, putVpushRange, putVpopRange, putInstruction

ThumbWriter — also: putBImm, putBlImm, putBlxImm, putBxReg, putCbzRegLabel, putCbnzRegLabel, putPushRegs, putPopRegs, putLdrRegAddress, putStrRegReg, putMovRegReg, putAddRegImm, putSubRegImm, putInstruction, putInstructionWide, commitLabel

Arm64Writer — also: putBImm, putBLabel, putBCondLabel, putBlImm, putBlrReg, putBrReg, putBrRegNoAuth, putBlrRegNoAuth, putRetReg, putCbzRegLabel, putCbnzRegLabel, putTbzRegImmLabel, putLdrRegAddress, putLdrRegU64, putLdrRegRef/putLdrRegValue, putAdrpRegAddress, putStrRegReg, putLdpRegRegRegOffset, putStpRegRegRegOffset, putMovRegReg, putAddRegRegImm, putSubRegRegImm, putXpaciReg, sign(value), putMrs

MipsWriter — also: putJAddress, putJrReg, putJalAddress, putBeqRegRegLabel, putLaRegAddress, putLwRegRegOffset, putSwRegRegOffset, putMoveRegReg, putAdduRegRegReg, putInstruction

Relocator Classes

1new XxxRelocator(inputCode, output)
2// inputCode: NativePointer; output: corresponding XxxWriter

ThumbRelocator also has copyOne().

Enum Types

x86 Register: xax xcx xdx xbx xsp xbp xsi xdi eax ecx … rax rcx … r8-r15 eip rip x86 InstructionId: jo jno jb jae je jne jbe ja js jns jp jnp jl jge jle jg jcxz jecxz jrcxz x86 BranchHint: no-hint likely unlikely x86 PointerTarget: byte dword qword

ARM Register: r0-r15 sp lr sb sl fp ip pc s0-s31 d0-d31 q0-q15 ARM ConditionCode: eq ne hs lo mi pl vs vc hi ls ge lt gt le al ARM Shifter: asr lsl lsr ror rrx asr-reg lsl-reg lsr-reg ror-reg rrx-reg

AArch64 Register: x0-x30 w0-w30 sp lr fp wsp wzr xzr nzcv ip0 ip1 s0-s31 d0-d31 q0-q31 AArch64 ConditionCode: eq ne hs lo mi pl vs vc hi ls ge lt gt le al nv AArch64 IndexMode: post-adjust signed-offset pre-adjust

MIPS Register: v0 v1 a0-a3 t0-t9 s0-s8 k0 k1 gp sp fp ra hi lo zero at 0-31

Others

Console

1console.log(line)    // stdout
2console.warn(line)   // stderr
3console.error(line)  // stderr

ArrayBuffer arguments are auto-formatted via hexdump().

Hexdump

1hexdump(target[, options])
2// target: ArrayBuffer or NativePointer
3// options: { offset: 0, length: 64, header: true, ansi: false, address: ptr('0x...') }

Shorthand

Communication (send/recv/rpc)

1// Agent side
2rpc.exports = {
3  add(a, b) { return a + b; },
4  sub(a, b) { return new Promise(r => setTimeout(() => r(a - b), 100)); }
5};
6
7// Host side (Python)
8print(script.exports.add(2, 3))   # 5
9print(script.exports.sub(5, 3))   # 2

Timing Events

Garbage Collection

1gc()  // Force GC. Useful for testing Script.bindWeak() logic.

Worker

Isolated JS heap/lock for background processing.

1const w = new Worker(url[, { onMessage }]);
2w.post(message[, data]);   // send to worker (use recv() inside)
3w.exports.method();        // call rpc.exports defined by worker → Promise
4w.terminate();

Cloak

Hide Frida’s resources from introspection APIs (Process.enumerateThreads(), etc.). Frida’s own resources are cloaked automatically.

Profiler

Worst-case profiler built on Interceptor. Tracks maximum time per function call.

1const profiler = new Profiler();
2profiler.instrument(functionAddress, sampler[, { describe(args) }]);
3// describe: called on new worst-case; return string describing args
4const xml = profiler.generateReport();

Samplers

All samplers have sample() → bigint.