fare9/dragon-talesLLVM上に構築されたバイナリ解析ライブラリで、x86、ARM、RISC-Vにわたる機械語の逆アセンブル、リフティング、シンボリック実行を可能にし、CFG復元とZ3求解を備えています。
複数のアーキテクチャにわたるマシンコードの逆アセンブル、アセンブル、解析を行うためのバイナリ解析ライブラリ。LLVM 21上に構築されています。
機能:
Function、または単一の平坦化されたIGNILブロック(CFG不要)をLLVM IRにリフトアップし、その上で最適化パイプライン(mem2reg/instcombine/GVN/DCE)を適用.patシグネチャデータベースから既知の関数を識別LoadedImageにパース:セクションおよびELFのPT_LOADセグメントを仮想アドレス上にR/W/Xパーミッション付きで配置し、エントリポイント、イメージベース、インポート/エクスポートフラグ付きのシンボル、そしてヘッダから自動検出されたアーキテクチャ(指定不要)を提供。loader::disassembleImageはファイルから1回の呼び出しで構築済みのGraphを生成。LLVMのllvm::object上に構築されているため、追加の依存関係は不要disassembler CLI — ELFまたはPEバイナリをロードして逆アセンブル結果をダンプするコマンドラインツール。迅速な検査やスクリプト作成に有用dragon_c.h)およびPython API(cffi)が上記の機能セットの大部分をカバー(パターンマッチングDSLテンプレート、アーキテクチャ固有の命令分類ヘルパーなど、一部のC++専用の領域は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
x86のセマンティックなラウンドトリップテストのうち、いくつかは高コストです。これらはリフトされたIRをJITコンパイルし、Unicorn上で生のバイト列を大規模なエッジケース入力のクロス積（それぞれ数千回のラウンドトリップ）にわたってエミュレートします。これらには[.][expensive]タグが付いており、デフォルトのctest実行からは除外されるため、実行は高速に保たれます。これらを明示的に実行するには（通常はより強力なマシン上またはCIで）、次のようにします:
./build/bin/dragon_tests "[expensive]"
Windows では、CMakeLists.txt 内の依存関係検出にいくつかのヒントが必要です。
これは Linux のパッケージレイアウト向けに書かれているためです。Z3 は LLVM に
同梱された FindZ3.cmake モジュールを通じて検出され、Unicorn は pkg-config
を通じて検出されます。どちらの仕組みも vcpkg がどこにインストールするかを
認識しておらず、LLVM はシステムパスではなく LLVM_DIR を介して検出されます。
3 つのヒントを指定すれば、すべて解決します。
前提条件
C:\llvm-21。ビルド済みの
clang+llvm-*-x86_64-pc-windows-msvc リリースで動作します)1. vcpkg でライブラリをインストールする (x64-windows トリプレット。pkgconf
が Unicorn の検出に必要な pkg-config 実行ファイルを提供します):
vcpkg install z3:x64-windows unicorn:x64-windows pkgconf:x64-windows
2. CMakeが必要とする3つのヒント
| ヒント | 目的 | 値の例 |
|---|---|---|
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 | pkg-config経由でUnicornを検出できるようにする | .../tools/pkgconf/pkgconf.exe および .../installed/x64-windows/lib/pkgconfig |
3a. 構成とビルド（1コマンド）
$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
A successful configure prints:
-- 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. プリセットを使用する（推奨）
設定を CMakeLists.txt の隣にある CMakeUserPresets.json に一度保存し、
単一のフラグで構成します。このファイルにはマシン固有のパスが含まれるため、
バージョン管理の対象外にしてください（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
注意事項
パスはお使いのマシンに合わせて調整してください。vcpkg が別の場所にある場合は、それに応じて %VCPKG_ROOT% を設定してください。LLVM を別の場所に展開した場合は、そのツリーの lib/cmake/llvm を指すように LLVM_DIR を設定してください。
ここでは vcpkg のツールチェーンファイル（-DCMAKE_TOOLCHAIN_FILE=.../vcpkg.cmake）を渡さないでください。これはパッケージ検索を制限し、vcpkg の外部にある LLVM を CMake が見つけられなくしてしまいます。これはこのプロジェクトにおける通常のセットアップです。
Unicorn はオプションです。動作する pkg-config がない場合は単に無効化され、tests/semantic/ のラウンドトリップテストのみがスキップされます。一方、Z3 は DRAGON_USE_Z3=ON の場合は常に必須です。
常に Release 構成でビルドしてください。 ビルド済みの clang+llvm-*-windows-msvc パッケージには Release ライブラリのみが含まれており、これらは動的リリース CRT（/MD）を使用します。Visual Studio ジェネレーターは --config が指定されない場合にデフォルトで Debug（/MDd）になり、Debug のプロジェクトコードを Release の LLVM に対してリンクすると、数百もの LNK2038 ランタイムライブラリ / _ITERATOR_DEBUG_LEVEL の不一致が発生し、最終的に LNK1319 で終わります。すべての cmake --build で --config Release を渡してください（または /MD でもある RelWithDebInfo を使用してください）:
cmake --build build --config Release -j
include/ C++ public headers (dragon/)
lib/ C++ implementation
c_shim/ C API (dragon_c.h + libdragon_c.so)
python/ Python API (cffi, wraps the C shim)
tool/ CLI tools (disassembler, opcode_audit)
tests/ Catch2 test suite
docs/ API documentation, examples, and the manual
公開ヘッダーは include/dragon/ 配下にあり、領域ごとにグループ化されています
（disassembler/、lifters/、analysis/、loader/、sigs/）。完全なサーフェスについては
以下のAPI ドキュメントを参照してください。
すべての API レイヤーの完全な例は docs/ にあります：
docs/cpp_api.md — C++ APIdocs/c_api.md — C シム APIdocs/python_api.md — Python APIIGNIL.md — IGNIL の設計と実装ガイドクラス別ではなくタスク別に整理された実践的なウォークスルーは
docs/manual/ にあります — 生のバイト列から IGNIL と LLVM
IR を経てシンボリック実行まで。
C++
#include <dragon/disassembler/Disassembler.hpp>
dragon::Configuration config;
dragon::Disassembler dis(dragon::Architecture::X86_64, config);
auto instructions = dis.disassemble(bytes, base_address);
for (const auto& insn : instructions)
std::cout << std::hex << insn.address() << " " << insn.disassembly() << "\n";
Python
import sys
sys.path.insert(0, 'python')
import dragon