mutator

<a href="https://scan.coverity.com/projects/bloodstalker-mutator"> <img alt="Coverity Scan Build Status" src="https://scan.coverity.com/projects/11154/badge.svg"/> </a>

Table of Contents

• Overview
  • bruiser
  • cgrep
  • delf
  • dwasm
  • luatablegen
  • obfuscator
  • m0
  • Safercpp
  • mutatord
• License
• How to get project mutator
• Dev Status
• Dev Plans
• Test Plans
• Announcements
• Buillding and Running
  • Building
  • Requirements
    • Linux and Mac
    • Windows
  • Running
    • Note
    • The Action File
• Implementation Notes
  • mutator-lvl0
• Directory Outline
• Acknowledgements
• FAQ
• Feedback
• Suggestions and Feature Requests
• TODO List
• Contributions
• Support
• Contact
• Gource

Overview

mutator is a suite of tools for C,C++ and machine code.<br/> Here's a detailed list of what's currently available:<br/>

bruiser

At its core, bruiser is a Lua REPL:

• bruiser comes with its own extensions and libraries implemented in C and Cpp.<br/>
• Through bruiser's Xobj feature, you can pull in functions from object code, run them and get the result back.<br/>
• Through the ASMRewriter functionality you can manipulate the machine code and push it back in the object. For more detail you can look at the wiki or check out bruiser's README.md.<br/>
• Luarocks: You can use your Luarocks modules/libraries in bruiser too. Just make sure luarocks is in your path and bruiser will take care of the rest.<br/> You can read more about buiser here

cgrep

cgrep is grep for c/c++ source files. simple as that.<br/> cgrep is added here as a submodule for more exposure. You can find the main repo here.<br/> You can read more about cgrep here

obfuscator

obfuscator is a C/C++ source code obfuscator.<br/> You can read more about obfuscator here

delf

delf is a custom ELF dump script developed for bruiser. bruiser uses it to interact with ELF files.<br/> You can also use the script as a standalone to dump info on the ELF file to stdout.<br/> delf is also hosted ona mirror repo here.<br/>

dwasm

'dwasm' is a custom WASM dump script. bruiser uses it to interact with WASM object files.<br/> The script is also usable in an standalone manner.<br/> dwasm is also hosted on a mirror repo here.<br/>

luatablegen

luatablegen is a python script that takes a json file including the details of a C structure, and generates C source and header files, a lua file including some convinience fields for the lua table and a markdown file including a summary of the table fields and their expected arg types and return types.<br/> luatablegen is also hosted on a mirror repo here.<br/>

m0

m0

Run static checks on the source code, which at the time of writing, includes SaferCpp, Misra-c:2004 and most of MSC2012 and MSC98 rules.<br/> m0's reports are generated in XML,JSON and simple text(AWK-friendly:RS="\n";FS=":". Look at ReportPrintPretty.sh under extra-tools.).<br/> m0 also accpets a formatted file as its input, passing it all the options needed to run it. This feature is only available if m0 is called through mutator.sh. For an example please look below.<br/> Also to refrain from confusions, m0's executable is actually named mutator-lvl0 but for the sake of berevity it will be referred to as m0.<br/>

Safercpp

Runs the automatic refactoring sets on your source code, automatically changing your code to use the SaferCpp libraries.<br/> SaferCPlusPlus is essentially a collection of safe data types that are compatible with, and can substitute for, common unsafe native C++ types. You can read more here.<br/>

mutatord

The mutator server/daemon and the client are also provided as optional features.<br/> At the time of writing the client and server are provided to facilitate use of m0 as a plugin.<br/>

You can Join the Maillist here, mutator maillist.<br/> You can follow Project mutator on twitter, @xashmith.<br/>

License

SaferCpp is currently licensed under GPL-2.0.<br/> All 3rd party libraries/code have their own respective license.<br/> Excluding SaferCpp and other 3rd party code/libraries, everything else under project mutator is provided under GPL-3.0.<br/>

How to get project mutator

Before you run make, make sure you have all the dependencies:<br/>

• You need LLVM/Clang(for supported versions see the section under building).<br/>
• For safercpp you will need to have LLVM RTTI also.<br/>
• For bruiser you will need the python 3.5 or higher's dev package(source code and libpython), libcapstone, libkeystone and libffi.<br/>
• The other libraries used are either submodules or copied inside.<br/>
• load.py needs capstone. You can get it through pip(pip install capstone).<br/> For More details you can look at the Building section.<br/>

Assuming you already have the dependencies:<br/>

git clone https://github.com/bloodstalker/mutator
git submodule init
git submodule update
make

mutator is also being hosted using IPFS but it's never up-to-date. To get it from IPFS just run:<br/>

git clone https://ipfs.io/ipfs/QmdBBG76K5rNSWB4iK4ZhTtiZAkSsyDpiWzcPsPfnHY2ZA/mutator

NOTE: this is mostly a novelty feature. The copy you can fetch from IPFS is usually outdated.<br/>

To build LLVM/Clang from source take a look at here and here.<br/> To build safercpp-arr you to need to build Clang with RTTI enabled.<br/> If you need any help regarding getting the requirements you can look at mutator's .travis.yaml or check out the nightly builds for Debian/Ubuntu.<br/>

Dev Status

Currently there is only the master branch which is the dev branch. All the as-of-yet implemented features of the project are very much buildable and usable at all times, even during the dev phase on the master branch even if they are called "experimantal". If something's broken, please make a new issue on it.<br/>

• All tools are in the development stage.<br/>

Dev Plans

• Bruiser: have bruiser support nested function calls and calls to external SOs.<br/>

Test Plans

For a detailed list, you can view tests.md under docs.<br/>

• The Dev method I'm using is TDD so of course, we currently have TDD tests.<br/>
• For static analysis tools, mutator uses Coverity which is integrated with Travic CI so it runs every time on every commit.<br/>
• For dynamic analysis tools, currently mutator is using Valgrind. You can run it using ./mutator.sh -test mutator-lvl0 valgrind. You do need to have valgrind installed.<br/>
• The code will be reviewed after the first pre-release version. I'm hoping to find some reviewers but if not, I'll have to do it myself.<br/>
• There will be unit tests after a first pre-release version.<br/>

Announcements

• Introducing cgrep, grep for c/c++ source files.<br/>
• I will be taking a one month break from mutator to learn/work on some other things.<br/>
• Project mutator will be re-licensed to GPL-3.0.<br/>
• bruiser has a working poc demo for asmrewriter.<br/>
• bruiser has a working poc demo for Xobjs. For more info checkout bruiser's README.md.<br/>
• announcing obfuscator, the newest mutator family member. it's a C/C++ source obfuscation tool.<br/>
• mutator has a new experimental member, bruiser. The idea is that we are already inside the code, so why not break it?<br/>
• mutator now has a daemon,a server and a client. It works, but we all know how much weight we can put on "it just works", don't we? I'll be polishing it over the coming days. For more info and detail see README.md under daemon in project root. Also, please do note that you don't have to use the