AFL++ Instrumentation in Practice: A Trace from Compilation to Fuzz I

In the previous post, we laid out the theoretical map of AFL++’s instrumentation modes, from the classic edge coverage to modern LLVM-based techniques. With that foundation in place, it’s time to move from theory to practice. This article focuses on the compilation process with afl-cc: how LTO and PCGUARD instrumentation are inserted into the binary, what transformations happen along the way, and how the compiled program is prepared for fuzzing.

The goal here is to understand what AFL++ “writes” into the binary during compilation. In the following post, we’ll continue the journey at runtime—tracing the instrumented code as it executes and seeing how afl-fuzz consumes the coverage data to discover new paths.

The Example Program

To make the exploration more tangible, we will use the same C program we used in the latest post. This minimal structure is enough to showcase how AFL++ instruments the binary, tracks execution, and ultimately guides fuzzing toward the crashing path. The code we’re using is the following:


#include <stdio.h>
#include <unistd.h>
#include <fcntl.h>
#include <stdint.h>

int main(int argc, char *argv[]) {
  int fd;
  char buff[10];

  if (2 != argc) {
    printf("Usage %s <input_file>\n", argv[0]);
    return 1;
  }

  fd = open(argv[1], O_RDONLY);
  read(fd, buff, sizeof(buff));
  close(fd);
  if ('F' == buff[0] && 'U' == buff[1] && 'Z' == buff[2] && 'Z' == buff[3]) {
    __builtin_trap();
    __builtin_unreachable();
  }

  return 0;
}

For this walkthrough, we are using AFL++ v4.33c, (commit eadc8a).

From afl-cc to the Instrumented Binary

In this section, we’ll compile our example using afl-clang-fast and follow the compiler’s steps as it injects instrumentation into the binary. In parallel we will be compiling another binary with afl-clang-lto.

Our starting point is afl-cc.c. Here is the main function that will be called whenever we execute afl-cc, afl-clang-fast or afl-clang-lto. The compilation state is managed by the struct aflcc. This struct has three variables we care about:

compiler_mode: This variable indicates what compilation mode we are using. The possible values are defined in this enum.
lto_mode: This variable tells us if we are using LTO mode.
instrument_mode: Finally this variable tells us what kind of instrumentation we are using. The possible values are defined in this enum.

The first variable is set during the call to the functions compiler_mode_by_callname, compiler_mode_by_environ and compiler_mode_by_cmdline.

The first one of these functions will set the compiler mode if we compile the program by using afl-clang-fast or afl-clang-lto.


/* Select compiler_mode by callname, such as "afl-clang-fast", etc. */
void compiler_mode_by_callname(aflcc_state_t *aflcc) {
  if (strncmp(aflcc->callname, "afl-clang-fast", 14) == 0) {

AFL++ Instrumentation in Practice: A Trace from Compilation to Fuzz I

The Example Program

From afl-cc to the Instrumented Binary

PCGUARD plugin

LTO plugin

Summary

References