Written and maintained by CASRAI Editorial Board
Published · Last updated
On this page
libFuzzer is the in-process, coverage-guided fuzzing engine that ships with the LLVM project: you write one function that receives a byte buffer, link it with the engine using Clang, and libFuzzer repeatedly mutates inputs, keeps the ones that reach new code and reports the first input that makes the function crash, hang or run out of memory. It is used to find memory-safety and robustness bugs in parsers, decoders and other code that consumes untrusted bytes, and it is usually paired with AddressSanitizer so that silent memory errors become reportable crashes.
What libFuzzer is used for in research
In security and software-reliability research, fuzzing is the practice of feeding a program large numbers of generated inputs to expose defects that a hand-written test suite did not anticipate. libFuzzer is a feedback-driven engine: it instruments the code under test, observes which code paths each input reaches, and keeps inputs that add new coverage in a corpus that it then mutates further. Because it runs inside the same process as the code under test, one fuzz target can execute thousands of inputs per second when the target is small and fast.
The LLVM documentation is explicit about the engine’s scope: libFuzzer is best suited to libraries that accept data as an array of bytes, are fast (the documentation warns that targets taking more than about 10 ms per input are a poor fit), and do not depend on file paths as their input. A fuzz target is a test in the same sense as a unit test, which is why the approach sits next to property-based testing and unit-test frameworks such as Catch2: all of them state a property that must hold for any input, but a fuzz engine chooses the inputs by observing coverage rather than by a generator you wrote. For the wider field this belongs to, see what cybersecurity is.
A research-reporting point worth recording with any result: the engine, the compiler version, the sanitizer set, the options, the seed corpus and the run duration all affect what a fuzzing campaign finds, so a reproducible write-up lists each of them. The corpus directory and the crash artifacts described below are the artefacts to archive.
Install or access libFuzzer
There is nothing separate to install if you already use Clang. According to the LLVM documentation, libFuzzer is included in Clang from version 6.0, and the library version must match the Clang version you compile with, so use the Clang that you build the target with rather than mixing toolchains. The reference page is the LLVM libFuzzer documentation at llvm.org/docs/LibFuzzer.html.
The documentation lists the supported sanitizer combinations: libFuzzer is designed to be combined with AddressSanitizer (ASan) and UndefinedBehaviorSanitizer (UBSan), while MemorySanitizer (MSan) support is described as experimental. It also states that Windows builds without ASan are not supported. AddressSanitizer itself is documented in the Clang manual as functional since LLVM 3.1 on Linux, macOS, iOS Simulator, Android, NetBSD, FreeBSD and (with less support) Windows 8.1 and later.
Step by step: write, build and run a fuzz target
Step 1. Write the fuzz target
A libFuzzer target is a function with this exact signature, taken from the LLVM documentation:
int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size);
The engine calls it many times in one process with different byte arrays. The function should return 0; the documentation says returning -1 rejects the input so that it is not added to the corpus. Here is a small illustrative target (a toy example written for this guide, not taken from the LLVM page) that contains a deliberate heap overflow reachable only when the input starts with the letter F and has a length of four to six bytes:
#include "stdint.h"
#include "stdlib.h"
int LLVMFuzzerTestOneInput(const uint8_t *Data, size_t Size) {
if (Size == 4 || Size == 5 || Size == 6) {
if (Data[0] == 'F') {
char *p = (char *)malloc(3);
p[Data[3] % 8] = 1; /* overflows when the index is 3 or more */
free(p);
}
}
return 0;
}
Whatever your real target does, the Google fuzzing project’s guidance on good fuzz targets and the LLVM page agree on the rules it must follow: it must tolerate any input, it must not call exit() or abort() on bad input, it must be deterministic, it should be fast and use modest memory, it should avoid global state that carries over between calls, it should not perform I/O, and it should join any threads it starts before returning. Narrow targets that exercise one parser or one function are better than a single target covering a whole program. The same guidance notes that a well-formed target does not depend on which fuzzing engine drives it, which is why the same function can later be run under another engine.
Step 2. Build with the fuzzer and a sanitizer
The documented build command compiles the target with the fuzzer runtime and AddressSanitizer in one step:
clang -g -O1 -fsanitize=fuzzer,address mytarget.c
The flag -fsanitize=fuzzer links libFuzzer’s own main(), which is why your file supplies only the target function. If you want the coverage instrumentation but a different engine’s main(), the documentation describes -fsanitize=fuzzer-no-link. AddressSanitizer requires optimisation level -O1 or higher for usable results and the Clang manual recommends -fno-omit-frame-pointer for readable stack traces; it also says to link with clang rather than invoking the linker directly.
Step 3. Run it against a corpus directory
Create a directory for the corpus and pass it as the first argument. The documentation’s form is:
./my_fuzzer CORPUS_DIR
libFuzzer reads any files already in the directory as seed inputs and writes new interesting inputs there. Start with a few small, valid examples of the format your code parses; an empty directory works, but seeds usually shorten the time needed to reach deeper code. To run in parallel or bound a run, use the options in the data table below, for example -max_total_time to stop after a set number of seconds or -runs to stop after a number of executions (the default is -1, meaning run until stopped).
Step 4. Minimise the corpus
After a long run the corpus contains redundant inputs. The documented merge command copies into a new directory only the inputs from the full corpus that contribute coverage:
./my_fuzzer -merge=1 NEW_CORPUS_DIR FULL_CORPUS_DIR
Keep the minimised directory as your seed corpus for the next campaign and for regression runs.
Output and how to read it
The status lines
While running, libFuzzer prints one line per event. The LLVM documentation defines the event names, and each one suggests a different reaction:
| Event or field | What the documentation says it means | What to do with it |
|---|---|---|
NEW |
An input reached new coverage and was added to the corpus. | Healthy progress; frequent early on is normal. |
REDUCE |
A smaller input reaching the same features replaced a larger one. | No action; the corpus is being shrunk. |
pulse |
Periodic heartbeat with no new coverage. | If only pulse lines appear for a long time, coverage has plateaued: add seeds or a dictionary. |
DONE |
The run finished (for example -runs or -max_total_time was reached). |
Archive the corpus. |
RELOAD |
The engine reloaded the corpus. | No action. |
Each line also carries counters. cov is the number of coverage points reached, ft is the number of features (a finer-grained coverage measure that the engine uses to decide an input is interesting), corp is the corpus size, exec/s is throughput and rss is memory use. Watch exec/s and rss: the documented fast-target and modest-memory rules are the first things to check when they degrade.
Crash artifacts and exit codes
When the target fails, libFuzzer writes the offending input to a file whose name begins crash-, leak- or timeout- followed by the SHA-1 of the input. You control where these go with -artifact_prefix or -exact_artifact_path. To reproduce, run the fuzzer binary with that file as its only argument; the input is executed once and the sanitizer report prints. Archive the artifact together with the exact binary and compiler version.
The process exit code also says what happened. These are the documented defaults:
- 77: the fuzzer found a bug (a crash or sanitizer error).
- 70: a timeout, by default after 1200 seconds per input (set with
-timeout). - 71: out of memory, when resident memory exceeds the
-rss_limit_mblimit (default 2048).
A leak- artifact appears when leak detection is enabled with -detect_leaks=1.
Troubleshooting
- Throughput is very low. The LLVM page notes that targets taking more than about 10 ms per input are a poor fit, and the Google guidance cites roughly 1000 executions per second per core as a reference point. Narrow the target to one function, remove I/O and cut large setup out of the per-input path.
- The run stops with exit code 71. The default memory limit is 2048 MB. Either the target allocates unboundedly for large inputs (cap input size with
-max_len, where 0 means the engine guesses) or the limit needs raising; setting-rss_limit_mb=0disables the check. - The run stops with exit code 70. An input ran past the timeout. Treat this as a finding (a hang) before raising
-timeout. - The target crashes on the first run on valid input. Check that it does not call
exit()and that it handles any buffer, including a very short one. - Behaviour differs between runs of the same input. The documentation requires determinism; hidden global state or time and random-number use breaks reproduction of artifacts.
- Library unloading. The documentation states that
dlcloseis not supported, so targets that load and unload shared objects per input are a poor fit. - The program needs a file path as input. The documentation lists this as a poor fit; read from the buffer instead, or write a thin wrapper that parses the buffer.
- Link errors or version mismatch. Build with the Clang whose version matches the libFuzzer you link, as described under installation above.
Free alternatives
libFuzzer is one of several open-source fuzzing engines, and because a well-formed target does not depend on the engine, the same LLVMFuzzerTestOneInput function can often be reused. The table below states only what the projects’ own documentation says.
| Engine | What its documentation says | Where to read more |
|---|---|---|
| libFuzzer | In-process, coverage-guided engine included with Clang 6.0 and later; combined with AddressSanitizer or UBSan. | LLVM documentation |
| honggfuzz | Security-oriented, feedback-driven evolutionary fuzzer; Apache 2.0 licence; supports persistent in-process fuzzing and hardware and software coverage feedback; runs on Linux, macOS, Android, NetBSD, FreeBSD and Windows through Cygwin. | github.com/google/honggfuzz |
| AFL and AFL++ | Coverage-guided fuzzers covered in a separate CASRAI guide. | CASRAI guide to AFL |
Choosing between engines is a research-design decision that should be justified by the target (a library function that takes bytes suits libFuzzer; a whole command-line program that reads files suits a process-level fuzzer) and recorded in the methods section of any write-up.
Frequently asked questions
What is libFuzzer?
libFuzzer is the coverage-guided, in-process fuzzing engine of the LLVM project. You supply a function named LLVMFuzzerTestOneInput and Clang links it with the engine, which then generates and mutates inputs and reports crashes.
Which Clang version includes libFuzzer?
According to the LLVM documentation, libFuzzer is included in Clang from version 6.0, and the library version must match the Clang version used to build the target.
Do I need AddressSanitizer?
The engine runs without it, but the documentation recommends combining libFuzzer with AddressSanitizer or UBSan, and without a sanitizer many memory errors will not cause a visible failure. The build command -fsanitize=fuzzer,address enables both.
What does it mean to return -1 from the target?
Returning -1 tells the engine to reject the input so that it is not added to the corpus. Returning 0 is the normal result.
How do I stop a run after a fixed time?
Pass -max_total_time with the number of seconds, or -runs with an execution count; the default for -runs is -1, meaning no limit.
Sources
- LLVM Project, libFuzzer: a library for coverage-guided fuzz testing, read 2026-11-15.
- Clang documentation, AddressSanitizer, read 2026-11-15.
- Google, What makes a good fuzz target, read 2026-11-15.
- Google, honggfuzz repository, read 2026-11-15.
Data: libFuzzer documented option defaults and process exit codes
Compiled from the LLVM libFuzzer documentation: the default values of four run-control options and the three documented process exit codes, one row per setting, for planning and reporting fuzzing campaigns.
Period covered: 2026.
| Setting | Kind | Default or value | Meaning |
|---|---|---|---|
| -max_len | option | 0 (engine guesses) | Maximum input length; 0 lets the engine choose |
| -runs | option | -1 (unlimited) | Number of executions before stopping |
| -timeout | option (seconds) | 1200 | Per-input time limit; exceeding it ends the run with exit code 70 |
| -rss_limit_mb | option (MB) | 2048 | Memory limit; exceeding it gives exit code 71; 0 disables the check |
| Bug found | exit code | 77 | Process exit code when a crash or sanitizer error is found |
| Timeout | exit code | 70 | Process exit code on timeout (default setting) |
| Out of memory | exit code | 71 | Process exit code when the RSS limit is exceeded |
Sources
- libFuzzer documentation, LLVM Project (accessed 2026-11-15)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







