---
title: "AFL++: review, setup & limitations · Undominated.ai"
canonical: https://undominated.ai/skills/trailofbits-aflpp/
description: "Runs AFL++ as a multi-core campaign and forbids afl-system-config on a production or development machine because that script needs root and turns OS protections off."
---

# AFL++: review, setup & limitations · Undominated.ai

> Runs AFL++ as a multi-core campaign and forbids afl-system-config on a production or development machine because that script needs root and turns OS protections off.

[← Explore all skills](/skills/)

TESTING / Trail of Bits

# AFL++

Runs AFL++ as a multi-core campaign and forbids afl-system-config on a production or development machine because that script needs root and turns OS protections off.

 [See setup guidance ↓](#setup)[Original source ↗](https://github.com/trailofbits/skills/tree/82fe8226252622fa807643bdca1710901198553a/plugins/testing-handbook-skills/skills/aflpp)

SOURCE REVIEW

 Reviewed 2026-10-14
 Evidence 2 linked sources
 Publisher Trail of Bits
 Licence [CC-BY-SA-4.0 ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/LICENSE)
 Revision 82fe82262526
 [Read what was—and wasn’t—checked ↓](#review)

“Sets up and runs AFL++ for multi-core fuzzing of C/C++ projects built with afl-clang-fast or afl-gcc-fast. Covers instrumentation modes, parallel main and secondary campaigns, persistent mode, corpus minimization, and crash triage. Use when scaling fuzzing across cores, fuzzing a mature C/C++ codebase, reading the afl-fuzz status screen, or moving on after libFuzzer has plateaued.”

 [Trail of Bits · upstream description ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/plugins/testing-handbook-skills/skills/aflpp/SKILL.md) Our analysis follows below.

01 / THE REASONING

## Why this made the selection.

 - afl-system-config and afl-persistent-config are called out as root scripts that disable OS security features.
- Docker runs omit -t on purpose, because docker run -ti aborts when stdin is not a terminal.
- The primary instance is the -M process; secondaries are separate, and AFL_FINAL_SYNC matters for later corpus minimization rather than for the fuzzing loop itself.

### A good fit for

 - Starting a dedicated-VM AFL++ campaign with one primary and several secondaries
- Avoiding a docker run -ti failure in a non-interactive agent
- Plan a bounded multi-worker fuzzing campaign with reproducible crashes and preserved corpus.

### Weigh up before choosing

 - The security warning says not to fuzz on production systems or the development environment.
- Sanitizer builds are described as necessary for memory corruption that does not crash immediately; a run without them is a narrower result.
- This review did not execute the skill or AFL++.
- The example Docker wrapper loses argument quoting. Privileged tuning can change the host kernel, and disabling mitigations is unsuitable for shared or production machines. Throughput scaling is workload-dependent.

02 / THE REVIEW RECORD

## What we actually inspected.

Source review has boundaries. A clear record is more useful than a “safe” badge.

### Material inspected

 - plugins/testing-handbook-skills/skills/aflpp/SKILL.md
- LICENSE
- README.md

### Our findings

 - The security warning says afl-system-config and afl-persistent-config require root, disable OS protections, and belong on a dedicated VM.
- The wrapper avoids docker run -ti because a missing TTY aborts the container for CI and for an agent.
- Campaign commands redirect stdin from /dev/null; the file says that redirect is required so docker run -i does not leave afl-fuzz stopped.
- AFL_FINAL_SYNC is documented as a final import into the primary for afl-cmin, not as something that changes the fuzzing loop.
- The definition documents non-TTY operation, background stdin handling and primary/secondary corpus synchronization, including final synchronization before minimization.

### Not established by this review

 - The skill was not executed inside a host agent.
- AFL++ was not installed and no fuzz campaign was started.

The review applies to the material and revision named here. A newer upstream release can change its behavior.

03 / PUT IT TO WORK

## Add a skill to your workflow.

[Upstream setup instructions ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/README.md)

DOCUMENTED COMMAND

 /plugin marketplace add trailofbits/skills Copy command ↗

Copying does not execute this command. It may retrieve a newer version than the reviewed source.

 - Claude Code: add the marketplace with /plugin marketplace add trailofbits/skills, then install the testing-handbook-skills plugin from /plugin menu; aflpp ships inside that plugin, not as a plugin of its own.
- Codex: the README documents codex plugin marketplace add trailofbits/skills, then codex plugin add <plugin-name>@trailofbits.
- The download holds SKILL.md and agents/openai.yaml from the pinned skill directory, with the licence.
- Run the kernel tuning steps only on a dedicated VM, as the skill says.
- Download the complete bundle from https://undominated.ai/resources/skills/trailofbits-aflpp/bundle.zip and extract it into a new directory. It holds SKILL.md and agents/openai.yaml unchanged at revision 82fe8226, the upstream licence and an attribution file.
- Place the extracted directory in your host's documented skills directory, named aflpp. Keep SKILL.md and the licence together.

### Before you start

 - AFL++ from Debian or Ubuntu packages, Docker Hub or source
- Docker for the wrapper’s default mode
- A C or C++ target that builds with Clang or GCC

### Compatibility

Claude Code plugin marketplace · Codex via Claude marketplace compatibility · AFL++ · C and C++ targets built with Clang or GCC

### Local Markdown instructions

 - The skill runs Docker or a local AFL++ install and, on the host path, can invoke root-only system-config scripts.
- It writes a corpus and crash directory on disk.
- Executes the target repeatedly and writes corpus/crash files; optional privileged tuning alters host security settings.

### Cost model

CC-BY-SA-4.0. The pinned LICENSE is Creative Commons Attribution-ShareAlike 4.0 International. The skill does not say a paid Trail of Bits account is required.

THE COMPLETE REVIEWED DEFINITION

## Read it before you reuse it.

Original source bytes, with attribution. Review the host-specific setup notes above.

 Copy definition ↗ [Download complete resource + licence ↗](/resources/skills/trailofbits-aflpp/bundle.zip)[Raw Markdown ↗](/resources/skills/trailofbits-aflpp/definition.md)
 ---
name: aflpp
type: fuzzer
description: "Sets up and runs AFL++ for multi-core fuzzing of C/C++ projects built with afl-clang-fast or afl-gcc-fast. Covers instrumentation modes, parallel main and secondary campaigns, persistent mode, corpus minimization, and crash triage. Use when scaling fuzzing across cores, fuzzing a mature C/C++ codebase, reading the afl-fuzz status screen, or moving on after libFuzzer has plateaued."
---

# AFL++

AFL++ is a fork of the original AFL fuzzer that offers better fuzzing performance and more advanced features while maintaining stability. A major benefit over libFuzzer is that AFL++ has stable support for running fuzzing campaigns on multiple cores, making it ideal for large-scale fuzzing efforts.

## When to Use

| Fuzzer | Best For | Complexity |
|--------|----------|------------|
| AFL++ | Multi-core fuzzing, diverse mutations, mature projects | Medium |
| libFuzzer | Quick setup, single-threaded, simple harnesses | Low |
| LibAFL | Custom fuzzers, research, advanced use cases | High |

**Choose AFL++ when:**
- You need multi-core fuzzing to maximize throughput
- Your project can be compiled with Clang or GCC
- You want diverse mutation strategies and mature tooling
- libFuzzer has plateaued and you need more coverage
- You're fuzzing production codebases that benefit from parallel execution

## Quick Start

```c++
extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
 // Call your code with fuzzer-provided data
 check_buf((char*)data, size);
 return 0;
}
```

Compile and run:
```bash
# Setup AFL++ wrapper script first (see Installation)
./afl++ docker afl-clang-fast++ -DNO_MAIN=1 -O2 -fsanitize=fuzzer harness.cc main.cc -o fuzz
mkdir seeds && echo "aaaa" > seeds/minimal_seed
./afl++ docker afl-fuzz -i seeds -o out -- ./fuzz
```

## Installation

AFL++ has many dependencies including LLVM, Python, and Rust. We recommend using a current Debian or Ubuntu distribution for fuzzing with AFL++.

| Method | When to Use | Supported Compilers |
|--------|-------------|---------------------|
| Ubuntu/Debian repos | Recent Ubuntu, basic features only | Ubuntu 23.10: Clang 14 & GCC 13<br>Debian 12: Clang 14 & GCC 12 |
| Docker (from Docker Hub) | Specific AFL++ version, Apple Silicon support | As of 4.35c: Clang 19 & GCC 11 |
| Docker (from source) | Test unreleased features, apply patches | Configurable in Dockerfile |
| From source | Avoid Docker, need specific patches | Adjustable via `LLVM_CONFIG` env var |

### Ubuntu/Debian

Prior to installing afl++, check the clang version dependency of the packge with `apt-cache show afl++`, and install the matching `lld` version (e.g., `lld-17`).

```bash
apt install afl++ lld-17
```

### Docker (from Docker Hub)

```bash
docker pull aflplusplus/aflplusplus:stable
```

### Docker (from source)

```bash
git clone --depth 1 --branch stable https://github.com/AFLplusplus/AFLplusplus
cd AFLplusplus
docker build -t aflplusplus .
```

### From source

Refer to the [Dockerfile](https://github.com/AFLplusplus/AFLplusplus/blob/stable/Dockerfile) for Ubuntu version requirements and dependencies. Set `LLVM_CONFIG` to specify Clang version (e.g., `llvm-config-18`).

### Wrapper Script Setup

Create a wrapper script to run AFL++ on host or Docker:

```bash
cat <<'EOF' > ./afl++
#!/bin/sh
AFL_VERSION="${AFL_VERSION:-"stable"}"
case "$1" in
 host)
 shift
 bash -c "$*"
 ;;
 docker)
 shift
 /usr/bin/env docker run -i \
 --privileged \
 -v ./:/src \
 --rm \
 --name "afl_fuzzing_$$" \
 "aflplusplus/aflplusplus:$AFL_VERSION" \
 bash -c "cd /src && bash -c \"$*\""
 ;;
 *)
 echo "Usage: $0 {host|docker}"
 exit 1
 ;;
esac
EOF
chmod +x ./afl++
```

The examples below use `docker` mode, apart from the system configuration commands that have to reach the host kernel. Swap in `host` to run any of them against an AFL++ installed on the machine itself. The wrapper joins everything after the mode argument into a single shell string, so quoting does not survive: an argument containing a space (`-x "my dict.dict"`) arrives word-split. Rename such files without spaces, or edit the wrapper for that run.

The missing `-t` is deliberate. `docker run -ti` aborts with `the input device is not a TTY` whenever stdin is not a terminal, which covers CI jobs and anything an agent or script drives. `afl-fuzz` notices there is no terminal and prints plain status lines in place of the full-screen UI. A program that insists on a terminal, such as `watch`, has to run on the host side of the wrapper instead. `$$` expands to the wrapper's PID, so parallel instances get distinct container names rather than colliding on a single `afl_fuzzing`. `docker ps` truncates the COMMAND column, so every row looks alike; use `docker ps --no-trunc` to tell the instances apart before stopping one.

**Security Warning:** The `afl-system-config` and `afl-persistent-config` scripts require root privileges and disable OS security features. Do not fuzz on production systems or your development environment. Use a dedicated VM instead.

### System Configuration

Run after each reboot for up to 15% more executions per second:

```bash
./afl++ host afl-system-config
```

`afl-system-config` tunes the kernel it runs against, so run it on the machine that hosts the campaign. `./afl++ docker afl-system-config` reaches the same settings through the wrapper's `--privileged` container, which is the only route when AFL++ is installed via Docker alone.

For maximum performance, disable kernel security mitigations (requires grub bootloader, not supported in Docker):

```bash
./afl++ host afl-persistent-config
update-grub
reboot
./afl++ host afl-system-config
```

Verify with `cat /proc/cmdline` - output should include `mitigations=off`.

## Writing a Harness

### Harness Structure

AFL++ supports libFuzzer-style harnesses:

```c++
#include <stdint.h>
#include <stddef.h>

extern "C" int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size) {
 // 1. Validate input size if needed
 if (size < MIN_SIZE || size > MAX_SIZE) return 0;

 // 2. Call target function with fuzz data
 target_function(data, size);

 // 3. Return 0 (non-zero reserved for future use)
 return 0;
}
```

### Harness Rules

| Do | Don't |
|----|-------|
| Reset global state between runs | Rely on state from previous runs |
| Handle edge cases gracefully | Exit on invalid input |
| Keep harness deterministic | Use random number generators |
| Free allocated memory | Create memory leaks |
| Validate input sizes | Process unbounded input |

> **See Also:** For detailed harness writing techniques, patterns for handling complex inputs,
> and advanced strategies, see the **fuzz-harness-writing** technique skill.

## Compilation

AFL++ offers multiple compilation modes with different trade-offs.

### Compilation Mode Decision Tree

Choose your compilation mode:
- **LTO mode** (`afl-clang-lto`): Best performance and instrumentation. Try this first.
- **LLVM mode** (`afl-clang-fast`): Fall back if LTO fails to compile.
- **GCC plugin** (`afl-gcc-fast`): For projects requiring GCC.

### Basic Compilation (LLVM mode)

```bash
./afl++ docker afl-clang-fast++ -DNO_MAIN=1 -O2 -fsanitize=fuzzer harness.cc main.cc -o fuzz
```

### GCC Compilation

```bash
./afl++ docker afl-g++-fast -DNO_MAIN=1 -O2 -fsanitize=fuzzer harness.cc main.cc -o fuzz
```

**Important:** GCC version must match the version used to compile the AFL++ GCC plugin.

### With Sanitizers

```bash
./afl++ docker AFL_USE_ASAN=1 afl-clang-fast++ -DNO_MAIN=1 -O2 -fsanitize=fuzzer harness.cc main.cc -o fuzz
```

> **See Also:** For detailed sanitizer configuration, common issues, and advanced flags,
> see the **address-sanitizer** and **undefined-behavior-sanitizer** technique skills.

### Build Flags

Note that `-g` is not necessary, it is added by default by the AFL++ compilers.

| Flag | Purpose |
|------|---------|
| `-DNO_MAIN=1` | Skip main function when using libFuzzer harness |
| `-O2` | Production optimization level (recommended for fuzzing) |
| `-fsanitize=fuzzer` | Enable libFuzzer compatibility mode and adds the fuzzer runtime when linking executable |
| `-fsanitize=fuzzer-no-link` | Instrument without linking fuzzer runtime (for static libraries and object files) |

## Corpus Management

### Creating Initial Corpus

AFL++ requires at least one non-empty seed file:

```bash
mkdir seeds
echo "aaaa" > seeds/minimal_seed
```

For real projects, gather representative inputs:
- Download example files for the format you're fuzzing
- Extract test cases from the project's test suite
- Use minimal valid inputs for your file format

### Corpus Minimization

After a campaign, minimize the corpus to keep only unique coverage:

```bash
./afl++ docker afl-cmin -i out/default/queue -o minimized_corpus -- ./fuzz
```

> **See Also:** For corpus creation strategies, dictionaries, and seed selection,
> see the **fuzzing-corpus** technique skill.

## Running Campaigns

### Basic Run

```bash
./afl++ docker afl-fuzz -i seeds -o out -- ./fuzz
```

### Setting Environment Variables

```bash
./afl++ docker AFL_FAST_CAL=1 afl-fuzz -i seeds -o out -- ./fuzz
```

### Interpreting Output

AFL++ reports these statistics either way, but how you read them depends on the
mode. The wrapper's `docker run -i` gives the container no TTY, so `afl-fuzz`
drops the full-screen UI and writes plain status lines to the log instead — the
fields below appear there, and in `state/<instance>/fuzzer_stats`. To get the
interactive UI, run `host` mode in a terminal, or add `-t` to the wrapper for a
run you are watching by hand.

| Output | Meaning |
|--------|---------|
| **execs/sec** | Execution speed - higher is better |
| **cycles done** | Number of queue passes completed |
| **corpus count** | Number of unique test cases in queue |
| **saved crashes** | Number of unique crashes found |
| **stability** | % of stable edges (should be near 100%) |

### Output Directory Structure

```text
out/default/
├── cmdline # How was the SUT invoked?
├── crashes/ # Inputs that crash the SUT
│ └── id:000000,sig:06,src:000002,time:286,execs:13105,op:havoc,rep:4
├── hangs/ # Inputs that hang the SUT
├── queue/ # Test cases reproducing final fuzzer state
│ ├── id:000000,time:0,execs:0,orig:minimal_seed
│ └── id:000001,src:000000,time:0,execs:8,op:havoc,rep:6,+cov
├── fuzzer_stats # Campaign statistics
└── plot_data # Data for plotting
```

### Analyzing Results

View live campaign statistics:

```bash
./afl++ docker afl-whatsup out
```

Create coverage plots. The `aflplusplus` image already ships `gnuplot-nox`; in host mode, install gnuplot first with `apt install gnuplot`.

```bash
./afl++ docker afl-plot out/default out_graph/
```

### Re-executing Test Cases

Pass one of the filenames from `out/default/crashes/`:

```bash
./afl++ docker ./fuzz out/default/crashes/id:000000,sig:06,src:000002,time:286,execs:13105,op:havoc,rep:4
```

### Fuzzer Options

| Option | Purpose |
|--------|---------|
| `-G 4000` | Maximum test input length (default: 1048576 bytes) |
| `-t 1000` | Timeout in milliseconds for each test case (default: 1000ms) |
| `-m 1000` | Memory limit in megabytes (default: 0 = unlimited) |
| `-x ./dict.dict` | Use dictionary file to guide mutations |

## Environment Variables That Matter

AFL++ has [many environment variables](https://aflplus.plus/docs/env_variables/), but most are niche. These are the ones that matter in practice.

### Always Set These

```bash
# Every campaign should use tmpfs — SSDs will thank you, and it's faster
AFL_TMPDIR=/dev/shm
```

`AFL_TMPDIR` is a free performance win with no downsides — not setting it wears out your SSD and slows fuzzing.

### Slow Targets

```bash
# Speeds up calibration ~2.5x — use when targets are slow (e.g., >10 ms/exec)
AFL_FAST_CAL=1
```

`AFL_FAST_CAL` reduces calibration time with negligible precision loss. Recommended specifically for slow targets where calibration would otherwise take a long time.

### Multi-Core Campaigns

```bash
# On the primary (-M) instance only — needed for afl-cmin, not for fuzzing itself
AFL_FINAL_SYNC=1

# On all instances — cache test cases in memory (default: 50 MB, good range: 50-250 MB)
AFL_TESTCACHE_SIZE=100
```

`AFL_FINAL_SYNC` tells the primary instance to do a final import from all secondaries when stopping. This does not affect the fuzzing process itself — it only matters when you later run `afl-cmin` for corpus minimization, ensuring the primary's queue has the full combined corpus. `AFL_TESTCACHE_SIZE` caches test cases in memory to reduce disk I/O; the default is 50 MB and values between 50-250 MB work well for most campaigns.

### CI/Automated Fuzzing

```bash
# Fail fast if fuzzing isn't finding anything
AFL_EXIT_ON_TIME=3600 # 1 hour with no new paths = stop

# Or run until "done" (all queue entries processed)
AFL_EXIT_WHEN_DONE=1

# Headless environments
AFL_NO_UI=1
```

Unbounded fuzzing in CI wastes resources. Set time limits or use exit conditions.

### Variables to Avoid

| Variable | Why Skip It |
|----------|-------------|
| `AFL_NO_ARITH` | Can hurt coverage on binary formats, but may be useful for text-based targets |
| `AFL_SHUFFLE_QUEUE` | Only for exotic setups, usually harmful |
| `AFL_DISABLE_TRIM` | Trimming is valuable, don't disable without reason |

## Multi-Core Fuzzing

AFL++ excels at multi-core fuzzing with two major advantages:
1. More executions per second (scales linearly with physical cores)
2. Asymmetrical fuzzing (e.g., one ASan job, rest without sanitizers)

### Starting a Campaign

Start the primary fuzzer (in background):

```bash
./afl++ docker afl-fuzz -M primary -i seeds -o state -- ./fuzz 1>primary.log 2>primary.error </dev/null &
```

Start secondary fuzzers (as many as you have cores):

```bash
./afl++ docker afl-fuzz -S secondary01 -i seeds -o state -- ./fuzz 1>secondary01.log 2>secondary01.error </dev/null &
./afl++ docker afl-fuzz -S secondary02 -i seeds -o state -- ./fuzz 1>secondary02.log 2>secondary02.error </dev/null &
```

The `</dev/null` is required, not decorative. `docker run -i` keeps the client
reading its own stdin, and a backgrounded process that reads the terminal is sent
`SIGTTIN`, whose default action stops it — so without the redirect these jobs show
up as `Stopped` in `jobs` and never fuzz.

### Monitoring Multi-Core Campaigns

List all running jobs:

```bash
jobs
```

View live statistics. `watch` needs a terminal that `docker run -i` does not give it, so wrap the whole invocation instead of running `watch` inside the container. Every tick starts a container, which is why the interval is 5 seconds rather than 1:

```bash
watch -n5 --color ./afl++ docker afl-whatsup state/
```

### Stopping All Fuzzers

```bash
kill $(jobs -p)
```

## Coverage Analysis

AFL++ automatically tracks coverage through edge instrumentation. Coverage information is stored in `fuzzer_stats` and `plot_data`.

### Measuring Coverage

Use `afl-plot` to visualize coverage over time:

```bash
./afl++ docker afl-plot out/default out_graph/
```

### Improving Coverage

- Use dictionaries for format-aware fuzzing
- Run longer campaigns (cycles_wo_finds indicates plateau)
- Try different mutation strategies with multi-core fuzzing
- Analyze coverage gaps and add targeted seed inputs

> **See Also:** For detailed coverage analysis techniques, identifying coverage gaps,
> and systematic coverage improvement, see the **coverage-analysis** technique skill.

## CMPLOG

CMPLOG/RedQueen is the best path constraint solving mechanism available in any fuzzer.
To enable it, the fuzz target needs to be instrumented for it.
Before building the fuzzing target set the environment variable:

```bash
./afl++ docker AFL_LLVM_CMPLOG=1 make
```

No special action is needed for compiling and linking the harness.

To run a fuzzer instance with a CMPLOG instrumented fuzzing target, add `-c0` to the command like arguments:

```bash
./afl++ docker afl-fuzz -c0 -S cmplog -i seeds -o state -- ./fuzz 1>cmplog.log 2>cmplog.error </dev/null &
```

## Sanitizer Integration

Sanitizers are essential for finding memory corruption bugs that don't cause immediate crashes.

### AddressSanitizer (ASan)

```bash
./afl++ docker AFL_USE_ASAN=1 afl-clang-fast++ -DNO_MAIN=1 -O2 -fsanitize=fuzzer harness.cc main.cc -o fuzz
```

**Note:** Memory limit (`-m`) is not supported with ASan due to 20TB virtual memory reservation.

### UndefinedBehaviorSanitizer (UBSan)

```bash
./afl++ docker AFL_USE_UBSAN=1 afl-clang-fast++ -DNO_MAIN=1 -O2 -fsanitize=fuzzer,undefined harness.cc main.cc -o fuzz
```

### Common Sanitizer Issues

| Issue | Solution |
|-------|----------|
| ASan slows fuzzing | Use only 1 ASan job in multi-core setup |
| Stack exhaustion | Increase stack with `ASAN_OPTIONS=stack_size=...` |
| GCC version mismatch | Ensure system GCC matches AFL++ plugin version |

> **See Also:** For comprehensive sanitizer configuration and troubleshooting,
> see the **address-sanitizer** technique skill.

## Advanced Usage

### Tips and Tricks

| Tip | Why It Helps |
|-----|--------------|
| Use LLVMFuzzerTestOneInput harnesses where possible | If a fuzzing campaign has at least 85% stability then this is the most efficient fuzzing style. If not then try standard input or file input fuzzing |
| Use dictionaries | Helps fuzzer discover format-specific keywords and magic bytes |
| Set realistic timeouts | Prevents false positives from system load |
| Limit input size | Larger inputs don't necessarily explore more space |
| Monitor stability | Low stability indicates non-deterministic behavior |

### Standard Input Fuzzing

AFL++ can fuzz programs reading from stdin without a libFuzzer harness:

```bash
./afl++ docker afl-clang-fast++ -O2 main_stdin.c -o fuzz_stdin
./afl++ docker afl-fuzz -i seeds -o out -- ./fuzz_stdin
```

This is slower than persistent mode but requires no harness code.

### File Input Fuzzing

For programs that read files, use `@@` placeholder:

```bash
./afl++ docker afl-clang-fast++ -O2 main_file.c -o fuzz_file
./afl++ docker afl-fuzz -i seeds -o out -- ./fuzz_file @@
```

For better performance, use `fmemopen` to create file descriptors from memory.

### Argument Fuzzing

Fuzz command-line arguments using `argv-fuzz-inl.h`:

```c++
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#ifdef __AFL_COMPILER
#include "argv-fuzz-inl.h"
#endif

void check_buf(char *buf, size_t buf_len) {
 if(buf_len > 0 && buf[0] == 'a') {
 if(buf_len > 1 && buf[1] == 'b') {
 if(buf_len > 2 && buf[2] == 'c') {
 abort();
 }
 }
 }
}

int main(int argc, char *argv[]) {
#ifdef __AFL_COMPILER
 AFL_INIT_ARGV();
#endif

 if (argc < 2) {
 fprintf(stderr, "Usage: %s <input_string>\n", argv[0]);
 return 1;
 }

 char *input_buf = argv[1];
 size_t len = strlen(input_buf);
 check_buf(input_buf, len);
 return 0;
}
```

Download the header:

```bash
curl -O https://raw.githubusercontent.com/AFLplusplus/AFLplusplus/stable/utils/argv_fuzzing/argv-fuzz-inl.h
```

Compile and run:

```bash
./afl++ docker afl-clang-fast++ -O2 main_arg.c -o fuzz_arg
./afl++ docker afl-fuzz -i seeds -o out -- ./fuzz_arg
```

### Performance Tuning

| Setting | Impact |
|---------|--------|
| CPU core count | Linear scaling with physical cores |
| Persistent mode | 10-20x faster than fork server |
| `-G` input size limit | Smaller = faster, but may miss bugs |
| ASan ratio | 1 ASan job per 4-8 non-ASan jobs |

## Troubleshooting

| Problem | Cause | Solution |
|---------|-------|----------|
| Low exec/sec (<1k) | Not using persistent mode | Create a LLVMFuzzerTestOneInput style harness |
| Low stability (<85%) | Non-deterministic code | Fuzz a program via stdin or file inputs, or create such a harness |
| GCC plugin error | GCC version mismatch | Ensure system GCC matches AFL++ build and install gcc-$GCC_VERSION-plugin-dev |
| No crashes found | Need sanitizers | Recompile with `AFL_USE_ASAN=1` |
| Memory limit exceeded | ASan uses 20TB virtual | Remove `-m` flag when using ASan |
| Docker performance loss | Virtualization overhead | Use bare metal or VM for production fuzzing |

## Related Skills

### Technique Skills

| Skill | Use Case |
|-------|----------|
| **fuzz-harness-writing** | Detailed guidance on writing effective harnesses |
| **address-sanitizer** | Memory error detection during fuzzing |
| **undefined-behavior-sanitizer** | Detect undefined behavior bugs |
| **fuzzing-corpus** | Building and managing seed corpora |
| **fuzzing-dictionaries** | Creating dictionaries for format-aware fuzzing |

### Related Fuzzers

| Skill | When to Consider |
|-------|------------------|
| **libfuzzer** | Quick prototyping, single-threaded fuzzing is sufficient |
| **libafl** | Need custom mutators or research-grade features |

## Resources

### Key External Resources

**[AFL++ GitHub Repository](https://github.com/AFLplusplus/AFLplusplus)**
Official repository with comprehensive documentation, examples, and issue tracker.

**[Fuzzing in Depth](https://raw.githubusercontent.com/AFLplusplus/AFLplusplus/refs/heads/stable/docs/fuzzing_in_depth.md)**
Advanced documentation by the AFL++ team covering instrumentation modes, optimization techniques, and advanced use cases.

**[AFL++ Under The Hood](https://blog.ritsec.club/posts/afl-under-hood/)**
Technical deep-dive into AFL++ internals, mutation strategies, and coverage tracking mechanisms.

**[AFL++: Combining Incremental Steps of Fuzzing Research](https://www.usenix.org/system/files/woot20-paper-fioraldi.pdf)**
Research paper describing AFL++ architecture and performance improvements over original AFL.

### Video Resources

- [Fuzzing cURL](https://blog.trailofbits.com/2023/02/14/curl-audit-fuzzing-libcurl-command-line-interface/) - Trail of Bits blog post on using AFL++ argument fuzzing for cURL
- [Sudo Vulnerability Walkthrough](https://www.youtube.com/playlist?list=PLhixgUqwRTjy0gMuT4C3bmjeZjuNQyqdx) - LiveOverflow series on rediscovering CVE-2021-3156
- [Rediscovery of libpng bug](https://www.youtube.com/watch?v=PJLWlmp8CDM) - LiveOverflow video on finding CVE-2023-4863

The download contains SKILL.md . Extract the whole bundle; the supporting files are required. Inspect the included MANIFEST.json for file hashes.

By **Trail of Bits**. [Exact upstream source ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/plugins/testing-handbook-skills/skills/aflpp/SKILL.md) · [Licence](/resources/skills/trailofbits-aflpp/LICENSE.txt) · [Attribution](/resources/skills/trailofbits-aflpp/ATTRIBUTION.txt)

SHA-256 0a31023527808e68a53b81b89c7a6c10c6f84755a410df820facef44252e518d

 Read the applicable licence Attribution-ShareAlike 4.0 International

=======================================================================

Creative Commons Corporation ("Creative Commons") is not a law firm and
does not provide legal services or legal advice. Distribution of
Creative Commons public licenses does not create a lawyer-client or
other relationship. Creative Commons makes its licenses and related
information available on an "as-is" basis. Creative Commons gives no
warranties regarding its licenses, any material licensed under their
terms and conditions, or any related information. Creative Commons
disclaims all liability for damages resulting from their use to the
fullest extent possible.

Using Creative Commons Public Licenses

Creative Commons public licenses provide a standard set of terms and
conditions that creators and other rights holders may use to share
original works of authorship and other material subject to copyright
and certain other rights specified in the public license below. The
following considerations are for informational purposes only, are not
exhaustive, and do not form part of our licenses.

 Considerations for licensors: Our public licenses are
 intended for use by those authorized to give the public
 permission to use material in ways otherwise restricted by
 copyright and certain other rights. Our licenses are
 irrevocable. Licensors should read and understand the terms
 and conditions of the license they choose before applying it.
 Licensors should also secure all rights necessary before
 applying our licenses so that the public can reuse the
 material as expected. Licensors should clearly mark any
 material not subject to the license. This includes other CC-
 licensed material, or material used under an exception or
 limitation to copyright. More considerations for licensors:
	wiki.creativecommons.org/Considerations_for_licensors

 Considerations for the public: By using one of our public
 licenses, a licensor grants the public permission to use the
 licensed material under specified terms and conditions. If
 the licensor's permission is not necessary for any reason--for
 example, because of any applicable exception or limitation to
 copyright--then that use is not regulated by the license. Our
 licenses grant only permissions under copyright and certain
 other rights that a licensor has authority to grant. Use of
 the licensed material may still be restricted for other
 reasons, including because others have copyright or other
 rights in the material. A licensor may make special requests,
 such as asking that all changes be marked or described.
 Although not required by our licenses, you are encouraged to
 respect those requests where reasonable. More_considerations
 for the public:
	wiki.creativecommons.org/Considerations_for_licensees

=======================================================================

Creative Commons Attribution-ShareAlike 4.0 International Public
License

By exercising the Licensed Rights (defined below), You accept and agree
to be bound by the terms and conditions of this Creative Commons
Attribution-ShareAlike 4.0 International Public License ("Public
License"). To the extent this Public License may be interpreted as a
contract, You are granted the Licensed Rights in consideration of Your
acceptance of these terms and conditions, and the Licensor grants You
such rights in consideration of benefits the Licensor receives from
making the Licensed Material available under these terms and
conditions.

Section 1 -- Definitions.

 a. Adapted Material means material subject to Copyright and Similar
 Rights that is derived from or based upon the Licensed Material
 and in which the Licensed Material is translated, altered,
 arranged, transformed, or otherwise modified in a manner requiring
 permission under the Copyright and Similar Rights held by the
 Licensor. For purposes of this Public License, where the Licensed
 Material is a musical work, performance, or sound recording,
 Adapted Material is always produced where the Licensed Material is
 synched in timed relation with a moving image.

 b. Adapter's License means the license You apply to Your Copyright
 and Similar Rights in Your contributions to Adapted Material in
 accordance with the terms and conditions of this Public License.

 c. BY-SA Compatible License means a license listed at
 creativecommons.org/compatiblelicenses, approved by Creative
 Commons as essentially the equivalent of this Public License.

 d. Copyright and Similar Rights means copyright and/or similar rights
 closely related to copyright including, without limitation,
 performance, broadcast, sound recording, and Sui Generis Database
 Rights, without regard to how the rights are labeled or
 categorized. For purposes of this Public License, the rights
 specified in Section 2(b)(1)-(2) are not Copyright and Similar
 Rights.

 e. Effective Technological Measures means those measures that, in the
 absence of proper authority, may not be circumvented under laws
 fulfilling obligations under Article 11 of the WIPO Copyright
 Treaty adopted on December 20, 1996, and/or similar international
 agreements.

 f. Exceptions and Limitations means fair use, fair dealing, and/or
 any other exception or limitation to Copyright and Similar Rights
 that applies to Your use of the Licensed Material.

 g. License Elements means the license attributes listed in the name
 of a Creative Commons Public License. The License Elements of this
 Public License are Attribution and ShareAlike.

 h. Licensed Material means the artistic or literary work, database,
 or other material to which the Licensor applied this Public
 License.

 i. Licensed Rights means the rights granted to You subject to the
 terms and conditions of this Public License, which are limited to
 all Copyright and Similar Rights that apply to Your use of the
 Licensed Material and that the Licensor has authority to license.

 j. Licensor means the individual(s) or entity(ies) granting rights
 under this Public License.

 k. Share means to provide material to the public by any means or
 process that requires permission under the Licensed Rights, such
 as reproduction, public display, public performance, distribution,
 dissemination, communication, or importation, and to make material
 available to the public including in ways that members of the
 public may access the material from a place and at a time
 individually chosen by them.

 l. Sui Generis Database Rights means rights other than copyright
 resulting from Directive 96/9/EC of the European Parliament and of
 the Council of 11 March 1996 on the legal protection of databases,
 as amended and/or succeeded, as well as other essentially
 equivalent rights anywhere in the world.

 m. You means the individual or entity exercising the Licensed Rights
 under this Public License. Your has a corresponding meaning.

Section 2 -- Scope.

 a. License grant.

 1. Subject to the terms and conditions of this Public License,
 the Licensor hereby grants You a worldwide, royalty-free,
 non-sublicensable, non-exclusive, irrevocable license to
 exercise the Licensed Rights in the Licensed Material to:

 a. reproduce and Share the Licensed Material, in whole or
 in part; and

 b. produce, reproduce, and Share Adapted Material.

 2. Exceptions and Limitations. For the avoidance of doubt, where
 Exceptions and Limitations apply to Your use, this Public
 License does not apply, and You do not need to comply with
 its terms and conditions.

 3. Term. The term of this Public License is specified in Section
 6(a).

 4. Media and formats; technical modifications allowed. The
 Licensor authorizes You to exercise the Licensed Rights in
 all media and formats whether now known or hereafter created,
 and to make technical modifications necessary to do so. The
 Licensor waives and/or agrees not to assert any right or
 authority to forbid You from making technical modifications
 necessary to exercise the Licensed Rights, including
 technical modifications necessary to circumvent Effective
 Technological Measures. For purposes of this Public License,
 simply making modifications authorized by this Section 2(a)
 (4) never produces Adapted Material.

 5. Downstream recipients.

 a. Offer from the Licensor -- Licensed Material. Every
 recipient of the Licensed Material automatically
 receives an offer from the Licensor to exercise the
 Licensed Rights under the terms and conditions of this
 Public License.

 b. Additional offer from the Licensor -- Adapted Material.
 Every recipient of Adapted Material from You
 automatically receives an offer from the Licensor to
 exercise the Licensed Rights in the Adapted Material
 under the conditions of the Adapter's License You apply.

 c. No downstream restrictions. You may not offer or impose
 any additional or different terms or conditions on, or
 apply any Effective Technological Measures to, the
 Licensed Material if doing so restricts exercise of the
 Licensed Rights by any recipient of the Licensed
 Material.

 6. No endorsement. Nothing in this Public License constitutes or
 may be construed as permission to assert or imply that You
 are, or that Your use of the Licensed Material is, connected
 with, or sponsored, endorsed, or granted official status by,
 the Licensor or others designated to receive attribution as
 provided in Section 3(a)(1)(A)(i).

 b. Other rights.

 1. Moral rights, such as the right of integrity, are not
 licensed under this Public License, nor are publicity,
 privacy, and/or other similar personality rights; however, to
 the extent possible, the Licensor waives and/or agrees not to
 assert any such rights held by the Licensor to the limited
 extent necessary to allow You to exercise the Licensed
 Rights, but not otherwise.

 2. Patent and trademark rights are not licensed under this
 Public License.

 3. To the extent possible, the Licensor waives any right to
 collect royalties from You for the exercise of the Licensed
 Rights, whether directly or through a collecting society
 under any voluntary or waivable statutory or compulsory
 licensing scheme. In all other cases the Licensor expressly
 reserves any right to collect such royalties.

Section 3 -- License Conditions.

Your exercise of the Licensed Rights is expressly made subject to the
following conditions.

 a. Attribution.

 1. If You Share the Licensed Material (including in modified
 form), You must:

 a. retain the following if it is supplied by the Licensor
 with the Licensed Material:

 i. identification of the creator(s) of the Licensed
 Material and any others designated to receive
 attribution, in any reasonable manner requested by
 the Licensor (including by pseudonym if
 designated);

 ii. a copyright notice;

 iii. a notice that refers to this Public License;

 iv. a notice that refers to the disclaimer of
 warranties;

 v. a URI or hyperlink to the Licensed Material to the
 extent reasonably practicable;

 b. indicate if You modified the Licensed Material and
 retain an indication of any previous modifications; and

 c. indicate the Licensed Material is licensed under this
 Public License, and include the text of, or the URI or
 hyperlink to, this Public License.

 2. You may satisfy the conditions in Section 3(a)(1) in any
 reasonable manner based on the medium, means, and context in
 which You Share the Licensed Material. For example, it may be
 reasonable to satisfy the conditions by providing a URI or
 hyperlink to a resource that includes the required
 information.

 3. If requested by the Licensor, You must remove any of the
 information required by Section 3(a)(1)(A) to the extent
 reasonably practicable.

 b. ShareAlike.

 In addition to the conditions in Section 3(a), if You Share
 Adapted Material You produce, the following conditions also apply.

 1. The Adapter's License You apply must be a Creative Commons
 license with the same License Elements, this version or
 later, or a BY-SA Compatible License.

 2. You must include the text of, or the URI or hyperlink to, the
 Adapter's License You apply. You may satisfy this condition
 in any reasonable manner based on the medium, means, and
 context in which You Share Adapted Material.

 3. You may not offer or impose any additional or different terms
 or conditions on, or apply any Effective Technological
 Measures to, Adapted Material that restrict exercise of the
 rights granted under the Adapter's License You apply.

Section 4 -- Sui Generis Database Rights.

Where the Licensed Rights include Sui Generis Database Rights that
apply to Your use of the Licensed Material:

 a. for the avoidance of doubt, Section 2(a)(1) grants You the right
 to extract, reuse, reproduce, and Share all or a substantial
 portion of the contents of the database;

 b. if You include all or a substantial portion of the database
 contents in a database in which You have Sui Generis Database
 Rights, then the database in which You have Sui Generis Database
 Rights (but not its individual contents) is Adapted Material,

 including for purposes of Section 3(b); and
 c. You must comply with the conditions in Section 3(a) if You Share
 all or a substantial portion of the contents of the database.

For the avoidance of doubt, this Section 4 supplements and does not
replace Your obligations under this Public License where the Licensed
Rights include other Copyright and Similar Rights.

Section 5 -- Disclaimer of Warranties and Limitation of Liability.

 a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
 EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
 AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
 ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
 IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
 WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
 PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
 ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
 KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
 ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.

 b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
 TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
 NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
 INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
 COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
 USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
 ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
 DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
 IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.

 c. The disclaimer of warranties and limitation of liability provided
 above shall be interpreted in a manner that, to the extent
 possible, most closely approximates an absolute disclaimer and
 waiver of all liability.

Section 6 -- Term and Termination.

 a. This Public License applies for the term of the Copyright and
 Similar Rights licensed here. However, if You fail to comply with
 this Public License, then Your rights under this Public License
 terminate automatically.

 b. Where Your right to use the Licensed Material has terminated under
 Section 6(a), it reinstates:

 1. automatically as of the date the violation is cured, provided
 it is cured within 30 days of Your discovery of the
 violation; or

 2. upon express reinstatement by the Licensor.

 For the avoidance of doubt, this Section 6(b) does not affect any
 right the Licensor may have to seek remedies for Your violations
 of this Public License.

 c. For the avoidance of doubt, the Licensor may also offer the
 Licensed Material under separate terms or conditions or stop
 distributing the Licensed Material at any time; however, doing so
 will not terminate this Public License.

 d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
 License.

Section 7 -- Other Terms and Conditions.

 a. The Licensor shall not be bound by any additional or different
 terms or conditions communicated by You unless expressly agreed.

 b. Any arrangements, understandings, or agreements regarding the
 Licensed Material not stated herein are separate from and
 independent of the terms and conditions of this Public License.

Section 8 -- Interpretation.

 a. For the avoidance of doubt, this Public License does not, and
 shall not be interpreted to, reduce, limit, restrict, or impose
 conditions on any use of the Licensed Material that could lawfully
 be made without permission under this Public License.

 b. To the extent possible, if any provision of this Public License is
 deemed unenforceable, it shall be automatically reformed to the
 minimum extent necessary to make it enforceable. If the provision
 cannot be reformed, it shall be severed from this Public License
 without affecting the enforceability of the remaining terms and
 conditions.

 c. No term or condition of this Public License will be waived and no
 failure to comply consented to unless expressly agreed to by the
 Licensor.

 d. Nothing in this Public License constitutes or may be interpreted
 as a limitation upon, or waiver of, any privileges and immunities
 that apply to the Licensor or You, including from the legal
 processes of any jurisdiction or authority.

=======================================================================

Creative Commons is not a party to its public
licenses. Notwithstanding, Creative Commons may elect to apply one of
its public licenses to material it publishes and in those instances
will be considered the “Licensor.” The text of the Creative Commons
public licenses is dedicated to the public domain under the CC0 Public
Domain Dedication. Except for the limited purpose of indicating that
material is shared under a Creative Commons public license or as
otherwise permitted by the Creative Commons policies published at
creativecommons.org/policies, Creative Commons does not authorize the
use of the trademark "Creative Commons" or any other trademark or logo
of Creative Commons without its prior written consent including,
without limitation, in connection with any unauthorized modifications
to any of its public licenses or any other arrangements,
understandings, or agreements concerning use of licensed material. For
the avoidance of doubt, this paragraph does not form part of the
public licenses.

Creative Commons may be contacted at creativecommons.org.

04 / FOLLOW THE EVIDENCE

## The source trail.

Our notes are separate from the original resource. Check upstream before adopting a new version.

 - [Skill definition ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/plugins/testing-handbook-skills/skills/aflpp/SKILL.md) Checked 2026-10-14 https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/plugins/testing-handbook-skills/skills/aflpp/SKILL.md Supports: Workflow and stated scope
- [Repository licence ↗](https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/LICENSE) Checked 2026-10-14 https://github.com/trailofbits/skills/blob/82fe8226252622fa807643bdca1710901198553a/LICENSE Supports: Redistribution terms

KEEP COMPARING

## Other approaches to consider.

Related by category or shared topics. These are alternatives to inspect, not a measured quality order.

 [### Atheris ↗ Sets up a Python fuzz harness, including C extensions, instead of treating a unit test as a fuzzer.](/skills/trailofbits-atheris/)[### cargo-fuzz ↗ Requires the nightly toolchain and a fuzz_target harness before a Rust fuzz run counts.](/skills/trailofbits-cargo-fuzz/)[### Coverage analysis ↗ Turns an uncovered region into the next harness or seed change, instead of treating a long run as done.](/skills/trailofbits-coverage-analysis/)

 [AI Tools ↗](/tools/)[Skills ↗](/skills/)[Agents ↗](/agents/)[MCP Servers ↗](/mcp-servers/)[Workflows ↗](/workflows/)

## Continue your investigation

 - [Choose a toolkit](/tools/)
- [Inspect execution hosts](/agents/)
- [Check tool access](/mcp-servers/)
- [Check project dependencies](/check-repo/)
