fare9/dragon-talesLibreria di analisi binaria basata su LLVM per il disassemblaggio, il lifting e l'esecuzione simbolica di codice macchina su x86, ARM e RISC-V, con recupero del CFG e risoluzione tramite Z3.
Una libreria di analisi binaria per il disassemblaggio, l'assemblaggio e l'analisi del codice macchina su più architetture. Basata su LLVM 21.
Funzionalità:
Function recuperata, o un singolo blocco IGNIL appiattito (senza bisogno di CFG), a LLVM IR, con una pipeline di ottimizzazione (mem2reg/instcombine/GVN/DCE) al di sopra.patLoadedImage: sezioni e segmenti ELF PT_LOAD ai loro indirizzi virtuali con permessi R/W/X, entry point, image base, simboli con flag di import/export, e l'architettura rilevata automaticamente dall'header (senza bisogno di specificarla). loader::disassembleImage va da un file a un Graph popolato in una sola chiamata. Basato su llvm::object di LLVM, quindi nessuna dipendenza aggiuntivadisassembler — uno strumento da riga di comando che carica un binario ELF o PE e mostra il disassemblaggio, utile per un'ispezione rapida e per gli scriptdragon_c.h) e API Python (cffi) che coprono la maggior parte delle funzionalità sopra (alcuni angoli solo C++ — template DSL di pattern-matching, helper di classificazione delle istruzioni specifici per architettura, e simili — sono documentati come tali in docs/cpp_api.md)Le release con tag includono un archivio SDK autonomo per piattaforma
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) sulla
pagina GitHub Releases. LLVM è linkato staticamente nelle
librerie, quindi non è richiesta un'installazione di LLVM di sistema per
utilizzarle; Z3 è incluso insieme. Ogni archivio contiene:
lib/ libdragon + libdragon_c (shared) and the bundled Z3 runtime
bin/ the `disassembler` CLI (plus the DLLs on Windows)
include/ the C++ headers (dragon/...) and the C-shim header (dragon/dragon_c.h)
share/dragon/python/dragon.py the Python API
Indica all'API Python la libreria inclusa con
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll a seconda dei casi).
Per compilare dai sorgenti, invece:
mkdir build && cd build
cmake ..
cmake --build .
Per eseguire i test:
ctest --output-on-failure
Un pugno di test semantici di round-trip x86 sono costosi: compilano JIT l'IR sollevato ed emulano i byte grezzi sotto Unicorn attraverso un ampio prodotto cartesiano di input di casi limite (migliaia di round-trip ciascuno). Sono contrassegnati con [.][expensive], il che li nasconde dall'esecuzione predefinita di ctest in modo che rimanga veloce. Eseguirli esplicitamente — tipicamente su una macchina più potente o in CI — con:
./build/bin/dragon_tests "[expensive]"
Su Windows il rilevamento delle dipendenze in CMakeLists.txt richiede alcuni suggerimenti,
poiché è scritto per i layout dei pacchetti Linux: Z3 viene individuato tramite il modulo
FindZ3.cmake incluso in LLVM, e Unicorn viene individuato tramite pkg-config.
Nessuno dei due meccanismi sa dove vcpkg installa le cose, e LLVM viene trovato tramite
LLVM_DIR anziché il percorso di sistema. Fornire tre suggerimenti risolve tutto.
Prerequisiti
C:\llvm-21 (la release precompilata
clang+llvm-*-x86_64-pc-windows-msvc funziona)1. Installare le librerie con vcpkg (il triplet x64-windows; pkgconf
fornisce l'eseguibile pkg-config necessario al rilevamento di Unicorn):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. I tre suggerimenti di cui CMake ha bisogno
| Suggerimento | Scopo | Valore di esempio |
|---|---|---|
LLVM_DIR | individuare LLVM 21 | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | consentire a FindZ3 di vedere l'albero vcpkg | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | consentire a Unicorn di essere trovato tramite pkg-config | .../tools/pkgconf/pkgconf.exe e .../installed/x64-windows/lib/pkgconfig |
3a. Configurare e compilare (un solo comando)
$env:PKG_CONFIG_PATH = "C:/vcpkg/installed/x64-windows/lib/pkgconfig"
cmake -S . -B build `
-DLLVM_DIR=C:/llvm-21/lib/cmake/llvm `
-DCMAKE_PREFIX_PATH=C:/vcpkg/installed/x64-windows `
-DPKG_CONFIG_EXECUTABLE=C:/vcpkg/installed/x64-windows/tools/pkgconf/pkgconf.exe `
-DDRAGON_USE_Z3=ON -DDRAGON_USE_UNICORN=ON
cmake --build build --config Release
Una configurazione riuscita stampa:
-- Found LLVM 21.1.8 at C:/llvm-21/lib/cmake/llvm
-- Found Z3 5.0.0 at C:/vcpkg/installed/x64-windows/lib/libz3.lib
-- Found Unicorn 2.1.4
3b. Oppure usa un preset (consigliato)
Salva le impostazioni una volta in un file CMakeUserPresets.json accanto a CMakeLists.txt,
poi configura con un singolo flag. Questo file contiene percorsi specifici della macchina, quindi
tienilo fuori dal controllo di versione (è ignorato da git).
{
"version": 3,
"configurePresets": [
{
"name": "win-vcpkg",
"generator": "Visual Studio 17 2022",
"architecture": "x64",
"binaryDir": "${sourceDir}/build",
"cacheVariables": {
"LLVM_DIR": "C:/llvm-21/lib/cmake/llvm",
"CMAKE_PREFIX_PATH": "C:/vcpkg/installed/x64-windows",
"PKG_CONFIG_EXECUTABLE": "C:/vcpkg/installed/x64-windows/tools/pkgconf/pkgconf.exe",
"DRAGON_USE_Z3": "ON",
"DRAGON_USE_UNICORN": "ON"
},
"environment": {
"PKG_CONFIG_PATH": "C:/vcpkg/installed/x64-windows/lib/pkgconfig"
}
}
],
"buildPresets": [
{ "name": "win-vcpkg", "configurePreset": "win-vcpkg", "configuration": "Release" }
]
}
cmake --preset win-vcpkg
cmake --build build --config Release
Note