afl-cov uses test case files produced by the AFL fuzzer afl-fuzz to generate gcov code coverage results for a targeted binary. Code coverage is interpreted from one case to the next by afl-cov in order to determine which new functions and lines are hit by AFL with each new test case. Further, afl-cov allows for specific lines or functions to be searched for within coverage results, and when a match is found the corresponding test case file is displayed. This allows the user to discover which AFL test case is the first to exercise a particular function. In addition, afl-cov produces a "zero coverage" report of functions and lines that were never executed during any AFL fuzzing run.

Although of no use to AFL itself, the main application of afl-cov is to wrap some automation around gcov together with AFL test cases and thereby provide data on how to maximize code coverage with AFL fuzzing runs. Manual interpretation of cumulative gcov results from AFL test cases is usually still required, but the "fiddly" steps of iterating over all test cases and generating code coverage reports (along with the "zero coverage" report) is automated by afl-cov.

Producing code coverage data for AFL test cases is an important step to try and maximize code coverage, and thereby help to maximize the effectiveness of AFL. For example, some binaries have code that is reachable only after a complicated (or even cryptographic) test is passed, and AFL may not be able to exercise this code without taking special measures. These measures commonly include patching the project code to bypass such tests. (For example, there is a patch to solve this problem for a CRC test in libpng included in the AFL sources at experimental/libpng_no_checksum/libpng-nocrc.patch.) When a project implements a patch to assist AFL in reaching code that would otherwise be inaccessible, a natural question to ask is whether the patch is effective. Code coverage results can help to verify this.

Prerequisites

Note that afl-cov can parse files created by afl-fuzz from a different system, so technically afl-fuzz does not need to be installed on the same system as afl-cov. This supports scenarios where fuzzing output is collected, say, within a git repository on one system, and coverage results are produced on a different system. However, most workflows typically focus on producing afl-cov results simultaneously for current fuzzing runs on the same system.

Workflow

At a high level, the general workflow for afl-cov against a targeted project is:

$ cd /path/to/project-gcov/
$ afl-cov -d /path/to/afl-fuzz-output/ --live --coverage-cmd \
"cat AFL_FILE | LD_LIBRARY_PATH=./lib/.libs ./bin/.libs/somebin -a -b -c" \
--code-dir .

The AFL_FILE string above refers to the test case file that AFL will build in the queue/ directory under /path/to/afl-fuzz-output. Just leave this string as-is since afl-cov will automatically substitute it with each AFL queue/id:NNNNNN* in succession as it builds the code coverage reports.

Also, in the above command, this handles the case where the AFL fuzzing cycle is fuzzing the targeted binary via stdin. This explains the cat AFL_FILE | ... ./bin/.lib/somebin ... invocation. For the other style of fuzzing with AFL where a file is read from the filesystem, here is an example:

$ cd /path/to/project-gcov/
$ afl-cov -d /path/to/afl-fuzz-output/ --live --coverage-cmd \
"LD_LIBRARY_PATH=./lib/.libs ./bin/.libs/somebin -f AFL_FILE -a -b -c" \
--code-dir .

$ LD_LIBRARY_PATH=./lib/.libs afl-fuzz -T somebin -t 1000 \
-i /path/to/test-cases/ -o /path/to/afl-fuzz-output/ ./bin/.libs/somebin -a -b -c

The familiar AFL status screen will be displayed, and afl-cov will start generating code coverage data.

Note that by default afl-cov does not direct lcov to include branch coverage results. This is because there are commonly many hundreds of AFL test cases in the queue/ directory, and generating branch coverage across all of these cases may slow afl-cov down significantly. If branch coverage is desired, just add the --enable-branch-coverage argument to afl-cov.

Here is a sample of what the afl-cov output looks like (note this includes the --enable-branch-coverage argument as described above):

$ afl-cov -d /path/to/afl-fuzz-output/ --live --coverage-cmd \
"LD_LIBRARY_PATH=./lib/.libs ./bin/.libs/somebin -f AFL_FILE -a -b -c" \
--code-dir . --enable-branch-coverage
[+] Imported 184 files from: /path/to/afl-fuzz-output/queue
[+] AFL file: id:000000,orig:somestr.start (1 / 184), cycle: 0
    lines......: 18.6% (1122 of 6032 lines)
    functions..: 30.7% (100 of 326 functions)
    branches...: 14.0% (570 of 4065 branches)
[+] AFL file: id:000001,orig:somestr256.start (2 / 184), cycle: 2
    lines......: 18.7% (1127 of 6032 lines)
    functions..: 30.7% (100 of 326 functions)
    branches...: 14.1% (572 of 4065 branches)
[+] Coverage diff id:000000,orig:somestr.start id:000001,orig:somestr256.start
    Src file: /path/to/project-gcov/lib/proj_decode.c
      New 'line' coverage: 140
      New 'line' coverage: 141
      New 'line' coverage: 142
    Src file: /path/to/project-gcov/lib/proj_util.c
      New 'line' coverage: 217
      New 'line' coverage: 218
