bronils/aotopsyFlutter/Dart AOTスナップショット用の静的アナライザー — Dart VMを埋め込んだり実行したりせずに、libapp.soから関数名、クラス階層、コールグラフ、および挙動シグナルを復元します。ARM64およびx86_64、Dart 2.10–3.12をサポート。
# AOTopsy
[](https://github.com/BroNils/aotopsy/actions/workflows/ci.yml)
[](https://github.com/BroNils/aotopsy/releases)
[](LICENSE)
Dart AOTスナップショットアナライザー。FlutterリリースAPK内にコンパイルされたDartコードである`libapp.so`を、関数名、クラスレイアウト、コールグラフ、行動シグナル、可読な擬似コードへと変換します。Dart VMもSDKコンパイルもランタイムフォールバックも不要です。
> **フォークに関する注意:** AOTopsyは、**Anthony Zboralski**による**unflutter**のフォークです。元の`zboralski/unflutter`リポジトリは現在利用できません（作者により削除済み）。コミュニティによる継続版が[`KristijanZic/unflutter`](https://github.com/KristijanZic/unflutter)に存在します。元のスナップショットパーサー、クラスタデシリアライザー、ARM64逆アセンブリパイプライン、Ghidra/IDA統合に関するすべての功績は原作者に帰属します。AOTopsyはこれにx86_64サポート、ネイティブデコンパイラ、プログラム全体の型推論、Fridaスクリプト生成、包括的なドキュメントを追加して拡張しています。
## 復元できるもの
| 出力 | 内容 |
|--------|-----------|
| 関数名 | コンパイルされた各関数の元のDart名 |
| クラス構造 | フィールド名、バイトオフセット、継承チェーン |
| コールグラフ | 出所情報付きの直接（BL）および間接（BLR/ディスパッチ）呼び出しエッジ |
| 文字列参照 | どの関数がオブジェクトプールからどの文字列リテラルをロードするか |
| 行動シグナル | 暗号、ネットワーク、ギャンブル、SIM、位置情報、WebView、ブロックチェーンキーワードの分類 |
| 擬似コード | ARM64またはx86_64マシンコードから生成されたアーキテクチャ非依存の逆コンパイル出力 |
| Dartソースエクスポート | クラス、フィールド、メソッドを再構築したプロジェクト全体のモジュール式`.dart`ファイル |
**ARM64**と**x86_64**をサポート。**Dart 2.10から3.13**までをカバー（3.13.2が現在の安定版フロンティア）— モデル化されたすべてのバージョンが両アーキテクチャでクリーンにパースされます。[COVERAGE.md](https://github.com/bronils/aotopsy/blob/main/COVERAGE.md)を参照（93サンプルビルド、失敗0件）。
## 精度と誠実性
AOTopsyは主張ではなく、グラウンドトゥルースに対して測定されます。2つの特性が
すべての変更においてテストスイートによって強制されます:
| 指標 | 値 | 意味 |
|--------|-------|---------------|
| **名前復元一致率** | 44のグラウンドトゥルースビルド全体で**90.2%**（最悪バンド81.3%、≥ 0.81のゲート下限） | 復元された関数名を、各ビルド自身のELF `.symtab`（外部グラウンドトゥルース）と比較 — `TestSymtabDifferential`。ビルドごとの完全なスコアボード: [BENCHMARK.md](https://github.com/bronils/aotopsy/blob/main/BENCHMARK.md)（`make bench`）。 |
| **デコンパイラ構文妥当性** | **100%** 有効なDart | 出力されるすべての擬似コード関数がDartとしてパースされる — `TestDecompileQualityCorpus`。 |
| **捏造率** | **0%** | §2のルール: 推測された名前、型、呼び出しターゲットを事実として決して出力しない。不明なものは正直に表示される（`indirectCall`、`<unknown>`、`dynamic`）。 |
グラウンドトゥルースのツインは再配布できない実際のプロダクションビルドであるため、これらの
差分ゲートは**ローカルで**実行されます。公開CIはビルド、vet、`gofmt`、
`staticcheck`、ユニットテスト（シャッフル）、およびプラットフォームマトリックス全体の
カバレッジ下限を検証します。`samples/`は再配布不可でgitignoreされているため、サンプル依存の
テストはそこでスキップされます — ただしコーパスが完全に存在しない場合に限ります。存在する
コーパスに登録済みサンプルが欠けている場合は失敗します。これらは正反対の意味を持つからです。
ここでのすべての数値の測定方法（グラウンドトゥルース、指標定義、再現方法）: [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md)。リリースバイナリの検証と以下の正直なスコープについては
[SECURITY.md](https://github.com/bronils/aotopsy/blob/main/SECURITY.md)を参照してください。
## クイックスタート
```bash
make build
./aotopsy libapp.so # full pipeline
./aotopsy doctor libapp.so # quick diagnostic
./aotopsy export-dart --lib libapp.so --out ./lib # reconstruct entire Dart source project
./aotopsy _debug decompile-native --lib libapp.so --find MyClass # find and decompile a function
```
実際のスナップショットを使った5分間のウォークスルーについては [DEMO.md](https://github.com/bronils/aotopsy/blob/main/DEMO.md) を、生のAPKがありどこから始めればよいかわからない場合のステップバイステップの方法論については `WORKFLOW.md` を参照してください。
## 仕組み
AOTopsyはDart AOTスナップショットを決定論的なバイナリ文法として扱います。適切な制約（ELF構造、スナップショットマジック、バージョンハッシュ、CIDテーブル、クラスタエンコーディング）が与えられれば、すべてのバイトはただ1つの正しい解釈を持ちます。パーサーは1つの解釈だけが残るまで制約を適用します — ヒューリスティクスも推測もありません。
パイプラインはステージごとに実行され、各ステージはバイトから構造化データへの純粋関数です:
```mermaid
flowchart TD
A[libapp.so] --> B[ELF parse]
B --> C[snapshot region extraction]
C --> D[version detection]
D --> E[cluster alloc<br/>object census]
E --> F[cluster fill<br/>field values, names, strings]
F --> G[instructions table<br/>code ranges, stub boundaries]
G --> H{architecture?}
H -->|ARM64| I[ARM64 disassembly]
H -->|x86_64| J[x86_64 disassembly]
I --> K[CFG + call edges<br/>register provenance]
J --> K
K --> L[type inference<br/>BLR receiver type resolution]
L --> M[signal classification<br/>behavioral keyword matching]
M --> N[JSONL + HTML + DOT<br/>pseudocode output]
```
2つの独立したバックエンドは同じ前半部分（ELFからクラスタフィルまで）を共有し、その後アーキテクチャごとに分岐します。ARM64用は`internal/disasm`、x86_64用は`internal/disasm/x86.go`です。デコンパイラ（`internal/decompiler`）は統一されたIRを通じて両方のアーキテクチャを処理します。
```mermaid
flowchart LR
subgraph "Shared front half"
A[elfx] --> B[snapshot]
B --> C[cluster]
end
subgraph "ARM64 backend"
C --> D1[disasm ARM64]
D1 --> E1[callgraph]
E1 --> F1[signal]
end
subgraph "x86_64 backend"
C --> D2[disasm x86_64]
D2 --> E2[callgraph]
E2 --> F2[signal]
end
subgraph "Decompiler (both archs)"
C --> G[decompiler IR]
G --> H[pseudocode]
end
```
## Blutter との比較
```mermaid
flowchart LR
subgraph Blutter
direction TB
B1[libapp.so] --> B2[Compile matching<br/>Dart SDK]
B2 --> B3[Embed Dart VM]
B3 --> B4[Deserialize via<br/>VM internal APIs]
B4 --> B5[Perfect fidelity]
end
subgraph AOTopsy
direction TB
A1[libapp.so] --> A2[Parse binary format<br/>directly]
A2 --> A3[No VM, no SDK]
A3 --> A4[Version-specific<br/>format modeling]
A4 --> A5[Portability + speed]
end
```
[Blutter](https://github.com/worawit/blutter) は Dart VM を組み込み、独自のコードパスを通じてスナップショットをデシリアライズします。完全な忠実性を備えていますが、ターゲットバージョンごとに対応する Dart SDK をコンパイルする必要があり、ARM64 専用で静的な x86_64 サポートはありません。AOTopsy は、ネイティブの擬似コードデコンパイラと公開されたグラウンドトゥルース精度を備えた、唯一の静的かつバージョン非依存のアナライザーです。
AOTopsy はバイナリ形式を直接解析します。VM も SDK も不要です。トレードオフとして、Dart のバージョン間におけるあらゆる形式の変更を明示的にモデル化する必要があります。それを自動的に処理するランタイムは存在しません。
## コマンド
### フルパイプライン
```bash
aotopsy libapp.so # disasm + call edges + signal + metadata (ARM64: + Ghidra/IDA)
aotopsy signal libapp.so # same, skip metadata
aotopsy libapp.so --graph # also build call graph DOT files
```
フラグ: `--out <dir>`（デフォルト: `<basename>.aotopsy/`）、`--quiet`、`--strict`、`--max-steps <n>`、`--k <n>`（シグナルコンテキストの深さ、デフォルト 2）、`--decompile`。
`--decompile` は関数ごとの Dart 疑似コードを `<out>/dart/` に書き出します。出力ディレクトリがおよそ3倍になるため、デフォルトでは無効になっています。無効のまま実行するたびにその旨が表示されるので、この機能は単に存在するだけでなく発見可能になっています。
### 診断
```bash
aotopsy doctor libapp.so # Dart version, pointer size, support status, build features
aotopsy find-libapp --apk app.apk # locate libapp.so inside an APK
```
### プロジェクト全体の Dart ソースエクスポート
すべてのクラス、フィールド、メソッド、getter、setter、コンストラクタを、元のライブラリ URI にマッピングされたモジュール式の `.dart` ファイルに再構築します:
```bash
aotopsy export-dart --lib libapp.so --out ./reconstructed_lib/ # full project export
aotopsy export-dart --lib libapp.so --out ./lib/ --app-only # filter out core/flutter framework
aotopsy export-dart --lib libapp.so --out ./lib/ --filter Auth # targeted export by name
```
### 高水準ネイティブデコンパイラ (ARM64 + x86_64)
バイナリの機械命令から、クリーンで慣用的な Dart コードを直接生成します:
- **構造的制御フロー**: 正確な PC 境界を持つ `for-in` イテレータ、`while`、`for`、`try-catch-finally`。
- **Async/Await の線形化**: `_SuspendState` ステートマシンを展開し、線形な `await future` および `await for` に変換します。
- **ラムダのインライン化**: 呼び出し箇所でアローコールバック `(item) => process(item)` を直接合成します。
- **型ラティス**: ライブ VM を実行することなく、具体的な Dart 型 (`String`、`int`、`UserModel`) を SSA 値全体に伝播します。
- **Dart のイディオム**: null 認識演算子 (`?.`、`??`、`??=`)、カスケード (`..`)、Set/List/Map リテラル、文字列補間 (`"${a}${b}"`)。
```bash
aotopsy _debug decompile-native --lib libapp.so --find MyClass # locate by name
aotopsy _debug decompile-native --lib libapp.so --func 0x1a92728 # one function at a VA
aotopsy _debug decompile-native --lib libapp.so --from-main --out out/ # reachability from app entry
aotopsy _debug decompile-native --lib libapp.so --all --filter MyClass # bulk, filtered
```
警告: 小さな `--max` を指定せずに `--all` を使用すると、実際のアプリでは約64GBのRAMが必要になる場合があります。`--find`/`--func`/`--from-main` を推奨します。
### Ghidra / IDA (ARM64のみ)
```bash
aotopsy ghidra libapp.so # headless Ghidra with metadata injection
aotopsy ida libapp.so # headless IDA via idalib
```
どちらも x86_64 入力は拒否します。x86_64 の擬似コードには `decompile-native` を使用してください。
### Frida スクリプト生成
```bash
aotopsy _debug decompile-native --lib libapp.so --func 0x1a92728 --gen-frida --gen-frida-out hooks.js
frida -U -f com.example.app -l hooks.js --no-pause
```
完全なガイドについては `FRIDA.md` を参照してください。
### 相互参照とトレース
```bash
aotopsy _debug strings --lib libapp.so --find "X-Signature" --xref # which function loads this string?
aotopsy _debug ffi-trace --lib libapp.so --filter MyClass # dart:ffi call sites
aotopsy _debug dispatch-table --lib libapp.so --filter MyClass # dispatch table entries
aotopsy _debug fingerprint --lib libapp.so # build-id and version markers
aotopsy _debug funcdiff --old old.so --new new.so # function set diff
aotopsy _debug symbolmap --stripped lib.so --unstripped debug.so # resolve stripped targets
```
### コーパスツール
```bash
aotopsy inventory --dir samples/ # catalog APKs
aotopsy parity --samples samples/ --out out/ # cross-version parse report
aotopsy _debug thr-audit -lib libapp.so -out thr.jsonl # THR access scan
```
## 出力成果物
| ファイル | 内容 |
|------|----------|
| `functions.jsonl` | 関数ごとの名前、アドレス、サイズ、所有者、パラメータ数 |
| `call_edges.jsonl` | 解決済みターゲットと来歴を持つ BL/BLR エッジ |
| `classes.jsonl` | クラスごとのフィールド名、オフセット、インスタンスサイズ |
| `string_refs.jsonl` | オブジェクトプールのロードからの文字列参照 |
| `dispatch_table.jsonl`| 推論されたディスパッチテーブルのレシーバ型とターゲットマッピング |
| `signal.html` | コンテキストグラフ付きの行動シグナルレポート |
| `dart_meta.json` | スナップショットメタデータ、圧縮ポインタフラグ、THR レイアウト |
| `flutter_meta.json` | Ghidra/IDA 用の統合メタデータ（ARM64 のみ） |
| `aotopsy.sarif` | SARIF 2.1.0 セキュリティ検出事項レポート（GitHub Code Scanning 用） |
| `evidence.jsonl` | 呼び出しサイトごとの信頼度と来歴を持つ統合エビデンスモデル |
| `asm/*.txt` | 関数ごとの注釈付き逆アセンブリ |
| `asm/*.bin` | 関数ごとの生の命令バイト（両アーキテクチャ） |
| `dart/*.dart` | 関数ごとの逆コンパイル済み擬似コード（`--decompile` 使用時） |
| `cfg/*.dot` | 関数ごとの CFG（`--graph` 使用時） |
## パッケージレイアウト
```
cmd/aotopsy/ CLI entry point and command handlers
internal/
analysis/ Pipeline orchestration, snapshot loader, and analysis engines
sdk/ Dart VM ground-truth facts, register mappings, and predicates
vmtables/ Versioned THR field offsets, stub names, and stub orders
thraudit/ Thread-relative memory access audit and classification
arch/arm64/ Centralized ARM64 bitmask instruction decoders
arch/x86/ Centralized x86_64 decode primitives and register helpers
naming/ Central pool lookups, name resolution, and stub builders
elfx/ ELF validation and symbol extraction
snapshot/ Snapshot region extraction, version profiles
dartfmt/ Dart VM variable-length integer encoding
cluster/ Two-phase snapshot deserialization (alloc + fill)
disasm/ ARM64 + x86_64 decode, CFG, call-edge provenance
callgraph/ Call graph construction and DOT rendering
signal/ Behavioral string and malware signal classification
render/ HTML/DOT/SVG visualization
output/ JSONL and SARIF 2.1.0 serialization
decompiler/ Dart-AOT pseudocode decompiler (both architectures)
typetrack/ Whole-program type inference and receiver recovery
fingerprint/ Build-id and version marker identification
funcdiff/ Function-set diffing between builds
symbolmap/ Stripped-vs-unstripped symbol resolution
ffitrace/ Static dart:ffi call-site tracing
strxref/ String-to-function cross-referencing
strutil/ Dart syntax sanitization and metadata serialization
jsonutil/ Generic JSONL stream readers and writers
evidence/ Unified evidence model with confidence and provenance
frida/ Frida runtime hook and probe generation
cli/ ANSI color helpers for CLI output
tools/ Standalone utilities (THR table extractor and validator)
ghidra_scripts/ Ghidra integration (Python)
ida_scripts/ IDA integration (Python)
```
各パッケージの詳細については `ARCHITECTURE.md` を参照してください。
## ビルド
Go 1.25+ が必要です。
```bash
make build # build ./aotopsy
make install # install to ~/.aotopsy/bin, plus the Ghidra/IDA integration
# assets into ~/.aotopsy/ghidra_scripts and ~/.aotopsy/ida_scripts
make test # run tests
make bench # regenerate BENCHMARK.md (needs local ground-truth twins)
make coverage # regenerate COVERAGE.md (needs local corpus samples)
make analyze # cross-check export-dart output against `dart analyze`
```
統合テストは `internal/samplecorpus` から入力を解決します。これは `samples/` ディレクトリを探しますが、設定するものは何もありません。`samples/` は gitignore されているため、それが存在しないチェックアウトではこれらのテストはスキップされます。しかし、コーパスを*持っている*チェックアウトで登録済みのサンプルが欠けている場合は失敗します。なぜなら、ずれたコーパスと存在しないコーパスは異なる意味を持つからです。
公開 CI は linux/amd64、darwin/arm64、windows/amd64 にわたって `gofmt`、`staticcheck`、ビルド、vet、シャッフルされたユニットテストを実行し、さらにカバレッジ下限付きの race+coverage ジョブも実行します。
## リリースとブランチ
AOTopsy は 2 ブランチモデルを採用しています:
| ブランチ | 役割 |
|--------|------|
| `main` | **安定版。** すべてのコミットはスカッシュマージされ、ゲートで検証されたリリース候補です。タグ付きリリース（クロスプラットフォームのビルド済みバイナリ付き）はここから切られます。 |
| `develop` | **ローリング / ナイトリー。** 日々の小さなコミット、機能、研究が最初に着地する場所です。マージ間では不安定な場合があります。ゲートがグリーンになったら、スカッシュマージ PR を介して `main` にバッチで取り込まれます。 |
コントリビュートは `develop` に対して行ってください。`main` への PR は、作業のバッチがゲートで検証された場合にのみオープンしてください。
Linux、macOS、Windows（amd64/arm64）向けのビルド済みバイナリが各
[GitHub リリース](../../releases)に添付されています。AOTopsy は純粋な Go なので、`make build` は任意のターゲット向けにクリーンにクロスコンパイルできます。
各リリースアーカイブにはバイナリの隣に `ghidra_scripts/` と `ida_scripts/` も含まれており、これが `aotopsy ghidra` と `aotopsy ida` が検出するレイアウトです。そのため、これらのコマンドはチェックアウト不要で、展開したダウンロードからそのまま動作します。
## 制限とスコープ
AOTopsy は、何を復元し、何を復元しないかを率直に示します。一部の制限はエンジニアリング上のスコープであり、その他は**AOT フォーマットのハードな下限**です — つまり Dart コンパイラがリリース（PRODUCT）ビルドで削除する情報であり、SDK ソースに対して検証済みです。私たちは下限を偽って覆い隠すのではなく、文書化します。
**ハードな AOT 下限（検証済み — 改善は期待しないでください）:**
- **インスタンスフィールド名は約 97〜99% 存在しません。** `Precompiler::DropFields` は `#if !defined(PRODUCT)` の下でのみフィールド名を保持します。実際のアプリでは約 233 個の名前付き `Field` オブジェクトに対し、約 16k 個の合成フィールドがあります。アクセサベースの復元（`get:`/`set:` は依然として名前を保持）はこれを部分的に突破します（−11〜22%、決定的、決して推測しない）が、残りは本当に失われています。
- **ローカル変数名とキャプチャされた変数名は失われています。** `local_*` / `tN` としてレンダリングされます。
- **真に多態的なディスパッチターゲットは静的に解決できません。** ディスパッチテーブル / 動的な `Closure` オブジェクトを介した BLR は AOT の制限であり、分析のギャップではありません。これらは `indirectCall` / `dynamicCall` として正直にレンダリングされます。[METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md#limits-of-this-method-honestly) を参照してください。
**エンジニアリングスコープ:**
- **AOT のみ。** JIT サポートはありません。
- **Ghidra/IDA の逆コンパイルは ARM64 のみです。** x86_64 は明確なエラーで拒否されます — 代わりに `decompile-native` を使用してください（唯一の静的 x86_64 Flutter 逆コンパイラ）。
- **`--all` の逆コンパイルはホストをクラッシュさせる可能性があります。** 実際のフルサイズアプリでは、無制限の `--all` に約 64GB の RAM が必要です。対象を絞ったモード（`--find`、`--func`、`--from-main`）を使用するか、`--max` で上限を設定してください。
- **仮想ディスパッチは `--from-main` の到達可能性からは見えません。** ウィジェットのライフサイクルコールバックは、直接の呼び出し命令ではなく、Flutter のフレームワークディスパッチを経由します。クラスタッチのヒューリスティックが一部を復元しますが、これは過剰近似です。残りには Frida を使用してください。
- **すべての Dart バージョンの変更をモデル化する必要があります。** フォーマットの変更を自動的に処理する VM は存在しません。スナップショットはバージョン番号ではなく git 由来のハッシュを保持するため、サポートは構造ベースです。現在モデル化済み: Dart 2.10 → 3.13。
- **グラウンドトゥルースのツインは再配布できません**（実際のプロダクションビルドのため）、そのため
名前復元の差分は公開 CI ではなくローカルで実行されます。
## ライセンス
BSD-3-Clause。CID テーブル、THR フィールドオフセット、スタブ名は [Dart SDK](https://github.com/dart-lang/sdk)（これも BSD-3-Clause）に由来します。`LICENSE` と `NOTICE` を参照してください。