386 lines
16 KiB
Groff
386 lines
16 KiB
Groff
.TH zzuf 1 "2006-12-22" "zzuf"
|
|
.SH NAME
|
|
zzuf \- multiple purpose fuzzer
|
|
.SH SYNOPSIS
|
|
\fBzzuf\fR [\fB\-AcdimnqSvx\fR] [\fB\-s\fR \fIseed\fR|\fB\-s\fR \fIstart:stop\fR] [\fB\-r\fR \fIratio\fR|\fB\-r\fR \fImin:max\fR]
|
|
.br
|
|
[\fB\-D\fR \fIdelay\fR] [\fB\-F\fR \fIforks\fR] [\fB\-C\fR \fIcrashes\fR] [\fB\-B\fR \fIbytes\fR] [\fB\-T\fR \fIseconds\fR]
|
|
.br
|
|
[\fB\-M\fR \fImegabytes\fR] [\fB\-b\fR \fIranges\fR] [\fB\-P\fR \fIprotect\fR] [\fB\-R\fR \fIrefuse\fR]
|
|
.br
|
|
[\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] [\fIPROGRAM\fR [\fB\-\-\fR] [\fIARGS\fR]...]
|
|
.br
|
|
\fBzzuf \-h\fR | \fB\-\-help\fR
|
|
.br
|
|
\fBzzuf \-V\fR | \fB\-\-version\fR
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\fBzzuf\fR is a transparent application input fuzzer. It works by intercepting
|
|
file and network operations and changing random bits in the program's input.
|
|
\fBzzuf\fR's behaviour is deterministic, making it easy to reproduce bugs.
|
|
.SH USAGE
|
|
.PP
|
|
\fBzzuf\fR will run an application specified on its command line, one or
|
|
several times, with optional arguments, and will report the application's
|
|
relevant behaviour on the standard error channel, eg:
|
|
.PP
|
|
\fB zzuf cat /dev/zero\fR
|
|
.PP
|
|
If you want to specify flags for your application, put a \(oq\fB\-\-\fR\(cq
|
|
marker before them on the command line (otherwise \fBzzuf\fR will try to
|
|
interpret them as arguments for itself), eg:
|
|
.PP
|
|
\fB zzuf \-B 1000 cat \-\- \-v /dev/zero\fR
|
|
.PP
|
|
When no program is specified, \fBzzuf\fR simply fuzzes the standard input, as
|
|
if the \fBcat\fR utility had been called:
|
|
.PP
|
|
\fB zzuf < /dev/zero\fR
|
|
.SH OPTIONS
|
|
.TP
|
|
\fB\-A\fR, \fB\-\-autoinc\fR
|
|
Increment random seed each time a new file is opened. This is only required
|
|
if one instance of the application is expected to open the same file several
|
|
times and you want to test a different seed each time.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-bytes\fR=\fIranges\fR
|
|
Restrict fuzzing to bytes whose offsets in the file are within \fIranges\fR.
|
|
|
|
Range values start at zero and are inclusive. Use dashes between range values
|
|
and commas between ranges. If the right-hand part of a range is ommited, it
|
|
means end of file. For instance, to restrict fuzzing to bytes 0, 3, 4, 5 and
|
|
all bytes after offset 31, use \(oq\fB\-r0,3-5,31-\fR\(cq.
|
|
|
|
This option is useful to preserve file headers or corrupt only a specific
|
|
portion of a file.
|
|
.TP
|
|
\fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR
|
|
Automatically terminate child processes that output more than \fIn\fR bytes
|
|
on the standard output and standard error channels. This is useful to detect
|
|
infinite loops. See also the \fB\-T\fR flag.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-cmdline\fR
|
|
Only fuzz files whose name is specified in the target application's command
|
|
line. This is mostly a shortcut to avoid specifying twice the argument:
|
|
|
|
\fB zzuf \-c cat file.txt\fR
|
|
|
|
has the same effect as
|
|
|
|
\fB zzuf \-I \(aq^file\\.txt$\(aq cat file.txt\fR
|
|
|
|
See the \fB\-I\fR flag for more information on restricting fuzzing to
|
|
specific files.
|
|
.TP
|
|
\fB\-C\fR, \fB\-\-max\-crashes\fR=\fIn\fR
|
|
Stop forking when at least \fIn\fR children have crashed. The default value
|
|
is 1, meaning \fBzzuf\fR will stop as soon as one child has crashed. A process
|
|
is considered to have crashed if any signal (such as, but not limited to,
|
|
\fBSIGSEGV\fR) caused it to exit. If the \fB\-x\fR flag is used, this will
|
|
also include processes that exit with a non-zero status.
|
|
|
|
This option is only relevant if the \fB\-s\fR flag is used with a range
|
|
argument.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-debug\fR
|
|
Activate the display of debug messages.
|
|
.TP
|
|
\fB\-D\fR, \fB\-\-delay\fR=\fIdelay\fR
|
|
Do not launch more than one process every \fIdelay\fR seconds. This option
|
|
should be used together with \fB\-F\fR to avoid fork bombs.
|
|
.TP
|
|
\fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR
|
|
Do not fuzz files whose name matches the \fIregex\fR regular expression. This
|
|
option supersedes anything that is specified by the \fB\-I\fR flag. Use this
|
|
for instance if you are unsure of what files your application is going to read
|
|
and do not want it to fuzz files in the \fB/etc\fR directory.
|
|
|
|
Multiple \fB\-E\fR flags can be specified, in which case files matching any one
|
|
of the regular expressions will be ignored.
|
|
.TP
|
|
\fB\-F\fR, \fB\-\-max\-forks\fR=\fIforks\fR
|
|
Specify the number of simultaneous children that can be run.
|
|
|
|
This option is only relevant if the \fB\-s\fR flag is used with a range
|
|
argument. See also the \fB\-D\fR flag.
|
|
.TP
|
|
\fB\-i\fR, \fB\-\-stdin\fR
|
|
Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files.
|
|
.TP
|
|
\fB\-I\fR, \fB\-\-include\fR=\fIregex\fR
|
|
Only fuzz files whose name matches the \fIregex\fR regular expression. Use
|
|
this for instance if your application reads configuration files at startup
|
|
and you only want specific files to be fuzzed.
|
|
|
|
Multiple \fB\-I\fR flags can be specified, in which case files matching any one
|
|
of the regular expressions will be fuzzed. See also the \fB\-c\fR flag.
|
|
.TP
|
|
\fB\-m\fR, \fB\-\-md5\fR
|
|
Instead of displaying the program's \fIstandard output\fR, just print its MD5
|
|
digest to \fBzzuf\fR's standard output. The standard error channel is left
|
|
untouched.
|
|
.TP
|
|
\fB\-M\fR, \fB\-\-max-memory\fR=\fImegabytes\fR
|
|
Specify the maximum amount of memory, in megabytes, that children are allowed
|
|
to allocate. This is useful to detect infinite loops that eat up a lot of
|
|
memory. The value should set reasonably high so as not to interfer with normal
|
|
program operation.
|
|
|
|
\fBzzuf\fR uses the \fBsetrlimit\fR() call to set memory usage limitations and
|
|
relies on the operating system's ability to enforce such limitations.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-network\fR
|
|
Fuzz the application's network input. By default \fBzzuf\fR only fuzzes files.
|
|
.TP
|
|
\fB\-P\fR, \fB\-\-protect\fR=\fIlist\fR
|
|
Protect a list of characters so that if they appear in input data that would
|
|
normally be fuzzed, they are left unmodified instead.
|
|
|
|
Characters in \fIlist\fR can be expressed verbatim or through escape sequences.
|
|
The sequences interpreted by \fBzzuf\fR are:
|
|
.RS
|
|
.TP
|
|
\fB\\n\fR
|
|
new line
|
|
.TP
|
|
\fB\\r\fR
|
|
return
|
|
.TP
|
|
\fB\\t\fR
|
|
tabulation
|
|
.TP
|
|
\fB\\\fR\fINNN\fR
|
|
the byte whose octal value is \fINNN\fR
|
|
.TP
|
|
\fB\\x\fR\fINN\fR
|
|
the byte whose hexadecimal value is \fINN\fR
|
|
.TP
|
|
\fB\\\\\fR
|
|
backslash (\(oq\\\(cq)
|
|
.RE
|
|
.IP
|
|
You can use \(oq\fB\-\fR\(cq to specify ranges. For instance, to protect all
|
|
bytes from \(oq\\001\(cq to \(oq/\(cq, use \(oq\fB\-P\ \(aq\\001\-/\(aq\fR\(cq.
|
|
|
|
The statistical outcome of this option should not be overlooked: if characters
|
|
are protected, the effect of the \(oq\fB\-r\fR\(cq flag will vary depending
|
|
on the data being fuzzed. For instance, asking to fuzz 1% of input bits
|
|
(\fB\-r0.01\fR) and to protect lowercase characters (\fB\-P\ a\-z\fR) will
|
|
result in an actual average fuzzing ratio of 0.9% with truly random data,
|
|
0.3% with random ASCII data and 0.2% with standard English text.
|
|
|
|
See also the \fB\-R\fR flag.
|
|
.TP
|
|
\fB\-q\fR, \fB\-\-quiet\fR
|
|
Hide the output of the fuzzed application. This is useful if the application
|
|
is very verbose but only its exit code or signaled status is really useful to
|
|
you.
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
|
|
.PD 0
|
|
.TP
|
|
\fB\-r\fR, \fB\-\-ratio\fR=\fImin:max\fR
|
|
.PD
|
|
Specify the proportion of bits that will be randomly fuzzed. A value of 0
|
|
will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
|
|
bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
|
|
the input files undiscernible from random data. The default fuzzing ratio
|
|
is 0.004 (fuzz 0.4% of the files' bits).
|
|
|
|
A range can also be specified. When doing so, \fBzzuf\fR will pick ratio
|
|
values from the interval. The choice is deterministic and only depends on
|
|
the interval bounds and the current seed.
|
|
.TP
|
|
\fB\-R\fR, \fB\-\-refuse\fR=\fIlist\fR
|
|
Refuse a list of characters by not fuzzing bytes that would otherwise be
|
|
changed to a character that is in \fIlist\fR. If the original byte is already
|
|
in \fIlist\fR, it is left unchanged.
|
|
|
|
See the \fB\-P\fR option for a description of \fIlist\fR.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR
|
|
.PD 0
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR
|
|
.PD
|
|
Specify the random seed to use for fuzzing, or a range of random seeds.
|
|
Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly
|
|
the same way, even with a different target application. The purpose of this is
|
|
to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that
|
|
causes the target application to crash.
|
|
|
|
If a range is specified, \fBzzuf\fR will run the application several times,
|
|
each time with a different seed, and report the behaviour of each run.
|
|
.TP
|
|
\fB\-S\fR, \fB\-\-signal\fR
|
|
Prevent children from installing signal handlers for signals that usually
|
|
cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR,
|
|
\fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running
|
|
platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and
|
|
\fBSIGXFSZ\fR. Instead of calling the signal handler, the application will
|
|
simply crash. If you do not want core dumps, you should set appropriate limits
|
|
with the \fBlimit coredumpsize\fR command. See your shell's documentation on
|
|
how to set such limits.
|
|
.TP
|
|
\fB\-T\fR, \fB\-\-max\-time\fR=\fIn\fR
|
|
Automatically terminate child processes that run for more than \fIn\fR
|
|
seconds. This is useful to detect infinite loops or processes stuck in other
|
|
situations. See also the \fB\-B\fR flag.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-verbose\fR
|
|
Print information during the run, such as the current seed, what processes
|
|
get run, their exit status, etc.
|
|
.TP
|
|
\fB\-x\fR, \fB\-\-check\-exit\fR
|
|
Report processes that exit with a non-zero status. By default only processes
|
|
that crash due to a signal are reported.
|
|
.TP
|
|
\fB\-h\fR, \fB\-\-help\fR
|
|
Display a short help message and exit.
|
|
.TP
|
|
\fB\-V\fR, \fB\-\-version\fR
|
|
Output version information and exit.
|
|
.SH DIAGNOSTICS
|
|
.PP
|
|
Exit status is zero if no child process crashed. If one or several children
|
|
crashed, \fBzzuf\fR exits with status 1.
|
|
.SH EXAMPLES
|
|
.PP
|
|
Fuzz the input of the \fBcat\fR program using default settings:
|
|
.PP
|
|
\fB zzuf cat /etc/motd\fR
|
|
.PP
|
|
Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
|
|
.PP
|
|
\fB zzuf \-s94324 \-r0.01 cat /etc/motd\fR
|
|
.PP
|
|
Fuzz the input of the \fBcat\fR program but do not fuzz newline characters
|
|
and prevent non-ASCII characters from appearing in the output:
|
|
.PP
|
|
\fB zzuf \-P \(aq\\n\(aq \-R \(aq\\x00\-\\x1f\\x7f\-\\xff\(aq cat /etc/motd\fR
|
|
.PP
|
|
Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the
|
|
original input and excluding \fB.xml\fR files from fuzzing (because
|
|
\fBconvert\fR will also open its own XML configuration files and we do not
|
|
want \fBzzuf\fR to fuzz them):
|
|
.PP
|
|
\fB zzuf \-E \(aq\\.xml$\(aq convert \-\- foo.jpeg \-format tga /dev/null\fR
|
|
.PP
|
|
Fuzz the input of VLC, using file \fBmovie.avi\fR as the original input
|
|
and restricting fuzzing to filenames that appear on the command line
|
|
(\fB\-c\fR), then generate \fBfuzzy\-movie.avi\fR which is a file that
|
|
can be read by VLC to reproduce the same behaviour without using
|
|
\fBzzuf\fR:
|
|
.PP
|
|
\fB zzuf \-c \-s87423 \-r0.01 vlc movie.avi\fR
|
|
.br
|
|
\fB zzuf \-c \-s87423 \-r0.01 <movie.avi >fuzzy\-movie.avi\fR
|
|
.br
|
|
\fB vlc fuzzy\-movie.avi\fR
|
|
.PP
|
|
Fuzz between 0.1% and 2% of MPlayer's input bits (\fB\-r0.001:0.02\fR)
|
|
with seeds 0 to 9999 (\fB\-s0:10000\fR), preserving the AVI 4-byte header
|
|
by restricting fuzzing to offsets after 4 (\fB\-b4\-\fR), disabling its
|
|
standard output messages (\fB\-q\fR), launching up to five simultaneous child
|
|
processes (\fB\-F5\fR) but waiting at least half a second between launches
|
|
(\fB\-D0.5\fR), killing MPlayer if it takes more than one minute to
|
|
read the file (\fB\-T60\fR) and disabling its \fBSIGSEGV\fR signal handler
|
|
(\fB\-S\fR):
|
|
.PP
|
|
\fB zzuf \-c \-r0.001:0.02 \-s0:10000 \-b4\- \-q \-F5 \-D0.5 \-T60 \-S \\\fR
|
|
.br
|
|
\fB mplayer \-\- \-benchmark \-vo null \-fps 1000 movie.avi\fR
|
|
.PP
|
|
Create an HTML-like file that loads 200 times the same \fBhello.jpg\fR image
|
|
and open it in Firefox\(tm in auto-increment mode (\fB\-A\fR):
|
|
.PP
|
|
\fB seq -f \(aq<img src="hello.jpg#%g">\(aq 1 200 > hello.html\fR
|
|
.br
|
|
(or: \fBjot -w \(aq<img src="hello.jpg#%d">\(aq 200 1 > hello.html\fR)
|
|
.br
|
|
\fB zzuf -A -I \(aqhello[.]jpg\(aq -r0.001 firefox hello.html\fR
|
|
.SH RESTRICTIONS
|
|
.PP
|
|
Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR,
|
|
\fB_RLD_LIST\fB, \fBDYLD_INSERT_LIBRARIES\fR, etc.) to run its child
|
|
processes, it will fail in the presence of any mechanism that disables
|
|
preloading. For instance setuid root binaries will not be fuzzed when run
|
|
as an unprivileged user.
|
|
.PP
|
|
For the same reasons, \fBzzuf\fR will also not work with statically linked
|
|
binaries. Bear this in mind when using \fBzzuf\fR on the OpenBSD platform,
|
|
where \fBcat\fR, \fBcp\fR and \fBdd\fR are static binaries.
|
|
.PP
|
|
Though best efforts are made, identical behaviour for different versions of
|
|
\fBzzuf\fR is not guaranteed. The reproducibility for subsequent calls on
|
|
different operating systems and with different target programs is only
|
|
guaranteed when the same version of \fBzzuf\fR is being used.
|
|
.SH BUGS
|
|
.PP
|
|
\fBzzuf\fR probably does not behave correctly with 64-bit offsets.
|
|
.PP
|
|
It is not yet possible to insert or drop bytes from the input, to fuzz
|
|
according to the file format, to swap bytes, etc. More advanced fuzzing
|
|
methods are planned.
|
|
.PP
|
|
As of now, \fBzzuf\fR does not really support multithreaded applications. The
|
|
behaviour with multithreaded applications where more than one thread does file
|
|
descriptor operations is undefined.
|
|
.SH NOTES
|
|
In order to intercept file and network operations, signal handlers and memory
|
|
allocations, \fBzzuf\fR diverts and reimplements the following functions,
|
|
which can be private libc symbols, too:
|
|
.TP
|
|
Unix file descriptor handling:
|
|
\fBopen\fR(), \fBlseek\fR(), \fBread\fR(), \fBreadv\fR(), \fBpread\fR(),
|
|
\fBaccept\fR(), \fBsocket\fR(), \fBrecv\fR(), \fBrecvfrom\fR(), \fBrecvmsg\fR(),
|
|
\fBaio_read\fR(), \fBaio_return\fR(), \fBclose\fR()
|
|
.TP
|
|
Standard IO streams:
|
|
\fBfopen\fR(), \fBfreopen\fR(), \fBfseek\fR(), \fBfseeko\fR(), \fBrewind\fR(),
|
|
\fBfread\fR(), \fBgetc\fR(), \fBfgetc\fR(), \fBfgets\fR(), \fBungetc\fR(),
|
|
\fBfclose\fR()
|
|
.TP
|
|
Memory management:
|
|
\fBmmap\fR(), \fBmunmap\fR(), \fBmalloc\fR(), \fBcalloc\fR(), \fBvalloc\fR(),
|
|
\fBfree\fR(), \fBmemalign\fR(), \fBposix_memalign\fR()
|
|
.TP
|
|
Linux-specific:
|
|
\fBopen64\fR(), \fBlseek64\fR(), \fBmmap64\fR(), \fB_IO_getc\fR(),
|
|
\fBgetline\fR(), \fBgetdelim\fR(), \fB__getdelim\fR()
|
|
.TP
|
|
BSD-specific:
|
|
\fBfgetln\fR(), \fB__srefill\fR()
|
|
.TP
|
|
Mac OS X-specific:
|
|
\fBmap_fd\fR()
|
|
.TP
|
|
Signal handling:
|
|
\fBsignal\fR(), \fBsigaction\fR()
|
|
.PP
|
|
If an application manipulates file descriptors (reading data, seeking around)
|
|
using functions that are not in that list, \fBzzuf\fR will not fuzz its
|
|
input consistently and the results should not be trusted. You can use a tool
|
|
such as \fBltrace(1)\fR on Linux to know the missing functions.
|
|
.PP
|
|
On BSD systems, such as FreeBSD or Mac OS X, \fB__srefill\fR() is enough to
|
|
monitor all standard IO streams functions. On other systems, such as Linux,
|
|
each function is reimplemented on a case by case basis. One important
|
|
unimplemented function is \fBfscanf\fR(), because of its complexity. Missing
|
|
functions will be added upon user request.
|
|
.SH HISTORY
|
|
.PP
|
|
\fBzzuf\fR started its life in 2002 as the \fBstreamfucker\fR tool, a small
|
|
multimedia stream corrupter used to find bugs in the VLC media player.
|
|
.SH AUTHOR
|
|
.PP
|
|
Copyright \(co 2002, 2007 Sam Hocevar <sam@zoy.org>.
|
|
.PP
|
|
\fBzzuf\fR and this manual page are free software. They come without any
|
|
warranty, to the extent permitted by applicable law. You can redistribute
|
|
them and/or modify them under the terms of the Do What The Fuck You Want
|
|
To Public License, Version 2, as published by Sam Hocevar. See
|
|
\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
|
|
.PP
|
|
\fBzzuf\fR's webpage can be found at \fBhttp://sam.zoy.org/zzuf/\fR.
|