NGFuzz

A command-line wrapper for Go fuzzing that simplifies the process of building, running, and analyzing fuzz tests.

Overview

NGFuzz streamlines the Go fuzzing workflow by providing a simple interface for common fuzzing operations. It wraps the standard Go fuzzing functionality to make it easier to compile fuzz targets, run tests, generate coverage reports, and deduplicate crashes.

Features

• Single command operation for common fuzzing tasks
• Automatic fuzz test discovery and compilation
• Parallel test execution
• Coverage report generation
• Crash deduplication
• Test corpus management

Prerequisites

• Go 1.18 or later
• Clang 17 with fuzzing support
• https://github.com/ispras/casr (crash reporting not available on macOS)

Writing Fuzz Tests

Fuzz tests should be placed in files with _test.go suffix and follow these conventions:

// file: package_test.go

package package

import (
	utils "github.com/trailofbits/go-fuzz-utils"
)

func FuzzMyFunction(f *testing.F) {
    // Fuzz test function
    f.Fuzz(func(t *testing.T, data []byte) {
        DoFuzzMyFunction(data)
    })
}

func InitFuzzMyFunction() {
    // Initialize variables and mocks
}

func DoFuzzMyFunction(input []byte) int {
	if len(input) < 100 {
		return -1
	}

	tp, err := utils.NewTypeProvider(input)
	if err != nil {
		return fuzzFailExitCode
	}

	var object Object
	err = tp.Fill(object)
	if err != nil {
		return -1
	}

    // Fuzz your logic

	return 0
}

Requirements:

• Test files must end with _test.go
• Fuzz function names must start with Fuzz
• Use standard Go fuzzing function signature
• Place seed corpus in the same directory as test file (optional)

Usage

Basic Commands

1. List Available Fuzz Functions

ngfuzz list --rootdir /path/to/project

2. Build and Run Fuzzing

# Fuzz all available functions
ngfuzz fuzz --rootdir /path/to/project

# Fuzz specific functions
ngfuzz fuzz --rootdir /path/to/project --funcs FuzzFunc

# Run with timeout (stop after N seconds)
ngfuzz fuzz --rootdir /path/to/project --timeout 3600

# Run until coverage stops increasing plus N seconds
ngfuzz fuzz --rootdir /path/to/project --timeout -3600

3. Generate Coverage Report

ngfuzz coverage --rootdir /path/to/project 

4. Clean Working Directory

ngfuzz clean

5. Process and Deduplicate Crashes (Linux only)

ngfuzz crashreport 

Dictionary Support

The tool automatically looks for dictionary files in two locations:

• tests/fuzzing/dict.txt in the project root
• tests/fuzzing/<function_name>/dict.txt for function-specific dictionaries

Dictionary format follows libFuzzer conventions:

# Comment
"keyword1"
"keyword2"
# Hex values
\x01\x02\x03

Command Options

Global Flags

• --verbose: Enable verbose logging
• --workdir: Specify working directory for artifacts (default: “.”)
• --rootdir: Specify root directory of the target project

Fuzz Command Flags

• --funcs: Specify list of fuzz functions to run (optional, runs all if not specified)
• --timeout: Set fuzzing timeout in seconds
  • Positive value: Stop after N seconds
  • Negative value: Continue for N seconds after coverage stops increasing

Working Directory Structure

The tool creates and maintains the following directory structure:

workdir/
├── fuzzbin/          # Built fuzz targets
├── fuzzcrashes/      # Detected crashes
├── fuzzreports/      # Coverage reports
├── report/           # Final reports
└── fuzzminimizedcrashes/ # Deduplicated crashes

Contributing

Contributions are welcome. Please open an issue first to discuss proposed changes.

Development Setup

• Clone the repository:

git clone https://gitflic.ru/project/yadro/ngfuzz.git

• Install dependencies:

go mod download

• Build the project:

make build

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please use the project issue tracker.