OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add trailofbits/skills --skill libfuzzer
Sets up and runs libFuzzer, the coverage-guided fuzzer built into LLVM, on C/C++ code that compiles with Clang. Covers harness structure, -fsanitize=fuzzer builds, corpus and dictionary management, sanitizer integration, and campaign triage. Use when writing or debugging an LLVMFuzzerTestOneInput harness, starting fuzzing on a C/C++ library, choosing between libFuzzer and AFL++, or working out why a libFuzzer run finds nothing.
npx skills add trailofbits/skills --skill libfuzzer
libFuzzer is an in-process, coverage-guided fuzzer that is part of the LLVM project. It's the recommended starting point for fuzzing C/C++ projects due to its simplicity and integration with the LLVM toolchain. While libFuzzer has been in maintenance-only mode since late 2022, it is easier to install and use than its alternatives, has wide support, and will be maintained for the foreseeable future.
| Fuzzer | Best For | Complexity |
|---|---|---|
| libFuzzer | Quick setup, single-project fuzzing | Low |
| AFL++ | Multi-core fuzzing, diverse mutations | Medium |
| LibAFL | Custom fuzzers, research projects | High |
| Honggfuzz | Hardware-based coverage | Medium |
Choose libFuzzer when:
Note: Fuzzing harnesses written for libFuzzer are compatible with AFL++, making it easy to transition if you need more advanced features like better multi-core support.
Compile and run:
For the latest LLVM version:
Install Clang through Visual Studio. Refer to Microsoft's documentation for setup instructions.
Recommendation: If possible, fuzz on a local x86_64 VM or rent one on DigitalOcean, AWS, or Hetzner. Linux provides the best support for libFuzzer.
The harness is the entry point for the fuzzer. libFuzzer calls the LLVMFuzzerTestOneInput function repeatedly with different inputs.
| Do | Don't |
|---|---|
| Handle all input types (empty, huge, malformed) | Call exit() - stops fuzzing process |
| Join all threads before returning | Leave threads running |
| Keep harness fast and simple | Add excessive logging or complexity |
| Maintain determinism | Use random number generators or read /dev/random |
| Reset global state between runs | Rely on state from previous executions |
| Use narrow, focused targets | Mix unrelated data formats (PNG + TCP) in one harness |
Rationale:
For complex inputs (strings, multiple parameters), use the FuzzedDataProvider helper:
Download FuzzedDataProvider.h from the LLVM repository.
Use a single harness to test multiple related functions:
See Also: For detailed harness writing techniques, patterns for handling complex inputs, structure-aware fuzzing, and protobuf-based fuzzing, see the fuzz-harness-writing technique skill.
The key flag is -fsanitize=fuzzer, which:
main function)memcmpFlags explained:
-fsanitize=fuzzer: Enable libFuzzer-g: Add debug symbols (helpful for crash analysis)-O2: Production-level optimizations (recommended for fuzzing)-DNO_MAIN: Define macro if your code has a main functionAddressSanitizer (recommended):
Multiple sanitizers:
See Also: For detailed sanitizer configuration, common issues, ASAN_OPTIONS flags, and advanced sanitizer usage, see the address-sanitizer and undefined-behavior-sanitizer technique skills.
| Flag | Purpose |
|---|---|
-fsanitize=fuzzer | Enable libFuzzer runtime and instrumentation |
-fsanitize=address | Enable AddressSanitizer (memory error detection) |
-fsanitize=undefined | Enable UndefinedBehaviorSanitizer |
-fsanitize=fuzzer-no-link | Instrument without linking fuzzer (for libraries) |
-g | Include debug symbols |
-O2 | Production optimization level |
-U_FORTIFY_SOURCE | Disable fortification (can interfere with ASan) |
For projects that produce static libraries:
Build with:
Create a directory for the corpus (can start empty):
Optional but recommended: Provide seed inputs (valid example files):
Benefits of seed inputs:
The corpus directory contains:
a9993e364706816aba3e25717850c26c9cd0d89d)libFuzzer automatically minimizes corpus entries during fuzzing. To explicitly minimize:
This creates a deduplicated, minimized corpus in minimized_corpus/.
See Also: For corpus creation strategies, seed selection, format-specific corpus building, and corpus maintenance, see the fuzzing-corpus technique skill.
This runs until a crash is found or you stop it (Ctrl+C).
The -fork and -ignore_crashes flags (experimental but widely used) allow fuzzing to continue after finding crashes.
Control input size:
Rule of thumb: 2x the size of minimal realistic input.
Set timeout:
Abort test cases that run longer than 2 seconds.
Use a dictionary:
Close stdout/stderr (speed up fuzzing):
See all options:
Option 1: Jobs and workers (recommended):
-jobs=4: Run 4 sequential campaigns-workers=4: Process jobs in parallel with 4 processesOption 2: Fork mode:
Note: For serious multi-core fuzzing, consider switching to AFL++, Honggfuzz, or LibAFL.
Re-run a single crash:
Test all inputs in a directory without fuzzing:
When fuzzing runs, you'll see statistics like:
| Output | Meaning |
|---|---|
INITED | Fuzzing initialized |
NEW | New coverage found, added to corpus |
REDUCE | Input minimized while keeping coverage |
cov: N | Number of coverage edges hit |
corp: X/Yb | Corpus size: X entries, Y total bytes |
exec/s: N | Executions per second |
rss: NMb | Resident memory usage |
On crash:
The crash is saved to ./crash-<hash> with the input shown in hex, UTF-8, and Base64.
Reproducibility: Use -seed=<value> to reproduce a fuzzing campaign (single-core only).
Dictionaries help the fuzzer discover interesting inputs faster by providing hints about the input format.
Create a text file with quoted strings (one per line):
From header files:
From man pages:
From binary strings:
Using LLMs: Ask ChatGPT or similar to generate a dictionary for your format (e.g., "Generate a libFuzzer dictionary for a JSON parser").
See Also: For advanced dictionary generation, format-specific dictionaries, and dictionary optimization strategies, see the fuzzing-dictionaries technique skill.
While libFuzzer shows basic coverage stats (cov: N), detailed coverage analysis requires additional tools.
1. Recompile with coverage instrumentation:
2. Run fuzzer to collect coverage:
3. Merge coverage data:
4. Generate coverage report:
5. Generate HTML report:
Tips:
See Also: For detailed coverage analysis techniques, identifying coverage gaps, systematic coverage improvement, and comparing coverage across fuzzers, see the coverage-analysis technique skill.
ASan detects memory errors like buffer overflows and use-after-free bugs. Highly recommended for fuzzing.
Enable ASan:
Example ASan output:
Configure ASan with environment variables:
Important flags:
verbosity=1: Show ASan is activedetect_leaks=0: Disable leak detection (leaks reported at end)abort_on_error=1: Call abort() instead of _exit() on errorsDrawbacks:
-rss_limit_mb=0)See Also: For comprehensive ASan configuration, common pitfalls, symbolization, and combining with other sanitizers, see the address-sanitizer technique skill.
UBSan detects undefined behavior like integer overflow, null pointer dereference, etc.
Enable UBSan:
Combine with ASan:
MSan detects uninitialized memory reads. More complex to use (requires rebuilding all dependencies).
| Issue | Solution |
|---|---|
| ASan slows fuzzing too much | Use -fsanitize-recover=address for non-fatal errors |
| Out of memory | Set ASAN_OPTIONS=rss_limit_mb=0 or -rss_limit_mb=0 |
| Stack exhaustion | Increase stack size: ASAN_OPTIONS=stack_size=8388608 |
False positives with _FORTIFY_SOURCE | Use -U_FORTIFY_SOURCE flag |
| MSan reports in dependencies | Rebuild all dependencies with -fsanitize=memory |
libpng is a widely-used library for reading/writing PNG images. Bugs can lead to security issues.
1. Get source code:
2. Install dependencies:
3. Compile with fuzzing instrumentation:
4. Get a harness (or write your own):
5. Prepare corpus and dictionary:
6. Link and compile fuzzer:
7. Run fuzzing campaign:
Harness that finds a division-by-zero bug:
Compile and fuzz:
The fuzzer will quickly find inputs causing a crash.
| Tip | Why It Helps |
|---|---|
| Start with single-core, switch to AFL++ for multi-core | libFuzzer harnesses work with AFL++ |
| Use dictionaries for structured formats | 10-100x faster bug discovery |
Close file descriptors with -close_fd_mask=3 | Speed boost if SUT writes output |
Set reasonable -max_len | Prevents wasted time on huge inputs |
| Run for days/weeks, not minutes | Coverage plateaus take time to break |
| Use seed corpus from test suites | Starts fuzzing from valid inputs |
For highly structured inputs (e.g., complex protocols, file formats), use libprotobuf-mutator:
See structure-aware fuzzing documentation for details.
libFuzzer allows custom mutators for specialized fuzzing:
| Setting | Impact |
|---|---|
-close_fd_mask=3 | Closes stdout/stderr, speeds up fuzzing |
-max_len=<reasonable_size> | Avoids wasting time on huge inputs |
-timeout=<seconds> | Detects hangs, prevents stuck executions |
| Disable ASan for baseline | 2-4x speed boost (but misses memory bugs) |
Use -jobs and -workers | Limited multi-core support |
| Run on Linux | Best platform support and performance |
| Problem | Cause | Solution |
|---|---|---|
| No crashes found after hours | Poor corpus, low coverage | Add seed inputs, use dictionary, check harness |
| Very slow executions/sec (<100) | Target too complex, excessive logging | Optimize target, use -close_fd_mask=3, reduce logging |
| Out of memory | ASan's 20TB virtual memory | Set -rss_limit_mb=0 to disable RSS limit |
| Fuzzer stops after first crash | Default behavior | Use -fork=1 -ignore_crashes=1 to continue |
| Can't reproduce crash | Non-determinism in harness/target | Remove random number generation, global state |
Linking errors with -fsanitize=fuzzer | Missing libFuzzer runtime | Ensure using Clang, check LLVM installation |
| GCC project won't compile with Clang | GCC-specific code | Switch to AFL++ with gcc_plugin instead |
| Coverage not improving | Corpus plateau | Run longer, add dictionary, improve seeds, check coverage report |
| Crashes but ASan doesn't trigger | Memory error not detected without ASan | Recompile with -fsanitize=address |
| Skill | Use Case |
|---|---|
| fuzz-harness-writing | Detailed guidance on writing effective harnesses, structure-aware fuzzing, and FuzzedDataProvider usage |
| address-sanitizer | Memory error detection configuration, ASAN_OPTIONS, and troubleshooting |
| undefined-behavior-sanitizer | Detecting undefined behavior during fuzzing |
| coverage-analysis | Measuring fuzzing effectiveness and identifying untested code paths |
| fuzzing-corpus | Building and managing seed corpora, corpus minimization strategies |
| fuzzing-dictionaries | Creating format-specific dictionaries for faster bug discovery |
| Skill | When to Consider |
|---|---|
| aflpp | When you need serious multi-core fuzzing, or when libFuzzer coverage plateaus |
| honggfuzz | When you want hardware-based coverage feedback on Linux |
| libafl | When building custom fuzzers or conducting fuzzing research |
clang++ -fsanitize=fuzzer,address -g -O2 harness.cc target.cc -o fuzz
mkdir corpus/
./fuzz corpus/apt install clang llvm# Add LLVM repository from apt.llvm.org
# Then install specific version, e.g.:
apt install clang-18 llvm-18# Using Homebrew
brew install llvm
# Or using Nix
nix-env -i clangclang++ --version
# Should show LLVM version information#include <stdint.h>
#include <stddef.h>
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
// 1. Optional: Validate input size
if (size < MIN_REQUIRED_SIZE) {
return 0; // Reject inputs that are too small
}
// 2. Optional: Convert raw bytes to structured data
// Example: Parse two integers from byte array
if (size >= 2 * sizeof(uint32_t)) {
uint32_t a = *(uint32_t*)(data);
uint32_t b = *(uint32_t*)(data + sizeof(uint32_t));
my_function(a, b);
}
// 3. Call target function
target_function(data, size);
// 4. Always return 0 (non-zero reserved for future use)
return 0;
}#include <stdint.h>
#include <stddef.h>
#include "FuzzedDataProvider.h" // From LLVM project
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
FuzzedDataProvider fuzzed_data(data, size);
// Extract structured data
size_t allocation_size = fuzzed_data.ConsumeIntegral<size_t>();
std::vector<char> str1 = fuzzed_data.ConsumeBytesWithTerminator<char>(32, 0xFF);
std::vector<char> str2 = fuzzed_data.ConsumeBytesWithTerminator<char>(32, 0xFF);
// Call target with extracted data
char* result = concat(&str1[0], str1.size(), &str2[0], str2.size(), allocation_size);
if (result != NULL) {
free(result);
}
return 0;
}extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
if (size < 1 + 2 * sizeof(int32_t)) {
return 0;
}
uint8_t mode = data[0];
int32_t numbers[2];
memcpy(numbers, data + 1, 2 * sizeof(int32_t));
// Select function based on first byte
switch (mode % 4) {
case 0: add(numbers[0], numbers[1]); break;
case 1: subtract(numbers[0], numbers[1]); break;
case 2: multiply(numbers[0], numbers[1]); break;
case 3: divide(numbers[0], numbers[1]); break;
}
return 0;
}clang++ -fsanitize=fuzzer -g -O2 harness.cc target.cc -o fuzzclang++ -fsanitize=fuzzer,address -g -O2 -U_FORTIFY_SOURCE harness.cc target.cc -o fuzzclang++ -fsanitize=fuzzer,address -g -O2 -U_FORTIFY_SOURCE harness.cc target.cc -o fuzzclang++ -fsanitize=fuzzer,address,undefined -g -O2 harness.cc target.cc -o fuzzclang++ -fsanitize=fuzzer,address,undefined -g -O2 harness.cc target.cc -o fuzzexport CC=clang CFLAGS="-fsanitize=fuzzer-no-link -fsanitize=address"
export CXX=clang++ CXXFLAGS="$CFLAGS"
./configure --enable-shared=no
makeexport CC=clang CFLAGS="-fsanitize=fuzzer-no-link -fsanitize=address"
export CXX=clang++ CXXFLAGS="$CFLAGS"
./configure --enable-shared=no
makeclang++ -fsanitize=fuzzer -fsanitize=address harness.cc libmylib.a -o fuzzproject(FuzzTarget)
cmake_minimum_required(VERSION 3.0)
add_executable(fuzz main.cc harness.cc)
target_compile_definitions(fuzz PRIVATE NO_MAIN=1)
target_compile_options(fuzz PRIVATE -g -O2 -fsanitize=fuzzer -fsanitize=address)
target_link_libraries(fuzz -fsanitize=fuzzer -fsanitize=address)cmake -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ .
cmake --build .mkdir corpus/# For a PNG parser:
cp examples/*.png corpus/
# For a protocol parser:
cp test_packets/*.bin corpus/mkdir minimized_corpus/
./fuzz -merge=1 minimized_corpus/ corpus/./fuzz corpus/./fuzz -fork=1 -ignore_crashes=1 corpus/./fuzz -max_len=4000 corpus/./fuzz -timeout=2 corpus/./fuzz -dict=./format.dict corpus/./fuzz -dict=./format.dict corpus/./fuzz -close_fd_mask=3 corpus/./fuzz -help=1./fuzz -jobs=4 -workers=4 -fork=1 -ignore_crashes=1 corpus/./fuzz -fork=4 -ignore_crashes=1 corpus/./fuzz ./crash-a9993e364706816aba3e25717850c26c9cd0d89d./fuzz -runs=0 corpus/INFO: Seed: 3517090860
INFO: Loaded 1 modules (9 inline 8-bit counters)
#2 INITED cov: 3 ft: 4 corp: 1/1b exec/s: 0 rss: 26Mb
#57 NEW cov: 4 ft: 5 corp: 2/4b lim: 4 exec/s: 0 rss: 26Mb==11672== ERROR: libFuzzer: deadly signal
artifact_prefix='./'; Test unit written to ./crash-a9993e364706816aba3e25717850c26c9cd0d89d
0x61,0x62,0x63,
abc
Base64: YWJj# Lines starting with '#' are comments
# Magic bytes
magic="\x89PNG"
magic2="IEND"
# Keywords
"GET"
"POST"
"Content-Type"
# Hex sequences
delimiter="\xFF\xD8\xFF"grep -o '".*"' header.h > header.dictman curl | grep -oP '^\s*(--|-)\K\S+' | sed 's/[,.]$//' | sed 's/^/"&/; s/$/&"/' | sort -u > man.dictstrings ./binary | sed 's/^/"&/; s/$/&"/' > strings.dictclang++ -fsanitize=fuzzer -fprofile-instr-generate -fcoverage-mapping harness.cc target.cc -o fuzzLLVM_PROFILE_FILE="coverage-%p.profraw" ./fuzz -runs=10000 corpus/llvm-profdata merge -sparse coverage-*.profraw -o coverage.profdatallvm-cov show ./fuzz -instr-profile=coverage.profdatallvm-cov show ./fuzz -instr-profile=coverage.profdata -format=html > coverage.html==1276163==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x6020000c4ab1
WRITE of size 1 at 0x6020000c4ab1 thread T0
#0 0x55555568631a in check_buf(char*, unsigned long) main.cc:13:25
#1 0x5555556860bf in LLVMFuzzerTestOneInput harness.cc:7:3ASAN_OPTIONS=verbosity=1:abort_on_error=1 ./fuzz corpus/clang++ -fsanitize=fuzzer,undefined -g -O2 harness.cc target.cc -o fuzzclang++ -fsanitize=fuzzer,memory -g -O2 harness.cc target.cc -o fuzzcurl -L -O https://downloads.sourceforge.net/project/libpng/libpng16/1.6.37/libpng-1.6.37.tar.xz
tar xf libpng-1.6.37.tar.xz
cd libpng-1.6.37/apt install zlib1g-devcurl -O https://raw.githubusercontent.com/glennrp/libpng/f8e5fa92b0e37ab597616f554bee254157998227/contrib/oss-fuzz/libpng_read_fuzzer.ccmkdir corpus/
curl -o corpus/input.png https://raw.githubusercontent.com/glennrp/libpng/acfd50ae0ba3198ad734e5d4dec2b05341e50924/contrib/pngsuite/iftp1n3p08.png
curl -O https://raw.githubusercontent.com/glennrp/libpng/2fff013a6935967960a5ae626fc21432807933dd/contrib/oss-fuzz/png.dictclang++ -fsanitize=fuzzer -fsanitize=address libpng_read_fuzzer.cc .libs/libpng16.a -lz -o fuzz./fuzz -close_fd_mask=3 -dict=./png.dict corpus/#include <stdint.h>
#include <stddef.h>
double divide(uint32_t numerator, uint32_t denominator) {
// Bug: No check if denominator is zero
return numerator / denominator;
}
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
if(size != 2 * sizeof(uint32_t)) {
return 0;
}
uint32_t numerator = *(uint32_t*)(data);
uint32_t denominator = *(uint32_t*)(data + sizeof(uint32_t));
divide(numerator, denominator);
return 0;
}clang++ -fsanitize=fuzzer harness.cc -o fuzz
./fuzzextern "C" size_t LLVMFuzzerCustomMutator(uint8_t *Data, size_t Size,
size_t MaxSize, unsigned int Seed) {
// Custom mutation logic
return new_size;
}
extern "C" size_t LLVMFuzzerCustomCrossOver(const uint8_t *Data1, size_t Size1,
const uint8_t *Data2, size_t Size2,
uint8_t *Out, size_t MaxOutSize,
unsigned int Seed) {
// Custom crossover logic
return new_size;
}