C++ Python CMake C Batchfile Assembly
Permalink
Failed to load latest commit information.
.travis travis: use conteiner build and cache Aug 6, 2015
arch core: use HookType instead of u32 ; arch_x86: fix semantic of lahf in… Feb 5, 2017
cmake core: fix Compiler module loading, change design of Compiler interfac… Dec 13, 2016
deps all: start changes for version 0.5.0, mostly focus on database and be… Oct 12, 2016
doc img: move logo to specific folder, add screenshots ; core: fix orphan… Feb 9, 2014
examples core: improve use of enum as bitmask (thx lemme) ; examples: update l… Nov 15, 2016
font font & ui_qt: add default font May 18, 2014
gen db_soci: remove commented code ; arch_st62: fix compilation ; pydusa:… Nov 14, 2016
img readme: add screenshots, update info/contributors ; appveyor: add yml… Feb 15, 2015
inc/medusa core: use HookType instead of u32 ; arch_x86: fix semantic of lahf in… Feb 5, 2017
package cmake: generate python package for pydusa (thx to serge) Jun 22, 2016
samples @ 64c72dd core: add simplification for -0 → 0 Jul 21, 2016
script gen: split yaml2cpp to cleaner scripts ; arch: move yaml files to spe… Jan 17, 2015
src db_soci: disable DEBUG_POSTFIX ; pydusa: fix missing shared_ptr decl … Feb 6, 2017
test core: find a bug in the implementation of symbolic execution Aug 29, 2014
.gitattributes git: remove ogdf reference as module ; readme: update Aug 3, 2015
.gitignore core: move cfg dumping to analyzer, comment View methods, more test f… May 6, 2013
.gitmodules git: remove ogdf reference as module ; readme: update Aug 3, 2015
.travis.yml appveyor: use vs2015 and update deps ; travis: workaround for compila… Jun 18, 2016
CMakeLists.txt core: fix PEGTL version, thanks dnivra Feb 19, 2017
Dockerfile docker: add initial script Dec 25, 2015
LICENSE.rtf git: include OGDF as a submodule ; cmake: force boost version to be a… Sep 1, 2014
LICENSE.txt core: add Execution which acts as a Emulator helper ; emul_llvm: upda… Aug 8, 2013
README.rst readme: update info, add options section Jun 19, 2016
appveyor.yml appveyor: use vs2015 and update deps ; travis: workaround for compila… Jun 18, 2016
bootstrap_use_llvm.bat core: BitVector now returns 0 if bitsize is 0, use different way to c… May 31, 2016

README.rst

Medusa

Medusa is a disassembler designed to be both modular and interactive. It runs on Windows and Linux, it should be the same on OSX. This project is organized as a library. To disassemble a file you have to use medusa_text or qMedusa.

Build-bot

branch Travis AppVeyor
dev Build status of the dev branch on Mac/Linux Build status of the dev branch on Windows

Prerequisites

Medusa requires the following libraries: boost >= 1.55 (system, filesystem, thread, date_time), OGDF (required git), and Qt5 >= 5.2 for the GUI. You also need CMake for compilation and a C++11 compiler (VS2015 update 2 on Windows). Git is optional but allows to clone remote repository for specific features, see Compilation/Options.

Feature

Loader
Name Mapping Import Export Symbols Notes
ELF yes yes no no Some kind of reloc are not handled
PE yes yes yes no Reloc are not handled
Mach-O yes yes no no
  • Doesn't support FAT binary
  • on X86, esi as glbptr is not handled
GameBoy yes yes yes yes
  • GameBoy Color registers are not handled
  • All mappers are not handled
ST62ROM yes yes yes yes  
Architecture
Name Mode Disassembly Semantic Notes
x86 16-bit yes partial Support until SEE4.2
x86 32-bit yes
x86 64-bit yes
z80 gameboy yes yes  
avr8   no no Broken
arm normal partial partial  
arm thumb partial no
arm thumb2 partial no
st62   yes partial  
Tool
Name interactivity Comment Label Graph Database Notes
qt partial yes yes yes yes  
text no no no no yes  
Binding
Name Notes
Python WIP
Database
Name Save Load Notes
text yes yes Incomplete
Operating System
Name Notes
UNIX WIP
Windows

