/AFL_Runner

Scaling best-practice AFLPlusPlus fuzzing campaigns made easy

Primary LanguageRustApache License 2.0Apache-2.0

AFL Runner

Crates.io License

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.

Getting Started 🚀

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

Prerequisites

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

...or install directly via crates.io:

cargo install afl_runner
aflr --help

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
    • 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:

    • 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

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
  • Allow AFLPlusPlus forks to be used on some amount of runners

Usage Example 💡

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

AFL_Runner_cmd_gen

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

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, and
  4. CMPLOG.

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:

AFL_Runner demo

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

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 :).

License 📜

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


🔼 Back to top