Foozzer - a quick and dirty, cross-platform fuzzing framework
=============================================================

Foozzer was originally created for fuzzing the playlist loader
of foobar2000[1].

From that point it evolved into a modular general purpose
fuzzing framework that is easily extensible with additional
runner and mutator modules.


Mode of operation
-----------------

The basic concept behind Foozzer is as follows:

* The main script start a target process, as specified by
  the selected runner module, under the supervision of
  Dr. Memory[2].
* Input files are generated by the selected mutator plugin.
* For every generated input file the runner module's run()
  method is called which then executes the necessary
  actions to initiate the processing of the input file
  in the target process.
* Information on the current iteration of and any errors
  found by Dr. Memory is written to a logfile for
  further examination.
* If errors are encountered, e.g. unexpected behavior of
  the target process that prevents the runner from
  correctly operating the process or crashes of the
  target the fuzzing process is reset to a known good
  state and continued with the next iteration of the
  mutator.
* Since interaction with the main process might be
  inhibited by certain types of runners, e.g. ones
  the cause high frequency mouse and keyboard
  operations, the process can be controlled via
  trigger files.
  The fuzzing process will only run if a file named
  'foozer.run' is present in the output directory
  specified on the command line and will pause without
  terminating the target process if a file named
  'foozer.pause' is present in the same directory.


Available plugins
-----------------

Foozzer comes with a runner plugin for fuzzing the
playlist loader of foobar2000 as well as a mock runner
for testing and the following example mutators:

'dry_run' only executes a single run with the
unmodified input file. This mutator should be used to
check if a fuzzing setup is generally sound before
the fuzzing with an actual mutator is started.

'fpl_basic' is a demo mutator for foobar2000 playlists
that should also work well on most other types of files.
It iterates over an input file and successively modifies
a single byte on each run.

'dword' is a generic mutator that iterates through
input files in 32 bit increments and sets each 32 bit
value to different extreme values.

'bitflip' iteratively flips every single bit in the
input file.

Installation and Dependencies
-----------------------------

No installation is required. foozzer.py can be run as is.

A working installation of Python 3.7 or newer is required.
Depending on the selected runner and mutator additional
modules might be required.

Dr. Memory is also required to run Foozzer although it does
not have to be installed system wide but can be run
directly from e.g. a download directory.
The path to Dr. Memory is specified on the command line
with the '-D' option. (See Example for details)

The included runner for foobar2000 depends on pyautogui[3].

In general Foozzer should be operating system independent
and work well on all platforms for which Dr. Memory is
available.

Individual runners might be platform specific as is the
case with the foobar2000 runner since the target
application is only available for Windows.


Example
-------

Required parameters for Foozer are:
* The directory containing the input files.
* A writeable directory for output files and state information.
* The path to the Dr. Memory binary.
* The name of the runner to use.
* The name of the mutator to use.

The available plugins can be listed with the option '-L':

$ python foozzer.py -L
    
    Mutators:
    
      dry_run : Single run with the first file in the input directory and not mutations applied
      dword : Iterates through file in 32 bit increments
      fpl_basic : Modifies individual bytes in the input file
    
    
    Runners:
    
      foobar2k : foobar2000 playlist fuzzer
      mock : mock runner


Using the foobar2k runner
-------------------------

The foobar2k runner needs the following additional parameters:
  * The path to foobar2000.exe
  * The path of the resource directory containing sample images
    of the GUI elements that are to be used.

A typical command line for the foobar2k runner might look like this:

> type nul > D:\Workspace\tmp\out\foozzer.run
> python foozzer.py -i D:\Workspace\tmp\in -o D:\Workspace\tmp\out -D "C:\Program Files (x86)\Dr. Memory\bin" -m fpl_basic -r foobar2k -- -F "C:\Program Files (x86)\foobar2000" -R D:\Workspace\foozzer\images


Using the mock runner
---------------------

For testing mutators or core program logic a mock runner is provided.
This runner does start a target process with a set of supplied arguments
under the supervision of Dr. Memory but does not interact with it
afterwards. Therefore an unlimited number of calls to its run() method
can be made to e.g. check if input files are generated correctly by
the selected mutator or if process creation and termination work as
intended.

A typical command line for the mock runner might look like this:

$ foozzer.py -v -v -i /tmp/in -o /tmp/out -D /usr/local/bin/DrMemory-Linux-2.3.0-1/bin64/ -m dry_run -r mock -- -t /usr/bin/tail -- -f /dev/null


License
-------

Foozzer is distributed under the terms of the ISC license.

See LICENSE for details.

---------------------------------

[1]: https://www.foobar2000.org/
[2]: http://www.drmemory.org/
[3]: https://github.com/asweigart/pyautogui