Fuzzware Fuzzing Pipeline

Note: This is a subcomponent of Fuzzware. You will not want to manually try to install this component. The place to start is the fuzzware parent repo. Please refer to the documentation and scripts provided there for installing Fuzzware and learning about how to use it.

This project aims to provide job distribution covering all aspects of fuzzware to fuzz a bare-metal firmware image.

Most of the actual work is performed by fuzzing workers using fuzzware's emulation component as a harness. The code which implements this harness resides in the fuzzware-emulator repository.

Different parts of required functionality are combined:

1. Baseline fuzzing of a binary firmware image file given a configuration file. This job is performed by a configurable number of fuzzing processes
2. Generation of trace files for an input file when thrown against a given firmware environment
3. Generation of MMIO access state files for use in MMIO model generation
4. MMIO model generation using angr

Installation

To install, you should use the installation scripts and documentation provided in the parent fuzzware directory/project.

Usage

Documentation on running the pipeline in docker as well as in a local installation is given in the parent README.

Among the most common arguments are:

1. Number of fuzzer processes (-n)
2. Total runtime of the pipeline (--run-for)
3. Using a custom base inputs directory (--base-inputs)

To read about all command-line arguments, use (within docker or a local fuzzware virtualenv):

fuzzware pipeline -h

Results Directory Structure

When running, fuzzware will create a fuzzware-project directory next to your firmware image configuration file. This directory contains all information on the generated fuzzing inputs, generated configurations, intermediate files and logs. The following subdirectories can be found:

1. fuzzware-project/logs: Logs for the worker instances which are automatically spawned by the pipeline in the background
2. fuzzware-project/mmio_config.yml: The MMIO configuration which was automatically generated.
3. fuzzware-project/main0XX: The directory holding the exact configuration and fuzzer output directories as well as compact traces for a given configuration iteration. Higher numbers in directory names indicate later configuration iterations with more applied models or generated firmware start states.
4. fuzzware-project/main001/fuzzers/fuzzer1: The AFL output directory for the first fuzzing instance of the first configuration iteration. This includes all standard directories such as queue and crashes and fuzzer stats. It also includes the custom traces directory which holds a compact variant of traces which are used by the pipeline for introspection.
5. fuzzware-project/stats: After using the fuzzware genstats utility, summary metrics will appear here.

Running Inputs within an fuzzware-project Directory

To understand how the emulator needs to be configured to run an input which got generated by a fuzzer within a fuzzware-project directory, we will first reproduce the emulator behavior the manual way (using the raw fuzzware emu utility), and then the easy way (using the fuzzware replay convenience wrapper).

Using the fuzzware-project/mainXXX directories with the fuzzware emu utility, the exact behavior of firmware executions for a given input within the directory can be reproduced. To re-run the emulation of a given input file, use the exact configuration file fuzzware-project/mainXXX/config.yml, command line options fuzzware-project/mainXXX/extra_args.txt (empty except for pipeline configurations using custom boot descriptions in config.yml) for an input file in one of the fuzzer input or crash directories fuzzware-project/mainXXX/fuzzers/fuzzer1/queue/id:000000,* and fuzzware-project/mainXXX/fuzzers/fuzzer1/crashes/id:000000,*.

As the command-line arguments of fuzzware emu can become clumsy within fuzzware-project/mainXXX directories, you can have the fuzzware replay utility automatically put these arguments together for you:

The following fuzzware emu command line (where you would still need to take care of relative paths within extra_args.txt):

fuzzware emu -c fuzzware-project/main002/config.yml $(cat fuzzware-project/main002/extra_args.txt) fuzzware-project/main002/fuzzers/fuzzer1/queue/id:000000,orig:01_base_input_512_ones

Can also just be called via:

fuzzware replay fuzzware-project/main002/fuzzers/fuzzer1/queue/id:000000,orig:01_base_input_512_ones