fare9/dragon-talesБиблиотека бинарного анализа, построенная на LLVM, для дизассемблирования, подъёма и символьного исполнения машинного кода на архитектурах x86, ARM и RISC-V, с восстановлением CFG и решением через Z3.
Библиотека бинарного анализа для дизассемблирования, ассемблирования и анализа машинного кода для нескольких архитектур. Построена на LLVM 21.
Возможности:
Function или отдельный уплощённый блок IGNIL (CFG не требуется) в LLVM IR с последующим конвейером оптимизаций (mem2reg/instcombine/GVN/DCE).patLoadedImage: секции и сегменты ELF PT_LOAD по их виртуальным адресам с правами R/W/X, точка входа, база образа, символы с флагами импорта/экспорта и архитектура, автоматически определённая по заголовку (указывать её не нужно). loader::disassembleImage переходит от файла к заполненному Graph за один вызов. Построено на llvm::object из LLVM, поэтому дополнительных зависимостей нетdisassembler — инструмент командной строки, который загружает бинарник ELF или PE и выводит дизассемблирование; полезен для быстрого просмотра и написания скриптовdragon_c.h) и Python API (cffi), покрывающие большую часть перечисленных выше возможностей (несколько углов, доступных только из C++ — шаблоны DSL для сопоставления с образцом, архитектурно-специфичные вспомогательные функции классификации инструкций и подобное — задокументированы как таковые в docs/cpp_api.md)Помеченные тегами релизы поставляются как самодостаточный архив SDK для каждой платформы
(dragon-<version>-{linux-x64,macos-arm64,windows-x64}.{tar.gz,zip}) на странице
GitHub Releases. LLVM статически слинкован в
библиотеки, поэтому для их использования установка системного LLVM не требуется; Z3 поставляется
в комплекте. Каждый архив содержит:
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
Укажите Python API на встроенную библиотеку с помощью
DRAGON_C_LIB=/path/to/lib/libdragon_c.so (.dylib/.dll в зависимости от платформы).
Чтобы собрать из исходников вместо этого:
mkdir build && cd build
cmake ..
cmake --build .
Для запуска тестов:
ctest --output-on-failure
Несколько семантических round-trip тестов для x86 дорогие: они JIT-компилируют
поднятый IR и эмулируют сырые байты под Unicorn на большом
перекрёстном произведении граничных входных данных (тысячи round-trip'ов каждый). Они
помечены тегом [.][expensive], что скрывает их от стандартного запуска ctest, чтобы он
оставался быстрым. Запускайте их явно — обычно на более мощной машине или в
CI — с помощью:
./build/bin/dragon_tests "[expensive]"
В Windows для обнаружения зависимостей в CMakeLists.txt требуется несколько подсказок,
поскольку он написан для структуры пакетов Linux: Z3 находится через встроенный
модуль LLVM FindZ3.cmake, а Unicorn — через pkg-config.
Ни один из этих механизмов не знает, куда vcpkg устанавливает пакеты, а LLVM находится через
LLVM_DIR, а не через системный путь. Указание трёх подсказок решает всё это.
Предварительные требования
C:\llvm-21 (подойдёт готовый
релиз clang+llvm-*-x86_64-pc-windows-msvc)1. Установите библиотеки с помощью vcpkg (триплет x64-windows; pkgconf
предоставляет исполняемый файл pkg-config, необходимый для обнаружения Unicorn):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. Три подсказки, которые нужны CMake
| Подсказка | Назначение | Пример значения |
|---|---|---|
LLVM_DIR | найти LLVM 21 | C:/llvm-21/lib/cmake/llvm |
CMAKE_PREFIX_PATH | позволить FindZ3 увидеть дерево vcpkg | C:/vcpkg/installed/x64-windows |
PKG_CONFIG_EXECUTABLE + PKG_CONFIG_PATH | позволить найти Unicorn через pkg-config | .../tools/pkgconf/pkgconf.exe и .../installed/x64-windows/lib/pkgconfig |
3a. Настройка и сборка (одна команда)
$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
Успешный запуск configure выводит:
-- 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. Или используйте пресет (рекомендуется)
Сохраните настройки один раз в CMakeUserPresets.json рядом с CMakeLists.txt,
затем выполните конфигурацию с помощью одного флага. Этот файл содержит пути, специфичные для конкретной машины, поэтому
не добавляйте его в систему контроля версий (он игнорируется 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
Примечания