@zsa233/frida-analykit-agent 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ZSA233
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @zsa233/frida-analykit-agent
+
+Runtime helpers for custom Frida agents used by `frida-analykit`.
+
+This package is designed to be consumed by `frida-compile` projects generated through `frida-analykit gen dev`.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@zsa233/frida-analykit-agent",
+  "version": "2.0.0",
+  "description": "Frida agent runtime for frida-analykit",
+  "keywords": [
+    "frida",
+    "reverse-engineering",
+    "instrumentation",
+    "typescript"
+  ],
+  "homepage": "https://github.com/ZSA233/frida-analykit#readme",
+  "bugs": {
+    "url": "https://github.com/ZSA233/frida-analykit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZSA233/frida-analykit.git",
+    "directory": "packages/frida-analykit-agent"
+  },
+  "type": "module",
+  "files": [
+    "src/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./rpc": "./src/rpc.ts",
+    "./*": "./src/*.ts"
+  },
+  "scripts": {
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "frida-java-bridge": "^7.0.8"
+  },
+  "devDependencies": {
+    "@types/frida-gum": "^18.7.2",
+    "typescript": "^5.8.3"
+  }
+}

package/src/api/android.ts

@@ -0,0 +1,80 @@
+
+
+
+export type NP = NativePointer
+
+
+export interface EnvJvmti {
+    handle: NP
+    vm: NP,
+    vtable: NP
+}
+
+
+
+// frida-java-bridge/lib/android.js
+export interface VMApi {
+    vm: NP
+    
+    module: Module
+
+    flavor: 'art' | 'dalvik'
+
+    addLocalRefrence: null
+
+    find(name: string): NativePointer, // export => symbol => null
+
+    artRuntime: NativePointer
+
+    artClassLinker: {
+        address: NativePointer,
+        quickResolutionTrampoline: NativePointer,
+        quickImtConflictTrampoline: NativePointer,
+        quickGenericJniTrampoline: NativePointer,
+        quickToInterpreterBridgeTrampoline: NativePointer,
+    }
+
+    jvmti: EnvJvmti
+
+    $new(size: number): NativePointer
+    $delete(pointer: NativePointer): void
+
+    // jint JNI_GetCreatedJavaVMs(JavaVM** vmBuf, jsize bufLen, jsize* nVMs);
+    JNI_GetCreateJavaVMs(vmBuf: NP, bufLen: number, nVMs: NP): number
+
+    // jobject JavaVMExt::AddGlobalRef(Thread* self, ObjPtr<mirror::Object> obj)
+    ['art::JavaVMExt::AddGlobalRef']: (vm: NP, self: NP, obj: NP) => NP
+
+    // void ReaderWriterMutex::ExclusiveLock(Thread* self)
+    ['art::ReaderWriterMutex::ExclusiveLock']: (lock: NP, self: NP) => void
+
+    // IndirectRef IndirectReferenceTable::Add(IRTSegmentState previous_state, ObjPtr<mirror:: Object> obj, std::string * error_msg)
+    ['art::IndirectReferenceTable::Add']: (table: NP, previous_state: NP, obj: number, error_msg: NP) => NP
+
+    // ObjPtr<mirror::Object> JavaVMExt::DecodeGlobal(IndirectRef ref)
+    // thread: 7 > Android >= 6
+    ['art::JavaVMExt::DecodeGlobal']: (vm: NP, thread: NP, ref: NP) => NP
+
+    // ObjPtr<mirror::Object> Thread::DecodeJObject(jobject obj) const
+    ['art::Thread::DecodeJObject']: (thread: NP, obj: NP) => NP
+
+
+    // TODO: 
+}
+
+
+
+
+declare global {
+    namespace Java {
+        const api: VMApi,
+        Env: {
+            handle: NativePointer
+            vm: Java.VM & {
+                handle: NativePointer
+            }
+            throwIfExceptionPending(): Error
+        }
+    }
+
+}

package/src/bridges.ts

