fare9/dragon-talesBiblioteca de análisis binario construida sobre LLVM para desensamblar, elevar y ejecutar simbólicamente código máquina en x86, ARM y RISC-V, con recuperación de CFG y resolución mediante Z3.
Una biblioteca de análisis binario para desensamblar, ensamblar y analizar código máquina en múltiples arquitecturas. Construida sobre LLVM 21.
Características:
Function recuperada, o un único bloque IGNIL aplanado (sin necesidad de CFG), a LLVM IR, con un pipeline de optimización (mem2reg/instcombine/GVN/DCE) encima.patLoadedImage: secciones y segmentos PT_LOAD de ELF en sus direcciones virtuales con permisos R/W/X, punto de entrada, base de imagen, símbolos con indicadores de importación/exportación, y la arquitectura autodetectada desde la cabecera (sin necesidad de nombrarla). loader::disassembleImage va de un archivo a un Graph poblado en una sola llamada. Construido sobre llvm::object de LLVM, por lo que no hay dependencia adicionaldisassembler — una herramienta de línea de comandos que carga un binario ELF o PE y vuelca el desensamblado, útil para inspección rápida y scriptingdragon_c.h) y API de Python (cffi) que cubren la mayor parte del conjunto de características anterior (algunos rincones exclusivos de C++ — plantillas DSL de coincidencia de patrones, ayudantes de clasificación de instrucciones específicos de la arquitectura, y similares — están documentados como tales en docs/cpp_api.md)Las versiones etiquetadas incluyen un archivo SDK autocontenido por plataforma
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) en la
página de Releases de GitHub. LLVM está enlazado estáticamente en las
bibliotecas, por lo que no se requiere una instalación de LLVM en el sistema para usarlas; Z3 se incluye
junto a ellas. Cada archivo 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
Apunte la API de Python a la biblioteca incluida con
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll según corresponda).
Para compilar desde el código fuente en su lugar:
mkdir build && cd build
cmake ..
cmake --build .
Para ejecutar las pruebas:
ctest --output-on-failure
Un puñado de pruebas semánticas de ida y vuelta de x86 son costosas: compilan JIT el IR elevado y emulan los bytes sin procesar bajo Unicorn a través de un gran producto cruzado de entradas de casos límite (miles de idas y vueltas cada una). Están etiquetadas como [.][expensive], lo que las oculta de la ejecución predeterminada de ctest para que esta se mantenga rápida. Ejecútalas explícitamente —normalmente en una máquina más potente o en CI— con:
./build/bin/dragon_tests "[expensive]"
En Windows, la detección de dependencias en CMakeLists.txt necesita algunas indicaciones,
porque está escrita para la disposición de paquetes de Linux: Z3 se localiza a través del
módulo FindZ3.cmake incluido en LLVM, y Unicorn se localiza a través de pkg-config.
Ninguno de los dos mecanismos sabe dónde instala las cosas vcpkg, y LLVM se encuentra mediante
LLVM_DIR en lugar de la ruta del sistema. Proporcionar tres indicaciones soluciona todo.
Requisitos previos
C:\llvm-21 (la versión precompilada
clang+llvm-*-x86_64-pc-windows-msvc funciona)1. Instalar las bibliotecas con vcpkg (el triplete x64-windows; pkgconf
proporciona el ejecutable pkg-config que necesita la detección de Unicorn):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. Las tres pistas que CMake necesita
| Pista | Propósito | Valor de ejemplo |
|---|---|---|
LLVM_DIR | localizar LLVM 21 | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | permitir que FindZ3 vea el árbol de vcpkg | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | permitir que Unicorn se encuentre mediante pkg-config | .../tools/pkgconf/pkgconf.exe y .../installed/x64-windows/lib/pkgconfig |
3a. Configurar y compilar (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 configuración exitosa imprime:
-- 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. O usar un preset (recomendado)
Guarda la configuración una vez en un CMakeUserPresets.json junto a CMakeLists.txt,
y luego configura con un solo flag. Este archivo contiene rutas específicas de la máquina, así que
mantenlo fuera del control de versiones (está ignorado por 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
Notas