Home

Gil Dabah edited this page Jun 18, 2016 · 10 revisions

Welcome to the diStorm3 binary stream disassembler library project!

diStorm3 is licensed under the BSD license starting with version 3.3.3.

No more parsing strings! - diStorm3 is really a decomposer, which means it takes an instruction and returns a binary structure which describes it rather than static text, this is great for advanced binary code analysis.

We benchmarked five popular open-source disassembly libraries and chose diStorm3, which had the best performance (and furthermore, has complete 64-bit support).

July 2014, Quoting David Williams-King in his Thesis about Binary Shuffling.

Features

diStorm is a lightweight, easy-to-use and fast decomposer library.

diStorm disassembles instructions in 16, 32 and 64 bit modes. Supported instruction sets: FPU, MMX, SSE, SSE2, SSE3, SSSE3, SSE4, 3DNow! (w/ extensions), new x86-64 instruction sets, VMX, AMD's SVM and AVX!

The output of new interface of diStorm is a special structure that can describe any x86 instruction, this structure can be later formatted into text for display too.

diStorm is written in C, but for rapidly use, diStorm also has wrappers in Python/Ruby/Java and can easily be used in C as well. It is also the fastest disassembler library!

The source code is very clean, readable, portable and platform independent (supports both little and big endianity). diStorm solely depends on the C library, therefore it can be used in embedded or kernel modules.

Note that diStorm3 is backward compatible with the interface of diStorm64 (however, make sure you use the newest header files).

Documentation

Please read the documentation before asking questions, everything you need is pretty much here! Don't forget that diStorm is open source and you can always take a look to understand how to do one thing or another, but don't do it before you really have to.

For simply using diStorm with the old interface (a la - text output) in C, refer to the C sample code and it's very important to read the documentation of the API too, right here. However, if you want to use diStorm in Python refer to the Python example.

Since diStorm3 has a new interface you can learn more about it, starting with the showcases to get some idea what to expect from using the decompose functionality. Then you better see how the resulting structure layout is and once you get a clue, continue to the ** must read ** decompose API documentation.

If you feel it's enough for you and you want to jump into the water and start coding, here are a few Tips&Tricks that are going to make your life easier while using diStorm.

For advanced users who wish to use diStorm for real flow control analysis, this is your guide: flow control support documentation.

As always, since diStorm is a stream disassembler there are some pitfalls that you may encounter, therefore this page about stream disassembler might give you some ideas of good practices.

If you wish to compile/build diStorm on your own, on whatever platform, refer to build compilation environment.

For learning a bit about x86/x64 machine code, see x86/x64 machine code paper. And if you want to get a depth knowledge of how the internals of diStorm work, refer to diStorm internals paper, though it's not up to date with diStorm3, it should give you a good idea how to start hacking your way around.