@@ -0,0 +1,18 @@
+import JavaBridge from "frida-java-bridge";
+
+type BridgeGlobals = typeof globalThis & {
+    Java?: typeof JavaBridge;
+    ObjC?: unknown;
+    Swift?: unknown;
+    __FRIDA_ANALYKIT_CONFIG__?: Record<string, unknown>;
+};
+
+const globals = globalThis as BridgeGlobals;
+
+export const Java = globals.Java ?? JavaBridge;
+export const ObjC = globals.ObjC;
+export const Swift = globals.Swift;
+
+if (!("Java" in globals)) {
+    globals.Java = Java;
+}

package/src/cmodule/scan_adrp.c

@@ -0,0 +1,81 @@
+#include <glib.h>
+#include <gum/gummemory.h>
+#include <gum/gumdefs.h>
+
+#define PAGE_SIZE 0x1000
+#define GET_ADDR_PAGE(x) ((uintptr_t)(x) & ~(PAGE_SIZE - 1))
+#define ADRP_IMM_LEN_MASK 0x1fffff
+#define ADRP_FIXED28_24_BITSET_MASK (0b10000 << 24)
+#define ADRP_PAGE_INSTR_MASK 0x9fffffe0
+
+typedef struct _MemoryScanRes MemoryScanRes;
+typedef struct _ScanUserData ScanUserData;
+
+static gboolean on_match_fuzzy_adrp(GumAddress address, gsize size, gpointer user_data);
+
+struct _ScanUserData
+{
+    gpointer target_address;
+    gint align_offset;
+};
+
+
+struct _MemoryScanRes 
+{
+    GArray *results;
+    ScanUserData *user_data;
+};
+
+void _dispose(const MemoryScanRes *res)
+{
+    g_array_free(res->results, TRUE);
+}
+
+static gboolean on_match_fuzzy_adrp(GumAddress address, gsize size, gpointer user_data)
+{
+    MemoryScanRes *scan_res = (MemoryScanRes *)user_data;
+    const guintptr target_page = (guintptr)GET_ADDR_PAGE(scan_res->user_data->target_address);
+    const guintptr align_offset = (guintptr)scan_res->user_data->align_offset;
+    const guintptr addr_val = (guintptr)address - align_offset;
+    const gpointer pc_addr = (gpointer)addr_val;
+    
+    // 4字节指令对齐
+    if ((addr_val & (sizeof(guint32) - 1)) != 0)
+        return TRUE;
+    
+    // 按pc页差进行匹配
+    const guintptr pc_page = (guintptr)GET_ADDR_PAGE(address);
+    const guint32 page_delta = (guint32)((target_page - pc_page) >> 12) & ADRP_IMM_LEN_MASK;
+    const guint32 immlo = page_delta & 0b11;
+    const guint32 immhi = page_delta >> 2;
+    const guint32 op = 0x1;
+    const guint32 adrp_sign =
+        (op << 31) | 
+        (immlo << 29) | 
+        ADRP_FIXED28_24_BITSET_MASK | 
+        (immhi << 5);
+
+    if (((*(guint32 *)pc_addr) & ADRP_PAGE_INSTR_MASK) != (adrp_sign & ADRP_PAGE_INSTR_MASK))
+        return TRUE;
+
+    g_array_append_val(scan_res->results, pc_addr);
+    return TRUE;
+}
+
+gpointer scan(const GumAddress base_address,
+               const gsize size,
+               const gchar *pattern_str,
+               MemoryScanRes *const scan_res)
+{
+    if (scan_res == NULL)
+        return NULL;
+
+    scan_res->results = g_array_new(FALSE, FALSE, sizeof(gpointer));
+
+    const GumMemoryRange range = {base_address, size};
+    const GumMatchPattern *pattern = gum_match_pattern_new_from_string(pattern_str);
+
+    gum_memory_scan(&range, pattern, on_match_fuzzy_adrp, scan_res);
+
+    return scan_res->results;
+}

package/src/cmodule/scan_adrp.ts

