Capstone

Welcome

Capstone is a lightweight multi-platform, multi-architecture disassembly framework.

Our target is to make Capstone the ultimate disassembly engine for binary analysis and reversing in the security community.

Highlight features


Some of the reasons making Capstone unique are elaborated here.

Find in this Blackhat USA 2014 slides more technical details behind our disassembly engine.

Testimonials

“Capstone is something people have wanted for years; the value is apparent in the implementation, and it’s nice to finally have an industry standard for this”. – George “Geohot” Hotz.

“Capstone has changed the Reverse Engineering landscape: We finally have a solid, independent, and free disassembler engine”. – Felix “FX” Lindner.

“Capstone will soon be the standard disassembly engine”. – Bruce Dang.

“Capstone solves a well known issue in the reversing community by a well tested and maintained library for most common architectures using a generic API”. – Pancake.

“And, nowadays, Capstone is the best embeddable disassembler out there”. – Joxean Koret.

“I must have mentioned it at least 25 times today with our client. Not sure yet, but this engine might just be the gold standard”. – Stephen Ridley.

“Developers of Capstone provide great support. Its small size and high modularity makes it perfectly working in kernel as well!”. – Peter Hlavaty.

“Love at first sight! Beautiful API, support latest instructions, Capstone truly is the ultimate disassembly framework!”. – Ole André Vadla Ravnås.

“Simply the best - recommended to anyone asking which disassembler to use!”. – Jurriaan Bremer.

“The most complete disassembler library available for the reverse engineering and information security communities”. – Pedro “osxreverser” Vilaça.

“The API is straightforward and easy to work with, and on the few occasions we have run into issues the Capstone developers have provided bug fixes, new features, and support in a matter of hours”. – Sean Heelan.

“I expect Capstone to become the standard, a stepping stone for all projects everywhere”. – Ange Albertini.

See complete testimonials for Capstone here.


Version 3.0.2

11
Mar
2015

We are happy to announce the stable version 3.0.2 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0.2 in our Github repo.

Find pre-compiled binaries in the Download section.

Please test and feed back via our contact.


NOTE:

  • Our Python package capstone on PyPi can build & install the core at the time of installing Python module, so the external dependency on the core is eliminated.

    Windows users can either instal Python binding of Capstone from Windows installer, or using our PyPi package capstone-windows. Note that this already includes the prebuilt libraries (for both Win32 & Win64 editions) inside, so there is no need to install the core separately.

    See bindings/python/README.TXT for more information on these PyPi modules.


Summary of the important changes of this version.


  • Library

    • On *nix, only export symbols that are part of the API (instead of all the internal symbols).


  • X86

    • Do not consider 0xF2 as REPNE prefix if it is a part of instruction encoding.
    • Fix implicit registers read/written & instruction groups of some instructions.
    • More flexible on the order of prefixes, so better handle some tricky instructions.
    • REPNE prefix can go with STOS & MOVS instructions.
    • Fix a compilation bug for X86_REDUCE mode.
    • Fix operand size of instructions with operand PTR [].


  • Arm

    • Fix a bug where arm_op_mem.disp is wrongly calculated (in DETAIL mode).
    • Fix a bug on handling the If-Then block.


  • Mips

    • Sanity check for the input size for MIPS64 mode.


  • MSVC

    • Compile capstone.dll with static runtime MSVCR built in.


  • Python binding

    • Fix a compiling issue of Cython binding with gcc 4.9.

Version 3.0.1

3
Feb
2015

We are excited to announce the stable version 3.0.1 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0.1 in our Github repo.

Find pre-compiled binaries in the Download section.

Please test and feed back via our contact.


NOTE:

  • This version fixes some important issues in the Python binding, so Python users should upgrade their binding. See bindings/python/README.TXT in source code on to do fresh-reinstall.

  • Since this version, our Python package capstone on PyPi can build & install the core at the time of installing Python module, so the external dependency on the core is eliminated.

    Another new package capstone-windows is available for Windows users who do not want to compile from source, as this package includes prebuilt libraries (for both Win32 & Win64 editions) inside.

    See bindings/python/README.TXT for more information on these PyPi modules.


Summary of the important changes of this version.

  • X86
    • Properly handle LOCK, REP, REPE & REPNE prefixes.
    • Handle undocumented immediates for SSE’s (V)CMPPS/PD/SS/SD instructions.
    • Print LJUMP/LCALL without * as prefix for Intel syntax.
    • Handle REX prefix properly for segment/MMX related instructions (x86_64).
    • Instruction with length > 15 is consider invalid.
    • Handle some tricky encodings for instructions MOVSXD, FXCH, FCOM, FCOMP, FSTP, FSTPNCE, NOP.
    • Handle some tricky code for some x86_64 instructions with REX prefix.
    • Add missing operands in detail mode for PUSH, POP, IN/OUT reg, reg
    • MOV32ms & MOV32sm reference word rather than dword.


  • Arm64
    • BL & BLR instructions do not read SP register.
    • Print absolute (rather than relative) address for instructions B, BL, CBNZ, ADR.


  • Arm
    • Instructions ADC & SBC do not update flags.
    • BL & BLX do not read SP, but PC register.
    • Alias LDR instruction with operands [sp], 4 to POP.
    • Print immediate operand of MVN instruction in positive hexadecimal form.


  • PowerPC
    • Fix some compilation bugs when DIET mode is enable.
    • Populate SLWI/SRWI instruction details with SH operand.


  • Python binding
    • Fix a Cython bug when CsInsn.bytes returns a shorten array of bytes.
    • Fixed a memory leak for Cython disasm functions when we immaturely quit the enumeration of disassembled instructions.
    • Fix a NULL memory access issue when SKIPDATA & Detail modes are enable at the same time.
    • Fix a memory leaking bug when when we stop enumeration over the disassembled instructions prematurely.
    • Export generic operand types & groups (CS_OP_xxx & CS_GRP_xxx).

Version 3.0.1-RC2

20
Jan
2015

We are happy to announce the Release Candidate 2 of version 3.0.1 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0.1-rc2 in our Github repo.

Please test and feed back via our contact.


NOTE

  • Do use the Python bindings come with this version, as this fixed some important issues in version 3.0.

    For Java/Ocaml/Python bindings, see respective README files under bindings/ directory in the source on how to do fresh-install.


Summary of the important changes of version 3.0.1-RC2 (see Changelog for more details):

  • Bug fixes for X86, Arm, Arm64.

  • Fixed some issues, including a memory leaking bug, for Python (Cython) bindings.


Version 3.0.1-RC1

5
Jan
2015

We are pleased to announce the Release Candidate 1 of version 3.0.1 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0.1-rc1 in our Github repo.

Please test and feed back via our contact.


NOTE

  • Do use the Python bindings come with this version, as this fixed some important issues in version 3.0.

    For Java/Ocaml/Python bindings, see respective README files under bindings/ directory in the source on how to do fresh-install.


Summary of the important changes of version 3.0.1-RC1 (see Changelog for more details):

  • Bug fixes for X86, Arm, Arm64 & PowerPC.

  • X86 engine now can handle better some tricky X86 code.

  • Fixed some memory leaking & NULL memory access issues for Python bindings.


Version 3.0

19
Nov
2014

We are excited to announce version 3.0 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0 in our Github repo.

Find pre-compiled binaries in the Download section.

Please test and feed back via our contact.


NOTE

  • Do use the bindings come with this version, as all the old bindings from previous version 3.0-rcX or 2.x are incompatible and cannot be run with the 3.0 core.

    For Java/Ocaml/Python bindings, see the respective README files under bindings/ directory in the source on how to do fresh-reinstall.


Summary of the important changes since 2.1.2 (more detail):

  • API
    • New API cs_disasm_iter & cs_malloc (See online doc).
    • Renamed API cs_disasm_ex to cs_disasm (cs_disasm_ex is still supported, but marked deprecated to be removed in future)
    • Support SKIPDATA mode, so Capstone can jump over unknown data and keep going from the next legitimate instruction.
    • API version was bumped to 3.0.
  • Bindings support
    • Python binding supports Python 3 (besides Python 2).
    • Support Ocaml binding.
  • Architectures
    • New architectures: Sparc, SystemZ & XCore.
    • Support new instructions & have important bugfixes for Arm, Arm64, Mips, PowerPC & X86.
    • Always expose absolute addresses rather than relative addresses (Arm, Arm64, Mips, PPC, Sparc, X86).

    • X86: more mature & handles all the malware tricks (that we are aware of).

    • ARM: Support new mode CS_MODE_V8 for Armv8 A32 encodings.

    • Mips
      • Supports new hardware modes: Mips32R6 (CS_MODE_MIPS32R6) & *MipsGP64 (CS_MODE_MIPSGP64).
      • Removed the ABI-only mode CS_MODE_N64.
      • New modes CS_MODE_MIPS32 & CS_MODE_MIPS64 (instead of CS_MODE_32 & CS_MODE_64).
  • Support Microsoft Visual Studio (so Windows native compilation using MSVC is possible).

  • Support CMake compilation.

  • Cross-compile for Android.

  • Build libraries/tests using XCode project

  • Much faster, while consuming less memory for all architectures.

