Skip to content

Latest commit

 

History

History
281 lines (241 loc) · 12 KB

USAGE.md

File metadata and controls

281 lines (241 loc) · 12 KB
Raw

REQUIREMENTS

  • A POSIX compliant operating system, MacOSX, Android or Windows (CygWin)
  • GNU/Linux with modern kernel (>= v4.2) for hardware-based code coverage guided fuzzing (intel PT, Intel BTS, instruction/branch counting)
  • An input corpus: You might be interested in the following for some common file formats:
    • Image formats: Tavis Ormandy's Image Testsuite 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 without the input corpus.

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
OpenBSD Works POSIX signal interface
NetBSD Works ptrace() API (x86, x86-64 disassembly support)
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 Maybe POSIX signal interface

USAGE

Non-persistent fuzzing w/o instrumentation (-x)

Input as a file (___FILE___)

honggfuzz -i input_dir -x -- /usr/bin/djpeg ___FILE___

Input on FD=0/STDIN (-s/--stdin_input)

honggfuzz -i input_dir -x -s -- /usr/bin/djpeg

Non-persistent fuzzing with instrumentation

Compile-time instrumentation (-z/--instrument). Note: it is enabled by default

  honggfuzz -i input_dir -z -- instrumented.djpeg ___FILE___

QEMU-mode (black-box instrumentation)

honggfuzz -i input_dir -- <honggfuzz_dir>/qemu_mode/honggfuzz-qemu/x86_64-linux-user/qemu-x86_64 /usr/bin/djpeg ___FILE___

Various hardware-based mechanisms/counters

  honggfuzz -i input_dir --linux_perf_bts_edge -- /usr/bin/djpeg ___FILE___
  honggfuzz -i input_dir --linux_perf_ipt_block -- /usr/bin/djpeg ___FILE___
  honggfuzz -i input_dir --linux_perf_instr -- /usr/bin/djpeg ___FILE___
  honggfuzz -i input_dir --linux_perf_branch -- /usr/bin/djpeg ___FILE___

Persistent-mode (-P). Note: it will be auto-detected

  honggfuzz -i input_dir -z -P -- jpeg_persistent_mode
  honggfuzz -i input_dir --linux_perf_bts_edge -P -- jpeg_persistent_mode
  honggfuzz -i input_dir --linux_perf_ipt_block -P -- jpeg_persistent_mode
  honggfuzz -i input_dir --linux_perf_branch -P -- jpeg_persistent_mode
  honggfuzz -i input_dir --linux_perf_instr -P -- jpeg_persistent_mode

but also a couple of instrumentation mechanisms used together

honggfuzz -i input_dir --linux_perf_bts_edge --linux_perf_instr -P -- jpeg_persistent_mode

Corpus Minimization (-M)

Minimize corpus directly inside the input (-i/--input) directory

honggfuzz -i input_dir -P -M -- jpeg_persistent_mode

or

honggfuzz -i input_dir -M -- instrumented.djpeg ___FILE___

Save minimized corpus to the output (--output) directory

honggfuzz -i input_dir --output output_dir -P -M -- jpeg_persistent_mode

or

honggfuzz -i input_dir --output output_dir -M -- instrumented.djpeg ___FILE___

CMDLINE --help

