Reference: Script

Global

• ptr(s): short-hand for new NativePointer(s)

• send(message[, data]): send the JavaScript object message to the debugger (it must be serializable to JSON). data may be optionally passed to include a raw payload, like a buffer returned by Memory#readByteArray

• recv([type, ], callback): request callback to be called on the next message received from the debugger. Optionally type may be specified to only receive a message where the 'type' field is set to type. This will only give you one message, so you need to call recv() again to receive the next one.

• setTimeout(fn, delay): call fn after delay milliseconds, returns an id that can be passed to clearTimeout to cancel it

• clearTimeout(id): cancel id returned by call to setTimeout

• setInterval(fn, delay): call fn every delay milliseconds, returns an id that can be passed to clearInterval to cancel it

• clearInterval(id): cancel id returned by call to setInterval

console

• log(line): write line to stdout

Process

• arch: read-only property containing the string: 'ia32', 'x64' or 'arm'
• platform: read-only property containing the string: 'linux', 'darwin', 'windows'
• getCurrentThreadId(): get this thread''s OS-specific id as a JavaScript number
• enumerateThreads(callbacks): enumerate threads alive right now, where callbacks is an object specifying: 'onMatch': function onMatch(thread): called with thread specifying: 'id': property specifying OS-specific id as a JavaScript number 'state': property containing the string: 'running', 'stopped', 'waiting', 'uninterruptible' or 'halted' 'registers': property containing an object with the keys 'pc' and 'sp', which are NativePointer objects specifying EIP/RIP/PC and ESP/RSP/SP, respectively, for ia32/x64/arm. This function may return the string 'stop' to cancel the enumeration early. 'onComplete': function onComplete(): called when all threads have been enumerated
• enumerateModules(callbacks): enumerate modules loaded right now, where callbacks is an object specifying: 'onMatch': function onMatch(name, address, path): called with name specifying the canonical module name as a string, address containing base address as a NativePointer, and path with the full filesystem path as a string This function may return the string 'stop' to cancel the enumeration early. 'onComplete': function onComplete(): called when all modules have been enumerated
• enumerateRanges(protection, callbacks): enumerate memory ranges satisfying protection given as a string of the form: 'rwx', where 'rw-' means "must be at least readable and writable". callbacks is an object specifying: 'onMatch': function onMatch(address, size, protection): called with address containing base address as a NativePointer, size specifying the size as a JavaScript number, and protection as a protection string (see above). This function may return the string 'stop' to cancel the enumeration early. 'onComplete': function onComplete(): called when all memory ranges have been enumerated

Module

• enumerateExports(name, callbacks): enumerate exports of module with the name as seen in Process#enumerateModules. callbacks is an object specifying: 'onMatch': function onMatch(name, address): called with name specifying the export name as a string and address containing its absolute address as a NativePointer This function may return the string 'stop' to cancel the enumeration early. 'onComplete': function onComplete(): called when all exports have been enumerated
• enumerateRanges(name, protection, callbacks): just like Process#enumerateRanges, except it''s scoped to the specified module name.
• findBaseAddress(name): returns the base address of the name module, or null if module isn''t loaded
• findExportByName(module, export): returns the absolute address of export in module

Memory

• scan(address, size, pattern, callbacks): scan memory for occurences of pattern in the memory range given by address and size. pattern must be of the form "13 37 ?? ff" to match 0x13 followed by 0x37 followed by any byte followed by 0xff. callbacks is an object with: 'onMatch': function onMatch(address, size): called with address containing address of occurence as a NativePointer and size specifying the size as a JavaScript number. This function may return the string 'stop' to cancel the memory scanning early. 'onError': function onError(reason): called with reason when there was a memory access error while scanning 'onComplete': function onComplete(): called when the memory range has been fully scanned
• alloc(size): allocate size bytes of memory on the heap. The returned object is a NativePointer and the heap memory will be released when all JavaScript handles to it are gone. This means you need to keep a reference to it while the pointer is being used by code outside the JavaScript runtime.
• readPointer(address): read a pointer from address and return it as a NativePointer A JavaScript exception will be thrown if address is invalid (not readable).
• writePointer(address, ptr): write ptr to address A JavaScript exception will be thrown if address is invalid (not writable).
• readS8(address), readU8(address), readS16(address), readU16(address), readS32(address), readU32(address), readS64(address), readU64(address): read a signed or unsigned 8/16/32/64 bit value from address and return it as a JavaScript number. A JavaScript exception will be thrown if address is invalid (not readable).
• writeU8(address, value): write the JavaScript number value to the byte at address. A JavaScript exception will be thrown if address is invalid (not writable).
• readByteArray(address, length): read length bytes from address and return it as a byte array. This byte array may be efficiently transferred to the debugger by passing it as the second argument to send(). A JavaScript exception will be thrown if any of the length bytes read from address isn''t readable.
• readUtf8String(address[, size = -1]), readUtf16String(address[, size = -1]), readAnsiString(address[, size = -1]): read the bytes at address as a UTF-8 string. Supply the optional size if you know the size of the string in bytes, or omit it or specify -1 if the string is NUL-terminated. A JavaScript exception will be thrown if any of the size bytes read from address isn''t readable.
• writeUtf8String(address, str): encode and write the JavaScript string to address (with NUL-terminator). A JavaScript exception will be thrown if any of the bytes written to address isn''t writable.
• allocUtf8String(str), allocUtf16String(str), allocAnsiString(str): allocate, encode and write out str as UTF-8/UTF-16/ANSI string on the heap. The returned object is a NativePointer, see Memory#alloc for details about its lifetime.

