AFL++ Support in PromptFuzz

April 10, 2026 ยท View on GitHub

This document explains how to run AFL++ with fuzz drivers generated by PromptFuzz.

It covers:

  • environment and preconditions
  • end-to-end workflow
  • coverage and crash triage
  • common pitfalls

1. Overview

PromptFuzz mainly targets LibFuzzer, but this repository also provides AFL++ support through:

  • AFL-instrumented library artifacts generated by each library: build.sh
  • generated fuzz drivers by normal PromptFuzz workflow: output/<project>/exploit_fuzzers/
  • helper script experiments/afl_script.py to compile the generated harnesses and analyze AFL runs

The AFL workflow is:

  1. Build target library artifacts (including _afl.a static library).
  2. Generate PromptFuzz exploit fuzzers (until the cargo run --bin harness -- <project> fuse-fuzzer} command).
  3. Compile an AFL executable from generated .cc files.
  4. Run AFL++ and collect queues/crashes.
  5. Reuse AFL queue to compute coverage and sanitize crashes with PromptFuzz tools.

2. End-to-End AFL++ Workflow

The examples below use libaom. Replace with your target project name.

2.1 Build library artifacts

In the library building scripts, we support additional AFL++ instrumentations (this step generates AFL variant libraries such as *_afl.a):

cd libraries/libaom
bash build.sh

You should check this building artifacts. Expected outputs include:

  • AFL static library under output/build/libaom/lib/ with suffix _afl.a

2.2 Generate exploit fuzzers with PromptFuzz

From repo root:

cd /root/promptfuzz
cargo run --bin fuzzer -- libaom

Then fuse and compile generated programs to exploit fuzzers:

cargo run --bin harness -- libaom fuse-fuzzer

This should create directories like:

  • output/libaom/exploit_fuzzers/Fuzzer_000/

2.3 Compile AFL executable

Use the helper script:

python3 experiments/afl_script.py libaom --compile

The script compiles all .cc files in:

  • output/libaom/exploit_fuzzers/Fuzzer_000/

and produces:

  • output/libaom/exploit_fuzzers/Fuzzer_000/afl_fuzzer

2.4 Run AFL++

Run from the fuzzer directory:

cd output/libaom/exploit_fuzzers/Fuzzer_000
afl-fuzz -i corpus -o output -V 86400 -t 10000 -- ./afl_fuzzer

For network-facing targets, use bwrap isolation (as suggested by the script):

bwrap --bind / / --dev /dev --proc /proc --unshare-net --tmpfs /tmp -- \
	afl-fuzz -i corpus -o output -V 86400 -t 10000 -- ./afl_fuzzer

3. Post-Run Analysis

After AFL finishes, run:

python3 experiments/afl_script.py libaom --analyze

This does two things:

  1. Copies AFL queue files into minimized_corpus (for coverage replay).
  2. Copies AFL crashes into work/ as crash-* files.

Then use PromptFuzz commands:

cargo run --bin harness -- libaom coverage collect
cargo run --bin harness -- libaom coverage report
cargo run --bin harness -- libaom sanitize-crash

4. Troubleshooting

4.1 Static library ... _afl.a does not exist

Cause: target library was not built with AFL artifacts.

Fix:

  • rerun the corresponding libraries/<project>/build.sh
  • verify output/build/<project>/lib/*_afl.a exists
  • let LLMs to fix the corresponding issues in the build scripts.

4.2 Fuzzer directory ... exploit_fuzzers/Fuzzer_000 does not exist

Cause: exploit fuzzers have not been generated/fused yet.

Fix:

  • run cargo run --bin fuzzer -- <project>
  • run cargo run --bin harness -- <project> fuse-fuzzer

4.3 AFL starts but reports no valid inputs

Cause: corpus/ is empty or missing.

Fix:

  • check corpus generated by library build script
  • seed corpus/ with a few valid files before AFL run

4.4 Path mismatch outside Docker

Cause: experiments/afl_script.py uses hard-coded root /root/promptfuzz.

Fix:

  • run in container path /root/promptfuzz, or
  • update ROOT_DIR in experiments/afl_script.py

5. Minimal Command Checklist

# 1) Build library artifacts
cd /root/promptfuzz/libraries/libaom && bash build.sh

# 2) Generate and fuse PromptFuzz drivers
cd /root/promptfuzz
cargo run --bin fuzzer -- libaom
cargo run --bin harness -- libaom fuse-fuzzer

# 3) Compile AFL binary
python3 experiments/afl_script.py libaom --compile

# 4) Run AFL
cd output/libaom/exploit_fuzzers/Fuzzer_000
afl-fuzz -i corpus -o output -V 86400 -t 10000 -- ./afl_fuzzer

# 5) Analyze and report
python3 experiments/afl_script.py libaom --analyze
cargo run --bin harness -- libaom coverage collect
cargo run --bin harness -- libaom coverage report
cargo run --bin harness -- libaom sanitize-crash