README.md

    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.

    Описание

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

    Конвейеры
    0 успешных
    0 с ошибкой