diff --git a/types/frida-gum/frida-gum-tests.ts b/types/frida-gum/frida-gum-tests.ts index 69552eca5788ff..cef1648fe4f8d9 100644 --- a/types/frida-gum/frida-gum-tests.ts +++ b/types/frida-gum/frida-gum-tests.ts @@ -173,6 +173,19 @@ Memory.scan(ptr("0x1234"), Process.pageSize, new MatchPattern("13 37"), { }, }); +// $ExpectType MemoryPointerMatch[] +Memory.findPointers({ base: ptr("0x1234"), size: Process.pageSize }, [ptr("0xdeadbeef")]); +// $ExpectType MemoryPointerMatch[] +const pointerMatches = Memory.findPointers( + [{ base: ptr("0x1234"), size: Process.pageSize }], + [ptr("0xdeadbeef")], + { mask: ptr("0x00007ffffffffff8") }, +); +// $ExpectType NativePointer +pointerMatches[0].address; +// $ExpectType NativePointer +pointerMatches[0].value; + // $ExpectType Module Process.mainModule; diff --git a/types/frida-gum/index.d.ts b/types/frida-gum/index.d.ts index 409d411bf964b2..c1ab65a6969cdd 100644 --- a/types/frida-gum/index.d.ts +++ b/types/frida-gum/index.d.ts @@ -757,6 +757,22 @@ declare namespace Memory { pattern: string | MatchPattern, ): MemoryScanMatch[]; + /** + * Scans one or more memory ranges for pointer-aligned words matching any of `values`. + * + * This is a focused, SIMD-accelerated alternative to `scan()` for the common task of finding pointers, e.g. + * references to a given address. All matches are collected and returned sorted by address. + * + * @param ranges Memory range, or array of ranges, to scan. + * @param values Pointer-width values to look for. + * @param options Options to customize the scan. + */ + function findPointers( + ranges: MemoryRange | MemoryRange[], + values: NativePointerValue[], + options?: MemoryFindPointersOptions, + ): MemoryPointerMatch[]; + /** * Allocates `size` bytes of memory on Frida's private heap, or, if `size` is a multiple of Process#pageSize, * one or more raw memory pages managed by the OS. The allocated memory will be released when the returned @@ -1461,6 +1477,26 @@ interface MemoryScanMatch { size: number; } +interface MemoryFindPointersOptions { + /** + * Bitmask applied to each scanned word and each value before comparing. Defaults to an exact match. + * Pass e.g. `ptr("0x00007ffffffffff8")` to strip arm64e PAC and non-pointer-isa bits. + */ + mask?: NativePointerValue; +} + +interface MemoryPointerMatch { + /** + * Memory address where a matching word was found. + */ + address: NativePointer; + + /** + * The matching word, i.e. the value stored at `address`, before masking. + */ + value: NativePointer; +} + interface KernelMemoryScanCallbacks { /** * Called with each occurence that was found. diff --git a/types/frida-gum/package.json b/types/frida-gum/package.json index 5c995206f43540..03cb651dcb1cf9 100644 --- a/types/frida-gum/package.json +++ b/types/frida-gum/package.json @@ -1,7 +1,7 @@ { "private": true, "name": "@types/frida-gum", - "version": "19.3.9999", + "version": "19.4.9999", "nonNpm": true, "nonNpmDescription": "frida-gum", "projects": [