frida-stalker-android

Frida Stalker（Android）

概述

当你需要在 Android 上使用 Frida 的 Stalker API 跟踪原生代码执行时，请使用此技能。它提供针对 ARM/ARM64 的模板，并采用兼顾性能的安全默认设置。

此技能基于 Frida 17+ 的 JavaScript 语义。

何时使用此技能

• 用户明确要求在 Android 上使用“Frida Stalker”。
• 你需要以较低开销衡量原生调用活动（调用了谁、调用了多少次）。
• 你需要有序的调用事件（重建调用图）或粗略的覆盖率。
• 你需要通过 transform(iterator) 在基本块编译时注入逻辑。

快速选择指南

• 需要统计每个目标的调用次数，不在意顺序：使用 onCallSummary。
• 需要有序的 call/ret/block/compile 事件：使用 onReceive，并通过 Stalker.parse() 解码。
• 需要指令级匹配和回调：使用 transform(iterator)（开销较大；应限制使用范围）。
• 需要监视少量调用目标：可以考虑使用 Stalker.addCallProbe()。

核心 API 事实（Frida 17+）

• Stalker.follow([threadId, options])
• 仅提供一个回调：onReceive(events) 或 onCallSummary(summary)。
• Stalker.unfollow([threadId])
• Stalker.parse(events, { annotate, stringify })
• Stalker.flush() 会提前排空缓冲的事件（否则，定期排空由 Stalker.queueDrainInterval 控制）。
• 应在 unfollow() 之后调用 Stalker.garbageCollect()，以便在安全时机释放累积的内存。
• Stalker.exclude({ base, size }) 会将一个内存范围排除在跟踪之外（适合跳过嘈杂模块或系统模块）。
• 调优：
• Stalker.trustThreshold 默认值为 1（设为 -1 表示不信任，设为 0 表示立即信任，或设为 N 表示在执行 N 次后信任）。
• Stalker.queueCapacity 默认值为 16384 个事件。
• Stalker.queueDrainInterval 默认值为 250 毫秒（设为 0 可禁用定期排空，并手动调用 Stalker.flush()）。

工作流

1. 明确目标。
2. 选择线程。
3. 选择捕获模式和筛选条件。
4. 选择模板并进行调整。
5. 运行、调优性能并清理。

如果你正在使用 Frida MCP 工具，还应启用 $frida-mcp-workflow 并遵循其阶段（Idea -> Scripting -> Execution -> Notes）。

模板

从以下模板开始，并将脚本保存为文件。

• templates/stalker-call-summary.js：通过 onCallSummary 以较低开销统计调用次数。
• templates/stalker-onreceive-parse.js：接收二进制事件，并使用 Stalker.parse() 解码。
• templates/stalker-start-stop-around-hook.js：仅在特定的钩取函数调用期间执行跟踪和取消跟踪。
• templates/stalker-call-probe.js：通过 Stalker.addCallProbe() 观察对单个目标的调用。
• templates/stalker-transform-skeleton.js：带 ARM/ARM64 安全检查的最简 transform(iterator) 框架。
• templates/stalker-filter-modules.js：用于在 Android 上选择“应用模块”并排除其余模块的辅助工具。

快速开始

1. 如果还不知道线程 ID，请从 templates/stalker-start-stop-around-hook.js 开始。
2. 如果已经知道线程 ID，且希望降低开销，请使用 templates/stalker-call-summary.js。
3. 如果需要有序事件，请使用 templates/stalker-onreceive-parse.js，并限制事件类型。
4. 如果只关注对某个目标的调用，请从 templates/stalker-call-probe.js 开始。

MCP 使用说明（如可用）

通过 Frida MCP 工具驱动此流程时，建议按以下步骤操作：

1. 创建会话或附加到会话（mcp__frida__create_interactive_session / mcp__frida__attach_to_process）。
2. 使用 mcp__frida__load_script 加载所选模板。
3. 通过 RPC 导出调用开始跟踪：mcp__frida__call_rpc_export（模板会在适用时提供 start() / stop()）。
4. 使用 mcp__frida__get_session_messages 获取输出。

维护脚本记录（已加载的脚本、用途和清理方式）。$frida-mcp-workflow 会强制执行此要求。

Android 专项说明（实用建议）

• 线程的选择比你想象的更重要。

• 如果开始跟踪了错误的线程，你将看不到任何内容，或者只能看到系统噪声。

• 一种稳妥的做法是在 Interceptor.attach() 回调中开始跟踪，使用 Process.getCurrentThreadId() 捕获当前正在执行目标函数的线程。

• 模块筛选至关重要。

• 在 Android 上，应用代码通常位于 path 包含 /data/app/、/data/data/ 或提取后的 APK 分包路径的模块中。

• 如果只关注应用自身的原生库，可使用 Stalker.exclude() 排除常见噪声来源（libart.so、libc.so、liblog.so 等）。

• 32 位 ARM 注意事项。

• 如果在 32 位 ARM 上使用原始地址，Thumb 函数的地址最低位必须设为 1。建议使用 Frida API 返回的地址，例如 Process.getModuleByName(...).getExportByName(...)。

• 除非你清楚自己在做什么，否则不要使用 Process.runOnThread()。

• 它可能会中断正在执行不可重入代码的线程，导致死锁或崩溃。

性能经验法则

• 除非确实需要指令级跟踪，否则不要使用 events.exec。它会产生海量数据。
• 如果可以，优先使用 onCallSummary 而不是 onReceive。
• 保持回调精简；尽可能将繁重的工作交给宿主端处理。
• 积极使用 Stalker.exclude()，减少在系统库中花费的时间。
• 需要确定性时间窗口时，优先手动排空（Stalker.queueDrainInterval = 0 + Stalker.flush()）。
• 取消跟踪后调用 Stalker.garbageCollect()，尤其是在反复启动和停止跟踪时。

清理检查清单

• Stalker.unfollow(threadId)
• Stalker.flush()
• Stalker.garbageCollect()

故障排查

• 完全没有输出。

• 你很可能跟踪了错误的线程，或者回调没有被调用（例如，你跟踪的线程从未运行）。

• 输出只有系统噪声。

• 添加模块筛选和排除项。在确定处于应用代码中的钩子内开始跟踪。

• 目标程序变得极其缓慢或停止运行。

• 减少启用的事件，不再使用 exec，并改用 onCallSummary。排除庞大或噪声较多的模块。

如需了解更深入的说明，请参阅：

• references/stalker-api.md
• references/android-filtering.md