
Analizzatore statico per snapshot AOT Flutter/Dart — recupera i nomi delle funzioni, le gerarchie delle classi, i grafi di chiamata e i segnali comportamentali da libapp.so senza incorporare o eseguire la Dart VM. Supporta ARM64 e x86_64, Dart 2.10–3.12.
# AOTopsy
[](https://github.com/BroNils/aotopsy/actions/workflows/ci.yml)
[](https://github.com/BroNils/aotopsy/releases)
[](LICENSE)
Un analizzatore di snapshot AOT per Dart. Trasforma `libapp.so` — il codice Dart compilato all'interno di un APK Flutter release — in nomi di funzioni, layout delle classi, grafi delle chiamate, segnali comportamentali e pseudocodice leggibile. Nessuna Dart VM, nessuna compilazione SDK, nessun fallback a runtime.
> **Avviso di fork:** AOTopsy è un fork di **unflutter**, originariamente creato da **Anthony Zboralski**. Il repository originale `zboralski/unflutter` non è più disponibile (rimosso dall'autore); esiste una continuazione della community presso [`KristijanZic/unflutter`](https://github.com/KristijanZic/unflutter). Tutto il merito per il parser originale degli snapshot, il deserializzatore dei cluster, la pipeline di disassemblaggio ARM64 e l'integrazione con Ghidra/IDA appartiene all'autore originale. AOTopsy lo estende con il supporto x86_64, un decompilatore nativo, l'inferenza dei tipi sull'intero programma, la generazione di script Frida e una documentazione completa.
## Cosa Recupera
| Output | Di cosa si tratta |
|--------|-----------|
| Nomi delle funzioni | Il nome Dart originale per ogni funzione compilata |
| Strutture delle classi | Nomi dei campi, offset in byte, catene di ereditarietà |
| Grafo delle chiamate | Archi di chiamata diretti (BL) e indiretti (BLR/dispatch) con provenienza |
| Riferimenti alle stringhe | Quali funzioni caricano quali stringhe letterali dal pool di oggetti |
| Segnali comportamentali | Classificazione per parole chiave di crypto, rete, gioco d'azzardo, SIM, posizione, WebView, blockchain |
| Pseudocodice | Output decompilato indipendente dall'architettura da codice macchina ARM64 o x86_64 |
| Esportazione del sorgente Dart | File `.dart` modulari dell'intero progetto ricostruiti con classi, campi e metodi |
Supporta **ARM64** e **x86_64**. Copre **Dart dalla 2.10 alla 3.13** (la 3.13.2 è l'attuale frontiera stabile) — ogni versione modellata viene analizzata correttamente su entrambe le architetture, vedi [COVERAGE.md](https://github.com/bronils/aotopsy/blob/main/COVERAGE.md) (93 build di esempio, 0 fallimenti).
## Accuratezza e Onestà
AOTopsy è misurato rispetto alla verità di riferimento, non affermato. Due proprietà sono verificate dalla
suite di test a ogni modifica:
| Metrica | Valore | Cosa significa |
|--------|-------|---------------|
| **Accordo nel recupero dei nomi** | **90.2%** complessivo (81.3% banda peggiore, soglia minima ≥ 0.81) su 44 build di riferimento | Nomi di funzioni recuperati confrontati con il `.symtab` ELF di ciascuna build, la verità di riferimento esterna — `TestSymtabDifferential`. Tabella di punteggio completa per build: [BENCHMARK.md](https://github.com/bronils/aotopsy/blob/main/BENCHMARK.md) (`make bench`). |
| **Validità sintattica del decompilatore** | **100%** Dart valido | Ogni funzione di pseudocodice emessa viene analizzata come Dart — `TestDecompileQualityCorpus`. |
| **Tasso di fabbricazione** | **0%** | La regola §2: non emettere mai un nome, tipo o destinazione di chiamata indovinati come fatto. Gli elementi sconosciuti vengono resi onestamente (`indirectCall`, `<unknown>`, `dynamic`). |
I gemelli di riferimento sono build di produzione reali che non possiamo ridistribuire, quindi quelle
soglie differenziali vengono eseguite **localmente**; la CI pubblica convalida build, vet, `gofmt`,
`staticcheck`, test unitari (mescolati) e una soglia di copertura attraverso la matrice
delle piattaforme. `samples/` non è ridistribuibile ed è escluso da git, quindi i test dipendenti dai campioni
vengono saltati lì — ma solo quando il corpus è del tutto assente; un corpus che è
presente ma manca di un campione registrato fallisce, perché queste due cose significano l'opposto.
Come viene misurato ogni numero qui (verità di riferimento, definizioni delle metriche, riproduzione): [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md). Vedi
[SECURITY.md](https://github.com/bronils/aotopsy/blob/main/SECURITY.md) per la verifica dei binari di rilascio e l'ambito onesto di seguito.
## Avvio Rapido
```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
```
Consulta [DEMO.md](https://github.com/bronils/aotopsy/blob/main/DEMO.md) per una guida introduttiva di cinque minuti su uno snapshot reale, oppure `WORKFLOW.md` per la metodologia passo-passo quando hai un APK grezzo e non sai da dove iniziare.
## Come funziona
AOTopsy tratta lo snapshot AOT di Dart come una grammatica binaria deterministica. Ogni byte ha esattamente una corretta interpretazione date le giuste condizioni (struttura ELF, magic dello snapshot, hash della versione, tabella CID, codifica dei cluster). Il parser applica vincoli finché non sopravvive una sola interpretazione — nessuna euristica, nessuna congettura.
La pipeline si articola in fasi, ciascuna una funzione pura da byte a dati strutturati:
```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]
```
Due backend indipendenti condividono la stessa prima metà (da ELF fino al riempimento dei cluster), poi si dividono per architettura: `internal/disasm` per ARM64, `internal/disasm/x86.go` per x86_64. Il decompilatore (`internal/decompiler`) gestisce entrambe le architetture tramite un IR unificato.
```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
```
## Confronto con 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) incorpora la Dart VM per deserializzare lo snapshot tramite i propri percorsi di codice. Fedeltà perfetta, ma richiede la compilazione di un Dart SDK corrispondente per ogni versione target — ed è solo per ARM64, senza supporto statico per x86_64. AOTopsy è l'unico analizzatore statico e indipendente dalla versione con un decompilatore nativo di pseudocodice e un'accuratezza ground-truth pubblicata.
AOTopsy analizza direttamente il formato binario. Nessuna VM, nessun SDK. Il compromesso: ogni modifica al formato tra le versioni di Dart deve essere modellata esplicitamente. Non esiste un runtime che la gestisca automaticamente.
## Comandi
### Pipeline completa
```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
```
Opzioni: `--out <dir>` (predefinito: `<basename>.aotopsy/`), `--quiet`, `--strict`, `--max-steps <n>`, `--k <n>` (profondità del contesto del segnale, predefinito 2), `--decompile`.
`--decompile` scrive pseudocodice Dart per funzione in `<out>/dart/`. È disattivato per
impostazione predefinita perché triplica circa la directory di output; ogni esecuzione senza di esso
lo segnala, così la funzionalità è individuabile anziché semplicemente presente.
### Diagnostica
```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
```
### Esportazione del codice sorgente Dart dell'intero progetto
Ricostruisce tutte le classi, i campi, i metodi, i getter, i setter e i costruttori in file `.dart` modulari mappati in base agli URI originali delle librerie:
```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
```
### Decompilatore nativo di alto livello (ARM64 + x86_64)
Produce codice Dart pulito e idiomatico direttamente dalle istruzioni macchina binarie:
- **Flusso di controllo strutturale**: iteratori `for-in`, `while`, `for`, `try-catch-finally` con delimitazione esatta del PC.
- **Linearizzazione async/await**: srotola le macchine a stati `_SuspendState` in `await future` e `await for` lineari.
- **Inlining delle lambda**: sintetizza callback arrow `(item) => process(item)` direttamente nei punti di chiamata.
- **Reticolo dei tipi**: propaga tipi Dart concreti (`String`, `int`, `UserModel`) attraverso i valori SSA senza eseguire una VM live.
- **Idiomi Dart**: null-aware (`?.`, `??`, `??=`), cascade (`..`), letterali Set/List/Map, interpolazione di stringhe (`"${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
```
Attenzione: `--all` senza un `--max` piccolo può richiedere ~64GB di RAM su un'app reale. Preferisci `--find`/`--func`/`--from-main`.
### Ghidra / IDA (solo ARM64)
```bash
aotopsy ghidra libapp.so # headless Ghidra with metadata injection
aotopsy ida libapp.so # headless IDA via idalib
```
Entrambi rifiutano input x86_64. Usa `decompile-native` per lo pseudocodice x86_64.
### Generazione di script 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
```
Consulta `FRIDA.md` per la guida completa.
### Riferimenti incrociati e tracciamento
```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
```
### Strumenti per il corpus
```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
```
## Artefatti di output
| File | Contenuto |
|------|----------|
| `functions.jsonl` | Nome, indirizzo, dimensione, owner, numero di parametri per funzione |
| `call_edges.jsonl` | Archi BL/BLR con target risolti e provenienza |
| `classes.jsonl` | Nomi dei campi, offset, dimensioni delle istanze per classe |
| `string_refs.jsonl` | Riferimenti a stringhe da caricamenti dell'object pool |
| `dispatch_table.jsonl`| Tipi di receiver della dispatch table inferiti e mappatura dei target |
| `signal.html` | Report dei segnali comportamentali con grafo di contesto |
| `dart_meta.json` | Metadati dello snapshot, flag dei puntatori compressi, layout THR |
| `flutter_meta.json` | Metadati unificati per Ghidra/IDA (solo ARM64) |
| `aotopsy.sarif` | Report dei risultati di sicurezza SARIF 2.1.0 (per GitHub Code Scanning) |
| `evidence.jsonl` | Modello di evidenza unificato con confidenza e provenienza per call site |
| `asm/*.txt` | Disassembly annotato per funzione |
| `asm/*.bin` | Byte delle istruzioni grezzi per funzione (entrambe le architetture) |
| `dart/*.dart` | Pseudocodice decompilato per funzione (con `--decompile`) |
| `cfg/*.dot` | CFG per funzione (con `--graph`) |
## Struttura del pacchetto
```
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)
```
Consulta `ARCHITECTURE.md` per un'analisi approfondita di ciascun pacchetto.
## Build
Richiede 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`
```
I test di integrazione risolvono il loro input da `internal/samplecorpus`, che cerca una directory `samples/`; non c'è nulla da impostare. `samples/` è esclusa da git, quindi un checkout che non ne contiene una salta quei test — ma un checkout che *ha* un corpus e a cui manca un campione registrato fallisce, perché un corpus divergente e uno assente significano cose diverse.
La CI pubblica esegue `gofmt`, `staticcheck`, build, vet e unit test in ordine casuale su linux/amd64, darwin/arm64 e windows/amd64, oltre a un job race+coverage con una soglia minima di copertura.
## Release e branch
AOTopsy utilizza un modello a due branch:
| Branch | Ruolo |
|--------|------|
| `main` | **Stabile.** Ogni commit è un release candidate squash-merged e verificato dai gate. Le release taggate (con binari precompilati multipiattaforma) vengono create da qui. |
| `develop` | **Rolling / nightly.** Dove atterrano per primi i piccoli commit quotidiani, le funzionalità e la ricerca. Può essere instabile tra un merge e l'altro. Raggruppato in `main` tramite una PR squash-merge una volta che i gate sono verdi. |
Contribuisci su `develop`; apri una PR verso `main` solo quando un blocco di lavoro è verificato dai gate.
I binari precompilati per Linux, macOS e Windows (amd64/arm64) sono allegati a ogni
[release GitHub](../../releases). AOTopsy è puro Go, quindi `make build` esegue la cross-compilazione in modo pulito per qualsiasi target.
Ogni archivio di release contiene anche `ghidra_scripts/` e `ida_scripts/` accanto al
binario, che è il layout che `aotopsy ghidra` e `aotopsy ida` individuano — così quei
comandi funzionano direttamente da un download scompattato, senza bisogno di un checkout.
## Limitazioni e ambito
AOTopsy dichiara chiaramente cosa recupera e cosa non recupera. Alcuni limiti sono di
ambito ingegneristico; altri sono **limiti invalicabili del formato AOT** — informazioni che il compilatore Dart rimuove nelle
build di release (PRODUCT), verificate rispetto al codice sorgente dell'SDK. Documentiamo i limiti invalicabili anziché fabbricare informazioni al loro posto.
**Limiti invalicabili AOT (verificati — non aspettarti che migliorino):**
- **I nomi dei campi di istanza sono assenti per circa il 97–99%.** `Precompiler::DropFields` mantiene i nomi dei campi
solo sotto `#if !defined(PRODUCT)`; un'app reale ha circa 233 oggetti `Field` con nome rispetto
a circa 16k sintetici. Il recupero basato sugli accessor (`get:`/`set:` portano ancora il nome) perfora
questo limite parzialmente (−11–22%, deterministico, mai indovinato); il resto è genuinamente perduto.
- **I nomi delle variabili locali e catturate sono perduti.** Resi come `local_*` / `tN`.
- **I target di dispatch veramente polimorfici non sono risolvibili staticamente.** BLR attraverso una
dispatch table / oggetto `Closure` dinamico è un limite AOT, non una lacuna dell'analisi; questi
vengono resi onestamente come `indirectCall` / `dynamicCall`. Vedi [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md#limits-of-this-method-honestly).
**Ambito ingegneristico:**
- **Solo AOT.** Nessun supporto JIT.
- **La decompilazione Ghidra/IDA è solo per ARM64.** x86_64 viene rifiutato con un errore chiaro — usa invece `decompile-native` (l'unico decompilatore statico per Flutter x86_64).
- **La decompilazione `--all` può mandare in crash l'host.** Un'app reale a dimensione piena richiede circa 64GB di RAM per `--all` senza limiti. Usa modalità mirate (`--find`, `--func`, `--from-main`) o limita con `--max`.
- **Il dispatch virtuale è invisibile alla raggiungibilità di `--from-main`.** I callback del ciclo di vita dei widget passano attraverso il dispatch del framework Flutter, non tramite istruzioni di chiamata diretta. Un'euristica basata sul tocco delle classi ne recupera alcuni, ma è una sovra-approssimazione. Usa Frida per il resto.
- **Ogni cambio di versione di Dart deve essere modellato.** Non c'è una VM che gestisca automaticamente i cambiamenti di formato. Lo snapshot porta un hash derivato da git, non un numero di versione, quindi il supporto è basato sulla struttura. Attualmente modellato: Dart 2.10 → 3.13.
- **I gemelli ground-truth non sono ridistribuibili** (build di produzione reali), quindi il
differenziale di recupero dei nomi viene eseguito localmente, non nella CI pubblica.
## Licenza
BSD-3-Clause. Le tabelle CID, gli offset dei campi THR e i nomi degli stub sono derivati dal [Dart SDK](https://github.com/dart-lang/sdk) (anch'esso BSD-3-Clause). Vedi `LICENSE` e `NOTICE`.