Roadmap

Each versions of Medusa bring a new specific feature.

  • 0.1 the beginning of the project
  • 0.2 new qt interface
  • 0.3 flow graph
  • 0.4 load/save database
  • 0.5 semantic support
  • 0.6 better python binding
  • 0.7 debugger

Compilation

First off, you need boost libraries; you can either download a built version or compile yourself. Boost is available here

Now, make sure you have installed Qt5 if you need a graphical user interface (and I'm pretty sure you do ;)). Medusa requires at least the version 5.2, be sure to pick the good version on the official website or use your package manager.

Finally, we're ready to retrieve and compile medusa:

git clone https://github.com/wisk/medusa.git
mkdir build
cd build
# UNIX users should define CMAKE_BUILD_TYPE e.g. -DCMAKE_BUILD_TYPE=Release to compile Medusa with optimization
cmake -DBOOST_ROOT:PATH=<path to the boost directory> -DQT5_CMAKE_PATH:PATH=<Path to Qt5 cmake scripts directory> ..

# for UNIX users
make && cd bin && ./qMedusa

# for Windows users
explorer Medusa.sln

Note: If CMake is unable to find Boost on Windows, try to define BOOST_LIBRARYDIR. This variable must be set to the library directory (e.g.: C:\boost_1_55_0\lib64-msvc-14.0). In my configuration, QT5_CMAKE_PATH is set to /usr/lib/cmake on ArchLinux and C:\Qt\5.6\msvc2015_64\lib\cmake on Windows. For Windows users, you should probably add -G"Visual Studio 14 Win64" where 14 is your Visual Studio version and Win64 if you build medusa in 64-bit. To run the Qt interface on Windows, you may have to add the folder %QTDIR%\bin to your %PATH% and copy the folder %QTDIR%\plugins\platforms. By default, Medusa searches modules in the current folder, so you should run medusa executables from the folder where modules are located (e.g. build/bin on UNIX or build\bin\{Debug,Release,...} on Windows).

Options

Name Default value Meaning
MEDUSA_BUILD_TOOLS TRUE Compile tools
MEDUSA_BUILD_TESTS TRUE Compile tests
MEDUSA_CMAKE_USE_COTIRE FALSE Use cotire for building
MEDUSA_BUILD_WITH_OGDF FALSE Add OGDF project and build it, this library allows qMedusa to display graph
MEDUSA_MODULES_TO_BUILD "all" Semicolon-separated list of modules to build, or "all"

Screenshots

Main interface

https://raw.github.com/wisk/medusa/dev/img/shots/main_interface.png

Control flow graph

https://raw.github.com/wisk/medusa/dev/img/shots/cfg.png

Interactivity

https://raw.github.com/wisk/medusa/dev/img/shots/interactivity.png

https://raw.github.com/wisk/medusa/dev/img/shots/label.png

Binding

https://raw.github.com/wisk/medusa/dev/img/shots/python_binding.png

Docker image

If you do not wish to install the various dependencies on your system, you can use this docker image instead. Even though it is working out of the box, you may want to customize it to suit your needs or for added security (e.g. restrict ssh access to public key authentication only).

Build the Medusa container

docker build -t medusa .

Going inside the container

docker run -it medusa /bin/bash

OR launch qMedusa (ssh with X forwarding)

  • docker run -it -d medusa
  • ssh -X developer@<containers_ip> "medusa/build/bin/qMedusa"

Contacts

Acknowledgements

  • My schoolmates: epieddy, flalande and FX.
  • My workmate: gg, w1gz, lemme.
  • Yusuke Kamiyamane for his icons
  • gunmetal313, saeschdivara, kangjoni76, KarlVogel, ekse for their contributions.