A wrapper for OCaml processes using afl-fuzz, intended for easy use in CI environments. See the README.md for more information.
Published: 07 Jul 2021
What is this?
bun is a tool for integrating fuzzer-based tests into a conventional CI pipeline. The popular afl-fuzz tool in particular is designed to use only one CPU core per invocation and keep records on persistent storage for later examination by an analyst; this particular workflow is ill-suited for cloud-based CI testing services, which do not persist storage for users and unceremoniously kill long-running processes. It also makes using available compute resources (two CPU cores even for free-tier Travis CI) challenging.
bun attempts to solve these problems.
How does it work?
afl-gotcpu to detect the number of free CPU cores and then launches that number of
afl-fuzz processes, configured in the correct manner to cooperate exploring the program's state space.
bun monitors the progress of running
afl-fuzz instances with
afl-fuzz instances launched by
bun run in a mode where they will stop when they find a crash or
afl-fuzz determines that there is a low likelihood of finding one with additional work.
When crashes are detected on any
bun will stop the others and report the crash information. If no crashes are detected,
bun will continue running until the last
afl-fuzz gives up. (You may wish to limit the wall-clock time consumed with
timeout when initially launching
How do I use the output?
When crashes are detected,
bun will base64-encode them and output them on the console. You can then copy the text chunks and base64-decode them into reproduction cases to run locally.
How do I run it?
bun --help for the most current information.
Here's an example of fuzzing one of Crowbar's packaged examples,
$ bun -i input/ -o output/ ./calendar
The last (or only) fuzzer (28129) has finished!
Crashes found! Take a look; copy/paste to save for reproduction:
echo UN5QAd5Q3t7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u | base64 -d > crash_0.$(date -u +%s)
$ echo UN5QAd5Q3t7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u7u | base64 -d > crash_0.$(date -u +%s)
$ ./calendar crash_0.1508880277
When given the input:
[1825-01-30 22:50:45; 1825-03-17 04:05:41]
the test failed:
1825-03-20 04:05:41 != 1825-03-17 04:05:41
Fatal error: exception Crowbar.TestFailure
dune command should be sufficient:
For an example of using
bun in a CI environment, see ocaml-test-stdlib, which uses
bun to manage its Crowbar tests in Travis CI.