@@ -0,0 +1,118 @@
+
+import { nativeFunctionOptions } from "../consts.js"
+import { CMemoryScanRes } from "../utils/scan.js"
+
+
+const CM = new CModule(`
+#include <glib.h>
+#include <gum/gummemory.h>
+#include <gum/gumdefs.h>
+
+#define PAGE_SIZE 0x1000
+#define GET_ADDR_PAGE(x) ((uintptr_t)(x) & ~(PAGE_SIZE - 1))
+#define ADRP_IMM_LEN_MASK 0x1fffff
+#define ADRP_FIXED28_24_BITSET_MASK (0b10000 << 24)
+#define ADRP_PAGE_INSTR_MASK 0x9fffffe0
+
+typedef struct _MemoryScanRes MemoryScanRes;
+typedef struct _ScanUserData ScanUserData;
+
+static gboolean on_match_fuzzy_adrp(GumAddress address, gsize size, gpointer user_data);
+
+struct _ScanUserData
+{
+    gpointer target_address;
+    gint align_offset;
+};
+
+
+struct _MemoryScanRes 
+{
+    GArray *results;
+    ScanUserData *user_data;
+};
+
+void _dispose(const MemoryScanRes *res)
+{
+    g_array_free(res->results, TRUE);
+}
+
+static gboolean on_match_fuzzy_adrp(GumAddress address, gsize size, gpointer user_data)
+{
+    MemoryScanRes *scan_res = (MemoryScanRes *)user_data;
+    const guintptr target_page = (guintptr)GET_ADDR_PAGE(scan_res->user_data->target_address);
+    const guintptr align_offset = (guintptr)scan_res->user_data->align_offset;
+    const guintptr addr_val = (guintptr)address - align_offset;
+    const gpointer pc_addr = (gpointer)addr_val;
+    
+    // 4字节指令对齐
+    if ((addr_val & (sizeof(guint32) - 1)) != 0)
+        return TRUE;
+    
+    // 按pc页差进行匹配
+    const guintptr pc_page = (guintptr)GET_ADDR_PAGE(address);
+    const guint32 page_delta = (guint32)((target_page - pc_page) >> 12) & ADRP_IMM_LEN_MASK;
+    const guint32 immlo = page_delta & 0b11;
+    const guint32 immhi = page_delta >> 2;
+    const guint32 op = 0x1;
+    const guint32 adrp_sign =
+        (op << 31) | 
+        (immlo << 29) | 
+        ADRP_FIXED28_24_BITSET_MASK | 
+        (immhi << 5);
+
+    if (((*(guint32 *)pc_addr) & ADRP_PAGE_INSTR_MASK) != (adrp_sign & ADRP_PAGE_INSTR_MASK))
+        return TRUE;
+
+    g_array_append_val(scan_res->results, pc_addr);
+    return TRUE;
+}
+
+gpointer scan(const GumAddress base_address,
+               const gsize size,
+               const gchar *pattern_str,
+               MemoryScanRes *const scan_res)
+{
+    if (scan_res == NULL)
+        return NULL;
+
+    scan_res->results = g_array_new(FALSE, FALSE, sizeof(gpointer));
+
+    const GumMemoryRange range = {base_address, size};
+    const GumMatchPattern *pattern = gum_match_pattern_new_from_string(pattern_str);
+
+    gum_memory_scan(&range, pattern, on_match_fuzzy_adrp, scan_res);
+
+    return scan_res->results;
+}
+
+`)
+
+
+export class ScanAdrpCMod {
+    static readonly cm: CModule = CM
+
+    static readonly $scan = new NativeFunction(this.cm.scan, 'pointer', ['pointer', 'size_t', 'pointer', 'pointer'], nativeFunctionOptions)
+
+    static scan(scanRange: { base: NativePointer, size: number }, pattern: string, targetAddr: NativePointer, alignOffset: number) {
+        let matcheResults: NativePointer[] = []
+        
+        const userData = Memory.alloc(8 + 4)
+        userData.writePointer(targetAddr)
+        userData.add(8).writeU32(alignOffset)
+        
+        const scanRes = new CMemoryScanRes(userData)
+        const { base, size } = scanRange
+        this.$scan(
+            base, size, Memory.allocUtf8String(pattern), scanRes.$handle,
+        )
+        if (scanRes.data.length > 0) {
+            matcheResults = scanRes.data.toArray().map(v => v.readPointer())
+        }
+        this.$dispose(scanRes.$handle)
+        return matcheResults
+    }
+
+    static readonly $dispose = new NativeFunction(this.cm._dispose, 'void', ['pointer'], nativeFunctionOptions)
+}
+

package/src/config.ts

