1 # INTRODUCTION # 2 3 This document describes the **honggfuzz** project. 4 5 # OBJECTIVE # 6 7 Honggfuzz is a security oriented, feedback-driven, evolutionary, easy-to-use fuzzer with interesting analysis options. 8 9 # FEATURES # 10 11 * It's __multi-threaded__ and __multi-process__: no need to run multiple copies of your fuzzer, as honggfuzz can unlock potential of all your available CPU cores. The file corpus is shared between threads (and 12 fuzzed instances) 13 * It's blazingly fast (specifically in the [persistent fuzzing mode](https://github.com/google/honggfuzz/blob/master/docs/PersistentFuzzing.md)). A simple _LLVMFuzzerTestOneInput_ function can be tested with __up to 1 14 mo iterations per second__ on a relatively modern CPU (e.g. i7-6600K) 15 * Has a nice track record of uncovered security bugs: e.g. the __only__ (to the date) __vulnerability in OpenSSL with the [critical](https://www.openssl.org/news/secadv/20160926.txt) score mark__ was discovered by honggfuzz 16 * Uses low-level interfaces to monitor processes (e.g. _ptrace_ under Linux and NetBSD). As opposed to other fuzzers, it __will discover and report hidden signals__ (caught and potentially hidden by signal handlers) 17 * Easy-to-use, feed it a simple input corpus (__can even consist of a single, 1-byte file__) and it will work its way up expanding it utilizing feedback-based coverage metrics 18 * Supports several (more than any other coverage-based feedback-driven fuzzer) hardware-based (CPU: branch/instruction counting, __Intel BTS__, __Intel PT__) and software-based [feedback-driven fuzzing](https://github.com/google/honggfuzz/blob/master/docs/FeedbackDrivenFuzzing.md) methods known from other fuzzers (libfuzzer, afl) 19 * Works (at least) under GNU/Linux, FreeBSD, NetBSD, Mac OS X, Windows/CygWin and [Android](https://github.com/google/honggfuzz/blob/master/docs/Android.md) 20 * Supports __persistent fuzzing mode__ (long-lived process calling a fuzzed API repeatedly) with libhfuzz/libhfuzz.a. More on that can be found [here](https://github.com/google/honggfuzz/blob/master/docs/PersistentFuzzing.md) 21 * It comes with the __[examples](https://github.com/google/honggfuzz/tree/master/examples) directory__, consisting of real world fuzz setups for widely-used software (e.g. Apache and OpenSSL) 22 23 # REQUIREMENTS # 24 25 * A POSIX compliant operating system, [Android](https://github.com/google/honggfuzz/blob/master/docs/Android.md) or Windows (CygWin) 26 * GNU/Linux with modern kernel (>= v4.2) for hardware-based code coverage guided fuzzing 27 * A corpus of input files. Honggfuzz expects a set of files to use and modify as input to the application you're fuzzing. How you get or create these files is up to you, but you might be interested in the following sources: 28 * Image formats: Tavis Ormandy's [Image Testuite](http://code.google.com/p/imagetestsuite/) has been effective at finding vulnerabilities in various graphics libraries. 29 * PDF: Adobe provides some [test PDF files](http://acroeng.adobe.com/). 30 31 _**Note**: With the feedback-driven coverage-based modes, you can start your fuzzing with even a single 1-byte file._ 32 33 ## Compatibility list ## 34 35 It should work under the following operating systems: 36 37 | **OS** | **Status** | **Notes** | 38 |:-------|:-----------|:----------| 39 | **GNU/Linux** | Works | ptrace() API (x86, x86-64 disassembly support)| 40 | **FreeBSD** | Works | POSIX signal interface | 41 | **NetBSD** | Works | ptrace() API (x86, x86-64 disassembly support)| 42 | **Mac OS X** | Works | POSIX signal interface/Mac OS X crash reports (x86-64/x86 disassembly support) | 43 | **Android** | Works | ptrace() API (x86, x86-64 disassembly support) | 44 | **MS Windows** | Works | POSIX signal interface via CygWin | 45 | **Other Unices** | Depends`*` | POSIX signal interface | 46 47 _`*`) It might work provided that a given operating system implements **wait4()** call_ 48 49 # USAGE # 50 51 ```shell 52 Usage: ./honggfuzz [options] -- path_to_command [args] 53 Options: 54 --help|-h 55 Help plz.. 56 --input|-f VALUE 57 Path to a directory containing initial file corpus 58 --persistent|-P 59 Enable persistent fuzzing (use hfuzz_cc/hfuzz-clang to compile code) 60 --instrument|-z 61 *DEFAULT-MODE-BY-DEFAULT* Enable compile-time instrumentation (use hfuzz_cc/hfuzz-clang to compile code) 62 --noinst|-x 63 Static mode (dry-mode), disable any instrumentation (hw/sw) 64 --keep_output|-Q 65 Don't close children's stdin, stdout, stderr; can be noisy 66 --timeout|-t VALUE 67 Timeout in seconds (default: '10') 68 --threads|-n VALUE 69 Number of concurrent fuzzing threads (default: number of CPUs / 2) 70 --stdin_input|-s 71 Provide fuzzing input on STDIN, instead of ___FILE___ 72 --mutations_per_run|-r VALUE 73 Maximal number of mutations per one run (default: '6') 74 --logfile|-l VALUE 75 Log file 76 --verbose|-v 77 Disable ANSI console; use simple log output 78 --verifier|-V 79 Enable crashes verifier 80 --debug_level|-d VALUE 81 Debug level (0 - FATAL ... 4 - DEBUG), (default: '3' [INFO]) 82 --extension|-e VALUE 83 Input file extension (e.g. 'swf'), (default: 'fuzz') 84 --workspace|-W VALUE 85 Workspace directory to save crashes & runtime files (default: '.') 86 --covdir VALUE 87 New coverage is written to a separate directory (default: use the input directory) 88 --dict|-w VALUE 89 Dictionary file. Format:http://llvm.org/docs/LibFuzzer.html#dictionaries 90 --stackhash_bl|-B VALUE 91 Stackhashes blacklist file (one entry per line) 92 --mutate_cmd|-c VALUE 93 External command producing fuzz files (instead of internal mutators) 94 --pprocess_cmd VALUE 95 External command postprocessing files produced by internal mutators 96 --run_time VALUE 97 Number of seconds this fuzzing session will last (default: '0' [no limit]) 98 --iterations|-N VALUE 99 Number of fuzzing iterations (default: '0' [no limit]) 100 --rlimit_as VALUE 101 Per process RLIMIT_AS in MiB (default: '0' [no limit]) 102 --rlimit_rss VALUE 103 Per process RLIMIT_RSS in MiB (default: '0' [no limit]) 104 --rlimit_data VALUE 105 Per process RLIMIT_DATA in MiB (default: '0' [no limit]) 106 --report|-R VALUE 107 Write report to this file (default: 'HONGGFUZZ.REPORT.TXT') 108 --max_file_size|-F VALUE 109 Maximal size of files processed by the fuzzer in bytes (default: '1048576') 110 --clear_env 111 Clear all environment variables before executing the binary 112 --env|-E VALUE 113 Pass this environment variable, can be used multiple times 114 --save_all|-u 115 Save all test-cases (not only the unique ones) by appending the current time-stamp to the filenames 116 --tmout_sigvtalrm|-T 117 Use SIGVTALRM to kill timeouting processes (default: use SIGKILL) 118 --sanitizers|-S 119 Enable sanitizers settings (default: false) 120 --monitor_sigabrt VALUE 121 Monitor SIGABRT (default: 'false for Android - 'true for other platforms) 122 --no_fb_timeout VALUE 123 Skip feedback if the process has timeouted (default: 'false') 124 --exit_upon_crash 125 Exit upon seeing the first crash (default: 'false') 126 --linux_symbols_bl VALUE 127 Symbols blacklist filter file (one entry per line) 128 --linux_symbols_wl VALUE 129 Symbols whitelist filter file (one entry per line) 130 --linux_pid|-p VALUE 131 Attach to a pid (and its thread group) 132 --linux_file_pid VALUE 133 Attach to pid (and its thread group) read from file 134 --linux_addr_low_limit VALUE 135 Address limit (from si.si_addr) below which crashes are not reported, (default: '0') 136 --linux_keep_aslr 137 Don't disable ASLR randomization, might be useful with MSAN 138 --linux_perf_ignore_above VALUE 139 Ignore perf events which report IPs above this address 140 --linux_perf_instr 141 Use PERF_COUNT_HW_INSTRUCTIONS perf 142 --linux_perf_branch 143 Use PERF_COUNT_HW_BRANCH_INSTRUCTIONS perf 144 --linux_perf_bts_edge 145 Use Intel BTS to count unique edges 146 --linux_perf_ipt_block 147 Use Intel Processor Trace to count unique blocks (requires libipt.so) 148 --linux_perf_kernel_only 149 Gather kernel-only coverage with Intel PT and with Intel BTS 150 --linux_ns_net 151 Use Linux NET namespace isolation 152 --linux_ns_pid 153 Use Linux PID namespace isolation 154 --linux_ns_ipc 155 Use Linux IPC namespace isolation 156 --netbsd_symbols_bl VALUE 157 Symbols blacklist filter file (one entry per line) 158 --netbsd_symbols_wl VALUE 159 Symbols whitelist filter file (one entry per line) 160 --netbsd_pid|-p VALUE 161 Attach to a pid (and its thread group) 162 --netbsd_file_pid VALUE 163 Attach to pid (and its thread group) read from file 164 --netbsd_addr_low_limit VALUE 165 Address limit (from si.si_addr) below which crashes are not reported, (default: '0') 166 167 Examples: 168 Run the binary over a mutated file chosen from the directory. Disable fuzzing feedback (dry/static mode) 169 honggfuzz -f input_dir -x -- /usr/bin/djpeg ___FILE___ 170 As above, provide input over STDIN: 171 honggfuzz -f input_dir -x -s -- /usr/bin/djpeg 172 Use compile-time instrumentation (libhfuzz/instrument.c): 173 honggfuzz -f input_dir -- /usr/bin/djpeg ___FILE___ 174 Use persistent mode (libhfuzz/persistent.c) w/o instrumentation: 175 honggfuzz -f input_dir -P -x -- /usr/bin/djpeg_persistent_mode 176 Use persistent mode (libhfuzz/persistent.c) and compile-time instrumentation: 177 honggfuzz -f input_dir -P -- /usr/bin/djpeg_persistent_mode 178 Run the binary with dynamically generate inputs, maximize total no. of instructions: 179 honggfuzz --linux_perf_instr -- /usr/bin/djpeg ___FILE___ 180 As above, maximize total no. of branches: 181 honggfuzz --linux_perf_branch -- /usr/bin/djpeg ___FILE___ 182 As above, maximize unique branches (edges) via Intel BTS: 183 honggfuzz --linux_perf_bts_edge -- /usr/bin/djpeg ___FILE___ 184 As above, maximize unique code blocks via Intel Processor Trace (requires libipt.so): 185 honggfuzz --linux_perf_ipt_block -- /usr/bin/djpeg ___FILE___ 186 ``` 187 188 # OUTPUT FILES # 189 190 | **Mode** | **Output file** | 191 |:---------|:----------------| 192 | Linux,NetBSD | **SIGSEGV.PC.4ba1ae.STACK.13599d485.CODE.1.ADDR.0x10.INSTR.mov____0x10(%rbx),%rax.fuzz** | 193 | POSIX signal interface | **SIGSEGV.22758.2010-07-01.17.24.41.tif** | 194 195 ## Description ## 196 197 * **SIGSEGV**,**SIGILL**,**SIGBUS**,**SIGABRT**,**SIGFPE** - Description of the signal which terminated the process (when using ptrace() API, it's a signal which was delivered to the process, even if silently discarded) 198 * **PC.0x8056ad7** - Program Counter (PC) value (ptrace() API only), for x86 it's a value of the EIP register (RIP for x86-64) 199 * **STACK.13599d485** - Stack signature (based on stack-tracing) 200 * **ADDR.0x30333037** - Value of the _siginfo`_`t.si`_`addr_ (see _man 2 signaction_ for more details) (most likely meaningless for SIGABRT) 201 * **INSTR.mov____0x10(%rbx),%rax`** - Disassembled instruction which was found under the last known PC (Program Counter) (x86, x86-64 architectures only, meaningless for SIGABRT) 202 203 # FAQ # 204 205 * Q: **Why the name _honggfuzz_**? 206 * A: The term honggfuzz was coined during a major and memorable event in the city of [Zurich](http://en.wikipedia.org/wiki/H%C3%B6ngg), where a Welsh security celebrity tried to reach Hngg in a cab while singing _[Another one bites the dust](https://en.wikipedia.org/wiki/Another_One_Bites_the_Dust)_. 207 208 * Q: **Why do you prefer the ptrace() API to the POSIX signal interface**? 209 * A: The ptrace() API is more flexible when it comes to analyzing a process' crash. wait3/4() syscalls are only able to determine the type of signal which crashed an application and limited resource usage information (see _man wait4_). 210 211 * Q: **Why isn't there any support for the ptrace() API when compiling under FreeBSD or Mac OS X operating systems**? 212 * A: These operating systems lack some specific ptrace() operations, including **PT`_`GETREGS** (Mac OS X) and **PT`_`GETSIGINFO**, both of which honggfuzz depends on. If you have any ideas on how to get around this limitation, send us an email or patch. 213 214 # LICENSE # 215 216 This project is licensed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0) 217 218 # CREDITS # 219 220 * Thanks to **[taviso (a] google.com Tavis Ormandy]** for many valuable ideas used in the course of this project's design and implementation phases 221 * Thanks to my 1337 friends for all sorts of support and distraction :) - **LiquidK, lcamtuf, novocainated, asiraP, ScaryBeasts, redpig, jln** 222
