frida-stalker-android

Frida Stalker（Android）

概要

Android で Frida の Stalker API を使ってネイティブコードの実行をトレースする必要がある場合に、このスキルを使用します。ARM／ARM64 向けのテンプレートと、パフォーマンスに配慮した既定値が用意されています。

このスキルでは、Frida 17 以降の JavaScript セマンティクスを前提としています。

このスキルを使用する場面

• ユーザーが「Frida Stalker」を Android で使うよう明示的に求めている場合。
• ネイティブ呼び出しの動作（どの関数が何回呼び出されたか）を、低いオーバーヘッドで測定する必要がある場合。
• 順序付きの呼び出しイベント（呼び出しグラフの再構築）や、大まかなカバレッジが必要な場合。
• transform(iterator) を通じて基本ブロックのコンパイル時にロジックを挿入する必要がある場合。

簡単な選択ガイド

• ターゲットごとの呼び出し回数が必要で、順序は気にしない場合：onCallSummary を使用します。
• 順序付きの call／ret／block／compile イベントが必要な場合：onReceive を使用し、Stalker.parse() でデコードします。
• 命令レベルの照合やコールアウトが必要な場合：transform(iterator) を使用します（負荷が高いため、対象を絞ってください）。
• 少数の呼び出しターゲットを監視する場合：Stalker.addCallProbe() を検討してください。

コア API の事実（Frida 17 以降）

• Stalker.follow([threadId, options])
• コールバックは必ず 1 つだけ指定してください：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 ミリ秒です（定期的な排出を無効にして Stalker.flush() を手動で呼び出すには 0 に設定します）。

ワークフロー

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：特定のフック対象関数の呼び出し中のみ follow／unfollow します。
• 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. 1 つのターゲットへの呼び出しだけに関心がある場合は、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 関数では下位ビットをセットする必要があります。Process.getModuleByName(...).getExportByName(...) など、Frida API が返すアドレスを使うことを推奨します。

• 何をしているかを理解していない限り、Process.runOnThread() は避けてください。

• 再入不可のコードでスレッドを中断し、デッドロックやクラッシュを引き起こす可能性があります。

パフォーマンスに関する経験則

• 命令レベルのトレースが本当に必要な場合を除き、events.exec は避けてください。膨大な量のデータが生成されます。
• 可能であれば、onReceive よりも onCallSummary を優先してください。
• コールバックは簡潔に保ち、可能な場合は重い処理をホスト側に移してください。
• システムライブラリでの処理時間を減らすため、積極的に 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