frida-stalker-android

name	frida-stalker-android
description	Trace native execution on Android with Frida Stalker (Frida 17+): call summaries, event parsing, transforms, and performance-safe start/stop patterns.

Frida Stalker (Android)

Overview

Use this skill when you need to trace native code execution on Android using Frida's Stalker API, with templates geared for ARM/ARM64 and performance-safe defaults.

This skill assumes Frida 17+ JavaScript semantics.

When To Use This Skill

• User explicitly asks for "Frida Stalker" on Android.
• You need to measure native call activity (who got called, how often) with low overhead.
• You need ordered call events (call graph reconstruction) or coarse coverage.
• You need to inject logic on basic-block compilation through transform(iterator).

Quick Decision Guide

• Want call counts per target and don't care about ordering: use onCallSummary.
• Want ordered call/ret/block/compile events: use onReceive and decode with Stalker.parse().
• Want instruction-level matching and callouts: use transform(iterator) (heavy; do it narrowly).
• Want to watch a small set of call targets: consider Stalker.addCallProbe().

Core API Facts (Frida 17+)

• Stalker.follow([threadId, options])
• Provide exactly one callback: onReceive(events) or onCallSummary(summary).
• Stalker.unfollow([threadId])
• Stalker.parse(events, { annotate, stringify })
• Stalker.flush() drains buffered events early (otherwise periodic draining is controlled by Stalker.queueDrainInterval).
• Stalker.garbageCollect() should be called after unfollow() to free accumulated memory at a safe point.
• Stalker.exclude({ base, size }) excludes a memory range from stalking (useful to skip noisy/system modules).
• Tuning:
• Stalker.trustThreshold default 1 (set -1 for no trust, 0 to trust immediately, or N to trust after N executions).
• Stalker.queueCapacity default 16384 events.
• Stalker.queueDrainInterval default 250 ms (set 0 to disable periodic draining and call Stalker.flush() manually).

Workflow

1. Define objective.
2. Choose thread(s).
3. Choose capture mode and filters.
4. Pick a template and adapt it.
5. Run, tune performance, and clean up.

If you are using the Frida MCP tools, also enable $frida-mcp-workflow and follow its phases (Idea -> Scripting -> Execution -> Notes).

Templates

Start from these and keep scripts file-based.

• templates/stalker-call-summary.js: low-overhead call counting via onCallSummary.
• templates/stalker-onreceive-parse.js: receive binary events and decode with Stalker.parse().
• templates/stalker-start-stop-around-hook.js: follow/unfollow only during a specific hooked function call.
• templates/stalker-call-probe.js: observe calls to a single target via Stalker.addCallProbe().
• templates/stalker-transform-skeleton.js: minimal transform(iterator) skeleton with ARM/ARM64 safety check.
• templates/stalker-filter-modules.js: helper to select "app modules" on Android and exclude the rest.

Quick Start

1. If you do not know the thread id yet, start with templates/stalker-start-stop-around-hook.js.
2. If you already know the thread id and want low overhead, use templates/stalker-call-summary.js.
3. If you need ordered events, use templates/stalker-onreceive-parse.js and keep event types narrow.
4. If you only care about calls to one target, start with templates/stalker-call-probe.js.

MCP Usage Notes (If Available)

When driving this through the Frida MCP tools, prefer this flow:

1. Create or attach a session (mcp__frida__create_interactive_session / mcp__frida__attach_to_process).
2. Load the selected template with mcp__frida__load_script.
3. Start tracing through RPC exports using mcp__frida__call_rpc_export (templates expose start() / stop() when appropriate).
4. Use mcp__frida__get_session_messages to consume output.

Keep a script ledger (what is loaded, purpose, and teardown path). This is enforced by $frida-mcp-workflow.

Android-Specific Notes (Practical)

• Thread choice matters more than you think.

• If you start stalking the wrong thread, you will see nothing, or only system noise.

• A safe pattern is to start stalking from inside an Interceptor.attach() callback, using Process.getCurrentThreadId() to capture the thread that is actually executing your target function.

• Module filtering is essential.

• On Android, app code is usually in modules whose path contains /data/app/, /data/data/, or an extracted APK split path.

• Exclude common noise sources (libart.so, libc.so, liblog.so, etc.) using Stalker.exclude() when you only care about your app's own native libs.

• 32-bit ARM note.

• If you use raw addresses on 32-bit ARM, Thumb functions require the low bit set. Prefer addresses returned by Frida APIs like Process.getModuleByName(...).getExportByName(...).

• Avoid Process.runOnThread() unless you know what you're doing.

• It can interrupt a thread in non-reentrant code and cause deadlocks/crashes.

Performance Rules Of Thumb

• Avoid events.exec unless you truly need instruction-level traces. It produces huge volumes of data.
• Prefer onCallSummary over onReceive when you can.
• Keep your callbacks lean; push heavy work to the host side when possible.
• Use Stalker.exclude() aggressively to reduce time spent in system libraries.
• Prefer manual draining (Stalker.queueDrainInterval = 0 + Stalker.flush()) when you need deterministic windows.
• Call Stalker.garbageCollect() after unfollowing, especially if you repeatedly start/stop.

Cleanup Checklist

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

Troubleshooting

• No output at all.

• You are likely stalking the wrong thread, or your callback isn't being invoked (e.g., you followed a thread that never runs).

• Output is only system noise.

• Add module filters and exclusions. Start stalking from inside a hook where you know you're in app code.

• Target slows to a crawl or dies.

• Reduce enabled events, stop using exec, and switch to onCallSummary. Exclude large/noisy modules.

For deeper notes, see:

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