0xricksanchez / afl_runner

Scaling best-practice AFLPlusPlus fuzzing campaigns made easy

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 💡
  • Showcase 🎥
  • Contributing 🤝
  • License 📜

Getting Started 🚀

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

Prerequisites

• Rust (nightly) toolchain 🦀
• AFLPlusPlus
• pgrep
• TMUX || screen (Optional)

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:

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:

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

afl_runner's Issues

Not generate "*-san" folder in out

Add tests

In particular, for the command-generation so that we can ensure the generated commands are within the expected limits.

Add a `remote-run` dedicated flag

Should do the exact same as run but on >=1 given remote servers. When implementing we need to:

1. Send all things to the remote (generated template, binaries, ...)
2. Update binary paths in the template/commands depending on the decided remote location
3. An updated health check
4. decide where to run the TUI
5. If we split to >1 server, decide on a corpora sync policy

Allow building the harnesses as well

Allow crash triaging on a specific campaign

Add optional docker layer

Make fuzzing runs introspectable/debuggable

Allow adding more new seeds to running instances

If you want to add new seeds to a fuzzing campaign, you can run a temporary fuzzing instance, e.g., when your main fuzzer is using -o out and the new seeds are in newseeds/ directory:

AFL_BENCH_JUST_ONE=1 AFL_FAST_CAL=1 afl-fuzz -i newseeds -o out -S newseeds -- ./target

So we just run a temporary instance for every new seed and need to ensure we're re-using the output directory of the running campaign

Add a "Log" section in the TUI

Instead of hiding warnings/errors and crashing eventually, it would be nice to have a log section in the TUI

Add generation coverage after stop fuzzing

https://clang.llvm.org/docs/SourceBasedCodeCoverage.html

web gui..?

Modularize message passing and TUI

The current implementation is very tightly coupled, which can make additions tough.
It would be nice to mostly decouple the message fetching/passing from the TUI component.

Maybe we can use LLMP here as well

Plot coverage data for current corpus

Allow tmux run to be exited cleanly