Capstone Disassembly Engine

Warnings

• breaking Capstone undergoes significant changes between major versions (e.g., 3.0, 4.0, 5.0), introducing new features, architectures, and sometimes API modifications. For instance, version 3.0.5-rc2 had API version bumps and new `cs_option()` modes. The RISC-V module, in particular, saw enormous changes in a recent update. Users should review release notes and migration guides when upgrading across major versions.
  Fix: Always consult the official release notes and upgrade guides for the specific versions you are migrating between. Re-test your code thoroughly after major version upgrades.
• gotcha When installing via `pip`, the `capstone` Python package automatically builds and includes its own native C core library. If you have a system-installed `libcapstone` and wish to use it instead, you must set the `LIBCAPSTONE_PATH` environment variable before installation to inhibit the bundled core build. Failure to do so will result in two copies of the library, potentially leading to confusion or unexpected behavior.
  Fix: If you intend to use a pre-existing `libcapstone` installation, set the environment variable `LIBCAPSTONE_PATH` (e.g., `export LIBCAPSTONE_PATH=/path/to/your/libcapstone`) before running `pip install capstone`.
• breaking In Capstone versions prior to 3.0.5-rc2, accessing irrelevant data fields when `skipdata` and `detail` modes were enabled might have silently returned default values. Since 3.0.5-rc2, the Python binding explicitly raises an error in such cases. This change ensures stricter error handling but can break older code relying on the previous, more lenient behavior.
  Fix: Ensure your code only accesses relevant data fields for the current instruction and mode. If you rely on `skipdata` and `detail` modes, adapt your error handling or data access logic to account for explicit error raising.
• gotcha Using `from capstone import *` is convenient for quick scripts but can lead to name collisions with other modules or variables in larger projects. This makes code less explicit and harder to debug.
  Fix: Prefer explicit imports, e.g., `from capstone import Cs, CS_ARCH_X86, CS_MODE_64`, to clearly identify where symbols originate and avoid potential conflicts.

Install

• pip install capstone Install via pip

Imports

• Cs

  from capstone import Cs, CS_ARCH_X86, CS_MODE_64

  While 'import *' works, it's generally discouraged in larger projects to avoid name collisions and improve readability. Explicitly import required symbols.

Quickstart

This quickstart demonstrates how to initialize the Capstone engine for different architectures (X86 64-bit and ARM) and then disassemble a byte string, printing the address, mnemonic, and operand string for each instruction.

from capstone import Cs, CS_ARCH_X86, CS_MODE_64

# X86 64-bit code to disassemble
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00\x48\x8b\x01\x49\x8b\x40\x10\x48\x8d\x34\x24"

# Initialize Capstone for X86 64-bit architecture
md = Cs(CS_ARCH_X86, CS_MODE_64)

# Disassemble the code
print("Disassembling X86 64-bit code:")
for i in md.disasm(CODE, 0x1000):
    print("0x%x:\t%s\t%s" % (i.address, i.mnemonic, i.op_str))

# Example with a different architecture (ARM)
from capstone import CS_ARCH_ARM, CS_MODE_ARM
ARM_CODE = b"\x04\xe0\x2d\xe5\x00\x00\x00\x00"
md_arm = Cs(CS_ARCH_ARM, CS_MODE_ARM)

print("\nDisassembling ARM code:")
for i in md_arm.disasm(ARM_CODE, 0x1000):
    print("0x%x:\t%s\t%s" % (i.address, i.mnemonic, i.op_str))