mutator

Build Status Build status Coverity Scan Build Status Codacy Badge CII Best Practices Coverage Status Gitter

Table of Contents

Overview

mutator is a suite of tools for C,C++ and machine code.
Here’s a detailed list of what’s currently available:

bruiser

At its core, bruiser is a Lua REPL:

cgrep

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

obfuscator

obfuscator is a C/C++ source code obfuscator.
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.
You can also use the script as a standalone to dump info on the ELF file to stdout.
delf is also hosted ona mirror repo here.

dwasm

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

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.
luatablegen is also hosted on a mirror repo here.

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.
m0’s reports are generated in XML,JSON and simple text(AWK-friendly:RS="\n";FS=":". Look at ReportPrintPretty.sh under extra-tools.).
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.
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.

Safercpp

Runs the automatic refactoring sets on your source code, automatically changing your code to use the SaferCpp libraries.
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.

mutatord

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

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

License

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

FOSSA Status

How to get project mutator

Before you run make, make sure you have all the dependencies:

Assuming you already have the dependencies:


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:


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.

To build LLVM/Clang from source take a look at here and here.
To build safercpp-arr you to need to build Clang with RTTI enabled.
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.

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.

Dev Plans

Test Plans

For a detailed list, you can view tests.md under docs.

Announcements

Building and Running

Building

Requirements

Linux

First clone the repo and then initialize and update the submodule in it:


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

Here Are the build options:

So for example if you want to build the code with clang++ without any coverage, and you only want to build the Misra-C rule checker, you should run:

make mutator-lvl0 CXX=clang++ BUILD_MODE=COV_NO_CLANG

Note: if you are building the llvm and clang libraries from source, then the llvm-config name will be llvm-config but if you are getting the libraries from a repository the llvm-config executable name may not be the same. In that case, you need to also pass make the LLVM_CONF variable. For example on Ubuntu trusty, if you get the repositories from llvm nightly builds, the llvm-config executable name will be llvm-config-3.9 so you need to run:

make mutator-lvl0 CXX=clang++ BUILD_MODE=COV_NO_CLANG LLVM_CONF=llvm-config-3.9

Also do note that building the llvm libraries from source in Debug mode will require big space on your harddrive and will need quite some RAM and needless say is slower. Release mode is less resource-greedy, of course.
Finally if you are having problems with the build, you could take a look at .travis.yml or under CITPreBuildDep.sh under extra-tools for some hints or help apart from asking for help, of course.

After building the executables, you can run(i personally don’t):


make install

Windows

Currently only cygwin builds are supported.
To build on cygwin just get the dependencies and run make. There are no extra steps required.
If you have trouble building, you can take a look at appveyor.yml in the root directory.

Running

To run any of the executables, just give a filename or a whitespace-separated list of files. The executables will print out the results to stdout.
To run the executables with the mutator UI, you can use mutator.sh. For a list of available options, you can type ./mutator.sh -h.

m0 options:

Note

Some of Misra-C rules are already implemented by Clang as warnings, so for those cases, mutator uses the built-in diagnostics instead of re-inventing the wheel. For those diagnostics to appear in the mutator report you should refrain from using the Clang -w flag as that silences the warnings.

If you are running the executables using mutator.sh you don’t need to read this note through. If you are running the executable directly however, then you have to pass groups of arguments in a specific order otherwise the executable won’t be able to recognize the options and will throw errors. For example this is the right way to run mutator-lvl0:


./mutator-lvl0 -SysHeader=false -MainOnly=true  ./test/testFuncs3.c -- -std=c90 -Wall -I/lib/gcc/x86_64-redhat-linux/5.3.1/include

So for example if you want to run the TDD tests for the Misra-C checker, you run:


./mutator.sh -c misrac -i ./test/testFuncs2.c ./test/testFuncs1.c -opts "-Wall -std=c90"

Do note that if your file has included standard header libraries, you do need to tell it where to look for them, so for the above example on Fedora, you would need to run:


./mutator.sh -c misrac -i ./test/testFuncs2.c ./test/testFuncs1.c -opts "-Wall -I/lib/gcc/x86_64-redhat-linux/5.3.1/include/"

Here’s the command I use to run the TDD tests:


/mutator.sh -c misrac -i ./test/testFuncs1.c ./test/testFuncs2.c -pp -opts "-std=c90 -I/lib/gcc/x86_64-redhat-linux/5.3.1/include" -copts "-SysHeader=false -MainOnly=true" 2> /dev/null

The Action File

mutator can accept a file which tells it what to do. Currently this feature is only supported for m0. You can find a sample under ./samples named action_file.mutator.


action_name:my_action1
executable_name:mutator-lvl0
#these are the options specific to the executable
exec_opts:-SysHeader=false -MainOnly=true
in_files:./test/testFuncs1.c ./test/testFuncs2.c ./test/testFuncs3.c
#clang options
libtooling_options:-std=c90 -I/lib/gcc/x86_64-redhat-linux/5.3.1/include
#the output file
out_files:./test/misra-log
#the log file
log_files:
print_pretty:true
end_action:run

Here’s the explanation for the fields:

Field names shall not have preceding whitespace or tab. The : character shall immediately follow the field name with options appearing after it.
end_action field should appear as the last field of a action.

You can run the sample action file with this:


./mutator.sh --file samples/action_file.mutator

Currently, the mutation-only features(mutation for the sake of mutation, technically implementing Misra-C is also a form of mutation) are turned off in mutator and mutator-lvl2 though some automatic code refactoring features work in both executables. Just run a sample code through mutator and then mutator-lvl2 for a demo.

If your code needs a compilation database for clang to understand it and you don’t have one,you can use Bear. Please note that bear will capture what the make runs, not what is in the makefile. So run make clean before invoking bear make target. cmake can also generate compilation databases if you are using it.

Implementation Notes

This part contains notes regarding the implementation of m0, m1 and m2.

mutator-lvl0

Directory Outline

Here’s a quick look into the project files and directories:

Dev Method

TDD tests are created for each added feature which are stored under the test folder in the repo.
Smoke tests and Daily builds are conducted to make sure the code base builds correctly more than once every day.
Every time there is a new commit, the code base is buildable and runnable. If you are having problems, raise an issue or let me know.
The code base uses Coverity for static analysis and CI Travis for checking the build matrix.
Coveralls integration with Travis for code coverage.
Also the precommitTests.sh script under extra-tools is run before every commit to make sure commits are not horribly broken.<br>

Notes

The project will be updated every time there is a major LLVM release and will use those libraries instead of the old ones for development

The project might, at a later point in time, start using Cmake for the build process.
Misra 2012 support will be added in the future.
Also a note regarding building the LLVM libraries. It is safer to build the libraries with clang++ if you’re going to later use those libraries with clang++(you can get the distro version of clang from your distro’s repo). The same applies to g++.
The master branch is the dev version. Release versions will be forked.

FAQ

tool complains that it can’t find stddef.h

Tool complains that it cannot find stddef.h or some other similar header. If that happens to you , it’s because the tool can’t find the clang built-in headers. run llvm-config --libdir, then head on to clang. Inside that directory you should see one(or maybe more) llvm/clang versions. Pick the one you used to build cgrep against. Inside that directory there will be a directory named include. Pass that to the tool any way you see fit.
Alternatively, $(llvm-config --libdir)/clang/$(llvm-config --version)/include should give the path the tool needs to include. If you build your llvm/clang from upstream, this might not work. SVN bulds will have the svn string attached to the version number.
You could,for example, use --extra-arg=-I/usr/lib/llvm-9/lib/clang/9.0.0/include to call cgrep or you could just alias cgrep to cgrep --extra-arg=-I/usr/lib/llvm-9/lib/clang/9.0.0/include.

Acknowledgements

Project mutator uses the following libraries:

All mutator source code is provided under GPL-3.0.
All libraries have their respective licences. For more info you can just visit their respective links.

Feedback

Besides that, If you have any suggestions or have any feature requests for project mutator, you can send them to thabogre@gmail.com. I’ll try to keep an open mind, so even if you feel like it might not be right up mutator’s alley, do send them. Worst case, I’ll just say no.

TODO List

For a list of things that need to be done, take a look at the list of issues.

Contributions

For a full description please read Contributions.md in the repo root.
You can also choose to contact me directly if you want to.

Support

Well, I don’t have the Misra-C:2012 Document. If you or your organization/company are willing to donate a copy to mutator, hit me up.

Testers are always welcome. If you are interested, let me know. Testing mutator is as important, if not more, than implementing it.

Contact

You can email me at thabogre@gmail.com, there is also the twitter account for the mutator project, @xashmith and there is the mutator maillist, mutator-repost@freelists.org. You need to be a member though to be able to send mail on the maillist. The maillist is moderated.

Gource

Mostly because why not:
gource-vid