2.6 KiB

Raw Blame History

Fuzzing howto

Intended Audience

This document is for a developer who wants to contribute fuzz tests.

Purpose

This document walks you through creating your first fuzzer, running it and evaluating its quality.

Prerequisites

Linux OS or Mac OS.
American Fuzzy Loop if building with GCC.

Steps

Create a fuzz test in the existing project at ./tests/fuzz. Fuzz test must follow <test name>-fuzzer.cc naming scheme and implement a LLVMFuzzerTestOneInput entry point.

cat << EOF > ./tests/fuzz/test_name-fuzzer.cc
#include <stdint.h>
#include <cstdlib>

extern "C" int LLVMFuzzerTestOneInput(const uint8_t* data, size_t size) {
  // put your fuzzing code here and use data+size as input.
  return 0;  // always return 0
}
EOF

Implement test logic under LLVMFuzzerTestOneInput.

See example fuzz test at tests/fuzz/read_network-fuzzer.cc.

Build fuzz tests with -DENABLE_FUZZING=ON flag for cmake.

    mkdir -p build && \
    (cd build && \
    CXX=afl-g++ CC=afl-gcc cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_FUZZING=ON -DENABLE_TESTS=ON .. && \
    make fuzz --jobs=$(getconf _NPROCESSORS_ONLN))

Prepare sample inputs for your fuzz test to teach fuzzer engine on input structure

(cd bin/intel64/Debug && \
mkdir test_name-corpus && \
echo sample input > test_name-corpus/in1.txt)

Evaluate fuzz test with afl-fuzz fuzzing engine

Run fuzz test:

(cd bin/intel64/Debug && \
afl-fuzz -i test_name-corpus -o test_name-out -- ./test_name-fuzzer @@

While fuzz test is running it prints out statistics. Besides just crashes uniq crashes and hangs uniq hangs you should care about fuzz test quality:

Fuzz test should be fast - speed of execution exec speed should be at least 100 exec/s. Speed less than 20 exec/s is not acceptable.
Fuzz test should be able to explore new code paths map coverage and findings in depth. Confirm it is increasing while fuzz test is running.

Reproduce fuzz test findings

All issues found by fuzz test are stored as a file in output folder specified earlier via -o afl-fuzz option. To reproduce an issue run fuzz test executable with an issue file as an argument.

Summary

We have created a simple fuzz test, run it and asses its results.

Extension

Try run parallel fuzzing with the help of afl-utils.

Tips or FAQs

GCC 7 in Ubuntu 18.04 LTS has a defect. Upgrade GCC 7 for AFL to work. GCC version Ubuntu 7.3.0-27ubuntu1~18.04 works OK.

2.6 KiB Raw Blame History