dragon-tales

कई आर्किटेक्चर पर मशीन कोड को डिसअसेम्बल, असेंबल और विश्लेषण करने के लिए एक बाइनरी विश्लेषण लाइब्रेरी। LLVM 21 पर आधारित।

विशेषताएँ:

• छह आर्किटेक्चर पर डिसअसेम्बली (लीनियर स्वीप और रिकर्सिव ट्रैवर्सल) और असेंबली
• CFG और फ़ंक्शन रिकवरी
• IGNIL — आर्किटेक्चर-स्वतंत्र विश्लेषण के लिए एक हल्की इंटरमीडिएट भाषा
• IGNIL पीफ़होल सिम्प्लिफ़ायर — ब्लॉक-लोकल कॉन्स्टेंट फ़ोल्डिंग, बीजगणितीय सर्वसमिकाएँ, डेड-टेम्प एलिमिनेशन
• बैकवर्ड स्लाइसर — जॉइन नोड्स को पार किए बिना IGNIL CFG के माध्यम से मानों का प्रसार करता है
• LLVMLifter — एक रिकवर किए गए Function, या एक एकल फ़्लैटन किए गए IGNIL ब्लॉक (CFG की आवश्यकता नहीं) को LLVM IR में लिफ़्ट करता है, साथ में एक ऑप्टिमाइज़ेशन पाइपलाइन (mem2reg/instcombine/GVN/DCE) भी
• Z3 एकीकरण — एक स्लाइस किए गए एक्सप्रेशन को Z3 बिटवेक्टर फ़ॉर्मूले में लोअर करें, उसके द्वारा लिए जा सकने वाले ठोस मानों की गणना करें, या एक अद्वितीय मान के लिए हल करें
• सिंबॉलिक एक्ज़ीक्यूशन — रजिस्टरों और मेमोरी को ठोस या सिंबॉलिक रूप से सीड करके Z3 बिटवेक्टरों पर एक IGNIL ब्लॉक चलाएँ: एक ऐसा इनपुट हल करें जो किसी जाँच को पास कर दे, सिद्ध करें कि एक ऑब्फ़स्केटेड एक्सप्रेशन वास्तव में क्या गणना करता है, और एक कंप्यूटेड जंप (जंप टेबल, VM डिस्पैच) को उन ठोस पतों तक रिज़ॉल्व करें जिन तक वह पहुँच सकता है
• SwitchDetector — एक स्लाइस किए गए जंप टारगेट से जंप-टेबल इनडायरेक्ट-ब्रांच पैटर्न को पहचानें और उसके ठोस केस टारगेट पढ़ें
• FLIRT-संगत सिग्नेचर मैचिंग — .pat सिग्नेचर डेटाबेस से ज्ञात फ़ंक्शनों की पहचान करें
• ट्रेस लिफ़्टिंग — एक मनमाना लीनियर इंस्ट्रक्शन अनुक्रम (जैसे कैप्चर किया गया एक्ज़ीक्यूशन ट्रेस) को सीधे IGNIL में लिफ़्ट करें, CFG/फ़ंक्शन/ब्लॉक-वैलिडिटी विश्लेषण को पूरी तरह बायपास करते हुए
• बाइनरी लोडर — एक ELF या PE/COFF फ़ाइल (या इन-मेमोरी बाइट्स) को सीधे एक LoadedImage में पार्स करें: सेक्शन और ELF PT_LOAD सेगमेंट उनके वर्चुअल पतों पर R/W/X अनुमतियों के साथ, एंट्री पॉइंट, इमेज बेस, इम्पोर्ट/एक्सपोर्ट फ़्लैग वाले सिंबल, और हेडर से ऑटो-डिटेक्ट किया गया आर्किटेक्चर (इसे नाम देने की आवश्यकता नहीं)। loader::disassembleImage एक ही कॉल में फ़ाइल से एक भरा हुआ Graph तक जाता है। LLVM के llvm::object पर आधारित, इसलिए कोई अतिरिक्त निर्भरता नहीं
• disassembler CLI — एक कमांड-लाइन टूल जो एक ELF या PE बाइनरी लोड करता है और डिसअसेम्बली डंप करता है, त्वरित निरीक्षण और स्क्रिप्टिंग के लिए उपयोगी
• C शिम (dragon_c.h) और Python API (cffi) जो ऊपर की अधिकांश विशेषताओं को कवर करते हैं (कुछ C++-केवल कोने — पैटर्न-मैचिंग DSL टेम्पलेट, आर्किटेक्चर-विशिष्ट इंस्ट्रक्शन क्लासिफ़िकेशन हेल्पर, और इसी तरह के — docs/cpp_api.md में इस प्रकार प्रलेखित हैं)

आवश्यकताएँ

• LLVM 21 (सिस्टम पर इंस्टॉल होना चाहिए)
• CMake 3.20 या बाद का
• एक C++20 कंपाइलर
• cffi के साथ Python 3 (वैकल्पिक, Python API के लिए)

समर्थित आर्किटेक्चर

• x86 (32-बिट और 64-बिट)
• ARM (32-बिट और 64-बिट)
• RISC-V (32-बिट और 64-बिट)

प्रीबिल्ट रिलीज़

टैग किए गए रिलीज़ प्रति प्लेटफ़ॉर्म एक स्व-निहित 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 पर बिल्ड करना (Visual Studio + vcpkg)

Windows पर CMakeLists.txt में निर्भरता की खोज के लिए कुछ संकेतों की आवश्यकता होती है, क्योंकि यह Linux पैकेज लेआउट के लिए लिखा गया है: Z3 LLVM के बंडल किए गए FindZ3.cmake मॉड्यूल के माध्यम से पाया जाता है, और Unicorn pkg-config के माध्यम से पाया जाता है। दोनों में से कोई भी तंत्र नहीं जानता कि vcpkg चीज़ें कहाँ इंस्टॉल करता है, और LLVM सिस्टम पथ के बजाय LLVM_DIR के माध्यम से पाया जाता है। तीन संकेत देने से यह सब ठीक हो जाता है।

पूर्वापेक्षाएँ

• Visual Studio 2022 (या इसके Build Tools) Desktop development with C++ वर्कलोड के साथ
• CMake 3.20+
• LLVM 21 कहीं अनपैक किया गया, जैसे C:\llvm-21 (प्रीबिल्ट clang+llvm-*-x86_64-pc-windows-msvc रिलीज़ काम करती है)
• vcpkg

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. या एक प्रीसेट का उपयोग करें (अनुशंसित)

सेटिंग्स को एक बार CMakeLists.txt के बगल में CMakeUserPresets.json में सहेजें, फिर एक ही फ़्लैग से कॉन्फ़िगर करें। यह फ़ाइल मशीन-विशिष्ट पथ रखती है, इसलिए इसे वर्ज़न कंट्रोल से बाहर रखें (यह git-ignored है)।

{
  "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

नोट्स