Skip to main content
v2026.11,986 entries · CC-BY 4.0

libFuzzer: Build a Fuzz Target, Run It and Read the Output

How to write a libFuzzer target, build it with Clang and AddressSanitizer, run it on a corpus and read the output and exit codes.

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_mb limit (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=0 disables 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 dlclose is 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

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.

libFuzzer documented option defaults and process exit codes
SettingKindDefault or valueMeaning
-max_lenoption0 (engine guesses)Maximum input length; 0 lets the engine choose
-runsoption-1 (unlimited)Number of executions before stopping
-timeoutoption (seconds)1200Per-input time limit; exceeding it ends the run with exit code 70
-rss_limit_mboption (MB)2048Memory limit; exceeding it gives exit code 71; 0 disables the check
Bug foundexit code77Process exit code when a crash or sanitizer error is found
Timeoutexit code70Process exit code on timeout (default setting)
Out of memoryexit code71Process exit code when the RSS limit is exceeded

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about libFuzzer: Build a Fuzz Target, Run It and Read the Output

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →