fare9/dragon-talesBibliothèque d'analyse binaire construite sur LLVM pour le désassemblage, le lifting et l'exécution symbolique de code machine sur x86, ARM et RISC-V, avec récupération de CFG et résolution par Z3.
Une bibliothèque d'analyse binaire pour le désassemblage, l'assemblage et l'analyse de code machine sur plusieurs architectures. Basée sur LLVM 21.
Fonctionnalités :
Function récupérée, ou un unique bloc IGNIL aplati (sans CFG nécessaire), vers du LLVM IR, avec un pipeline d'optimisation (mem2reg/instcombine/GVN/DCE) par-dessus.patLoadedImage : sections et segments ELF PT_LOAD à leurs adresses virtuelles avec permissions R/W/X, point d'entrée, base d'image, symboles avec indicateurs d'import/export, et l'architecture auto-détectée depuis l'en-tête (sans besoin de la nommer). loader::disassembleImage passe d'un fichier à un Graph peuplé en un seul appel. Basé sur llvm::object de LLVM, donc aucune dépendance supplémentairedisassembler — un outil en ligne de commande qui charge un binaire ELF ou PE et vide le désassemblage, utile pour une inspection rapide et le scriptingdragon_c.h) et API Python (cffi) couvrant la majeure partie de l'ensemble de fonctionnalités ci-dessus (quelques recoins réservés au C++ — modèles DSL de correspondance de motifs, assistants de classification d'instructions spécifiques à l'architecture, et similaires — sont documentés comme tels dans docs/cpp_api.md)Les versions étiquetées fournissent une archive SDK autonome par plateforme
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) sur la
page GitHub Releases. LLVM est lié statiquement dans les
bibliothèques, donc aucune installation système de LLVM n'est requise pour
les utiliser ; Z3 est fourni à côté. Chaque archive contient :
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
Pointez l'API Python vers la bibliothèque fournie avec
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll selon le cas).
Pour compiler à partir des sources à la place :
mkdir build && cd build
cmake ..
cmake --build .
Pour exécuter les tests :
ctest --output-on-failure
Quelques tests sémantiques aller-retour x86 sont coûteux : ils compilent à la volée l'IR soulevé et émulent les octets bruts sous Unicorn sur un large produit cartésien d'entrées de cas limites (des milliers d'aller-retours chacun). Ils sont étiquetés [.][expensive], ce qui les masque de l'exécution ctest par défaut afin qu'elle reste rapide. Exécutez-les explicitement — généralement sur une machine plus puissante ou en CI — avec :
./build/bin/dragon_tests "[expensive]"
Sous Windows, la découverte des dépendances dans CMakeLists.txt nécessite quelques indications,
car elle est écrite pour les dispositions de paquets Linux : Z3 est localisé via le module
FindZ3.cmake fourni avec LLVM, et Unicorn est localisé via pkg-config.
Aucun de ces mécanismes ne sait où vcpkg installe les choses, et LLVM est trouvé via
LLVM_DIR plutôt que par le chemin système. Fournir trois indications résout tout cela.
Prérequis
C:\llvm-21 (la version précompilée
clang+llvm-*-x86_64-pc-windows-msvc fonctionne)1. Installer les bibliothèques avec vcpkg (le triplet x64-windows ; pkgconf
fournit l'exécutable pkg-config dont la découverte d'Unicorn a besoin) :
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. Les trois indications dont CMake a besoin
| Indication | Objectif | Exemple de valeur |
|---|---|---|
LLVM_DIR | localiser LLVM 21 | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | permettre à FindZ3 de voir l'arborescence vcpkg | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | permettre à Unicorn d'être trouvé via pkg-config | .../tools/pkgconf/pkgconf.exe et .../installed/x64-windows/lib/pkgconfig |
3a. Configurer et compiler (une seule commande)
$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
Une configuration réussie affiche :
-- 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. Ou utilisez un preset (recommandé)
Enregistrez les paramètres une fois dans un fichier CMakeUserPresets.json à côté de CMakeLists.txt,
puis configurez avec un seul indicateur. Ce fichier contient des chemins spécifiques à la machine, donc
gardez-le hors du contrôle de version (il est ignoré par 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
Remarques