| 1 |
# Fuzz Testing |
| 2 |
|
| 3 |
A single libFuzzer fuzz target is provided which tests `bstrlib`, `bstraux`, and optionally `utf8util` and `buniutil`. |
| 4 |
|
| 5 |
Unicode support is conditional: when the project is built with `-Denable-utf8=true`, |
| 6 |
the target is compiled with `-DBSTRING_ENABLE_UTF8` and the unicode fuzzing code |
| 7 |
is included automatically. |
| 8 |
|
| 9 |
## Prerequisites |
| 10 |
|
| 11 |
libFuzzer is part of LLVM. The compiler runtime libraries are shipped in a |
| 12 |
separate package from the compiler itself. |
| 13 |
|
| 14 |
**Debian/Ubuntu:** |
| 15 |
|
| 16 |
```sh |
| 17 |
sudo apt-get install clang libclang-rt-dev |
| 18 |
``` |
| 19 |
|
| 20 |
**Fedora:** |
| 21 |
|
| 22 |
```sh |
| 23 |
sudo dnf install clang compiler-rt |
| 24 |
``` |
| 25 |
|
| 26 |
## Build |
| 27 |
|
| 28 |
```sh |
| 29 |
CC=clang meson setup build-fuzz \ |
| 30 |
-Denable-fuzzing=true \ |
| 31 |
-Denable-tests=false \ |
| 32 |
--buildtype=plain |
| 33 |
meson compile -C build-fuzz |
| 34 |
``` |
| 35 |
|
| 36 |
## Run |
| 37 |
|
| 38 |
```sh |
| 39 |
# Run against the seed corpus for 60 seconds |
| 40 |
./build-fuzz/fuzz/fuzz_bstring fuzz/corpus/ -max_total_time=60 -max_len=260 |
| 41 |
|
| 42 |
# Run indefinitely, saving new corpus entries and crash inputs as they are found |
| 43 |
mkdir -p fuzz/crashes |
| 44 |
./build-fuzz/fuzz/fuzz_bstring fuzz/corpus/ \ |
| 45 |
-max_len=260 \ |
| 46 |
-artifact_prefix=fuzz/crashes/ \ |
| 47 |
-jobs=$(nproc) |
| 48 |
``` |
| 49 |
|
| 50 |
Useful libFuzzer flags: |
| 51 |
|
| 52 |
| Flag | Description | |
| 53 |
| --- | --- | |
| 54 |
| `-max_total_time=N` | Stop after N seconds | |
| 55 |
| `-jobs=N` | Run N parallel fuzzing instances | |
| 56 |
| `-max_len=4096` | Cap input size in bytes | |
| 57 |
| `-artifact_prefix=DIR/` | Directory for crash and timeout inputs | |
| 58 |
| `-runs=N` | Stop after N iterations | |
| 59 |
|
| 60 |
## Reproducing a crash |
| 61 |
|
| 62 |
If a crash input is found, reproduce it by passing the file directly to the |
| 63 |
relevant target: |
| 64 |
|
| 65 |
```sh |
| 66 |
./build-fuzz/fuzz/fuzz_bstring path/to/crash-input |
| 67 |
``` |
| 68 |
|
| 69 |
## Seed corpus |
| 70 |
|
| 71 |
The `corpus/` directory contains initial seed inputs that guide the fuzzer |
| 72 |
toward interesting code paths on the first run. As the fuzzer discovers new |
| 73 |
coverage it writes additional entries to the corpus directory automatically. |
| 74 |
|
| 75 |
## CI (ClusterFuzzLite) |
| 76 |
|
| 77 |
The `.clusterfuzzlite/` directory at the repository root contains the |
| 78 |
Dockerfile and `build.sh` used by ClusterFuzzLite. The GitHub Actions |
| 79 |
workflow at `.github/workflows/clusterfuzzlite.yml` runs two jobs: |
| 80 |
|
| 81 |
- **code-change** — 60 seconds on every push and pull request targeting `main` |
| 82 |
- **batch** — 1 hour on a weekly schedule |
| 83 |
|
| 84 |
Crash reports from the batch job are surfaced as GitHub Security alerts via |
| 85 |
SARIF upload. |