Debian Codegraph @

fuzz/README.md

raw
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.