capstone
Capstone disassembly/disassembler framework for ARM, ARM64 (ARMv8), Alpha, BPF, Ethereum VM, HPPA, LoongArch, M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86.
Top Related Projects
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
UNIX-like reverse engineering framework and command-line toolset
A powerful and user-friendly binary analysis platform!
UNIX-like reverse engineering framework and command-line toolset.
Quick Overview
Capstone is a lightweight, multi-platform, multi-architecture disassembly framework. It provides a powerful and versatile API for disassembling machine code for various architectures, including x86, ARM, MIPS, PowerPC, and more. Capstone is designed to be easily integrated into reverse engineering tools, debuggers, and other software that requires disassembly capabilities.
Pros
- Supports a wide range of architectures and instruction sets
- High performance and lightweight design
- Provides detailed information about disassembled instructions
- Actively maintained and regularly updated
Cons
- Learning curve for beginners due to its extensive API
- Limited documentation for some advanced features
- May require additional setup for certain architectures or platforms
- Not suitable for assembly or reassembly tasks
Code Examples
- Basic disassembly example:
from capstone import *
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
md = Cs(CS_ARCH_X86, CS_MODE_64)
for i in md.disasm(CODE, 0x1000):
print("0x%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))
This code disassembles a sequence of x86-64 machine code and prints the address, mnemonic, and operands of each instruction.
- Detailed instruction information:
from capstone import *
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
md = Cs(CS_ARCH_X86, CS_MODE_64)
md.detail = True
for i in md.disasm(CODE, 0x1000):
print("0x%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))
print("Instruction groups:", [g for g in i.groups])
print("Operands:")
for op in i.operands:
print("\t", op.type, op.value)
print()
This example demonstrates how to access detailed information about each instruction, including instruction groups and operand types.
- Disassembling with syntax options:
from capstone import *
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
md = Cs(CS_ARCH_X86, CS_MODE_64)
md.syntax = CS_OPT_SYNTAX_ATT
for i in md.disasm(CODE, 0x1000):
print("0x%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))
This example shows how to change the syntax option to AT&T syntax for x86 disassembly.
Getting Started
To get started with Capstone:
-
Install Capstone:
pip install capstone
-
Import the library and create a disassembler instance:
from capstone import * md = Cs(CS_ARCH_X86, CS_MODE_64)
-
Disassemble code:
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00" for i in md.disasm(CODE, 0x1000): print("0x%x:\t%s\t%s" %(i.address, i.mnemonic, i.op_str))
Competitor Comparisons
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
Pros of Unicorn
- Full system emulation capabilities, allowing for more comprehensive analysis and testing
- Supports a wider range of architectures, including ARM, MIPS, and RISC-V
- Integrates well with other security tools and frameworks
Cons of Unicorn
- Higher resource consumption due to full emulation
- Steeper learning curve for beginners
- May be overkill for simple disassembly tasks
Code Comparison
Unicorn (emulation):
from unicorn import *
# Initialize emulator
mu = Uc(UC_ARCH_X86, UC_MODE_32)
# Map memory and write code
mu.mem_map(0x1000, 0x1000)
mu.mem_write(0x1000, b"\x41\x4a") # INC ecx; DEC edx
# Emulate code
mu.emu_start(0x1000, 0x1002)
Capstone (disassembly):
from capstone import *
# Initialize disassembler
md = Cs(CS_ARCH_X86, CS_MODE_32)
# Disassemble code
for i in md.disasm(b"\x41\x4a", 0x1000):
print(f"0x{i.address:x}:\t{i.mnemonic}\t{i.op_str}")
Unicorn provides full emulation, while Capstone focuses on disassembly. Unicorn is more suitable for complex analysis and testing scenarios, whereas Capstone is efficient for quick disassembly tasks.
UNIX-like reverse engineering framework and command-line toolset
Pros of radare2
- More comprehensive toolkit with disassembly, debugging, and analysis features
- Extensible plugin architecture for customization
- Active community and frequent updates
Cons of radare2
- Steeper learning curve due to complex feature set
- Larger codebase and resource footprint
- Can be slower for simple disassembly tasks
Code Comparison
radare2:
RCore *core = r_core_new();
r_core_cmd_str(core, "pd 10");
r_core_free(core);
Capstone:
csh handle;
cs_open(CS_ARCH_X86, CS_MODE_64, &handle);
cs_disasm(handle, code, code_size, address, 0, &insn);
cs_close(&handle);
Summary
radare2 is a comprehensive reverse engineering framework with a wide range of features, while Capstone is a lightweight, focused disassembly engine. radare2 offers more functionality but comes with increased complexity, while Capstone provides a simpler API for basic disassembly tasks. The choice between them depends on the specific requirements of the project and the user's familiarity with the tools.
A powerful and user-friendly binary analysis platform!
Pros of angr
- More comprehensive binary analysis framework with symbolic execution capabilities
- Supports multiple architectures and operating systems
- Provides higher-level abstractions for program analysis tasks
Cons of angr
- Steeper learning curve due to its complexity
- Slower execution compared to Capstone for basic disassembly tasks
- Requires more system resources and dependencies
Code Comparison
angr example (symbolic execution):
import angr
proj = angr.Project('binary')
state = proj.factory.entry_state()
simgr = proj.factory.simulation_manager(state)
simgr.explore(find=0x400000)
Capstone example (disassembly):
from capstone import *
md = Cs(CS_ARCH_X86, CS_MODE_64)
CODE = b"\x55\x48\x8b\x05\xb8\x13\x00\x00"
for i in md.disasm(CODE, 0x1000):
print(f"0x{i.address:x}:\t{i.mnemonic}\t{i.op_str}")
angr provides a more powerful framework for advanced binary analysis, including symbolic execution, while Capstone focuses on efficient disassembly. angr is better suited for complex analysis tasks, while Capstone excels in performance-critical disassembly operations.
UNIX-like reverse engineering framework and command-line toolset.
Pros of rizin
- More comprehensive reverse engineering framework with additional features beyond disassembly
- Active community-driven development with frequent updates
- Supports a wider range of architectures and file formats
Cons of rizin
- Steeper learning curve due to its extensive feature set
- Larger codebase and potentially higher resource usage
- May be overkill for simple disassembly tasks
Code Comparison
Capstone (disassembling x86 code):
cs_insn *insn;
size_t count = cs_disasm(handle, code, code_size, address, 0, &insn);
for (size_t j = 0; j < count; j++) {
printf("0x%"PRIx64":\t%s\t\t%s\n", insn[j].address, insn[j].mnemonic, insn[j].op_str);
}
rizin (disassembling x86 code):
RzAnalysisOp op = {0};
while (offset < len) {
rz_analysis_op(analysis, &op, offset, buf + offset, len - offset, RZ_ANALYSIS_OP_MASK_ALL);
printf("0x%08"PFMT64x" %s %s\n", offset, op.mnemonic, op.op_str);
offset += op.size;
}
Both tools provide disassembly capabilities, but rizin offers a more extensive set of features for reverse engineering tasks. Capstone is focused primarily on disassembly, making it lighter and potentially easier to integrate into other projects. The choice between the two depends on the specific requirements of your project and the depth of analysis needed.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Capstone Engine
Capstone is a disassembly framework with the target of becoming the ultimate disasm engine for binary analysis and reversing in the security community.
Created by Nguyen Anh Quynh, then developed and maintained by a small community, Capstone offers some unparalleled features:
-
Support multiple hardware architectures: ARM, AArch64, Alpha, BPF, Ethereum VM, LoongArch, HP PA-RISC (HPPA), M68K, M680X, Mips, MOS65XX, PPC, RISC-V(rv32G/rv64G), SH, Sparc, SystemZ, TMS320C64X, TriCore, Webassembly, XCore and X86 (16, 32, 64), Xtensa.
-
Having clean/simple/lightweight/intuitive architecture-neutral API.
-
Provide details on disassembled instruction (called âdecomposerâ by others).
-
Provide semantics of the disassembled instruction, such as list of implicit registers read & written.
-
Implemented in pure C language, with lightweight bindings for Swift, D, Clojure, F#, Common Lisp, Visual Basic, PHP, PowerShell, Emacs, Haskell, Perl, Python, Ruby, C#, NodeJS, Java, GO, C++, OCaml, Lua, Rust, Delphi, Free Pascal & Vala ready either in main code, or provided externally by the community).
-
Native support for all popular platforms: Windows, Mac OSX, iOS, Android, Linux, *BSD, Solaris, etc.
-
Thread-safe by design.
-
Special support for embedding into firmware or OS kernel.
-
High performance & suitable for malware analysis (capable of handling various X86 malware tricks).
-
Distributed under the open source BSD license.
Further information is available at https://www.capstone-engine.org
Compile
See BUILDING.md file for how to compile and install Capstone.
Documentation
- Useful links and tutorials: docs/README
- Software architecture overview: docs/ARCHITECTURE.md
- Testing documentation: tests/README.md
- Updater (Auto-Sync) documentation: suite/auto-sync/README.md
Contributing
See CONTRIBUTING.md for an intro.
Fuzz
See suite/fuzz/README.md for more information.
License
This project is released under the BSD license. If you redistribute the binary or source code of Capstone, please attach file LICENSE.TXT with your products.
Top Related Projects
Unicorn CPU emulator framework (ARM, AArch64, M68K, Mips, Sparc, PowerPC, RiscV, S390x, TriCore, X86)
UNIX-like reverse engineering framework and command-line toolset
A powerful and user-friendly binary analysis platform!
UNIX-like reverse engineering framework and command-line toolset.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot