* Totally reworked webpage.
This commit is contained in:
Sam Hocevar
sam
368
doc/zzuf.1
368
doc/zzuf.1
@@ -2,293 +2,191 @@
|
||||
.SH NAME
|
||||
zzuf \- multiple purpose fuzzer
|
||||
.SH SYNOPSIS
|
||||
.B zzuf
|
||||
[
|
||||
.B \-cdhiqSv
|
||||
] [
|
||||
.B \-r
|
||||
.I ratio
|
||||
] [
|
||||
.B \-s
|
||||
.I seed
|
||||
|
|
||||
.B \-s
|
||||
.I start:stop
|
||||
]
|
||||
.PD 0
|
||||
.IP
|
||||
.PD
|
||||
[
|
||||
.B \-F
|
||||
.I children
|
||||
] [
|
||||
.B \-B
|
||||
.I bytes
|
||||
] [
|
||||
.B \-T
|
||||
.I seconds
|
||||
]
|
||||
.PD 0
|
||||
.IP
|
||||
.PD
|
||||
[
|
||||
.B \-I
|
||||
.I include
|
||||
] [
|
||||
.B \-E
|
||||
.I exclude
|
||||
]
|
||||
.I COMMAND [ARGS]...
|
||||
.RI
|
||||
\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\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fICOMMAND\fR [\fIARGS\fR]...
|
||||
.br
|
||||
\fBzzuf \-h\fR | \fB\-\-help\fR
|
||||
.br
|
||||
\fBzzuf \-v\fR | \fB\-\-version\fR
|
||||
.SH DESCRIPTION
|
||||
.B Zzuf
|
||||
is a transparent application input fuzzer. It works by intercepting
|
||||
file operations and changing random bits in the program's input.
|
||||
.B Zzuf's
|
||||
.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.
|
||||
.RI
|
||||
.SH USAGE
|
||||
.B Zzuf
|
||||
will run an application specified on its command line, one or several times,
|
||||
with optional arguments, and will report the application's behaviour on
|
||||
the standard output.
|
||||
|
||||
If you want to specify arguments for your application, put a
|
||||
.B \-\-
|
||||
marker before them on the command line, or
|
||||
.B zzuf
|
||||
will try to interpret them as arguments for itself.
|
||||
.RI
|
||||
.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
|
||||
behaviour on the standard output.
|
||||
.PP
|
||||
If you want to specify arguments for your application, put a \fB\-\-\fR
|
||||
marker before them on the command line, or \fBzzuf\fR will try to interpret
|
||||
them as arguments for itself.
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.B \-B, \-\-max\-bytes <n>
|
||||
Automatically terminate child processes that output more than
|
||||
.B <n>
|
||||
bytes on the standard output and standard error channels. This is useful to
|
||||
detect infinite loops.
|
||||
\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
|
||||
.B \-c, \-\-cmdline
|
||||
\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:
|
||||
.B zzuf \-c cat file.txt
|
||||
has the same effect as
|
||||
.B zzuf \-I "^file\\.txt$" cat
|
||||
.BR file.txt .
|
||||
See the
|
||||
.B \-I
|
||||
flag for more information.
|
||||
\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
|
||||
.B \-d, \-\-debug
|
||||
\fB\-d\fR, \fB\-\-debug\fR
|
||||
Activate the display of debug messages.
|
||||
.TP
|
||||
.B \-E, \-\-exclude <regex>
|
||||
Do not fuzz files whose name matches the
|
||||
.B <regex>
|
||||
regular expression. This option supersedes anything that is specified by the
|
||||
.B \-\-include
|
||||
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
|
||||
.B /etc
|
||||
directory.
|
||||
\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
|
||||
.B \-E
|
||||
flags can be specified, in which case files matching any one of the regular
|
||||
expressions will be ignored.
|
||||
Multiple \fB\-E\fR flags can be specified, in which case files matching any one
|
||||
of the regular expressions will be ignored.
|
||||
.TP
|
||||
.B \-F, \-\-fork <children>
|
||||
\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
|
||||
.B \-s
|
||||
flag is used with an interval argument.
|
||||
only useful if the \fB\-s\fR flag is used with an interval argument.
|
||||
.TP
|
||||
.B \-h, \-\-help
|
||||
\fB\-h\fR, \fB\-\-help\fR
|
||||
Display a short help message and exit.
|
||||
.TP
|
||||
.B \-i, \-\-stdin
|
||||
Fuzz the application's standard input. By default
|
||||
.B zzuf
|
||||
only fuzzes files.
|
||||
\fB\-i\fR, \fB\-\-stdin\fR
|
||||
Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files.
|
||||
.TP
|
||||
.B \-I, \-\-include <regex>
|
||||
Only fuzz files whose name matches the
|
||||
.B <regex>
|
||||
regular expression. Use this for instance if your application reads
|
||||
configuration files at startup and you only want specific files to be fuzzed.
|
||||
\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
|
||||
.B \-I
|
||||
flags can be specified, in which case files matching any one of the regular
|
||||
expressions will be fuzzed. See also the
|
||||
.B \-c
|
||||
flag.
|
||||
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
|
||||
.B \-q, \-\-quiet
|
||||
\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
|
||||
.B \-r, \-\-ratio <ratio>
|
||||
\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
|
||||
Specify the amount 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
|
||||
.B \-s, \-\-seed <seed>
|
||||
\fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR
|
||||
.PD 0
|
||||
.TP
|
||||
.B \-s, \-\-seed <start:stop>
|
||||
\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
|
||||
.B zzuf
|
||||
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
|
||||
.B cat
|
||||
or
|
||||
.B cp
|
||||
to generate a file that causes the target application to crash.
|
||||
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,
|
||||
.B zzuf
|
||||
will run the application several times, each time with a different seed, and
|
||||
report the behaviour of each run.
|
||||
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
|
||||
.B \-S, \-\-signal
|
||||
\fB\-S\fR, \fB\-\-signal\fR
|
||||
Prevent children from installing signal handlers for signals that usually
|
||||
cause coredumps. These signals are
|
||||
.BR SIGABRT ,
|
||||
.BR SIGFPE ,
|
||||
.BR SIGILL ,
|
||||
.BR SIGQUIT ,
|
||||
.BR SIGSEGV ,
|
||||
.B SIGTRAP
|
||||
and, if available on the running platform,
|
||||
.BR SIGSYS ,
|
||||
.BR SIGEMT ,
|
||||
.BR SIGBUS ,
|
||||
.B SIGXCPU
|
||||
and
|
||||
.BR SIGXFSZ .
|
||||
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
|
||||
.B limit coredumpsize
|
||||
command. See your shell's documentation on how to set such limits.
|
||||
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
|
||||
.B \-T, \-\-max\-time <n>
|
||||
Automatically terminate child processes that run for more than
|
||||
.B <n>
|
||||
\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.
|
||||
situations. See also the \fB\-B\fR flag.
|
||||
.TP
|
||||
.B \-v, \-\-version
|
||||
\fB\-v\fR, \fB\-\-version\fR
|
||||
Output version information and exit.
|
||||
.RI
|
||||
.SH EXAMPLES
|
||||
Fuzz the input of the
|
||||
.B cat
|
||||
program using default settings:
|
||||
.PP
|
||||
Fuzz the input of the \fBcat\fR program using default settings:
|
||||
.PP
|
||||
.RS
|
||||
.nf
|
||||
|
||||
.B % zzuf cat /etc/motd
|
||||
|
||||
\fB# zzuf cat /etc/motd\fR
|
||||
.fi
|
||||
Fuzz 1% of the input bits of the
|
||||
.B cat
|
||||
program using seed 94324:
|
||||
.RE
|
||||
.PP
|
||||
Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
|
||||
.PP
|
||||
.RS
|
||||
.nf
|
||||
|
||||
.B % zzuf -s 94324 -r 0.01 cat /etc/motd
|
||||
|
||||
\fB# zzuf -s 94324 -r 0.01 cat /etc/motd\fR
|
||||
.fi
|
||||
Fuzz the input of the
|
||||
.B convert
|
||||
program, using file
|
||||
.B foo.jpeg
|
||||
as the original input and excluding
|
||||
.B .xml
|
||||
files from fuzzing (because
|
||||
.B convert
|
||||
will also open its own XML configuration files and we do not want
|
||||
.B zzuf
|
||||
to fuzz them):
|
||||
.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
|
||||
|
||||
.B % zzuf -E "\\.xml$" convert -- foo.jpeg -format tga /dev/null
|
||||
|
||||
\fB# zzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
|
||||
.fi
|
||||
Fuzz the input of
|
||||
.BR vlc ,
|
||||
using file
|
||||
.B movie.avi
|
||||
as the original input and restricting fuzzing to filenames that appear on
|
||||
the command line, then generate
|
||||
.B fuzzy-movie.avi
|
||||
which is a file that can be fed to
|
||||
.B vlc
|
||||
to reproduce the same behaviour without using
|
||||
.BR zzuf :
|
||||
.fn
|
||||
|
||||
.B % zzuf -c -s 87423 -r 0.01 vlc movie.avi
|
||||
|
||||
.B % zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi
|
||||
|
||||
.B % vlc fuzzy-movie.avi
|
||||
|
||||
.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
|
||||
\fB# zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
|
||||
\fB# zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
|
||||
\fB# vlc fuzzy-movie.avi\fR
|
||||
.fi
|
||||
Fuzz 2% of
|
||||
.BR mplayer 's
|
||||
input bits
|
||||
.RB ( \-r
|
||||
.BR 0.02 )
|
||||
with seeds 0 to 9999
|
||||
.RB ( \-s
|
||||
.BR 0:10000 ),
|
||||
disabling its standard output messages
|
||||
.RB ( \-q ),
|
||||
launching up to three simultaneous child processes
|
||||
.RB ( \-F
|
||||
.BR 3 ),
|
||||
killing
|
||||
.B mplayer
|
||||
if it takes more than one minute to read the file
|
||||
.RB ( \-T
|
||||
.BR 60 )
|
||||
and disabling its
|
||||
.B SIGSEGV
|
||||
signal handler
|
||||
.RB ( \-S ):
|
||||
.fn
|
||||
|
||||
.B % zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 mplayer movie.avi -- -benchmark -vo null -fps 1000
|
||||
|
||||
.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
|
||||
\fB# zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
|
||||
\fB mplayer movie.avi -- -benchmark -vo null -fps 1000\fR
|
||||
.fi
|
||||
.RI
|
||||
.RE
|
||||
.SH BUGS
|
||||
Only the most common file operations are implemented as of now:
|
||||
.BR open (),
|
||||
.BR read (),
|
||||
.BR fopen (),
|
||||
.BR fseek (),
|
||||
etc. One important unimplemented function is
|
||||
.BR fscanf ().
|
||||
|
||||
.PP
|
||||
Only the most common file operations are implemented as of now: \fBopen\fR(),
|
||||
\fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented
|
||||
function is \fBfscanf\fR().
|
||||
.PP
|
||||
Network fuzzing is not implemented. 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. They are planned, though.
|
||||
|
||||
Due to
|
||||
.B zzuf
|
||||
using
|
||||
.B LD_PRELOAD
|
||||
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.
|
||||
.RI
|
||||
.PP
|
||||
Due to \fBzzuf\fR using \fBLD_PRELOAD\fR 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.
|
||||
.SH AUTHOR
|
||||
.B Zzuf
|
||||
and this manual page were written by Sam Hocevar <sam@zoy.org>. There is a
|
||||
webpage available at http://sam.zoy.org/zzuf/
|
||||
.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.
|
||||
|
||||
Reference in New Issue
Block a user