fare9/dragon-talesBiblioteca de análise binária construída sobre LLVM para desmontagem, lifting e execução simbólica de código de máquina em x86, ARM e RISC-V, com recuperação de CFG e resolução via Z3.
Uma biblioteca de análise binária para desmontagem, montagem e análise de código de máquina em múltiplas arquiteturas. Construída sobre o LLVM 21.
Recursos:
Function recuperada, ou um único bloco IGNIL achatado (sem necessidade de CFG), para LLVM IR, com um pipeline de otimização (mem2reg/instcombine/GVN/DCE) por cima.patLoadedImage: seções e segmentos PT_LOAD de ELF em seus endereços virtuais com permissões R/W/X, ponto de entrada, base da imagem, símbolos com flags de importação/exportação, e a arquitetura detectada automaticamente a partir do cabeçalho (sem necessidade de nomeá-la). loader::disassembleImage vai de um arquivo a um Graph populado em uma única chamada. Construído sobre o llvm::object do LLVM, portanto sem dependência extradisassembler — uma ferramenta de linha de comando que carrega um binário ELF ou PE e despeja a desmontagem, útil para inspeção rápida e scriptsdragon_c.h) e API Python (cffi) cobrindo a maior parte do conjunto de recursos acima (alguns cantos exclusivos de C++ — templates de DSL de correspondência de padrões, auxiliares de classificação de instruções específicos de arquitetura, e similares — estão documentados como tal em docs/cpp_api.md)As versões marcadas com tag incluem um arquivo SDK autocontido por plataforma
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) na
página de Releases do GitHub. O LLVM é vinculado estaticamente
às bibliotecas, portanto não é necessária uma instalação do LLVM no sistema
para usá-las; o Z3 é incluído junto. Cada arquivo contém:
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
Aponte a API Python para a biblioteca incluída com
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll conforme apropriado).
Para compilar a partir do código-fonte, em vez disso:
mkdir build && cd build
cmake ..
cmake --build .
Para executar os testes:
ctest --output-on-failure
Um punhado de testes de ida e volta semânticos x86 são caros: eles compilam JIT
o IR levantado e emulam os bytes brutos sob o Unicorn através de um grande
produto cartesiano de entradas de casos extremos (milhares de idas e voltas cada). Eles são
marcados com [.][expensive], o que os oculta da execução padrão do ctest para que ela
permaneça rápida. Execute-os explicitamente — normalmente em uma máquina mais potente ou em
CI — com:
./build/bin/dragon_tests "[expensive]"
No Windows, a descoberta de dependências em CMakeLists.txt precisa de algumas dicas,
porque está escrita para layouts de pacotes Linux: o Z3 é localizado através do módulo
FindZ3.cmake incluído no LLVM, e o Unicorn é localizado através do pkg-config.
Nenhum dos mecanismos sabe onde o vcpkg instala as coisas, e o LLVM é encontrado via
LLVM_DIR em vez do caminho do sistema. Fornecer três dicas resolve tudo.
Pré-requisitos
C:\llvm-21 (a versão pré-compilada
clang+llvm-*-x86_64-pc-windows-msvc funciona)1. Instalar as bibliotecas com o vcpkg (o triplet x64-windows; o pkgconf
fornece o executável pkg-config de que a descoberta do Unicorn precisa):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. As três dicas que o CMake precisa
| Dica | Finalidade | Valor de exemplo |
|---|---|---|
LLVM_DIR | localizar o LLVM 21 | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | permitir que FindZ3 veja a árvore do vcpkg | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | permitir que o Unicorn seja encontrado via pkg-config | .../tools/pkgconf/pkgconf.exe e .../installed/x64-windows/lib/pkgconfig |
3a. Configurar e compilar (um único 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
Uma configuração bem-sucedida 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. Ou use um preset (recomendado)
Salve as configurações uma vez em um CMakeUserPresets.json ao lado de CMakeLists.txt,
depois configure com uma única flag. Este arquivo contém caminhos específicos da máquina, então
mantenha-o fora do controle de versão (ele é ignorado pelo 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