@@ -0,0 +1,56 @@
+type InjectedConfig = {
+    OnRPC?: boolean
+    OutputDir?: string
+    LogLevel?: number
+    LogCollapse?: boolean
+}
+
+const injectedConfig = ((globalThis as typeof globalThis & {
+    __FRIDA_ANALYKIT_CONFIG__?: InjectedConfig
+}).__FRIDA_ANALYKIT_CONFIG__) || {}
+
+export function setGlobalProperties(keyValues: { [key: string]: any }): void {
+    for (let [k, v] of Object.entries(keyValues)) {
+        if (k in globalThis) {
+            throw new Error(`global property[${k}] exists already`)
+        }
+        ;(globalThis as typeof globalThis & { [key: string]: unknown })[k] = v
+    }
+}
+
+
+export const LogLevel = {
+    DEBUG: 0,
+    INFO: 1,
+    WARN: 2,
+    ERROR: 3,
+    _MUST_LOG: 9999999,
+} as const
+
+export type LogLevel = (typeof LogLevel)[keyof typeof LogLevel]
+
+
+
+declare global {
+    const LogLevel: {
+        DEBUG: number
+        INFO: number
+        WARN: number
+        ERROR: number
+        _MUST_LOG: number
+    }
+}
+
+export class Config {
+    static OnRPC: boolean = injectedConfig.OnRPC ?? false
+    static OutputDir?: string = injectedConfig.OutputDir
+    static LogLevel: number = injectedConfig.LogLevel ?? LogLevel.INFO
+    static LogCollapse: boolean = injectedConfig.LogCollapse ?? true
+}
+
+
+
+setGlobalProperties({
+    'Config': Config,
+    'LogLevel': LogLevel,
+})

package/src/consts.ts

@@ -0,0 +1,31 @@
+
+
+
+
+export const nativeFunctionOptions: NativeABI | NativeFunctionOptions = {
+    exceptions: 'propagate',
+}
+
+
+
+
+export enum SYM_INFO_BIND {
+    STB_LOCAL = 0x0,
+    STB_GLOBAL = 0x1,
+    STB_WEAK = 0x2,
+    STB_GNU_UNIQUE = 0x3,
+}
+
+
+export enum SYM_INFO_TYPE {
+    STT_NOTYPE = 0x0,
+    STT_OBJECT = 0x1,
+    STT_FUNC = 0x2,
+    STT_SECTION = 0x3,
+    STT_FILE = 0x4,
+}
+
+export enum SYM_SHNDX {
+    SHN_UNDEF = 0,
+    SHN_ABS = 0xfff1,
+}

package/src/elf/insn.ts

@@ -0,0 +1,61 @@
+import { setGlobalProperties } from "../config.js"
+import { NativePointerObject } from "../helper.js"
+
+
+
+export class InstructionSequence extends NativePointerObject {
+    protected readonly entryInsn: Arm64Instruction
+    protected readonly insns: Arm64Instruction[] = []
+    protected eoi?: Arm64Instruction
+
+    constructor(entry: Arm64Instruction) {
+        const handle = entry.address
+        super(handle)
+        this.entryInsn = entry
+        this.insns = [entry]
+    }
+
+    static loadFromPointer<T extends InstructionSequence>(
+        this: new (insn: Arm64Instruction) => T,
+        handle: NativePointer
+    ): T {
+        const insn = Instruction.parse(handle) as Arm64Instruction
+        return new this(insn)
+    }
+
+    *[Symbol.iterator]() {
+        let insns = this.insns
+        let insn: Arm64Instruction = this.entryInsn
+        let inc = 0
+        const that = this
+
+        let value: Arm64Instruction | undefined
+
+        while (true) {
+            value = insns[inc]
+            if (value === undefined && that.eoi === undefined) {
+                try {
+                    insn = Instruction.parse(insns[inc - 1].next) as Arm64Instruction
+                    insns.push(insn)
+                } catch (error) {
+                    that.eoi = insn
+                    break
+                }
+            }
+            inc++
+            yield insn
+        }
+
+    }
+
+    clearCache() {
+        this.insns.length = 0
+    }
+
+
+}
+
+
+setGlobalProperties({
+    InstructionSequence,
+})