278 lines
10 KiB
Groff
278 lines
10 KiB
Groff
.TH zzuf 1 "2006-12-22" "zzuf"
|
|
.SH NAME
|
|
zzuf \- multiple purpose fuzzer
|
|
.SH SYNOPSIS
|
|
\fBzzuf\fR [\fB\-cdiqS\fR] [\fB\-r\fR \fIratio\fR] [\fB\-s\fR \fIseed\fR | \fB\-s\fR \fIstart:stop\fR]
|
|
.br
|
|
[\fB\-F\fR \fIchildren\fR] [\fB\-B\fR \fIbytes\fR] [\fB\-T\fR \fIseconds\fR]
|
|
.br
|
|
[\fB\-P\fR \fIlist\fR] [\fB\-R\fR \fIlist\fR]
|
|
.br
|
|
[\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fIPROGRAM\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 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 output, eg:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf cat /dev/zero\fR
|
|
.fi
|
|
.RE
|
|
.PP
|
|
If you want to specify flags for your application, put a '\fB\-\-\fR'
|
|
marker before them on the command line (otherwise \fBzzuf\fR will try to
|
|
interpret them as arguments for itself), eg:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf \-B 1000 cat \-\- \-v /dev/zero\fR
|
|
.fi
|
|
.RE
|
|
.SH OPTIONS
|
|
.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 specifiying twice the argument:
|
|
\fBzzuf \-c cat file.txt\fR has the same effect as \fBzzuf \-I
|
|
\(dq^file\\.txt$\(dq cat file.txt\fR. See the \fB\-I\fR flag for more
|
|
information.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-debug\fR
|
|
Activate the display of debug messages.
|
|
.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\-\-fork\fR=\fIchildren\fR
|
|
Specify the number of simultaneous children that can be run. This option is
|
|
only useful if the \fB\-s\fR flag is used with an interval argument.
|
|
.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\-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\\0\fR
|
|
null byte
|
|
.TP
|
|
\fB\\n\fR
|
|
new line
|
|
.TP
|
|
\fB\\r\fR
|
|
return
|
|
.TP
|
|
\fB\\t\fR
|
|
tabulation
|
|
.TP
|
|
\fB\\x\fR\fINN\fR
|
|
the byte whose hexadecimal value is \fINN\fR
|
|
.TP
|
|
\fB\\\\\fR
|
|
backslash ('\\')
|
|
.RE
|
|
.IP
|
|
You can use '\fB-\fR' to specify ranges. For instance, to protect all bytes
|
|
from '\fB\\x01\fR' to ' ', use '\fB\-P \(dq\\x01- \(dq\fR'.
|
|
|
|
The statistical outcome of this option should not be overlooked. Because
|
|
\fBzzuf\fR cannot know the nature of the input data beforehands and must
|
|
fuzz it even if only one byte of data was received, protecting characters
|
|
may change the meaning of the \fB\-r\fR flag depending on the data being
|
|
fuzzed. For instance, asking to fuzz 1% of input bits and to protect
|
|
lowercase characters (using '\fB\-r 0.01 \-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 a normal 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
|
|
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).
|
|
.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 an interval 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 an interval 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\-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 EXAMPLES
|
|
.PP
|
|
Fuzz the input of the \fBcat\fR program using default settings:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf cat /etc/motd\fR
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf -s 94324 -r 0.01 cat /etc/motd\fR
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Fuzz the input of the \fBcat\fR program but do not fuzz the newline character
|
|
and prevent non-ASCII characters from appearing in the output:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf -P \(dq\\n\(dq -R \(dq\\0-\\x1f\\x7f-\\xff\(dq cat /etc/motd\fR
|
|
.fi
|
|
.RE
|
|
.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
|
|
.RS
|
|
.nf
|
|
\fBzzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Fuzz the input of \fBvlc\fR, 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 \fBvlc\fR to reproduce the same behaviour without using \fBzzuf\fR:
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
|
|
\fBzzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
|
|
\fBvlc fuzzy-movie.avi\fR
|
|
.fi
|
|
.RE
|
|
.PP
|
|
Fuzz 2% of \fBmplayer\fR's input bits (\fB\-r 0.02\fR) with seeds 0 to 9999
|
|
(\fB\-s 0:10000\fR), disabling its standard output messages (\fB\-q\fR),
|
|
launching up to three simultaneous child processes (\fB\-F 3\fR), killing
|
|
\fBmplayer\fR if it takes more than one minute to read the file (\fB\-T 60\fR)
|
|
and disabling its \fBSIGSEGV\fR signal handler (\fB\-S\fR):
|
|
.PP
|
|
.RS
|
|
.nf
|
|
\fBzzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
|
|
\fB mplayer -- -benchmark -vo null -fps 1000 movie.avi\fR
|
|
.fi
|
|
.RE
|
|
.SH BUGS
|
|
.PP
|
|
Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR on most
|
|
Unix systems, \fBDYLD_INSERT_LIBRARIES\fR on Mac OS X) 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. This limitation will probably not be addressed.
|
|
.PP
|
|
Network fuzzing is not implemented. This feature will be added.
|
|
.PP
|
|
It is not yet possible to insert or drop bytes from the input, to fuzz
|
|
according to the file format, or to do all these complicated operations. These
|
|
features are planned.
|
|
.PP
|
|
Only the most common file operations are implemented: \fBopen\fR(),
|
|
\fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented
|
|
function is \fBfscanf\fR(). These features will be implemented based on user
|
|
request.
|
|
.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. This bug will be fixed.
|
|
.PP
|
|
Though best efforts are made, the reproducibility of \fBzzuf\fR's behaviour
|
|
is guaranteed for subsequent calls with the same settings on different
|
|
operating systems, with different target programs, but not for calls with
|
|
different versions of \fBzzuf\fR.
|
|
.SH AUTHOR
|
|
.PP
|
|
Copyright \(co 2006, 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.
|