Skip to content

Installing a Grinder Node

Jump to bottom
Stephen Fewer edited this page Feb 28, 2014 · 9 revisions

The following is a step by step guide to install and run a Grinder Node on a Windows host.

Install

  1. Download and install Ruby (http://rubyinstaller.org/downloads/). Ruby 2.0 x64 is recommended. When installing Ruby, be sure to select to 'Add Ruby executables to your PATH' as this will make it easier to work from the command line later on. Ruby 2.0 x64 can fuzz both 32bit and 64bit targets. Ruby 2.0 or 1.9 x86 can only fuzz 32bit targets.

  2. Download the latest Grinder source code. The easiest way to get the latest source code is to download a ZIP file of the master (https://github.com/stephenfewer/grinder/zipball/master) if you require the latest development version. Alternatively you can download a ZIP file of the latest tagged release (https://github.com/stephenfewer/grinder/tags).

  3. Extract all the source code to the folder 'C:\grinder'.

  4. Make a new directory 'C:\symbols' for symbol files to be downloaded to during fuzzing.

  5. Copy the grinder_logger.dll to the correct location(s):

  • On a 32bit Windows system: Copy '.\grinder\node\data\x86\grinder_logger.dll' to 'c:\windows\system32'
  • On a 64bit Windows system: Copy '.\grinder\node\data\x86\grinder_logger.dll' to 'c:\windows\syswow64'
  • On a 64bit Windows system: Copy '.\grinder\node\data\x64\grinder_logger.dll' to 'c:\windows\system32'
  1. Now you must edit the config file to suit this node. The default config file is located at 'C:\grinder\node\config.rb'. If you only plan to run one Grinder Node on this host you can edit this default config file. If however you plan on running two or more nodes on this host you will need to copy the default config file and create a unique config file for each Grinder Node you wish to run on this host. Later when you bring up a node you can specify the appropriate config file to use. For a simple configuration you will only need to edit the $grinder_node, $webstats_baseurl and $webstats_key variables.

  • You must specify a unique name for this node via the $grinder_node variable.

  • When a crash is detected a hash value of the call stack is generated to help identify unique and similar crashes. You can optionally seed this hash value by modifying the $hash_seed variable. Only modify this variable if you want your crash hashes to be different from other peoples. Also it is important that all your own Grinder Nodes use the same hash seed value.

  • Each Grinder Node instance will create a HTTP server in order to serve out the fuzzers to the target browser. You must modify the $server_address and $server_port values if needed but the default values should be fine. If however you are running more then one Grinder Node on this host you should specify a unique $server_port so as not to conflict with any other node on the same host.

  • The $crashes_dir specifies where all crash and log files will be stored after a crash has been detected in a browser. The default value for this will place all crash and log files in 'C:\grinder\node\crashes'.

  • The $fuzzers_dir specifies where all the fuzzers are located. The default value for this will locate all the fuzzers from 'C:\grinder\node\fuzzers'.

  • The $symbols_dir specifies where all the PDB files will be downloaded and saved to from the various symbol servers used by the Grinder Node. The default value will store the symbol files in 'C:\symbols'.

  • If you have more then one fuzzer located in your $fuzzers_dir location you can use the $swap_fuzzers_count variable to force the Grinder Node to change over to the next fuzzer every N testcases in order to give each fuzzer an equal attempt at generating some crashes.

  • To avoid the situation whereby a browser is indefinitely hung on a testcase and will never continue, the Grinder Node will automatically restart itself every 30 minutes. You can change this value by modifying the $debugger_restart_count variable. It is best left around the 30 to 60 minute mark.

  • The $logger_dir variable is the temporary location where log files are written to during fuzzing (via grinder_logger.dll which is injected into the browser). This location must be writable from a Low integrity process so the most suitable location is the default 'C:\Users%USERNAME%\AppData\Local\Temp\Low'. The %USERNAME% keyword will be resolved at run time to the current user running the node. Note, on older systems (2003/XP) you will need to use a directory such as 'C:\Documents and Settings%USERNAME%\Local Settings\Temp' instead.

  • The $internetexplorer_exe, $chrome_exe, $firefox_exe, $safari_exe and $opera_exe variables should all point to the location of the respective browsers main exe file.

  • The $crashes_encrypt variable lets you specify if you wish to encrypt all crash and log files with an RSA public key. The default for this is false. If you set this variable to true you must then use the $public_key_file variable to specify the location of an RSA public key to use.

  • If you have also installed the Grinder Server to collate crashes from all of your Grinder Nodes then you must set the $webstats_baseurl variable to point to the Grinder Servers status.php page. When you install a Grinder Server you choose a value for the Grinder Key, this value must entered into the $webstats_key variable and be the same for all the Grinder Nodes so as they can successfully communicate with the Grinder Server. If you are using basic auth for communication to the Grinder Server then set the $webstats_username and $webstats_password variables to suit. If you are not using basic auth then just leave these as nil. If your Grinder Server is using HTTPS instead of HTTP then set $webstats_https to true.

  1. With the config file edited to suit your Grinder Node you can now bring up the node and start fuzzing. Open a Command Prompt and change into the grinder node directory cd c:\grinder\node\. This is important as the node will rely on some files to be relative to this path.

  2. Now bring up the node via the following command (run from the c:\grinder\node\ directory): C:\grinder\node>ruby grinder.rb --browser=IE. You can use the values IE, FF, SF or CM to fuzz a particular browser. Alternatively you can specify a config file to use via the --config parameter, e.g.: C:\grinder\node>ruby grinder.rb --config=c:\config_g2.rb --browser=IE

  3. You may be presented with a dialog to accept the license for using the symbol server, just accept to continue. To avoid this dialog you can simply create the file 'C:\grinder\node\data\symsrv.yes' to indicate your agreement (This file is also created if you accept the dialog).

  4. Check for any error messages to determine if there is an issue with your setup. Also it is worth double checking that some XML log files have been created in the $logger_dir you specified as this indicates the fuzzer is logging successfully.

Tips

  • You can use a RAM disk for the temporary location where log files are written to during fuzzing (via grinder_logger.dll which is injected into the browser) and pointed to by the $logger_dir variable in your config.rb settings. A freeware RAM Disk application is Datarams RAMDisk (http://memory.dataram.com/products-and-services/software/ramdisk). Once a RAM disk has been created you will need to format it and map it to a suitable drive (e.g. Z:). You may also need to adjust the integrity level of the drive to Low in order for logging to work (you can use the command: icacls.exe z: /setintegritylevel low).

  • You may want to disable automatic crash reporting on whatever browser(s) you are fuzzing.

  • If you are developing a new fuzzer you can use the --fuzzer=FUZZER param when bringing up a Grinder Node so as to only load that fuzzer into the node and ignore any other fuzzers present in the nodes fuzzer directory, e.g. C:\grinder\node>ruby grinder.rb --config=c:\g1.rb --browser=IE --fuzzer=MyAwesomeNewFuzzer

Clone this wiki locally