Usage: ./honggfuzz [options] -- path_to_command [args]
Options:
 --help|-h 
	Help plz..
 --input|-i VALUE
	Path to a directory containing initial file corpus
 --output VALUE
	Output data (new dynamic coverage corpus, or the minimized coverage corpus) is written to this directory (default: input directory is used)
 --persistent|-P 
	Enable persistent fuzzing (use hfuzz_cc/hfuzz-clang to compile code). This will be auto-detected!!!
 --instrument|-z 
	*DEFAULT-MODE-BY-DEFAULT* Enable compile-time instrumentation (use hfuzz_cc/hfuzz-clang to compile code)
 --minimize|-M 
	Minimize the input corpus. It will most likely delete some corpus files (from the --input directory) if no --output is used!
 --noinst|-x 
	Static mode only, disable any instrumentation (hw/sw) feedback
 --keep_output|-Q 
	Don't close children's stdin, stdout, stderr; can be noisy
 --timeout|-t VALUE
	Timeout in seconds (default: 10)
 --threads|-n VALUE
	Number of concurrent fuzzing threads (default: number of CPUs / 2)
 --stdin_input|-s 
	Provide fuzzing input on STDIN, instead of ___FILE___
 --mutations_per_run|-r VALUE
	Maximal number of mutations per one run (default: 6)
 --logfile|-l VALUE
	Log file
 --verbose|-v 
	Disable ANSI console; use simple log output
 --verifier|-V 
	Enable crashes verifier
 --debug|-d 
	Show debug messages (level >= 4)
 --quiet|-q 
	Show only warnings and more serious messages (level <= 1)
 --extension|-e VALUE
	Input file extension (e.g. 'swf'), (default: 'fuzz')
 --workspace|-W VALUE
	Workspace directory to save crashes & runtime files (default: '.')
 --crashdir VALUE
	Directory where crashes are saved to (default: workspace directory)
 --covdir_all VALUE
	** DEPRECATED ** use --output
 --covdir_new VALUE
	New coverage (beyond the dry-run fuzzing phase) is written to this separate directory
 --dict|-w VALUE
	Dictionary file. Format:http://llvm.org/docs/LibFuzzer.html#dictionaries
 --stackhash_bl|-B VALUE
	Stackhashes blacklist file (one entry per line)
 --mutate_cmd|-c VALUE
	External command producing fuzz files (instead of internal mutators)
 --pprocess_cmd VALUE
	External command postprocessing files produced by internal mutators
 --ffmutate_cmd VALUE
	External command mutating files which have effective coverage feedback
 --run_time VALUE
	Number of seconds this fuzzing session will last (default: 0 [no limit])
 --iterations|-N VALUE
	Number of fuzzing iterations (default: 0 [no limit])
 --rlimit_as VALUE
	Per process RLIMIT_AS in MiB (default: 0 [no limit])
 --rlimit_rss VALUE
	Per process RLIMIT_RSS in MiB (default: 0 [no limit]). It will also set *SAN's soft_rss_limit_mb if used
 --rlimit_data VALUE
	Per process RLIMIT_DATA in MiB (default: 0 [no limit])
 --rlimit_core VALUE
	Per process RLIMIT_CORE in MiB (default: 0 [no cores are produced])
 --report|-R VALUE
	Write report to this file (default: '<workdir>/HONGGFUZZ.REPORT.TXT')
 --max_file_size|-F VALUE
	Maximal size of files processed by the fuzzer in bytes (default: 1048576 = 1MB)
 --clear_env 
	Clear all environment variables before executing the binary
 --env|-E VALUE
	Pass this environment variable, can be used multiple times
 --save_all|-u 
	Save all test-cases (not only the unique ones) by appending the current time-stamp to the filenames
 --save_smaller|-U
    Save smaller test-cases, renaming first found with .orig suffix
 --tmout_sigvtalrm|-T 
	Use SIGVTALRM to kill timeouting processes (default: use SIGKILL)
 --sanitizers|-S 
	Enable sanitizers settings (default: false)
 --monitor_sigabrt VALUE
	Monitor SIGABRT (default: false for Android, true for other platforms)
 --no_fb_timeout VALUE
	Skip feedback if the process has timeouted (default: false)
 --exit_upon_crash 
	Exit upon seeing the first crash (default: false)
 --socket_fuzzer 
	Instrument external fuzzer via socket
 --netdriver 
	Use netdriver (libhfnetdriver/). In most cases it will be autodetected through a binary signature
 --only_printable 
	Only generate printable inputs
 --linux_symbols_bl VALUE
	Symbols blacklist filter file (one entry per line)
 --linux_symbols_wl VALUE
	Symbols whitelist filter file (one entry per line)
 --linux_addr_low_limit VALUE
	Address limit (from si.si_addr) below which crashes are not reported, (default: 0)
 --linux_keep_aslr 
	Don't disable ASLR randomization, might be useful with MSAN
 --linux_perf_ignore_above VALUE
	Ignore perf events which report IPs above this address
 --linux_perf_instr 
	Use PERF_COUNT_HW_INSTRUCTIONS perf
 --linux_perf_branch 
	Use PERF_COUNT_HW_BRANCH_INSTRUCTIONS perf
 --linux_perf_bts_edge 
	Use Intel BTS to count unique edges
 --linux_perf_ipt_block 
	Use Intel Processor Trace to count unique blocks (requires libipt.so)
 --linux_perf_kernel_only 
	Gather kernel-only coverage with Intel PT and with Intel BTS
 --linux_ns_net 
	Use Linux NET namespace isolation
 --linux_ns_pid 
	Use Linux PID namespace isolation
 --linux_ns_ipc 
	Use Linux IPC namespace isolation

Examples:
 Run the binary over a mutated file chosen from the directory. Disable fuzzing feedback (static mode):
  honggfuzz -i input_dir -x -- /usr/bin/djpeg ___FILE___
 As above, provide input over STDIN:
  honggfuzz -i input_dir -x -s -- /usr/bin/djpeg
 Use compile-time instrumentation (-fsanitize-coverage=trace-pc-guard,...):
  honggfuzz -i input_dir -- /usr/bin/djpeg ___FILE___
 Use persistent mode w/o instrumentation:
  honggfuzz -i input_dir -P -x -- /usr/bin/djpeg_persistent_mode
 Use persistent mode and compile-time (-fsanitize-coverage=trace-pc-guard,...) instrumentation:
  honggfuzz -i input_dir -P -- /usr/bin/djpeg_persistent_mode
 Run the binary with dynamically generate inputs, maximize total no. of instructions:
  honggfuzz --linux_perf_instr -- /usr/bin/djpeg ___FILE___
 As above, maximize total no. of branches:
  honggfuzz --linux_perf_branch -- /usr/bin/djpeg ___FILE___
 As above, maximize unique branches (edges) via Intel BTS:
  honggfuzz --linux_perf_bts_edge -- /usr/bin/djpeg ___FILE___
 As above, maximize unique code blocks via Intel Processor Trace (requires libipt.so):
  honggfuzz --linux_perf_ipt_block -- /usr/bin/djpeg ___FILE___

OUTPUT FILES

Mode Output file
Linux,NetBSD 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