| OLD | NEW |
| 1 # Efficient Fuzzer | 1 # Efficient Fuzzer |
| 2 | 2 |
| 3 This document describes ways to determine your fuzzer efficiency and ways | 3 This document describes ways to determine your fuzzer efficiency and ways |
| 4 to improve it. | 4 to improve it. |
| 5 | 5 |
| 6 ## Overview | 6 ## Overview |
| 7 | 7 |
| 8 Being a coverage-driven fuzzer, libFuzzer considers a certain input *interesting
* | 8 Being a coverage-driven fuzzer, libFuzzer considers a certain input *interesting
* |
| 9 if it results in new coverage. The set of all interesting inputs is called | 9 if it results in new coverage. The set of all interesting inputs is called |
| 10 *corpus*. | 10 *corpus*. |
| (...skipping 101 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 112 | 112 |
| 113 ``` | 113 ``` |
| 114 ./out/libfuzzer/my_fuzzer ~/tmp/my_fuzzer_corpus | 114 ./out/libfuzzer/my_fuzzer ~/tmp/my_fuzzer_corpus |
| 115 ``` | 115 ``` |
| 116 | 116 |
| 117 The directory can initially be empty. The fuzzer would store all the interesting | 117 The directory can initially be empty. The fuzzer would store all the interesting |
| 118 items it finds in the directory. You can help the fuzzer by "seeding" the corpus
: | 118 items it finds in the directory. You can help the fuzzer by "seeding" the corpus
: |
| 119 simply copy interesting inputs for your function to the corpus directory before | 119 simply copy interesting inputs for your function to the corpus directory before |
| 120 running. This works especially well for strictly defined file formats or data | 120 running. This works especially well for strictly defined file formats or data |
| 121 transmission protocols. | 121 transmission protocols. |
| 122 |
| 122 * For file-parsing functionality just use some valid files from your test suite. | 123 * For file-parsing functionality just use some valid files from your test suite. |
| 124 |
| 123 * For protocol processing targets put raw streams from test suite into separate | 125 * For protocol processing targets put raw streams from test suite into separate |
| 124 files. | 126 files. |
| 125 | 127 |
| 126 After discovering new and interesting items, [upload corpus to ClusterFuzz]. | 128 |
| 129 ClusterFuzz uses seed corpus stored in Chromium repository. You need to add |
| 130 `seed_corpus` attribute to fuzzer target: |
| 131 |
| 132 ``` |
| 133 fuzzer_test("my_protocol_fuzzer") { |
| 134 ... |
| 135 seed_corpus = "src/fuzz/testcases" |
| 136 ... |
| 137 } |
| 138 ``` |
| 139 |
| 140 If you don't want to store seed corpus in Chromium repository, you can upload |
| 141 corpus to Google Cloud Storage bucket used by ClusterFuzz: |
| 142 |
| 143 |
| 144 1) go to [Corpus GCS Bucket] |
| 145 |
| 146 2) open directory named `%YOUR_FUZZER_NAME%_static` |
| 147 |
| 148 3) upload corpus files into the directory |
| 149 |
| 150 |
| 151 Alternative way is to use `gsutil` tool: |
| 152 ```bash |
| 153 gsutil -m rsync <corpus_dir_on_disk> gs://clusterfuzz-corpus/libfuzzer/%YOUR_FUZ
ZER_NAME%_static |
| 154 ``` |
| 155 |
| 127 | 156 |
| 128 ### Fuzzer Dictionary | 157 ### Fuzzer Dictionary |
| 129 | 158 |
| 130 It is very useful to provide fuzzer a set of common words/values that you expect | 159 It is very useful to provide fuzzer a set of common words/values that you expect |
| 131 to find in the input. This greatly improves efficiency of finding new units and | 160 to find in the input. This greatly improves efficiency of finding new units and |
| 132 works especially well while fuzzing file format decoders. | 161 works especially well while fuzzing file format decoders. |
| 133 | 162 |
| 134 To add a dictionary, first create a dictionary file. | 163 To add a dictionary, first create a dictionary file. |
| 135 Dictionary syntax is similar to that used by [AFL] for its -x option: | 164 Dictionary syntax is similar to that used by [AFL] for its -x option: |
| 136 | 165 |
| (...skipping 46 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 183 "max_len=2048", | 212 "max_len=2048", |
| 184 "use_traces=1", | 213 "use_traces=1", |
| 185 ] | 214 ] |
| 186 } | 215 } |
| 187 ``` | 216 ``` |
| 188 | 217 |
| 189 Please note that `dict` parameter should be provided [separately](#Fuzzer-Dictio
nary). | 218 Please note that `dict` parameter should be provided [separately](#Fuzzer-Dictio
nary). |
| 190 Other options may be passed through `libfuzzer_options` property. | 219 Other options may be passed through `libfuzzer_options` property. |
| 191 | 220 |
| 192 | 221 |
| 193 [ClusterFuzz status]: ./clusterfuzz.md#Status-Links | |
| 194 [upload corpus to ClusterFuzz]: ./clusterfuzz.md#Upload-Corpus | |
| 195 [AFL]: http://lcamtuf.coredump.cx/afl/ | 222 [AFL]: http://lcamtuf.coredump.cx/afl/ |
| 223 [ClusterFuzz status]: clusterfuzz.md#Status-Links |
| 224 [Corpus GCS Bucket]: https://goto.google.com/libfuzzer-clusterfuzz-corpus |
| OLD | NEW |