Skip to main content
The afl-cc compiler wrapper instruments programs for coverage-guided fuzzing. It supports multiple compilation modes and instrumentation strategies.

Synopsis

afl-cc [compiler options] source_files...
afl-c++ [compiler options] source_files...

Description

afl-cc is a drop-in replacement for your regular compiler (gcc/clang) that adds instrumentation to track code coverage during fuzzing. The wrapper automatically selects the appropriate compiler backend and instrumentation mode based on available toolchains.

Compiler Mode Selection

The compiler mode can be selected in three ways (in order of priority):

1. Command-line Option

afl-cc --afl-MODE source.c
Available modes:
  • --afl-lto - LTO (Link-Time Optimization) mode
  • --afl-llvm - LLVM mode with PCGUARD instrumentation
  • --afl-gcc-plugin - GCC plugin mode
  • --afl-gcc - Traditional GCC mode
  • --afl-clang - Clang assembly mode
Create symlinks to afl-cc:
  • afl-clang-fast → LLVM mode
  • afl-clang-lto → LTO mode
  • afl-gcc-fast → GCC plugin mode
  • afl-gcc → GCC mode
  • afl-clang → Clang mode

3. Environment Variable

export AFL_CC_COMPILER=LTO  # or LLVM, GCC_PLUGIN, GCC, CLANG

Instrumentation Options

AFL_LLVM_INSTRUMENT
string
Configure the instrumentation mode. Available options:
  • CLASSIC - Traditional AFL edge coverage (default)
  • PCGUARD - Optimized PCGUARD instrumentation
  • LTO - Link-time optimization mode
  • CTX - Context-sensitive instrumentation
  • NGRAM-2 to NGRAM-16 - N-gram coverage
Multiple modes can be combined: AFL_LLVM_INSTRUMENT=CLASSIC,CTX
AFL_LLVM_CMPLOG
boolean
Enable CmpLog instrumentation for better coverage of comparison operations.
AFL_LLVM_CMPLOG=1 afl-cc -o target target.c
AFL_USE_ASAN
boolean
Enable AddressSanitizer (detects memory corruption bugs).
AFL_USE_ASAN=1 afl-cc -o target target.c
AFL_USE_MSAN
boolean
Enable MemorySanitizer (detects use of uninitialized memory).
AFL_USE_UBSAN
boolean
Enable UndefinedBehaviorSanitizer (detects undefined behavior).
AFL_HARDEN
boolean
Automatically add hardening flags: -D_FORTIFY_SOURCE=2 -fstack-protector-all.

Selective Instrumentation

AFL_LLVM_ALLOWLIST
path
File containing functions/files to instrument (one per line).
AFL_LLVM_ALLOWLIST=whitelist.txt afl-cc -o target target.c
AFL_LLVM_DENYLIST
path
File containing functions/files to NOT instrument (one per line).
AFL_INST_RATIO
number
Percentage of branches to instrument (0-100). Useful for very large programs.
AFL_INST_RATIO=50 afl-cc -o target target.c

LAF-INTEL Transform

Split complex comparisons for better fuzzing:
AFL_LLVM_LAF_ALL
boolean
Enable all LAF transformations.
AFL_LLVM_LAF_SPLIT_COMPARES
boolean
Split integer comparisons into byte-by-byte checks.
AFL_LLVM_LAF_SPLIT_SWITCHES
boolean
Split switch statements.
AFL_LLVM_LAF_TRANSFORM_COMPARES
boolean
Transform string comparison functions.

Advanced Options

AFL_DONT_OPTIMIZE
boolean
Disable automatic -O3 optimization.
AFL_OPT_LEVEL
string
Set optimization level (default: 3). Example: AFL_OPT_LEVEL=2
AFL_CC
path
Specify alternative C compiler to use.
AFL_CXX
path
Specify alternative C++ compiler to use.
AFL_PATH
path
Directory containing AFL++ runtime objects and plugins.
AFL_QUIET
boolean
Suppress banner and compilation messages.

Examples

Basic Compilation

# Compile with default instrumentation
afl-cc -o program program.c

# Compile C++ program
afl-c++ -o program program.cpp
# Use LTO for collision-free coverage
afl-clang-lto -o program program.c

# Or via environment variable
AFL_CC_COMPILER=LTO afl-cc -o program program.c

With Sanitizers

# Enable AddressSanitizer
AFL_USE_ASAN=1 afl-cc -o program program.c

# Multiple sanitizers
AFL_USE_ASAN=1 AFL_USE_UBSAN=1 afl-cc -o program program.c

CmpLog Mode

# Build CmpLog binary for afl-fuzz -c option
AFL_LLVM_CMPLOG=1 afl-cc -o program.cmplog program.c

Context-Sensitive Coverage

# Enable context-sensitive instrumentation
AFL_LLVM_INSTRUMENT=CTX afl-cc -o program program.c

LAF-INTEL Transforms

# Split all comparisons
AFL_LLVM_LAF_ALL=1 afl-cc -o program program.c

Selective Instrumentation

# Only instrument specific files
echo "target_function" > allowlist.txt
AFL_LLVM_ALLOWLIST=allowlist.txt afl-cc -o program program.c

Persistent Mode Macros

For in-process fuzzing with __AFL_LOOP():
#include <unistd.h>

__AFL_FUZZ_INIT();

int main(int argc, char **argv) {
  __AFL_INIT();  // Optional: early forkserver
  
  unsigned char *buf = __AFL_FUZZ_TESTCASE_BUF;
  
  while (__AFL_LOOP(10000)) {
    int len = __AFL_FUZZ_TESTCASE_LEN;
    
    // Fuzz target with buf[0..len-1]
    fuzz_target(buf, len);
  }
  
  return 0;
}

See Also

Build docs developers (and LLMs) love