
Analizador estático para instantáneas AOT de Flutter/Dart — recupera nombres de funciones, jerarquías de clases, grafos de llamadas y señales de comportamiento de libapp.so sin incrustar ni ejecutar la VM de Dart. Compatible con ARM64 y 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 analizador de snapshots AOT de Dart. Convierte `libapp.so` —el código Dart compilado dentro de un APK de release de Flutter— en nombres de funciones, diseños de clases, grafos de llamadas, señales de comportamiento y pseudocódigo legible. Sin Dart VM, sin compilación del SDK, sin fallback en tiempo de ejecución.
> **Aviso de fork:** AOTopsy es un fork de **unflutter**, originalmente creado por **Anthony Zboralski**. El repositorio original `zboralski/unflutter` ya no está disponible (eliminado por el autor); existe una continuación de la comunidad en [`KristijanZic/unflutter`](https://github.com/KristijanZic/unflutter). Todo el crédito por el parser de snapshots original, el deserializador de clústeres, la pipeline de desensamblado ARM64 y la integración con Ghidra/IDA pertenece al autor original. AOTopsy lo amplía con soporte para x86_64, un descompilador nativo, inferencia de tipos de programa completo, generación de scripts de Frida y documentación exhaustiva.
## Qué recupera
| Salida | Qué es |
|--------|-----------|
| Nombres de funciones | El nombre Dart original de cada función compilada |
| Estructuras de clases | Nombres de campos, desplazamientos en bytes, cadenas de herencia |
| Grafo de llamadas | Aristas de llamada directas (BL) e indirectas (BLR/dispatch) con procedencia |
| Referencias a cadenas | Qué funciones cargan qué literales de cadena desde el pool de objetos |
| Señales de comportamiento | Clasificación por palabras clave de criptografía, red, apuestas, SIM, ubicación, WebView, blockchain |
| Pseudocódigo | Salida descompilada neutral respecto a la arquitectura a partir de código máquina ARM64 o x86_64 |
| Exportación de código fuente Dart | Archivos `.dart` modulares de todo el proyecto reconstruidos con clases, campos y métodos |
Compatible con **ARM64** y **x86_64**. Cubre **Dart 2.10 hasta 3.13** (3.13.2 es la frontera estable actual) — cada versión modelada se parsea limpiamente en ambas arquitecturas, véase [COVERAGE.md](https://github.com/bronils/aotopsy/blob/main/COVERAGE.md) (93 compilaciones de muestra, 0 fallos).
## Precisión y honestidad
AOTopsy se mide contra la verdad de referencia, no se afirma sin más. Dos propiedades se verifican mediante
la suite de pruebas en cada cambio:
| Métrica | Valor | Qué significa |
|--------|-------|---------------|
| **Concordancia en la recuperación de nombres** | **90.2%** global (81.3% en la peor banda, umbral mínimo ≥ 0.81) en 44 compilaciones de referencia | Nombres de funciones recuperados comparados contra el propio `.symtab` ELF de cada compilación, la verdad de referencia externa — `TestSymtabDifferential`. Marcador completo por compilación: [BENCHMARK.md](https://github.com/bronils/aotopsy/blob/main/BENCHMARK.md) (`make bench`). |
| **Validez sintáctica del descompilador** | **100%** Dart válido | Cada función de pseudocódigo emitida se parsea como Dart — `TestDecompileQualityCorpus`. |
| **Tasa de fabricación** | **0%** | La regla §2: nunca emitir un nombre, tipo u objetivo de llamada adivinado como hecho. Los valores desconocidos se muestran con honestidad (`indirectCall`, `<unknown>`, `dynamic`). |
Los gemelos de verdad de referencia son compilaciones de producción reales que no podemos redistribuir, por lo que esas
verificaciones diferenciales se ejecutan **localmente**; la CI pública valida build, vet, `gofmt`,
`staticcheck`, pruebas unitarias (mezcladas) y un umbral de cobertura en toda la matriz
de plataformas. `samples/` no es redistribuible y está en gitignore, por lo que las pruebas dependientes de muestras
se omiten allí — pero solo cuando el corpus está completamente ausente; un corpus que está
presente y le falta una muestra registrada falla, porque esos casos significan cosas opuestas.
Cómo se mide cada número aquí (verdad de referencia, definiciones de métricas, reproducción): [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md). Véase
[SECURITY.md](https://github.com/bronils/aotopsy/blob/main/SECURITY.md) para la verificación del binario de release y el alcance honesto a continuación.
## Inicio rápido
```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) para ver un recorrido de cinco minutos sobre una instantánea real, o `WORKFLOW.md` para conocer la metodología paso a paso cuando tengas un APK sin procesar y no sepas por dónde empezar.
## Cómo funciona
AOTopsy trata la instantánea AOT de Dart como una gramática binaria determinista. Cada byte tiene exactamente una interpretación correcta dadas las restricciones adecuadas (estructura ELF, magic de la instantánea, hash de versión, tabla CID, codificación de clústeres). El analizador aplica restricciones hasta que solo sobrevive una interpretación — sin heurísticas, sin adivinanzas.
El pipeline se ejecuta por etapas, cada una una función pura de bytes a datos estructurados:
```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]
```
Dos backends independientes comparten la misma mitad frontal (ELF hasta el llenado de clústeres), luego se dividen por arquitectura: `internal/disasm` para ARM64, `internal/disasm/x86.go` para x86_64. El descompilador (`internal/decompiler`) maneja ambas arquitecturas a través de un IR unificado.
```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
```
## Comparación 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 VM de Dart para deserializar el snapshot a través de sus propias rutas de código. Fidelidad perfecta, pero requiere compilar un SDK de Dart compatible para cada versión objetivo — y es solo para ARM64, sin soporte estático para x86_64. AOTopsy es el único analizador estático e independiente de la versión con un descompilador de pseudocódigo nativo y una precisión de referencia publicada.
AOTopsy analiza el formato binario directamente. Sin VM, sin SDK. La contrapartida: cada cambio de formato entre versiones de Dart debe modelarse explícitamente. No hay un entorno de ejecución que lo maneje automáticamente.
## Comandos
### Pipeline completo
```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
```
Opciones: `--out <dir>` (predeterminado: `<basename>.aotopsy/`), `--quiet`, `--strict`, `--max-steps <n>`, `--k <n>` (profundidad del contexto de señal, predeterminado 2), `--decompile`.
`--decompile` escribe pseudocódigo Dart por función en `<out>/dart/`. Está desactivado por defecto porque aproximadamente triplica el directorio de salida; cada ejecución sin él lo indica, de modo que la capacidad es descubrible en lugar de meramente estar presente.
### Diagnóstico
```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
```
### Exportación de código fuente Dart de todo el proyecto
Reconstruye todas las clases, campos, métodos, getters, setters y constructores en archivos `.dart` modulares asignados según los URIs de biblioteca originales:
```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
```
### Descompilador nativo de alto nivel (ARM64 + x86_64)
Produce código Dart limpio e idiomático directamente a partir de instrucciones máquina del binario:
- **Flujo de control estructural**: iteradores `for-in`, `while`, `for`, `try-catch-finally` con delimitación exacta de PC.
- **Linealización de Async/Await**: Desenvuelve las máquinas de estado `_SuspendState` en `await future` y `await for` lineales.
- **Inlining de lambdas**: Sintetiza callbacks de flecha `(item) => process(item)` directamente en los puntos de llamada.
- **Retículo de tipos**: Propaga tipos Dart concretos (`String`, `int`, `UserModel`) a través de valores SSA sin ejecutar una VM en vivo.
- **Idioms de Dart**: Null-aware (`?.`, `??`, `??=`), cascade (`..`), literales Set/List/Map, interpolación de cadenas (`"${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
```
Advertencia: `--all` sin un `--max` pequeño puede requerir ~64GB de RAM en una aplicación real. Prefiere `--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
```
Ambos rechazan la entrada x86_64. Utilice `decompile-native` para pseudocódigo x86_64.
### Generación de scripts de 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` para la guía completa.
### Referencias cruzadas y trazado
```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
```
### Herramientas de 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
```
## Artefactos de salida
| Archivo | Contenido |
|------|----------|
| `functions.jsonl` | Nombre, dirección, tamaño, propietario, número de parámetros por función |
| `call_edges.jsonl` | Aristas BL/BLR con destinos resueltos y procedencia |
| `classes.jsonl` | Nombres de campos, desplazamientos, tamaños de instancia por clase |
| `string_refs.jsonl` | Referencias de cadenas desde cargas del pool de objetos |
| `dispatch_table.jsonl`| Tipos de receptor de la tabla de despacho inferidos y mapeo de destinos |
| `signal.html` | Informe de señales de comportamiento con grafo de contexto |
| `dart_meta.json` | Metadatos del snapshot, indicador de punteros comprimidos, diseño de THR |
| `flutter_meta.json` | Metadatos unificados para Ghidra/IDA (solo ARM64) |
| `aotopsy.sarif` | Informe de hallazgos de seguridad SARIF 2.1.0 (para GitHub Code Scanning) |
| `evidence.jsonl` | Modelo de evidencia unificado con confianza y procedencia por sitio de llamada |
| `asm/*.txt` | Desensamblado anotado por función |
| `asm/*.bin` | Bytes de instrucción sin procesar por función (ambas arquitecturas) |
| `dart/*.dart` | Pseudocódigo descompilado por función (con `--decompile`) |
| `cfg/*.dot` | CFG por función (con `--graph`) |
## Estructura del paquete
```
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` para obtener un análisis detallado de cada paquete.
## Compilación
Requiere 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`
```
Las pruebas de integración resuelven su entrada desde `internal/samplecorpus`, que busca un directorio `samples/`; no hay nada que configurar. `samples/` está en gitignore, por lo que una copia de trabajo sin él omite esas pruebas — pero una copia de trabajo que *tiene* un corpus y le falta una muestra registrada falla, porque un corpus desviado y uno ausente significan cosas distintas.
La CI pública ejecuta `gofmt`, `staticcheck`, build, vet y pruebas unitarias aleatorizadas en linux/amd64, darwin/arm64 y windows/amd64, además de un trabajo de race+cobertura con un umbral mínimo de cobertura.
## Releases y ramas
AOTopsy utiliza un modelo de dos ramas:
| Rama | Rol |
|--------|------|
| `main` | **Estable.** Cada commit es un candidato a release verificado por las compuertas y fusionado con squash. Las releases etiquetadas (con binarios multiplataforma precompilados) se cortan desde aquí. |
| `develop` | **Continua / nocturna.** Donde aterrizan primero los commits pequeños del día a día, las funcionalidades y la investigación. Puede ser inestable entre fusiones. Se integra por lotes en `main` mediante un PR de squash-merge una vez que las compuertas están en verde. |
Contribuye contra `develop`; abre un PR hacia `main` solo cuando un lote de trabajo esté verificado por las compuertas.
Los binarios precompilados para Linux, macOS y Windows (amd64/arm64) se adjuntan a cada
[release de GitHub](../../releases). AOTopsy es Go puro, por lo que `make build` compila de forma cruzada limpiamente para cualquier objetivo.
Cada archivo de release también incluye `ghidra_scripts/` e `ida_scripts/` junto al
binario, que es la disposición que descubren `aotopsy ghidra` y `aotopsy ida` — así que esos
comandos funcionan directamente desde una descarga descomprimida, sin necesidad de una copia de trabajo.
## Limitaciones y alcance
AOTopsy declara con claridad qué recupera y qué no. Algunos límites son de alcance de
ingeniería; otros son **límites duros del formato AOT** — información que el compilador de Dart elimina en
las compilaciones release (PRODUCT), verificada contra el código fuente del SDK. Documentamos los límites en lugar de
fabricar por encima de ellos.
**Límites duros de AOT (verificados — no esperes que mejoren):**
- **Los nombres de campos de instancia están ausentes en ~97–99%.** `Precompiler::DropFields` conserva los nombres
de campo solo bajo `#if !defined(PRODUCT)`; una aplicación real tiene ~233 objetos `Field` con nombre frente a
~16k sintéticos. La recuperación basada en accesores (`get:`/`set:` aún llevan el nombre) perfora
esto parcialmente (−11–22%, determinista, nunca adivinado); el resto está genuinamente perdido.
- **Los nombres de variables locales y capturadas se han perdido.** Se representan como `local_*` / `tN`.
- **Los destinos de despacho verdaderamente polimórficos no son resolubles estáticamente.** BLR a través de una
tabla de despacho / objeto `Closure` dinámico es un límite de AOT, no una laguna de análisis; estos
se representan honestamente como `indirectCall` / `dynamicCall`. Consulta [METHODOLOGY.md](https://github.com/bronils/aotopsy/blob/main/METHODOLOGY.md#limits-of-this-method-honestly).
**Alcance de ingeniería:**
- **Solo AOT.** Sin soporte para JIT.
- **La descompilación de Ghidra/IDA es solo para ARM64.** x86_64 se rechaza con un error claro — usa `decompile-native` en su lugar (el único descompilador estático de Flutter para x86_64).
- **La descompilación con `--all` puede colapsar el host.** Una aplicación real de tamaño completo necesita ~64GB de RAM para `--all` sin límites. Usa modos dirigidos (`--find`, `--func`, `--from-main`) o limita con `--max`.
- **El despacho virtual es invisible para la alcanzabilidad de `--from-main`.** Las devoluciones de llamada del ciclo de vida de los widgets pasan por el despacho del framework de Flutter, no por instrucciones de llamada directas. Una heurística de toque de clase recupera algunas, pero es una sobreaproximación. Usa Frida para el resto.
- **Cada cambio de versión de Dart debe modelarse.** No hay una VM que maneje los cambios de formato automáticamente. El snapshot lleva un hash derivado de git, no un número de versión, por lo que el soporte se basa en la estructura. Actualmente modelado: Dart 2.10 → 3.13.
- **Los gemelos de verdad fundamental no son redistribuibles** (compilaciones de producción reales), por lo que el
diferencial de recuperación de nombres se ejecuta localmente, no en la CI pública.
## Licencia
BSD-3-Clause. Las tablas CID, los desplazamientos de campos THR y los nombres de stubs se derivan del [Dart SDK](https://github.com/dart-lang/sdk) (también BSD-3-Clause). Consulta `LICENSE` y `NOTICE`.