Fuzzer harnesses for H3

This directory contains helper programs for testing the H3 library using the American fuzzy lop/ AFL++ or libFuzzer fuzzers. Fuzzing is a technique for discovering crashes and other edge cases in code such as the H3 core library.

Function coverage

The public API of H3 is covered in the following fuzzers:

Internal function coverage

In addition to the public API, the following internal functions of H3 are covered in fuzzers:

libFuzzer Usage

libFuzzer is one of the supported fuzzing drivers.

This is the fuzzer used in oss-fuzz.

Build

You must build H3 with Clang and enable support for libFuzzer.

CC=clang cmake -DENABLE_LIBFUZZER=ON .
make fuzzers

Run

To begin fuzzing, execute the fuzzer binary:

fuzzerLatLngToCell

For command line options including how to specify a test corpus, consult the libFuzzer documentation.

AFL Usage

AFL/AFL++ are supported fuzzing drivers.

Installation

apt install afl-clang

(There is also an afl-cov which looks interesting but isn't necessary.)

Build

You must compile with the instrumented compiler:

CXX=afl-clang++ CC=afl-clang cmake .
make fuzzers

Generate a blank (zeroed) test case file. This will not be very a interesting test case but is usedful for having files of the right size.

fuzzerLatLngToCell --generate bytes24

An individual fuzzer run is invoked as follows. The argument is a file containing the number of bytes needed.

fuzzerLatLngToCell bytes24

Run

To begin running the fuzzer, run the following. The testcase directory (testcase_dir) should contain a file with at least the right number of bytes that the fuzzer will read (this can be generated using the --generate option above.)

afl-fuzz -i testcase_dir -o findings_dir -- fuzzerLatLngToCell @@