package bun

  1. Overview
  2. Docs
simple management of afl-fuzz processes

Install

Dune Dependency

Authors

Maintainers

Sources

bun-0.3.2.tbz
sha256=9957de6e56e73814947df3d3093b60f56789184d6a056409dcfc527b07ff300c
md5=8982123a94bbde0815cf8e769eb1bd01

Description

Published: 06 May 2018

README

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?

bun uses 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-whatsup. 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 afl-fuzz process, 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 bun.)

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?

See bun --help for the most current information.

Here's an example of fuzzing one of Crowbar's packaged examples, calendar:

$ 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 
calendar: ....
calendar: FAIL

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

Building

The usual jbuilder runes should be sufficient:

jbuilder build --dev @install

For CI

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.

Dependencies (9)

  1. afl = "2.52b"
  2. spawn >= "v0.12"
  3. astring
  4. rresult >= "0.3.0"
  5. fpath
  6. cmdliner >= "1.0.0" & < "1.1.0"
  7. bos >= "0.2.0"
  8. jbuilder >= "1.0+beta7"
  9. ocaml >= "4.05"

Dev Dependencies

None

Used by

None

Conflicts

None

OCaml

Innovation. Community. Security.