fare9/dragon-talesEine auf LLVM basierende Bibliothek zur Binäranalyse für das Disassemblieren, Lifting und symbolische Ausführen von Maschinencode über x86, ARM und RISC-V hinweg, mit CFG-Rekonstruktion und Z3-Solving.
Eine Bibliothek zur Binäranalyse für das Disassemblieren, Assemblieren und Analysieren von Maschinencode über mehrere Architekturen hinweg. Basiert auf LLVM 21.
Funktionen:
Function oder einen einzelnen abgeflachten IGNIL-Block (kein CFG erforderlich) nach LLVM IR an, mit einer Optimierungspipeline (mem2reg/instcombine/GVN/DCE) obendrauf.pat-Signaturdatenbanken identifizierenLoadedImage parsen: Sektionen und ELF-PT_LOAD-Segmente an ihren virtuellen Adressen mit R/W/X-Berechtigungen, Einstiegspunkt, Image Base, Symbole mit Import-/Export-Flags und die aus dem Header automatisch erkannte Architektur (keine Angabe erforderlich). loader::disassembleImage geht von einer Datei zu einem befüllten Graph in einem einzigen Aufruf. Basiert auf LLVMs llvm::object, daher keine zusätzliche Abhängigkeitdisassembler-CLI — ein Kommandozeilenwerkzeug, das eine ELF- oder PE-Binärdatei lädt und die Disassemblierung ausgibt, nützlich für schnelle Inspektion und Skriptingdragon_c.h) und Python-API (cffi), die den Großteil der oben genannten Funktionalität abdecken (einige wenige rein C++-spezifische Ecken — Pattern-Matching-DSL-Templates, architekturspezifische Instruktionsklassifizierungs-Helfer und Ähnliches — sind als solche in docs/cpp_api.md dokumentiert)Getaggte Releases liefern ein eigenständiges SDK-Archiv pro Plattform
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) auf der
GitHub-Releases-Seite. LLVM ist statisch in die
Bibliotheken eingebunden, sodass keine System-LLVM-Installation erforderlich ist, um sie zu verwenden; Z3 wird
mitgeliefert. Jedes Archiv enthält:
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
Richte die Python-API mit
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll je nach Bedarf) auf die mitgelieferte Bibliothek aus.
Um stattdessen aus dem Quellcode zu bauen:
mkdir build && cd build
cmake ..
cmake --build .
Um die Tests auszuführen:
ctest --output-on-failure
Eine Handvoll x86-Semantik-Roundtrip-Tests sind teuer: Sie JIT-kompilieren die geliftete IR und emulieren die Rohbytes unter Unicorn über ein großes Kreuzprodukt von Edge-Case-Eingaben (Tausende von Roundtrips jeweils). Sie sind mit [.][expensive] getaggt, was sie aus dem standardmäßigen ctest-Lauf ausblendet, damit dieser schnell bleibt. Führen Sie sie explizit aus – typischerweise auf einer leistungsfähigeren Maschine oder in der CI – mit:
./build/bin/dragon_tests "[expensive]"
Unter Windows benötigt die Abhängigkeitserkennung in CMakeLists.txt einige Hinweise,
da sie für Linux-Paketlayouts geschrieben ist: Z3 wird über LLVMs
mitgeliefertes FindZ3.cmake-Modul gefunden, und Unicorn wird über pkg-config
gefunden. Keiner der beiden Mechanismen weiß, wohin vcpkg Dinge installiert, und LLVM wird
über LLVM_DIR statt über den Systempfad gefunden. Das Angeben von drei Hinweisen behebt all das.
Voraussetzungen
C:\llvm-21 (das vorgebaute
clang+llvm-*-x86_64-pc-windows-msvc-Release funktioniert)1. Die Bibliotheken mit vcpkg installieren (das Triplet x64-windows; pkgconf
stellt die pkg-config-Executable bereit, die die Unicorn-Erkennung benötigt):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. Die drei Hinweise, die CMake benötigt
| Hinweis | Zweck | Beispielwert |
|---|---|---|
LLVM_DIR | LLVM 21 lokalisieren | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | FindZ3 den vcpkg-Baum sehen lassen | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | Unicorn über pkg-config auffindbar machen | .../tools/pkgconf/pkgconf.exe und .../installed/x64-windows/lib/pkgconfig |
3a. Konfigurieren und bauen (ein Befehl)
$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
Eine erfolgreiche Konfiguration gibt Folgendes aus:
-- 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. Oder verwenden Sie ein Preset (empfohlen)
Speichern Sie die Einstellungen einmalig in einer CMakeUserPresets.json neben CMakeLists.txt
und konfigurieren Sie dann mit einem einzigen Flag. Diese Datei enthält maschinenspezifische Pfade, daher
halten Sie sie aus der Versionskontrolle heraus (sie ist git-ignoriert).
{
"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
Hinweise