{"id":20481289,"url":"https://github.com/0xricksanchez/afl_runner","last_synced_at":"2025-04-13T14:11:05.375Z","repository":{"id":218488603,"uuid":"746154075","full_name":"0xricksanchez/AFL_Runner","owner":"0xricksanchez","description":"AFLPlusPlus command generator to make the best use of multiple cores","archived":false,"fork":false,"pushed_at":"2024-03-07T07:24:35.000Z","size":27,"stargazers_count":3,"open_issues_count":7,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-07T11:02:57.411Z","etag":null,"topics":["afl","aflplusplus","fuzzer","fuzzing","multiprocessing","multithreading","tmux"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/afl_runner","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xricksanchez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2024-01-21T08:13:08.000Z","updated_at":"2024-04-30T08:42:39.842Z","dependencies_parsed_at":null,"dependency_job_id":"4b80871b-f46c-4184-8344-bd465285fbb9","html_url":"https://github.com/0xricksanchez/AFL_Runner","commit_stats":null,"previous_names":["0xricksanchez/afl_runner"],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2FAFL_Runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2FAFL_Runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2FAFL_Runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xricksanchez%2FAFL_Runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xricksanchez","download_url":"https://codeload.github.com/0xricksanchez/AFL_Runner/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248724629,"owners_count":21151561,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["afl","aflplusplus","fuzzer","fuzzing","multiprocessing","multithreading","tmux"],"created_at":"2024-11-15T16:07:39.367Z","updated_at":"2025-04-13T14:11:05.368Z","avatar_url":"https://github.com/0xricksanchez.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AFL Runner\n\n[![Crates.io](https://img.shields.io/crates/v/afl_runner.svg)](https://crates.io/crates/afl_runner)\n[![License](https://img.shields.io/badge/license%20-%20Apache%202.0%20-%20blue)](LICENSE)\n[![Rust](https://github.com/0xricksanchez/AFL_Runner/actions/workflows/rust.yml/badge.svg)](https://github.com/0xricksanchez/AFL_Runner/actions/workflows/rust.yml)\n\n`AFL_Runner` is a modern CLI tool designed to streamline running efficient multi-core [AFLPlusPlus](https://github.com/AFLplusplus/AFLplusplus) campaigns. The default configuration is based on the section [_Using multiple cores_](https://aflplus.plus/docs/fuzzing_in_depth/#c-using-multiple-cores) of the official documentation.\n\n- [AFL Runner](#afl-runner)\n  - [Getting Started 🚀](#getting-started-)\n    - [Prerequisites](#prerequisites)\n    - [Installation](#installation)\n  - [Features ✨](#features-)\n    - [What is not? ❌](#what-is-not-)\n    - [Roadmap 🗺️](#roadmap-)\n  - [Usage Example 💡](#usage-example-)\n    - [Shell Completion ⚡](#shell-completion-)\n  - [Showcase 🎥](#showcase-)\n  - [Contributing 🤝](#contributing-)\n  - [License 📜](#license-)\n\n## Getting Started 🚀\n\nCurrently, this tool should work on all \\*NIX flavor operating-systems.\n\n### Prerequisites\n\n- [Rust toolchain v1.85.0](https://www.rust-lang.org/tools/install) 🦀\n- [AFLPlusPlus](https://github.com/AFLplusplus/AFLplusplus)\n- [pgrep](https://man7.org/linux/man-pages/man1/pgrep.1.html)\n- [TMUX](https://github.com/tmux/tmux) || [screen](https://www.gnu.org/software/screen/) (Optional for TUI)\n- [LLVM](https://llvm.org/) (Optional for coverage reporting)\n\n### Installation\n\nYou can compile `AFL_Runner` yourself...:\n\n```bash\ngit clone https://github.com/0xricksanchez/AFL_Runner.git\ncd AFL_Runner\ncargo build --release\n./target/release/aflr --help\n\n# Optional: Generate completion scripts\ncargo run --features completion --bin generate_completions\n```\n\n...or install directly via [crates.io](https://crates.io/crates/afl_runner):\n\n```bash\ncargo install afl_runner\naflr --help\n\n# Alternatively, with the completion support included\ncargo install --path . --features completion\n```\n\n## Features ✨\n\n`AFL_Runner` allows you to set the most necessary AFLPlusplus flags and mimics the AFLplusplus syntax for these options:\n\n- Supported AFLplusplus flags:\n\n  - [x] Corpus directory\n  - [x] Output directory\n  - [x] Dictionary file/directory\n  - [x] Custom `afl-fuzz` binary path for all instances\n  - [x] Supply arguments to target binary (including @@)\n  - [x] Amount of runner commands to generate\n  - [x] Support for \\*SAN, CMPLOG, CMPCOV binaries\n\n- Other features:\n  - [x] Coverage collection/visualization\n  - [x] `Tmux` or `screen` option to automatically create an appropriate layout for all runners\n  - [x] TUI\n  - [x] Provide a configuration file via `--config` to make sharing/storing per project configurations easier\n    - [x] Automatically read out a configuration named `aflr_cfg.toml` in the `CWD` when no `--config` was supplied\n  - [x] Mode: `default` (vanilla AFL++), `multiple-cores` ([Ref.](https://aflplus.plus/docs/fuzzing_in_depth/#c-using-multiple-cores)), and `ci-fuzzing` ([Ref.](https://aflplus.plus/docs/fuzzing_in_depth/#5-ci-fuzzing))!\n  - [x] _Deterministic_ command generation and AFL++ with seeding\n\n_Note_: Arguments supplied over the command-line take precedence over any configuration file options.\n\n### What is not? ❌\n\n`AFL_Runner` aims to be a plug \u0026 play solution for when you're at a stage of fuzzing campaign where all that is left is running a multi-core setup.\nSo, this tool is **not** (yet) a helper for:\n\n- Compiling a target in multiple flavors\n- Preparing a good initial seed corpus\n- Providing a decent dictionary to boost code-coverage\n- Debugging a fuzzing campaign\n\n### Roadmap 🗺️\n\n- [ ] Add remote option 🌐\n- [ ] Native integration for [statsd](https://registry.hub.docker.com/r/prom/statsd-exporter)\n- [ ] Add more configuration options\n  - [ ] Add more sensible defaults for other options\n  - [ ] Full modularity to cater to very specialized fuzzing campaigns\n- [ ] Allow AFLPlusPlus forks to be used on some amount of runners\n\n## Usage Example 💡\n\nHere's an example of generating AFL++ commands with `AFL_Runner`:\n\n![AFL_Runner_cmd_gen](img/gen.gif)\n\n_Note_: Supplying the \\*SAN, CMPLOG, or CMPCOV binaries is optional and if omitted all invocations just contain the (mandatory) instrumented target instead.\n\n### Shell Completion ⚡\n\nThe tool supports shell completion for tmux session names when using the kill command. To enable completion:\n\n1. First generation the completion scripts:\n\n```bash\ncargo run --bin generate_completions\n```\n\n2. Depending on your shell, do the following:\n\nFor ZSH:\n\n```bash\n# Option 1: Source directly\nsource completions/aflr_dynamic.zsh\n\n# Option 2 (preferred): Install to completion directory\nmkdir -p ~/.zsh/completions\ncp completions/aflr_dynamic.zsh ~/.zsh/completions/_aflr\n# Add to your .zshrc:\nfpath=(~/.zsh/completions $fpath)\nautoload -U compinit \u0026\u0026 compinit\n```\n\nFor Bash:\n\n```bash\n# Add to your .bashrc:\nsource /path/to/completions/aflr_dynamic.bash\n```\n\nOnce set up, you can use tab completion to see available tmux sessions:\n\n```bash\naflr kill \u003cTAB\u003e\n```\n\n## Showcase 🎥\n\n`AFL_Runner` also includes a terminal user interface (TUI) for monitoring the fuzzing campaign progress.\nThe following demo can be found in `examples/` and can be build locally by running `cargo make` from the root directory of the project.\n\nThe example builds a recent version of _libxml2_ four times with different compile-time instrumentations:\n\n1. plain AFL++ instrumentation\n2. Address-Sanitizer (ASan)\n3. CMPCOV,\n4. CMPLOG, and\n5. Coverage visualization\n\nAfterwards, the necessary commands for 16 instances are being generated, which then are executed in a dedicated TMUX session.\nFinally, a custom TUI offered by _AFL Runner_ is tracking the progress of the fuzzing campaign in a centralized space:\n\n![AFL_Runner demo](img/demo.gif)\n\n_Note_: The TUI can be used as a **full** replacement for `afl-whatsup` by using `afl_runner tui \u003cafl_output_dir\u003e`!\n\nCoverage visualization is also covered by `AFL_Runner`:\n\n![AFL_Runner cov](img/cov.gif)\n\n_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.\n\n## Contributing 🤝\n\nContributions are welcome! Please feel free to submit a pull request or open an issue for any bugs, feature requests, or improvements.\nAny other support is also more than welcome :). Feel to reach out on [X](https://x.com/0xricksanchez) or [BSKY](https://bsky.app/profile/434b.bsky.social).\n\n## License 📜\n\nThis project is licensed under the Apache License. See the [LICENSE](LICENSE) file for details.\n\n\u003cbr\u003e\u003chr\u003e\n[🔼 Back to top](#afl-runner)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xricksanchez%2Fafl_runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xricksanchez%2Fafl_runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xricksanchez%2Fafl_runner/lists"}