diff --git a/types/frida-gum/index.d.ts b/types/frida-gum/index.d.ts index a6aa02f962..540135c7a6 100644 --- a/types/frida-gum/index.d.ts +++ b/types/frida-gum/index.d.ts @@ -1,4 +1,4 @@ -// Type definitions for non-npm package frida-gum 14.1 +// Type definitions for non-npm package frida-gum 14.2 // Project: https://github.com/frida/frida // Definitions by: Ole André Vadla Ravnås // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped @@ -660,6 +660,18 @@ declare namespace Memory { function patchCode(address: NativePointerValue, size: number | UInt64, apply: MemoryPatchApplyCallback): void; } +interface MemoryRange { + /** + * Base address. + */ + base: NativePointer; + + /** + * Size in bytes. + */ + size: number; +} + /** * Monitors one or more memory ranges for access, and notifies on the first * access of each contained memory page. @@ -2268,8 +2280,14 @@ declare namespace Interceptor { * Intercepts calls to function/instruction at `target`. It is important * to specify a `InstructionProbeCallback` if `target` is not the first * instruction of a function. + * + * @param target Address of function/instruction to intercept. + * @param callbacksOrProbe Callbacks or instruction-level probe callback. + * @param data User data exposed to `NativeInvocationListenerCallbacks` + * through the `GumInvocationContext *`. */ - function attach(target: NativePointerValue, callbacksOrProbe: InvocationListenerCallbacks | InstructionProbeCallback): InvocationListener; + function attach(target: NativePointerValue, callbacksOrProbe: InvocationListenerCallbacks | InstructionProbeCallback, + data?: NativePointerValue): InvocationListener; /** * Detaches all previously attached listeners. @@ -2278,8 +2296,17 @@ declare namespace Interceptor { /** * Replaces function at `target` with implementation at `replacement`. + * + * May be implemented using e.g. `NativeCallback` or `CModule`. + * + * @param target Address of function to replace. + * @param replacement Replacement implementation. + * @param data User data exposed to native replacement through the + * `GumInvocationContext *`, obtained using + * `gum_interceptor_get_current_invocation()`. */ - function replace(target: NativePointerValue, replacement: NativePointerValue): void; + function replace(target: NativePointerValue, replacement: NativePointerValue, + data?: NativePointerValue): void; /** * Reverts the previously replaced function at `target`. @@ -2297,11 +2324,40 @@ declare class InvocationListener { /** * Callbacks to invoke synchronously before and after a function call. */ -interface InvocationListenerCallbacks { +type InvocationListenerCallbacks = ScriptInvocationListenerCallbacks | NativeInvocationListenerCallbacks; + +interface ScriptInvocationListenerCallbacks { + /** + * Called synchronously when a thread is about to enter the target function. + */ onEnter?: (this: InvocationContext, args: InvocationArguments) => void; + + /** + * Called synchronously when a thread is about to leave the target function. + */ onLeave?: (this: InvocationContext, retval: InvocationReturnValue) => void; } +interface NativeInvocationListenerCallbacks { + /** + * Called synchronously when a thread is about to enter the target function. + * + * Typically implemented using `CModule`. + * + * Signature: `void onEnter (GumInvocationContext * ic)` + */ + onEnter?: NativePointer; + + /** + * Called synchronously when a thread is about to leave the target function. + * + * Typically implemented using `CModule`. + * + * Signature: `void onLeave (GumInvocationContext * ic)` + */ + onLeave?: NativePointer; +} + /** * Callback to invoke when an instruction is about to be executed. */ @@ -2369,6 +2425,19 @@ interface UnixInvocationContext extends PortableInvocationContext { * Follows execution on a per thread basis. */ declare namespace Stalker { + /** + * Marks a memory range as excluded. This means Stalker will not follow + * execution when encountering a call to an instruction in such a range. + * You will thus be able to observe/modify the arguments going in, and + * the return value coming back, but won't see the instructions that + * happened between. + * + * Useful to improve performance and reduce noise. + * + * @param range Range to exclude. + */ + function exclude(range: MemoryRange): void; + /** * Starts following the execution of a given thread. * @@ -2408,14 +2477,16 @@ declare namespace Stalker { function garbageCollect(): void; /** - * Calls `callback` synchronously when a `CALL` is made to `address`. + * Calls `callback` synchronously when a call is made to `address`. * Returns an id that can be passed to `removeCallProbe()` later. * * @param address Address of function to monitor stalked calls to. * @param callback Function to be called synchronously when a stalked * thread is about to call the function at `address`. + * @param data User data to be passed to `StalkerNativeCallProbeCallback`. */ - function addCallProbe(address: NativePointerValue, callback: StalkerCallProbeCallback): StalkerCallProbeId; + function addCallProbe(address: NativePointerValue, callback: StalkerCallProbeCallback, + data?: NativePointerValue): StalkerCallProbeId; /** * Removes a call probe added by `addCallProbe()`. @@ -2526,6 +2597,11 @@ interface StalkerOptions { * by the stalked thread. */ transform?: StalkerTransformCallback; + + /** + * User data to be passed to `StalkerNativeTransformCallback`. + */ + data?: NativePointerValue; } interface StalkerParseOptions { @@ -2546,7 +2622,19 @@ interface StalkerCallSummary { [target: string]: number; } -type StalkerCallProbeCallback = (args: InvocationArguments) => void; +type StalkerCallProbeCallback = StalkerScriptCallProbeCallback | StalkerNativeCallProbeCallback; + +/** + * Called synchronously when a call is made to the given address. + */ +type StalkerScriptCallProbeCallback = (args: InvocationArguments) => void; + +/** + * Called synchronously when a call is made to the given address. + * + * Signature: `void onCall (GumCallSite * site, gpointer user_data)` + */ +type StalkerNativeCallProbeCallback = NativePointer; type StalkerCallProbeId = number; @@ -2578,24 +2666,41 @@ type StalkerBlockEventBare = [ NativePointer | string, NativePointer | type StalkerCompileEventFull = [ "compile", NativePointer | string, NativePointer | string ]; type StalkerCompileEventBare = [ NativePointer | string, NativePointer | string ]; -type StalkerTransformCallback = StalkerX86TransformCallback | StalkerArm64TransformCallback; +type StalkerTransformCallback = + | StalkerX86TransformCallback + | StalkerArm64TransformCallback + | StalkerNativeTransformCallback + ; type StalkerX86TransformCallback = (iterator: StalkerX86Iterator) => void; + type StalkerArm64TransformCallback = (iterator: StalkerArm64Iterator) => void; +/** + * Signature: `void transform (GumStalkerIterator * iterator, GumStalkerWriter * output, gpointer user_data)` + */ +type StalkerNativeTransformCallback = NativePointer; + declare abstract class StalkerX86Iterator extends X86Writer { next(): X86Instruction | null; keep(): void; - putCallout(callout: StalkerCallout): void; + putCallout(callout: StalkerCallout, data?: NativePointerValue): void; } declare abstract class StalkerArm64Iterator extends Arm64Writer { next(): Arm64Instruction | null; keep(): void; - putCallout(callout: StalkerCallout): void; + putCallout(callout: StalkerCallout, data?: NativePointerValue): void; } -type StalkerCallout = (context: CpuContext) => void; +type StalkerCallout = StalkerScriptCallout | StalkerNativeCallout; + +type StalkerScriptCallout = (context: CpuContext) => void; + +/** + * Signature: `void onAesEnc (GumCpuContext * cpu_context, gpointer user_data)` + */ +type StalkerNativeCallout = NativePointer; /** * Provides efficient API resolving using globs, allowing you to quickly @@ -2731,6 +2836,54 @@ declare class DebugSymbol { toString(): string; } +/** + * Compiles C source code to machine code, straight to memory. + * + * Useful for implementing hot callbacks, e.g. for `Interceptor` and `Stalker`, + * but also useful when needing to start new threads in order to call functions + * in a tight loop, e.g. for fuzzing purposes. + * + * Global functions are automatically exported as `NativePointer` properties + * named exactly like in the C source code. This means you can pass them to + * `Interceptor` and `Stalker`, or call them using `NativeFunction`. + * + * Symbols can also be plugged in at creation, e.g. memory allocated using + * `Memory.alloc()`, or `NativeCallback` for receiving callbacks from the C + * module. + * + * To perform initialization and cleanup, you may define functions with the + * following names and signatures: + * + * `void init (void)` + * `void finalize (void)` + * + * Note that all data is read-only, so writable globals should be declared + * `extern`, allocated using e.g. `Memory.alloc()`, and passed in as symbols + * through the constructor's second argument. + */ +declare class CModule { + /** + * Creates a new C module by compiling the provided C source code to machine + * code, straight to memory. + * + * @param source C source code to compile. + * @param symbols Symbols to expose to the C module. Declare them as `extern`. + */ + constructor(source: string, symbols?: CSymbols); + + /** + * Eagerly unmaps the module from memory. Useful for short-lived modules + * when waiting for a future garbage collection isn't desirable. + */ + dispose(): void; + + readonly [name: string]: any; +} + +interface CSymbols { + [name: string]: NativePointerValue; +} + declare class Instruction { /** * Parses the instruction at the `target` address in memory.