Coverage Guided Fuzzing Framework for Image Classifiers

This repository contains a coverage-guided fuzzing framework for Deep Neural Network image classifiers. It identifies corner case inputs from existing limited test inputs by mutating seed images, keeps the most useful inputs in a queue, and measures how well the resulting data explores a model's internal behavior using various coverage criteria.

In practice, the codebase helps you:

1. Build an initial seed set for a model and dataset.
2. Construct a model profile that the fuzzer uses to guide mutations.
3. Run coverage-guided fuzzing to discover new corner cases.
4. Evaluate the generated data with latent-space and coverage-based metrics.

The repository currently supports MNIST, SVHN, GTSRB, and CIFAR-100 datasets but can be easily extended to other datasets.

What Runs What

• main.py runs the fuzzing loop.
• evaluation.py evaluates DNN performance on generated or stored datasets.
• config/ contains dataset/model configuration files.
• fuzzer/ contains the seed construction, profile construction, coverage tracking, mutation loop, and queue logic.
• metrics_utils/ and coverage_calculation/ contain the quality and coverage metric helpers.

How The Fuzzer Works

The workflow is:

1. Load a trained classifier and its matching configuration file.
2. Build or load a model profile that describes coverage-relevant internal activations.
3. Build or load an initial seed corpus.
4. Run the fuzzer, which mutates seeds and keeps inputs that improve coverage or other selected criteria.
5. Save the discovered inputs and crash/corner-case artifacts in the output directory.

The main script supports wide-range of structural and non-structural fuzzing criteria for evaluating DNNs. This includes various forms of Neuron Coverage - nc, kmnc, bknc, tknc, nbc, snac, and Non-stuctural latent-space based coverage criteria - lsc, dsc, mdsc, and lscd.

Example Run

For a typical fuzzing run, start with a dataset-specific config file and a directory of seed images:

python main.py -i /path/to/seed_dir -o /path/to/output_dir -config_file config/cifar100.toml

If you want the project to generate inputs for you, rebuild the seed corpus first:

python main.py -i /path/to/seed_dir -o /path/to/output_dir -config_file config/cifar100.toml -construct_seeds 1

If the model profile is missing or outdated, rebuild it before fuzzing:

python main.py -i /path/to/seed_dir -o /path/to/output_dir -config_file config/cifar100.toml -construct_profile 1

Quick Start

1. Set up Python

Create and activate a virtual environment, then install dependencies:

python -m venv .env
source .env/bin/activate
pip install -r requirements.txt

If you are on macOS, use requirements_mac.txt and follow the extra system-package notes in that file.

2. Verify the entry point

python main.py --help

3. Run fuzzing

Pick one of the configuration files in config/ and point the fuzzer at an input seed directory and output directory:

python main.py \
   -i /path/to/seed_dir \
   -o /path/to/output_dir \
   -config_file config/cifar100.toml

To rebuild the seed corpus or the model profile, use the matching flags:

python main.py -i /path/to/seed_dir -o /path/to/output_dir -config_file config/cifar100.toml -construct_seeds 1
python main.py -i /path/to/seed_dir -o /path/to/output_dir -config_file config/cifar100.toml -construct_profile 1

4. Evaluate results

Use evaluation.py to score generated data or stored crash/corner-case inputs.

Requirements And Setup Notes

• Each run needs a trained model checkpoint, a matching config file, a model profile, and an initial seed set.
• Model checkpoints are expected in the location referenced by the selected config file.
• New architectures need implementations for intermediate_outputs and seed-selection logic compatible with the fuzzer.
• The project uses Git LFS for large binary artifacts such as .pkl, .pth, and .pt files.

Repository Layout

• dataset/: dataset wrappers and preprocessing helpers.
• fuzzer/: the core fuzzing engine and queue management.
• coverage_calculation/: scripts for computing coverage and related metrics.
• metrics_utils/: metric utilities used during evaluation.
• models/: model definitions for supported architectures.
• mutation/: input mutation operators.
• plot_scripts/: analysis and plotting helpers.

Formatting

If you change Python files, run isort and black before sending updates.

pip install isort black
isort path/to/file.py
black path/to/file.py

Accessing Datasets (Download Link)

Due to the large size of our corner cases datasets used in our empirical study, we are sharing them via a cloud download link. Please download the necessary files using the following link: https://www.dropbox.com/scl/fi/a2dws2hjpf8qslqc2riqx/fuzzing_data_eq_samples.zip?rlkey=fy22mwm4c1j73rczq0ag4mgbp&st=thm1w4wy&dl=0