Version 3.0-RC3

2
Nov
2014

We are happy to announce the Release Candidate 3 of version 3.0 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0-rc3 in our Github repo.

Please test and feed back via our contact.


NOTE

  • Do use the bindings come with this version, as all the old bindings from previous version 3.0-RC2 or 2.x are incompatible and cannot be run with the *3.0-RC3 core*.

    For Java/Ocaml/Python bindings, see the respective README files under bindings/ directory in the source on how to do fresh-reinstall.


Summary of the important changes since 3.0-RC2 (more detail):

  • Better support for cross-platform analysis:

    • Use common instruction operand types REG, IMM, MEM & FP across all architectures.

    • Use common instruction group types across all architectures.

  • Fix an buffer overflow bug in fill_insn() in cs.c.

  • X86:

    • Remove bogus instructions X86_INS_REP/REPNE/LOCK.

    • Added prefixed symbols X86_PREFIX_REP/REPNE/LOCK/CS/DS/SS/FS/GS/ES/OPSIZE/ADDRSIZE.

  • ARM: instructions B, BL, BX, BLX, BXJ belong to ARM_GRP_JUMP group.

  • Mips: properly handle modes MIPS32R6 & MICRO.

  • PPC: add new operand type PPC_OP_CRX.


Version 3.0-RC2

16
Oct
2014

We are glad to announce the Release Candidate 2 of version 3.0 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0-rc2 in our Github repo.

Please test and feed back via our contact.


NOTE

  • Do use the bindings come with this version, as all the old bindings from version 2.x are incompatible and cannot be run with the 3.0 core.

    For Java/Ocaml/Python bindings, see respective README files under bindings/ directory in the source on how to do fresh-install.


Summary of the important changes of version 3.0-RC2 since 3.0-RC1:

  • New APIs: cs_disasm_iter & cs_malloc. See documentation at http://capstone-engine.org/iteration.html

  • Some optimizations to improve performance of cs_disasm, especially for Windows platform.

  • Properly handle cs_disasm when count is in range [2, 32].

  • Build libraries/tests using XCode project

  • Ocaml binding: major update on interface & some important fixes.

  • ARM: add a new field subtracted to cs_arm_op struct.

  • Mips

    • Remove the ABI-only mode CS_MODE_N64.

    • Get rid of MIPS_REG_PC register.

  • PPC

    • Do not add CR0 to the operand list as it’s not displayed by the disassembly.

    • Print absolute address rather than relative address for some relative branch instructions.

  • X86: properly calculate absolute addresses for relative CALL & JMP - for AT&T syntax.


Version 3.0-RC1

1
Oct
2014

We are pleased to announce the Release Candidate 1 of version 3.0 of Capstone disassembly framework!

The source code is available in zip and tar.gz formats, or at tagname 3.0-rc1 in our Github repo.

Please test and feed back via our contact.


NOTE

  • Do use the bindings come with this version, as all the old bindings from version 2.x are incompatible and cannot be run with the 3.0 core.

    For Java/Ocaml/Python bindings, see respective README files under bindings/ directory in the source on how to do fresh-install.


Summary of the important changes of version 3.0-RC1 (see Changelog for more details):

  • New architectures: Sparc, SystemZ & XCore.

  • Important bugfixes for Arm, Arm64, Mips, PowerPC & X86.

  • X86 engine now can decode 3DNow instructions.

  • X86 engine is mature & handles all the malware tricks that we are aware of. If you have any code that Capstone wrongly processes, please report.

  • Mips engine added supports for new hardware modes: Mips3, Mips32R6 & MipsGP64.

  • Support for Microsoft Visual Studio (so Windows native compilation using MSVC is possible).

  • Support CMake compilation.

  • Cross-compile for Android.

  • Much faster, while consuming less memory for all architectures.

  • API version was bumped to 3.0.

  • Renamed API cs_disasm_ex to cs_disasm (cs_disasm_ex is marked obsolete to be removed in future versions)

  • Support SKIPDATA mode, so Capstone can jump over unknown data and keep going from the next legitimate instruction.

  • Python binding supports Python3.

  • Support Ocaml binding.


See the news archive for older posts.