[+] AFL file: id:000002,orig:somestr384.start (3 / 184), cycle: 10
    lines......: 18.8% (1132 of 6032 lines)
    functions..: 30.7% (100 of 326 functions)
    branches...: 14.1% (574 of 4065 branches)
[+] Coverage diff id:000001,orig:somestr256.start id:000002,orig:somestr384.start
    Src file: /path/to/project-gcov/lib/proj_decode.c
      New 'line' coverage: 145
      New 'line' coverage: 146
      New 'line' coverage: 147
    Src file: /path/to/project-gcov/lib/proj_util.c
      New 'line' coverage: 220
      New 'line' coverage: 221
[+] AFL file: id:000003,orig:somestr.start (4 / 184), cycle: 5
    lines......: 18.9% (1141 of 6032 lines)
    functions..: 31.0% (101 of 326 functions)
    branches...: 14.3% (581 of 4065 branches)
[+] Coverage diff id:000002,orig:somestr384.start id:000003,orig:somestr.start
    Src file: /path/to/project-gcov/lib/proj_message.c
      New 'function' coverage: validate_cmd_msg()
      New 'line' coverage: 244
      New 'line' coverage: 247
      New 'line' coverage: 248
      New 'line' coverage: 250
      New 'line' coverage: 255
      New 'line' coverage: 262
      New 'line' coverage: 263
      New 'line' coverage: 266
.
.
.
[+] Coverage diff id:000182,src:000000,op:havoc,rep:64 id:000184,src:000000,op:havoc,rep:4
[+] Processed 184 / 184 files

[+] Final zero coverage report: /path/to/afl-fuzz-output/cov/zero-cov
[+] Final positive coverage report: /path/to/afl-fuzz-output/cov/pos-cov
[+] Final lcov web report: /path/to/afl-fuzz-output/cov/web/lcov-web-final.html

In the last few lines above, the locations of the final web coverage and zero coverage reports are shown. The zero coverage reports contains function names that were never executed across the entire afl-fuzz run.

The code coverage results in /path/to/afl-fuzz-output/cov/web/lcov-web-final represent cumulative code coverage across all AFL test cases. This data can then be reviewed to ensure that all expected functions are indeed exercised by AFL - just point a web browser at /path/to/afl-fuzz-output/cov/web/lcov-web-final.html. Below is a sample of what this report looks like for a cumulative AFL fuzzing run - this is against the fwknop project, and the full report is available here. Note that even though fwknop has a dedicated set of AFL wrappers, it is still difficult to achieve high percentages of code coverage. This provides evidence that measuring code coverage under AFL fuzzing runs is an important aspect of trying to achieve maximal fuzzing results. Every branch/line/function that is not exercised by AFL represents a location for which AFL has not been given the opportunity to find bugs.

Parallelized AFL Execution

With the 0.4 release, afl-cov supports parallelized execution runs of afl-fuzz. All that is required is to point afl-cov -d sync_dir at the top level sync directory that is used by all afl-fuzz instances (afl-fuzz -o sync_dir). The coverage results are calculated globally across all fuzzing instances, and in --live mode new instances will be added to the coverage results as they are created.

Other Examples

The workflow above is probably the main strategy for using afl-cov. However, additional use cases are supported such as:

Here is an example where the first test case that executes the function validate_cmd_msg() is returned (this is after all afl-cov results have been produced in the main workflow above):

$ ./afl-cov -d /path/to/afl-fuzz-output --func-search "validate_cmd_msg"
[+] Function 'validate_cmd_mag()' executed by: id:000002,orig:somestr384.start

An equivalent way of searching the coverage results is to just grep the function from the cov/id-delta-cov file described below. The number "3" in the output below is the AFL cycle number where the function is first executed:

$ grep validate_cmd_msg /path/to/afl-fuzz-output/cov/id-delta-cov
id:000002,orig:somestr384.start, 3, /path/to/project-gcov/file.c, function, validate_cmd_msg()

Directory / File Structure

afl-cov creates a few files and directories for coverage results within the specified afl-fuzz directory (-d). These files and directories are displayed below, and all are contained within the main /path/to/afl-fuzz-output/cov/ directory and <dirname> refers to the top level directory name for the fuzzing instance. When AFL is parallelized, there will be one <dirname> directory path for each afl-fuzz instance.

Usage Information

License

afl-cov is released as open source software under the terms of the GNU General Public License (GPL v2). The latest release can be found at https://github.com/mrash/afl-cov/releases

Contact

All feature requests and bug fixes are managed through github issues tracking. However, you can email me (michael.rash_AT_gmail.com), or reach me through Twitter ([@michaelrash](https://twitter.com/michaelrash)).

afl-cov - AFL Fuzzing Code Coverage

Introduction