Thread

• sleep(delay): suspend execution of the current thread for delay seconds specified as a JavaScript number. For example 0.05 to sleep for 50 ms.

NativePointer

• constructor(s): create a new NativePointer from the string s containing a memory address in either decimal or hexadecimal if prefixed with "0x"

• add(rhs): make a new NativePointer with this NativePointer plus rhs. rhs may either be a JavaScript number or another NativePointer
• sub(rhs): make a new NativePointer with this NativePointer minus rhs. rhs may either be a JavaScript number or another NativePointer
• toInt32(): cast this NativePointer to a signed 32-bit integer
• toString([radix = 10]): convert to a string of optional radix (defaults to 10)

NativeFunction

• constructor(address, returnType, argTypes[, abi]): create a new NativeFunction from address specified with a NativePointer, return type and array of argument types, optionally also specifying the abi if not system default

Supported types:

• void
• pointer
• int
• uint
• long
• ulong
• char
• uchar
• float
• double
• int8
• uint8
• int16
• uint16
• int32
• uint32
• int64
• uint64

Supported ABIs: all platforms:

• default

Windows 32-bit:

• sysv
• stdcall
• thiscall
• fastcall
• mscdecl

Windows 64-bit:

• win64

UNIX x86:

• sysv
• unix64

UNIX ARM:

• sysv
• vfp

Socket

• type(handle): inspect the OS socket handle and return its type as a string which is either 'tcp', 'udp', 'tcp6', 'udp6', 'unix:stream', 'unix:dgram', or null if invalid or unknown.
• localAddress(handle), peerAddress(handle): inspect the OS socket handle and return its local or peer address, or null if invalid or unknown. The address object returned has the fields: 'ip' (IP sockets) The IP address as a string. 'port' (IP sockets) The port number as a JavaScript number. 'path' (UNIX sockets) The UNIX path as a string.

Interceptor

• attach(address, callbacks): Intercept calls to function at address, where callbacks is an object containing one or more of: 'onEnter': function onEnter(args): callback function given one argument args that can be used to read or write arguments as an array of NativePointer objects. 'onLeave': function onLeave(retval): callback function given one argument retval that is a NativePointer containing the return value Note that these functions will be invoked with this bound to a per-invocation (thread-local) object where you can store arbitrary data, which is useful if you want to read an argument onEnter and act on it in onLeave. For example: Interceptor.attach(readImpl, { onEnter: function onEnter(args) { this.fileDescriptor = args[0].toInt32(); }, onLeave: function onLeave(retval) { if (retval.toInt32() > 0) { /* do something with this.fileDescriptor */ } } });

Stalker

• follow([threadId,] callbacks): start stalking threadId (or the current thread if omitted), and provide feedback through callbacks: 'onReceive': function onReceive(events): called with events containing an array of events. This is currently hard-coded to generate an event per CALL instruction only.
• unfollow([threadId]): stop stalking threadId (or the current thread if omitted).
• garbageCollect(): free accumulated memory at a safe point after Stalker#unfollow. This is needed to avoid race-conditions where the thread just unfollowed is executing its last instructions.
• addCallProbe(address, callback): call callback (see Interceptor#attach#onEnter for signature) synchronously when a CALL is made to address. Returns an id that can be passed to Stalker#removeCallProbe later.
• removeCallProbe: Remove a call probe added by Stalker#addCallProbe.