Home

Awesome

About

Grinder is a system to automate the fuzzing of web browsers and the management of a large number of crashes. Grinder Nodes provide an automated way to fuzz a browser, and generate useful crash information (such as call stacks with symbol information as well as logging information which can be used to generate reproducible test cases at a later stage). A Grinder Server provides a central location to collate crashes and, through a web interface, allows multiple users to login and manage all the crashes being generated by all of the Grinder Nodes.

System Requirements

A Grinder Node requires a 32/64 bit Windows system and Ruby 2.0 (Ruby 1.9 is also supported but you wont be able to fuzz 64bit targets).

A Grinder Server requires a web server with MySQL and PHP.

Features

Grinder Server features:

Grinder Node features:

Grinder Screenshots

Grinder Server Screenshot 1

Grinder Server Screenshot 2

Grinder Node Screenshot

Grinder Crash Screenshot

Fuzzers

Grinder does not include any fuzzers for the Grinder Nodes and you will need to write your own. However a very simple example fuzzer is included (.\grinder\node\fuzzer\SimpleExample.html) to show how to begin writing suitable fuzzers for use with Grinder.

Installing a Grinder Server

Installing a Grinder server requires a web server with PHP and MySQL.

Installing a Grinder Node

For a detailed step by step guide to install a Grinder Node please refer to the following wiki page:

https://github.com/stephenfewer/grinder/wiki/Installing-a-Grinder-Node

For a quick start, the steps for installing a node are as follows:

.\grinder\node>ruby grinder.rb [--config=c:\path\to\alternative\config.rb] --browser=BROWSER

Setting Up Encryption For Crash Information

When a Grinder Node generates a crash in a browser, two files are created within the .\grinder\node\crashes\ directory. The contents of these files are also transmitted to the remote Grinder Server. The .crash file contains useful debugging information (call stack, disassembly, register info, and so on), while the .log file contains the logging information generated by the fuzzer which can be used to generate a reproducible testcase so you can trigger the crash again. As this information is sensitive in nature it is useful (and recommended) to encrypt it.

A Grinder Node can be configured to use an RSA public key to encrypt this information for storage both locally on the respective Node as well as for transmission and storage on the Grinder Server. Simply generate a suitable public key (details below) and edit the config.rb to use this key. Now when you download the crash/log files from the Grinder Server you will need to decrypt them before you can use them.

To generate a suitable key pair you can use the included crypto.rb utility:

.\grinder\node>ruby crypto.rb /generate /pubkey public.pem /privkey private.pem [/keysize 4096] [/keypass MyKeYpAsSwOrD]

The generated public key will need to be copied over to all the Grinder Nodes while the private key will need to be stored securely on the analyst's workstations.

To decrypt an encrypted crash/log file you can then use the following command:

.\grinder\node>ruby crypto.rb /decrypt /privkey private.pem /inputfile XXXXXXXX.XXXXXXXX.crash [/outputfile plaintext.txt] [/keypass MyKeYpAsSwOrD]

Generating a Testcase From a Log File

When you have generated a crash and downloaded the log/crash files you can use the testcase.rb utility to transform the .log file into a html file that will (hopefully) reproduce the crash.

.\grinder\node>ruby testcase.rb [--config=c:\path\to\CONFIG.RB] --log=c:\path\to\XXXXXXXX.XXXXXXXX.log --save=c:\path\to\XXXXXXXX.XXXXXXXX.html

If the log file has been automatically encrypted, you can pass in a private key (and optional keypass) to testcase.rb in order to decrypt the log file on the fly:

.\grinder\node>ruby testcase.rb [--config=c:\path\to\CONFIG.RB] --log=c:\path\to\XXXXXXXX.XXXXXXXX.log --save=c:\path\to\XXXXXXXX.XXXXXXXX.html --key=c:\path\to\PRIVATE.PEM --keypass=PASSPHRASE

Depending on how you write your fuzzers you may need to modify testcase.rb to suit or edit the testcase options ($testcase_opts) in your config file.

If the testcase does not reproduce the crash it is useful to create an 'Alert' within the Grinder Server to alert you by email whenever the same crash is encountered again. Using a different log file for the same crash may help reproduce it.

Source Code

The latest source code for Grinder can be found at https://github.com/stephenfewer/grinder

Bug Reports and Code Contributions

Please file all bug reports via GitHub at the following address: https://github.com/stephenfewer/grinder/issues

Please submit all code contributions as pull requests via GitHub, thanks!.

Donations

If you find Grinder useful, please consider a Bitcoin donation to 12cS37zQSvAGEokQJfWzhwyeGPBA2SwCxQ, thanks!

License

Grinder is licensed under a 3 clause BSD license. Please see the full text of this license in the .\grinder\LICENSE.txt file.

The following libraries are included with Grinder and are licensed separately as follows: