The Manual

A hands-on walkthrough of dragon-tales, from raw bytes to optimized LLVM IR. Unlike the API references (cpp_api.md, c_api.md, python_api.md in the repository), which are organized by class and function, this manual is organized by task: each chapter builds on the previous one, using one running example — a small ARM64/x86-64 function — all the way through the pipeline.

Every code snippet in this manual is runnable as-is; most are lightly trimmed versions of the example programs under examples/ in the repository.

Which API layer?

Examples are shown in C++ and Python side by side, with a slider, wherever the two diverge meaningfully. The C shim (c_shim/dragon_c.h) is the same shape as the Python API — it’s what the Python bindings wrap — see docs/c_api.md in the repository if you’re integrating from C directly.

1. 01Getting Started Building dragon-tales and running your first snippet
2. 02Assembling Your Code Turning assembly text into raw machine bytes
3. 03Disassembling Your First Binary Turning bytes back into instructions
4. 04Functions, Basic Blocks and Instructions Recovering structure from a flat instruction stream
5. 05Lifting to IGNIL dragon-tales' architecture-independent IL
6. 06Moving to LLVM IR From IGNIL to optimizable LLVM IR
7. 07A Real-World Example Compiling C, pulling .text with objdump, and running it through the whole pipeline
8. 08Symbolic Execution with Z3 solving for inputs, pruning dead branches, and resolving computed jumps

the theory behind dragon-tales

dragon-tales is a project of . The theory this library is built on — disassembly, function and CFG recovery, semantic ILs, lowering to LLVM IR, emulation and symbolic execution — is taught end to end in the following trainings, all with in-browser labs and no local setup:

Basic Training

Wyvern — Building an ARM Disassembler & IL From Scratch

Assemble and decode AArch64 through LLVM’s MC layer, recover functions and basic blocks from a flat instruction stream, build the control-flow graph, then design WVIL — a semantic IL — and lift instructions into it. The same ground dragon-tales covers from raw bytes to an architecture-independent IL.

fuzzsociety.org →

Advanced Training

Wyvern Advanced — From AArch64 Machine Code to LLVM IR & Program Analysis

The full pipeline: disassembly, function discovery, basic-block recovery, CFG construction, the WVIL semantic IL, then lowering to LLVM IR, optimizing it and analysing the result — backward slicing, jump-table recovery, a C API and Python bindings over cffi, closing on ARM32/Thumb.

fuzzsociety.org →

Binary Analysis bundle

Program Analysis Bundle — Wyvern Advanced + Emulation & Symbolic Execution

Wyvern Advanced together with Emulators & Symbolic Execution Engines: the three ways of reading a binary — static lifting to an IR, concrete execution under emulation, and symbolic reasoning over constraints — which is exactly the combination the VMProtect write-up leans on.

fuzzsociety.org →