1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>Chapter 23 Fuzzing with afl-fuzz</title>
</head>
<body>
<a href="spacetime.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="instrumented-runtime.html"><img src="next_motif.svg" alt="Next"></a>
<hr>
<h1 class="chapter" id="sec555">Chapter 23 Fuzzing with afl-fuzz</h1>
<ul>
<li><a href="afl-fuzz.html#s%3Aafl-overview">23.1 Overview</a>
</li><li><a href="afl-fuzz.html#s%3Aafl-generate">23.2 Generating instrumentation</a>
</li><li><a href="afl-fuzz.html#s%3Aafl-example">23.3 Example</a>
</li></ul>
<h2 class="section" id="s:afl-overview"><a class="section-anchor" href="#s:afl-overview" aria-hidden="true"></a>23.1 Overview</h2>
<p>American fuzzy lop (“afl-fuzz”) is a <em>fuzzer</em>, a tool for
testing software by providing randomly-generated inputs, searching for
those inputs which cause the program to crash.</p><p>Unlike most fuzzers, afl-fuzz observes the internal behaviour of the
program being tested, and adjusts the test cases it generates to
trigger unexplored execution paths. As a result, test cases generated
by afl-fuzz cover more of the possible behaviours of the tested
program than other fuzzers.</p><p>This requires that programs to be tested are instrumented to
communicate with afl-fuzz. The native-code compiler “ocamlopt” can
generate such instrumentation, allowing afl-fuzz to be used against
programs written in OCaml.</p><p>For more information on afl-fuzz, see the website at
<a href="http://lcamtuf.coredump.cx/afl/">http://lcamtuf.coredump.cx/afl/</a>.
</p>
<h2 class="section" id="s:afl-generate"><a class="section-anchor" href="#s:afl-generate" aria-hidden="true"></a>23.2 Generating instrumentation</h2>
<p>The instrumentation that afl-fuzz requires is not generated by
default, and must be explicitly enabled, by passing the <span class="c003">-afl-instrument</span> option to <span class="c003">ocamlopt</span>.</p><p>To fuzz a large system without modifying build tools, OCaml’s <span class="c003">configure</span> script also accepts the <span class="c003">afl-instrument</span> option. If
OCaml is configured with <span class="c003">afl-instrument</span>, then all programs
compiled by <span class="c003">ocamlopt</span> will be instrumented.</p>
<h3 class="subsection" id="ss:afl-advanced"><a class="section-anchor" href="#ss:afl-advanced" aria-hidden="true"></a>23.2.1 Advanced options</h3>
<p>In rare cases, it is useful to control the amount of instrumentation
generated. By passing the <span class="c003">-afl-inst-ratio N</span> argument to <span class="c003">ocamlopt</span> with <span class="c003">N</span> less than 100, instrumentation can be
generated for only N% of branches. (See the afl-fuzz documentation on
the parameter <span class="c003">AFL_INST_RATIO</span> for the precise effect of this).</p>
<h2 class="section" id="s:afl-example"><a class="section-anchor" href="#s:afl-example" aria-hidden="true"></a>23.3 Example</h2>
<p>As an example, we fuzz-test the following program, <span class="c003">readline.ml</span>:</p><pre>let _ =
let s = read_line () in
match Array.to_list (Array.init (String.length s) (String.get s)) with
['s'; 'e'; 'c'; 'r'; 'e'; 't'; ' '; 'c'; 'o'; 'd'; 'e'] -> failwith "uh oh"
| _ -> ()
</pre><p>
There is a single input (the string “secret code”) which causes this
program to crash, but finding it by blind random search is infeasible.</p><p>Instead, we compile with afl-fuzz instrumentation enabled:
</p><pre>ocamlopt -afl-instrument readline.ml -o readline
</pre><p>Next, we run the program under afl-fuzz:
</p><pre>mkdir input
echo asdf > input/testcase
mkdir output
afl-fuzz -i input -o output ./readline
</pre><p>By inspecting instrumentation output, the fuzzer finds the crashing input quickly.
</p>
<hr>
<a href="spacetime.html"><img src="previous_motif.svg" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.svg" alt="Up"></a>
<a href="instrumented-runtime.html"><img src="next_motif.svg" alt="Next"></a>
</body>
</html>
|
