How rizinorg/rizin works
1. Rizin is a C-based reverse-engineering platform built as a layered library plus thin CLI tools. The main reusable surface lives under librz/include, while the implementation is split into focused modules under librz/*. The user-facing executables are wrappers around that library, not separate apps with their own logic.
2. The architectural center is librz/core. It orchestrates the rest of the system: opening files, seeking, disassembly, analysis, debugging, search, flags, types, projects, and command execution. If you want one “hub” box in a diagram, it is core, because almost every interactive workflow passes through it.
3. Binary ingestion starts in the I/O and binary-format layers. librz/io abstracts file descriptors, memory, caches, maps, remote sources, and special transports. librz/bin then identifies and parses executable/container formats such as ELF, PE, Mach-O, DWARF/PDB-rich binaries, Java class files, WASM, firmware images, and many console-specific formats. This boundary is important: IO gets bytes; bin interprets structure.
4. Analysis is architecture-driven and heavily plugin-oriented. librz/arch contains the generic analysis framework plus per-ISA implementations for disassembly, instruction semantics, control-flow, calling conventions, RTTI, and platform profiles. The librz/arch/isa, isa_gnu, p, p_gnu, and opcodes trees show that much of the CPU-specific behavior is code-generated or table-driven rather than hardcoded in a single engine.
5. Rizin models instruction behavior in two complementary ways: ESIL and IL. ESIL lives under librz/arch/esil and is used for emulation-like semantic evaluation, tracing, and analysis support. The newer IL layer is under librz/il and provides a more structured intermediate representation with validation, export, graphing, and VM evaluation. In a diagram, both sit beneath higher analysis features and above raw disassembly.
6. Debugging is a separate subsystem, not a special mode inside analysis. librz/debug provides breakpoints, register access, traces, signals, process/session management, and platform-specific backends for Linux, Windows, macOS/XNU, BSDs, and remote protocols. IO also participates here through debug-oriented transports under librz/io/p and related wrappers, so “debugged process” is effectively another IO source.
7. The command-line and visual UI layer is handled by librz/cons and librz/core/cmd plus the TUI code under librz/core/tui. Command parsing is data-driven via librz/core/cmd_descs, and the repo also includes a dedicated shell parser subproject for the interactive command language. The result is an interactive console where commands are translated into core operations, with output formatting handled separately by the console layer.
8. Several cross-cutting services provide specialized capabilities to the core workflows: librz/search for byte/string/regexp/entropy/hash/magic searches, librz/hash for hashing and similarity functions, librz/crypto for encoding/crypto primitives, librz/type and librz/reg for type systems and register profiles, and librz/flag/librz/mark/librz/project for user state. These are not isolated utilities; they feed analysis, printing, and serialization throughout the product.
9. A major design boundary is the use of declarative data files. Large parts of architecture metadata live in .sdb.txt tables under librz/arch, librz/syscall, librz/type, librz/reg, and librz/bin. These tables define opcodes, syscalls, calling conventions, platform profiles, and format details, making many subsystems data-driven and easier to extend without changing the engine.
10. The repo exposes multiple frontends, all thin relative to the library. The top-level tools include rizin, rz-bin, rz-asm, rz-ar, rz-diff, rz-find, rz-hash, rz-gg, rz-run, rz-sign, rz-ax, and rz-test. Each tool focuses on a narrow slice of the core capabilities, but they share the same underlying library and plugin ecosystem.
11. Remote and automation paths are first-class. librz/socket and librz/core/rtr* support pipe, TCP/HTTP, process, and shell-style connectivity, while the examples/api tree shows embeddable APIs for hashes, signatures, and syscalls. The README’s rzpipe mention reflects the intended external scripting boundary: other languages call into Rizin rather than reimplementing the analysis pipeline.
12. Build and portability are architectural concerns, not afterthoughts. The project is built with Meson and relies on bundled subprojects/wraps for optional dependencies like capstone, zydis, tree-sitter, zlib/zstd/lzma/libzip, crypto libraries, and platform shims. The extensive CI, cross-compilation, and OS-specific directories show that the codebase is designed to produce the same layered product across many operating systems and architectures.
13. Testing mirrors the architecture. test/unit checks the foundational utilities and subsystems, test/integration exercises cross-module flows like binary loading, analysis, DWARF/PDB, projects, and remote/debug interactions, and test/db contains golden inputs/outputs for formats, commands, analysis, and disassembly. This structure reflects the real dependency chain: utilities → format/arch/debug/search → core command flows → tool behavior.
Main entry points: core Core Hub · arch Arch Engine · include Public API · test Tests
Components 23
Library
Reusable C library surface and core subsystems.
- Public API · Primary reusable headers and exported interfaces under librz/include.
librz/include - Core Hub · Central coordinator for open/seek/analyze/debug/search/commands.
librz/core - IO Layer · File, memory, cache, map, remote, and transport abstractions.
librz/io - Binary Loader · Container and executable format identification and parsing.
librz/bin - Arch Engine · Architecture framework plus disassembly, semantics, conventions, and platform profiles.
librz/arch - ESIL · ESIL emulation-style semantics, tracing, and analysis support.
librz/arch/esil - RZIL · Structured intermediate representation with validation, export, graphing, and VM evaluation.
librz/il - Debug Core · Breakpoints, registers, traces, sessions, signals, and native backends.
librz/debug - Console · Formatting, prompts, paging, canvases, and terminal interaction helpers.
librz/cons - Search · Byte, string, regexp, entropy, hash, magic, and value searches.
librz/search - Types · Type definitions, parsing, formatting, and serialization.
librz/type - Registers · Register arenas, profiles, and calling/ABI metadata.
librz/reg - State DB · Flags, marks, projects, seek history, and serialized user state.
- Cmd Router · Command parser, descriptors, and dispatch into core operations.
librz/core/cmd - TUI · Visual panels, HUDs, and interactive screen modes.
librz/core/tui
Frontends
Thin command-line entry points and interactive UI layer.
- CLI Tools · Thin executables such as rizin, rz-bin, rz-asm, rz-hash, and friends.
librz/main - Shell Parser · Interactive command-language parser used by the console frontends.
subprojects/rizin-shell-parser
Plugins & Data
Plugin backends and declarative tables that drive formats, CPUs, and profiles.
- Plugins · Format, architecture, debug, IO, and language plugins loaded by core.
- Data Tables · Declarative opcode, syscall, ABI, type, and format tables.
- Remote IO · Socket, HTTP, process, and rzpipe-style automation transports.
librz/socket - Crypto · Hashes, ciphers, and encoding helpers used across analysis and search.
librz/crypto
Support
Build, packaging, and repository infrastructure.
- Build System · Meson, wraps, subprojects, packaging, and cross-platform build orchestration.
meson.build - Tests · Unit, integration, and database-backed regression coverage.
test
Connections 36
- CLI Tools → Cmd Router: dispatches · CLI entrypoints hand commands to the router.
- CLI Tools → Core Hub: drives · Tools are thin wrappers around core workflows.
- Cmd Router → Core Hub: invokes · Command parsing resolves to core operations.
- TUI → Cmd Router: issues · Visual modes route actions through commands.
- Core Hub → IO Layer: reads · Core opens sources through the IO abstraction.
- Core Hub → Binary Loader: loads · Core delegates binary identification and parsing.
- Core Hub → Arch Engine: analyzes · Core asks architecture services for disassembly and analysis.
- Core Hub → Debug Core: debugs · Core coordinates sessions, breakpoints, and process control.
- Core Hub → Search: searches · Core exposes search workflows over the loaded target.
- Core Hub → Types: types · Core uses the type system for inspection and formatting.
- Core Hub → Registers: profiles · Core consults register and ABI profiles.
- Core Hub → State DB: persists · Core stores user state such as flags, marks, and projects.
- Core Hub → Crypto: uses · Core invokes hashing and encoding helpers.
- Arch Engine → ESIL: semantics · Architecture analysis can lower to ESIL semantics.
- Arch Engine → RZIL: lowers · Architecture analysis can emit RZIL.
- Binary Loader → Data Tables: consults · Binary parsing relies on declarative metadata tables.
- Arch Engine → Data Tables: consults · ISA and ABI behavior are largely table-driven.
- Debug Core → Remote IO: transports · Remote debugging and automation share socket/process transports.
- IO Layer → Remote IO: wraps · IO includes remote and debug-oriented backends.
- Shell Parser → Cmd Router: parses · Interactive shell grammar feeds the command layer.
- Public API → Core Hub: exports · Public headers expose the central API surface.
- Public API → IO Layer: exports · Public headers expose IO interfaces.
- Public API → Arch Engine: exports · Public headers expose analysis and architecture interfaces.
- Public API → Debug Core: exports · Public headers expose debugging interfaces.
- Public API → RZIL: exports · Public headers expose RZIL interfaces.
- Plugins → Arch Engine: extends · Architecture plugins provide ISA-specific behavior.
- Plugins → Binary Loader: extends · Binary plugins add format support.
- Plugins → Debug Core: extends · Debug plugins provide platform backends.
- Plugins → IO Layer: extends · IO plugins add transport and source support.
- Build System → Plugins: assembles · Build system wires in plugins and subprojects.
- Build System → CLI Tools: produces · Build system produces the thin executables.
- Tests → Core Hub: verifies · Integration and regression tests exercise core flows.
- Tests → Binary Loader: verifies · Format fixtures validate binary loading.
- Tests → Arch Engine: verifies · Assembly and analysis fixtures validate ISA support.
- Tests → Debug Core: verifies · Debug fixtures validate backend behavior.
- Tests → Cmd Router: verifies · Command database tests validate interactive flows.