INTRODUCTION
This document describes the honggfuzz project.
OBJECTIVE
Honggfuzz is a general-purpose fuzzing tool. Given an input corpus files, honggfuzz modifies input to a test program and utilize the ptrace() API/POSIX signal interface to detect and log crashes. It can also use software or hardware-based code coverage techniques to produce more and more interesting inputs
FEATURES
- It's multi-threaded and multi-process: no need to run multiple copies of your fuzzer. The file corpus is shared between threads (and fuzzed instances)
- It's blazingly fast (esp. in the persistent fuzzing mode). A simple LLVMFuzzerTestOneInput function can be tested with up to 1mo iterations per second on a relatively modern CPU (e.g. i7-6600K)
- Has a nice track record of uncovered security bugs: e.g. the only (to the date) vulnerability in OpenSSL with the critical score mark was discovered by honggfuzz
- Uses low-level interfaces to monitor processes (e.g. ptrace under Linux). As opposed to other fuzzers, it will discover and report hidden signals (caught and potentially hidden by signal handlers)
- 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
- 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 methods
- Works (at least) under GNU/Linux, FreeBSD, Mac OS X, Windows/CygWin and Android
- Supports persistent fuzzing mode (long-lived process calling a fuzzed API repeatedly) with libhfuzz/libhfuzz.a. More on that can be found here
- Can fuzz remote/standalone long-lasting processes (e.g. network servers like Apache's httpd and ISC's bind)
- It comes with the examples directory, consisting of real world fuzz setups for widely-used software (e.g. Apache and OpenSSL)
REQUIREMENTS
A POSIX compliant operating system, Android or Windows (CygWin)
GNU/Linux with modern kernel (>= v4.2) for hardware-based code coverage guided fuzzing
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:
- Image formats: Tavis Ormandy's Image Testuite has been effective at finding vulnerabilities in various graphics libraries.
- PDF: Adobe provides some test PDF files.
Note: With the feedback-driven coverage-based modes, you can start your fuzzing with even a single 1-byte file.
Compatibility list
It should work under the following operating systems:
| OS | Status | Notes |
|---|
| GNU/Linux | Works | ptrace() API (x86, x86-64 disassembly support) |
| FreeBSD | Works | POSIX signal interface |
| Mac OS X | Works | POSIX signal interface/Mac OS X crash reports (x86-64/x86 disassembly support) |
| Android | Works | ptrace() API (x86, x86-64 disassembly support) |
| MS Windows | Works | POSIX signal interface via CygWin |
| Other Unices | Depends* | POSIX signal interface |
*) It might work provided that a given operating system implements wait4() call
USAGE
OUTPUT FILES
| Mode | Output file |
|---|
| Linux | SIGSEGV.PC.4ba1ae.STACK.13599d485.CODE.1.ADDR.0x10.INSTR.mov____0x10(%rbx),%rax.fuzz |
| POSIX signal interface | SIGSEGV.22758.2010-07-01.17.24.41.tif |
Description
- 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)
- PC.0x8056ad7 - Program Counter (PC) value (ptrace() API only), for x86 it's a value of the EIP register (RIP for x86-64)
- STACK.13599d485 - Stack signature (based on stack-tracing)
- ADDR.0x30333037 - Value of the siginfo
_t.si_addr (see man 2 signaction for more details) (most likely meaningless for SIGABRT) - 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)
FAQ
Q: Why the name honggfuzz?
A: The term honggfuzz was coined during a major and memorable event in the city of Zurich, where a Welsh security celebrity tried to reach Höngg in a cab while singing Another one bites the dust.
Q: Why do you prefer the ptrace() API to the POSIX signal interface?
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).
Q: Why isn't there any support for the ptrace() API when compiling under FreeBSD or Mac OS X operating systems?
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.
LICENSE
This project is licensed under the Apache License, Version 2.0
CREDITS
- Thanks to [taviso@google.com Tavis Ormandy] for many valuable ideas used in the course of this project's design and implementation phases
- Thanks to my 1337 friends for all sorts of support and distraction :) - LiquidK, lcamtuf, novocainated, asiraP, ScaryBeasts, redpig, jln