bronils/aotopsyStatischer Analysator für Flutter/Dart-AOT-Snapshots — rekonstruiert Funktionsnamen, Klassenhierarchien, Aufrufgraphen und Verhaltenssignale aus libapp.so, ohne die Dart-VM einzubetten oder auszuführen. Unterstützt ARM64 und x86_64, Dart 2.10–3.12.
# AOTopsy
[](https://github.com/BroNils/aotopsy/actions/workflows/ci.yml)
[](https://github.com/BroNils/aotopsy/releases)
[](LICENSE)
Ein Dart-AOT-Snapshot-Analysator. Verwandelt `libapp.so` — den kompilierten Dart-Code innerhalb einer Flutter-Release-APK — in Funktionsnamen, Klassenlayouts, Aufrufgraphen, Verhaltenssignale und lesbaren Pseudocode. Keine Dart-VM, keine SDK-Kompilierung, kein Runtime-Fallback.
> **Fork-Hinweis:** AOTopsy ist ein Fork von **unflutter**, ursprünglich von **Anthony Zboralski**. Das ursprüngliche Repository `zboralski/unflutter` ist nicht mehr verfügbar (vom Autor entfernt); eine Community-Fortführung existiert unter [`KristijanZic/unflutter`](https://github.com/KristijanZic/unflutter). Die gesamte Anerkennung für den ursprünglichen Snapshot-Parser, Cluster-Deserializer, die ARM64-Disassembly-Pipeline und die Ghidra/IDA-Integration gebührt dem ursprünglichen Autor. AOTopsy erweitert es um x86_64-Unterstützung, einen nativen Decompiler, programmweite Typinferenz, Frida-Skriptgenerierung und umfassende Dokumentation.
## Was es wiederherstellt
| Ausgabe | Was es ist |
|--------|-----------|
| Funktionsnamen | Der ursprüngliche Dart-Name für jede kompilierte Funktion |
| Klassenstrukturen | Feldnamen, Byte-Offsets, Vererbungsketten |
| Aufrufgraph | Direkte (BL) und indirekte (BLR/Dispatch) Aufrufkanten mit Provenienz |
| String-Referenzen | Welche Funktionen welche String-Literale aus dem Objektpool laden |
| Verhaltenssignale | Klassifizierung von Krypto-, Netzwerk-, Glücksspiel-, SIM-, Standort-, WebView- und Blockchain-Schlüsselwörtern |
| Pseudocode | Architekturneutraler dekompilierter Output aus ARM64- oder x86_64-Maschinencode |
| Dart-Quellexport | Modular rekonstruierte `.dart`-Dateien des gesamten Projekts mit Klassen, Feldern und Methoden |
Unterstützt **ARM64** und **x86_64**. Deckt **Dart 2.10 bis 3.13** ab (3.13.2 ist die aktuelle stabile Grenze) — jede modellierte Version wird auf beiden Architekturen sauber geparst, siehe [COVERAGE.md](https://github.com/bronils/aotopsy/blob/main/COVERAGE.md) (93 Beispiel-Builds, 0 Fehler).
## Genauigkeit & Ehrlichkeit
AOTopsy wird an der Ground Truth gemessen, nicht behauptet. Zwei Eigenschaften werden bei jeder Änderung durch die Testsuite erzwungen:
| Metrik | Wert | Was sie bedeutet |
|--------|-------|---------------|
| **Übereinstimmung bei der Namenswiederherstellung** | **90,2 %** insgesamt (81,3 % schlechtestes Band, ≥ 0,81 Gate-Untergrenze) über 44 Ground-Truth-Builds | Wiederhergestellte Funktionsnamen im Vergleich zur eigenen ELF `.symtab` jedes Builds, der externen Ground Truth — `TestSymtabDifferential`. Vollständige Rangliste pro Build: [BENCHMARK.md](https://github.com/bronils/aotopsy/blob/main/BENCHMARK.md) (`make bench`). |
| **Syntaktische Gültigkeit des Decompilers** | **100 %** gültiges Dart | Jede ausgegebene Pseudocode-Funktion wird als Dart geparst — `TestDecompileQualityCorpus`. |
| **Fabrikationsrate** | **0 %** | Die §2-Regel: niemals einen geratenen Namen, Typ oder Aufrufziel als Tatsache ausgeben. Unbekanntes wird ehrlich dargestellt (`indirectCall`, `<unknown>`, `dynamic`). |
Die Ground-Truth-Zwillinge sind echte Produktions-Builds, die wir nicht weitergeben können, daher laufen diese differentiellen Gates **lokal**; die öffentliche CI validiert Build, Vet, `gofmt`, `staticcheck`, Unit-Tests (gemischt) und eine Coverage-Untergrenze über die Plattformmatrix. `samples/` ist nicht weitergebbar und wird von Git ignoriert, daher werden sample-abhängige Tests dort übersprungen — aber nur, wenn das Korpus vollständig fehlt; ein Korpus, der vorhanden ist und ein registriertes Sample vermissen lässt, schlägt fehl, weil diese beiden Fälle das Gegenteil bedeuten. Wie jede Zahl hier gemessen wird (Ground Truth, Metrikdefinitionen, Reproduktion): [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md). Siehe [SECURITY.md](https://github.com/bronils/aotopsy/blob/main/SECURITY.md) für die Verifikation von Release-Binaries und den ehrlichen Geltungsbereich unten.
## Schnellstart
```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
```
Siehe [DEMO.md](https://github.com/bronils/aotopsy/blob/main/DEMO.md) für eine fünfminütige Einführung anhand eines echten Snapshots oder `WORKFLOW.md` für die schrittweise Methodik, wenn Sie eine rohe APK haben und nicht wissen, wo Sie anfangen sollen.
## Funktionsweise
AOTopsy behandelt den Dart-AOT-Snapshot als eine deterministische binäre Grammatik. Jedes Byte hat bei den richtigen Einschränkungen (ELF-Struktur, Snapshot-Magic, Versions-Hash, CID-Tabelle, Cluster-Encoding) genau eine korrekte Interpretation. Der Parser wendet Einschränkungen an, bis nur noch eine Interpretation übrig bleibt – keine Heuristiken, kein Raten.
Die Pipeline läuft in Stufen ab, wobei jede eine reine Funktion von Bytes zu strukturierten Daten ist:
```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]
```
Zwei unabhängige Backends teilen sich dieselbe vordere Hälfte (ELF bis Cluster-Füllung) und verzweigen sich dann nach Architektur: `internal/disasm` für ARM64, `internal/disasm/x86.go` für x86_64. Der Decompiler (`internal/decompiler`) verarbeitet beide Architekturen über eine einheitliche 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
```
## Vergleich mit 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) bettet die Dart-VM ein, um den Snapshot über ihre eigenen Codepfade zu deserialisieren. Perfekte Genauigkeit, erfordert jedoch das Kompilieren eines passenden Dart-SDK für jede Zielversion – und es ist nur für ARM64 verfügbar, ohne statische x86_64-Unterstützung. AOTopsy ist der einzige statische, versionsunabhängige Analyzer mit einem nativen Pseudocode-Decompiler und veröffentlichter Ground-Truth-Genauigkeit.
AOTopsy parst das Binärformat direkt. Keine VM, kein SDK. Der Kompromiss: Jede Formatänderung über Dart-Versionen hinweg muss explizit modelliert werden. Es gibt keine Laufzeitumgebung, die dies automatisch übernimmt.
## Befehle
### Vollständige Pipeline
```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
```
Flags: `--out <dir>` (Standard: `<basename>.aotopsy/`), `--quiet`, `--strict`, `--max-steps <n>`, `--k <n>` (Signalkontexttiefe, Standard 2), `--decompile`.
`--decompile` schreibt Dart-Pseudocode pro Funktion nach `<out>/dart/`. Es ist standardmäßig deaktiviert, weil es das Ausgabeverzeichnis etwa verdreifacht; jeder Lauf ohne diese Option weist darauf hin, sodass die Funktion auffindbar ist und nicht bloß vorhanden.
### Diagnose
```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-Quellcode-Export des gesamten Projekts
Rekonstruiert alle Klassen, Felder, Methoden, Getter, Setter und Konstruktoren in modulare `.dart`-Dateien, die den ursprünglichen Bibliotheks-URIs zugeordnet sind:
```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
```
### Hochwertiger nativer Decompiler (ARM64 + x86_64)
Erzeugt sauberen, idiomatischen Dart-Code direkt aus binären Maschinenanweisungen:
- **Strukturelle Kontrollflussanalyse**: `for-in`-Iteratoren, `while`, `for`, `try-catch-finally` mit exakter PC-Begrenzung.
- **Async/Await-Linearisierung**: Entpackt `_SuspendState`-Zustandsmaschinen in lineares `await future` und `await for`.
- **Lambda-Inlining**: Synthetisiert Arrow-Callbacks `(item) => process(item)` direkt an den Aufrufstellen.
- **Typgitter**: Propagiert konkrete Dart-Typen (`String`, `int`, `UserModel`) über SSA-Werte, ohne eine laufende VM zu benötigen.
- **Dart-Idiome**: Null-bewusste Operatoren (`?.`, `??`, `??=`), Kaskaden (`..`), Set/List/Map-Literale, String-Interpolation (`"${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
```
Warnung: `--all` ohne ein kleines `--max` kann bei einer echten App ~64GB RAM erfordern. Bevorzuge `--find`/`--func`/`--from-main`.
### Ghidra / IDA (nur ARM64)
```bash
aotopsy ghidra libapp.so # headless Ghidra with metadata injection
aotopsy ida libapp.so # headless IDA via idalib
```
Beide lehnen x86_64-Eingaben ab. Verwenden Sie `decompile-native` für x86_64-Pseudocode.
### Frida-Skriptgenerierung
```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
```
Siehe `FRIDA.md` für die vollständige Anleitung.
### Querverweise und Tracing
```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
```
### Korpus-Tools
```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
```
## Ausgabeartefakte
| Datei | Inhalt |
|------|----------|
| `functions.jsonl` | Name, Adresse, Größe, Eigentümer, Parameteranzahl pro Funktion |
| `call_edges.jsonl` | BL/BLR-Kanten mit aufgelösten Zielen und Provenienz |
| `classes.jsonl` | Feldnamen, Offsets, Instanzgrößen pro Klasse |
| `string_refs.jsonl` | String-Referenzen aus Object-Pool-Ladevorgängen |
| `dispatch_table.jsonl`| Abgeleitete Empfängertypen der Dispatch-Tabelle und Zielzuordnung |
| `signal.html` | Bericht über Verhaltenssignale mit Kontextgraph |
| `dart_meta.json` | Snapshot-Metadaten, Flag für komprimierte Zeiger, THR-Layout |
| `flutter_meta.json` | Einheitliche Metadaten für Ghidra/IDA (nur ARM64) |
| `aotopsy.sarif` | SARIF 2.1.0-Bericht über Sicherheitsbefunde (für GitHub Code Scanning) |
| `evidence.jsonl` | Einheitliches Evidenzmodell mit Konfidenz und Provenienz pro Aufrufstelle |
| `asm/*.txt` | Annotierte Disassemblierung pro Funktion |
| `asm/*.bin` | Rohe Instruktionsbytes pro Funktion (beide Architekturen) |
| `dart/*.dart` | Dekompilierter Pseudocode pro Funktion (mit `--decompile`) |
| `cfg/*.dot` | CFGs pro Funktion (mit `--graph`) |
## Paketaufbau
```
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)
```
Siehe `ARCHITECTURE.md` für einen detaillierten Einblick in jedes Paket.
## Build
Erfordert 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`
```
Integrationstests beziehen ihre Eingaben aus `internal/samplecorpus`, das nach einem `samples/`-Verzeichnis sucht; es muss nichts konfiguriert werden. `samples/` ist in gitignore eingetragen, sodass ein Checkout ohne dieses Verzeichnis diese Tests überspringt – aber ein Checkout, der *ein* Korpus *hat* und dem ein registriertes Sample fehlt, schlägt fehl, weil ein abweichender Korpus und ein fehlender Korpus unterschiedliche Dinge bedeuten.
Die öffentliche CI führt `gofmt`, `staticcheck`, Build, Vet und gemischte Unit-Tests auf linux/amd64, darwin/arm64 und windows/amd64 aus, plus einen Race+Coverage-Job mit einer Coverage-Untergrenze.
## Releases & Branches
AOTopsy verwendet ein Zwei-Branch-Modell:
| Branch | Rolle |
|--------|------|
| `main` | **Stabil.** Jeder Commit ist ein squash-gemergter, durch Gates verifizierter Release-Kandidat. Getaggte Releases (mit vorgebauten plattformübergreifenden Binärdateien) werden von hier aus erstellt. |
| `develop` | **Rolling / Nightly.** Hier landen zuerst die alltäglichen kleinen Commits, Features und Forschungsarbeiten. Zwischen Merges kann dieser Branch instabil sein. Wird per Squash-Merge-PR in `main` gebündelt, sobald die Gates grün sind. |
Beiträge richten sich an `develop`; öffne einen PR in `main` nur, wenn ein Arbeitspaket durch Gates verifiziert ist.
Vorgebaute Binärdateien für Linux, macOS und Windows (amd64/arm64) sind an jedes
[GitHub-Release](../../releases) angehängt. AOTopsy ist reines Go, daher kompiliert `make build` sauber für jedes Ziel. Jedes Release-Archiv enthält außerdem `ghidra_scripts/` und `ida_scripts/` neben der Binärdatei – das ist die Layout-Struktur, die `aotopsy ghidra` und `aotopsy ida` erkennen –, sodass diese Befehle direkt aus einem entpackten Download funktionieren, ohne dass ein Checkout nötig ist.
## Einschränkungen & Umfang
AOTopsy legt offen dar, was es wiederherstellt und was nicht. Einige Grenzen sind
Engineering-Umfang; andere sind **harte AOT-Format-Untergrenzen** – Informationen, die der Dart-Compiler in Release-Builds (PRODUCT) entfernt, verifiziert gegen den SDK-Quellcode. Wir dokumentieren Untergrenzen, statt über sie hinweg zu fabrizieren.
**Harte AOT-Untergrenzen (verifiziert – erwarte nicht, dass sich diese verbessern):**
- **Instanzfeldnamen fehlen zu ~97–99 %.** `Precompiler::DropFields` behält Feldnamen
nur unter `#if !defined(PRODUCT)`; eine echte App hat ~233 benannte `Field`-Objekte gegenüber
~16k synthetischen. Die accessor-basierte Wiederherstellung (`get:`/`set:` tragen den Namen noch) durchbricht dies teilweise (−11–22 %, deterministisch, niemals geraten); der Rest ist wirklich verloren.
- **Namen lokaler und erfasster Variablen sind verloren.** Dargestellt als `local_*` / `tN`.
- **Echt polymorphe Dispatch-Ziele sind statisch nicht auflösbar.** BLR durch eine
Dispatch-Tabelle / ein dynamisches `Closure`-Objekt ist eine AOT-Grenze, keine Analyse-Lücke; diese werden ehrlich als `indirectCall` / `dynamicCall` dargestellt. Siehe [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md#limits-of-this-method-honestly).
**Engineering-Umfang:**
- **Nur AOT.** Keine JIT-Unterstützung.
- **Ghidra/IDA-Dekompilierung ist nur für ARM64.** x86_64 wird mit einem klaren Fehler abgelehnt – verwende stattdessen `decompile-native` (den einzigen statischen x86_64-Flutter-Dekompiler).
- **`--all`-Dekompilierung kann den Host zum Absturz bringen.** Eine echte App in voller Größe benötigt ~64 GB RAM für unbegrenztes `--all`. Verwende gezielte Modi (`--find`, `--func`, `--from-main`) oder begrenze mit `--max`.
- **Virtueller Dispatch ist für die Erreichbarkeitsanalyse von `--from-main` unsichtbar.** Widget-Lifecycle-Callbacks laufen über das Framework-Dispatch von Flutter, nicht über direkte Call-Instruktionen. Eine Klassen-Touch-Heuristik erfasst einige davon, ist aber eine Überapproximation. Verwende Frida für den Rest.
- **Jede Dart-Versionsänderung muss modelliert werden.** Es gibt keine VM, die Formatänderungen automatisch behandelt. Der Snapshot trägt einen aus git abgeleiteten Hash, keine Versionsnummer, daher ist die Unterstützung strukturbasiert. Derzeit modelliert: Dart 2.10 → 3.13.
- **Ground-Truth-Zwillinge sind nicht weiterverbreitbar** (echte Produktions-Builds), daher läuft das Namenswiederherstellungs-Differential lokal, nicht in der öffentlichen CI.
## Lizenz
BSD-3-Clause. CID-Tabellen, THR-Feld-Offsets und Stub-Namen sind vom [Dart SDK](https://github.com/dart-lang/sdk) abgeleitet (ebenfalls BSD-3-Clause). Siehe `LICENSE` und `NOTICE`.