# Capstone — Multi-Architecture Disassembly Framework

> A lightweight multi-architecture disassembly framework written in C with bindings for numerous programming languages.

## Install

Save in your project root:

# Capstone — Multi-Architecture Disassembly Framework

## Quick Use

```bash
# Install Capstone library and Python bindings
sudo apt install libcapstone-dev
pip install capstone

# Disassemble x86-64 bytes from Python
python3 -c "
from capstone import *
code = b'x55x48x89xe5x89x7dxfcx8bx45xfcx5dxc3'
md = Cs(CS_ARCH_X86, CS_MODE_64)
for insn in md.disasm(code, 0x1000):
    print(f'0x{insn.address:x}: {insn.mnemonic}	{insn.op_str}')
"
```

## Introduction

Capstone is a lightweight, multi-architecture disassembly framework designed to be the core engine for binary analysis tools. Written in C for performance, it provides clean APIs and bindings for Python, Java, Go, Ruby, and many other languages. Capstone is used as the disassembly backend in numerous security tools including radare2, Ghidra plugins, and various malware analysis frameworks.

## What Capstone Does

- Disassembles machine code for x86, x86-64, ARM, AARCH64, MIPS, PowerPC, SPARC, SystemZ, and more
- Provides detailed instruction semantics including operand types, register access, and instruction groups
- Operates on raw byte buffers with no requirement for executable file format parsing
- Supports AT&T and Intel syntax output for x86 architecture
- Offers both a C API and idiomatic bindings for high-level languages

## Architecture Overview

Capstone is built as a modular C library where each architecture has its own disassembly module. The core engine dispatches byte sequences to the appropriate architecture decoder based on the configured mode. Each decoder translates raw bytes into an internal instruction representation that captures the mnemonic, operands, encoding details, and semantic information like register reads and writes. The library is designed to be stateless and thread-safe, making it suitable for embedding in multi-threaded analysis tools. Language bindings wrap the C API using FFI mechanisms native to each target language.

## Self-Hosting & Configuration

- Install the C library from package managers (apt, brew, vcpkg) or build from source with cmake
- Python bindings are available via pip and do not require the system library if using the bundled version
- Configure architecture and mode at engine creation time (e.g., CS_ARCH_ARM + CS_MODE_THUMB)
- Enable detail mode with `md.detail = True` to access operand-level instruction information
- Link against the static or shared library depending on deployment requirements

## Key Features

- Support for 10+ architectures with consistent API across all of them
- Instruction detail mode providing operand types, implicit registers, and semantic groups
- Diet mode build option that strips non-essential data to reduce library size for embedded use
- Thread-safe design with no global state for safe use in concurrent analysis tools
- Skipdata mode for gracefully handling data bytes mixed with code in raw binary blobs

## Comparison with Similar Tools

- **Zydis**: A fast x86/x86-64 decoder focused on performance; Capstone supports many more architectures with richer semantic information
- **distorm**: An x86/x64 disassembler library; Capstone provides broader architecture coverage and more detailed instruction information
- **LLVM MC Disassembler**: Part of the LLVM project with extensive architecture support; Capstone offers a simpler API focused purely on disassembly without the full LLVM dependency
- **objdump (binutils)**: A command-line disassembler; Capstone is a library designed for programmatic use and embedding in other tools

## FAQ

**Q: Which programming languages have Capstone bindings?**
A: Official and community bindings exist for Python, Java, C#, Go, Ruby, JavaScript (Node.js), Rust, Haskell, OCaml, and several others.

**Q: What is the difference between Capstone and its successor DIET mode?**
A: Diet mode is a compile-time option that removes non-critical data (like operand string mnemonics) to reduce the library's memory footprint, useful for resource-constrained environments like embedded systems.

**Q: Can Capstone disassemble Thumb and Thumb-2 ARM instructions?**
A: Yes. Use CS_MODE_THUMB when creating the engine to disassemble 16-bit Thumb and 32-bit Thumb-2 encoded ARM instructions.

**Q: How does Capstone handle invalid or data bytes in a code stream?**
A: Enable skipdata mode with `md.skipdata = True` to have Capstone emit pseudo-instructions for bytes it cannot decode, allowing disassembly to continue past data regions.

## Sources

- Repository: https://github.com/capstone-engine/capstone
- Documentation: https://www.capstone-engine.org/documentation.html

---
Source: https://tokrepo.com/en/workflows/asset-0407ff00
Author: AI Open Source