AFL Runner

AFL_Runner is a modern CLI tool designed to streamline running efficient multi-core AFLPlusPlus campaigns. The default configuration is based on the section Using multiple cores of the official documentation.

• AFL Runner
  • Getting Started 🚀
    • Prerequisites
    • Installation
  • Features ✨
    • What is not? ❌
    • Roadmap 🗺️
  • Usage Example 💡
    • Shell Completion ⚡
  • Showcase 🎥
  • Contributing 🤝
  • License 📜

Getting Started 🚀

Currently, this tool should work on all *NIX flavor operating-systems.

Prerequisites

• Rust toolchain v1.85.0 🦀
• AFLPlusPlus
• pgrep
• TMUX || screen (Optional for TUI)
• LLVM (Optional for coverage reporting)

Installation

You can compile AFL_Runner yourself...:

git clone https://github.com/0xricksanchez/AFL_Runner.git
cd AFL_Runner
cargo build --release
./target/release/aflr --help

# Optional: Generate completion scripts
cargo run --features completion --bin generate_completions

...or install directly via crates.io:

cargo install afl_runner
aflr --help

# Alternatively, with the completion support included
cargo install --path . --features completion

Features ✨

AFL_Runner allows you to set the most necessary AFLPlusplus flags and mimics the AFLplusplus syntax for these options:

• Supported AFLplusplus flags:

  • Corpus directory
  • Output directory
  • Dictionary file/directory
  • Custom afl-fuzz binary path for all instances
  • Supply arguments to target binary (including @@)
  • Amount of runner commands to generate
  • Support for *SAN, CMPLOG, CMPCOV binaries

• Other features:

  • Coverage collection/visualization
  • Tmux or screen option to automatically create an appropriate layout for all runners
  • TUI
  • Provide a configuration file via --config to make sharing/storing per project configurations easier
    • Automatically read out a configuration named aflr_cfg.toml in the CWD when no --config was supplied
  • Mode: default (vanilla AFL++), multiple-cores (Ref.), and ci-fuzzing (Ref.)!
  • Deterministic command generation and AFL++ with seeding

Note: Arguments supplied over the command-line take precedence over any configuration file options.

What is not? ❌

AFL_Runner aims to be a plug & play solution for when you're at a stage of fuzzing campaign where all that is left is running a multi-core setup. So, this tool is not (yet) a helper for:

• Compiling a target in multiple flavors
• Preparing a good initial seed corpus
• Providing a decent dictionary to boost code-coverage
• Debugging a fuzzing campaign

Roadmap 🗺️

• Add remote option 🌐
• Native integration for statsd
• Add more configuration options
  • Add more sensible defaults for other options
  • Full modularity to cater to very specialized fuzzing campaigns
• Allow AFLPlusPlus forks to be used on some amount of runners

Usage Example 💡

Here's an example of generating AFL++ commands with AFL_Runner:

Note: Supplying the *SAN, CMPLOG, or CMPCOV binaries is optional and if omitted all invocations just contain the (mandatory) instrumented target instead.

Shell Completion ⚡

The tool supports shell completion for tmux session names when using the kill command. To enable completion:

1. First generation the completion scripts:

cargo run --bin generate_completions

2. Depending on your shell, do the following:

For ZSH:

# Option 1: Source directly
source completions/aflr_dynamic.zsh

# Option 2 (preferred): Install to completion directory
mkdir -p ~/.zsh/completions
cp completions/aflr_dynamic.zsh ~/.zsh/completions/_aflr
# Add to your .zshrc:
fpath=(~/.zsh/completions $fpath)
autoload -U compinit && compinit

For Bash:

# Add to your .bashrc:
source /path/to/completions/aflr_dynamic.bash

Once set up, you can use tab completion to see available tmux sessions:

aflr kill <TAB>

Showcase 🎥

AFL_Runner also includes a terminal user interface (TUI) for monitoring the fuzzing campaign progress. The following demo can be found in examples/ and can be build locally by running cargo make from the root directory of the project.

The example builds a recent version of libxml2 four times with different compile-time instrumentations:

1. plain AFL++ instrumentation
2. Address-Sanitizer (ASan)
3. CMPCOV,
4. CMPLOG, and
5. Coverage visualization

Afterwards, the necessary commands for 16 instances are being generated, which then are executed in a dedicated TMUX session. Finally, a custom TUI offered by AFL Runner is tracking the progress of the fuzzing campaign in a centralized space:

Note: The TUI can be used as a full replacement for afl-whatsup by using afl_runner tui <afl_output_dir>!

Coverage visualization is also covered by AFL_Runner:

Note: IFF you ran the AFLR demo campaign for a while you can run cargo make afl_coverage to run the coverage collection as shown above.

Contributing 🤝

Contributions are welcome! Please feel free to submit a pull request or open an issue for any bugs, feature requests, or improvements. Any other support is also more than welcome :). Feel to reach out on X or BSKY.

License 📜

This project is licensed under the Apache License. See the LICENSE file for details.