Changeset 1539 for zzuf


Ignore:
Timestamp:
Jan 2, 2007, 6:15:34 PM (14 years ago)
Author:
Sam Hocevar
Message:
  • Totally reworked webpage.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • zzuf/trunk/doc/zzuf.1

    r1536 r1539  
    33zzuf \- multiple purpose fuzzer
    44.SH SYNOPSIS
    5 .B zzuf
    6 [
    7 .B \-cdhiqSv
    8 ] [
    9 .B \-r
    10 .I ratio
    11 ] [
    12 .B \-s
    13 .I seed
    14 |
    15 .B \-s
    16 .I start:stop
    17 ]
    18 .PD 0
    19 .IP
    20 .PD
    21 [
    22 .B \-F
    23 .I children
    24 ] [
    25 .B \-B
    26 .I bytes
    27 ] [
    28 .B \-T
    29 .I seconds
    30 ]
    31 .PD 0
    32 .IP
    33 .PD
    34 [
    35 .B \-I
    36 .I include
    37 ] [
    38 .B \-E
    39 .I exclude
    40 ]
    41 .I COMMAND [ARGS]...
    42 .RI
     5\fBzzuf\fR [\fB\-cdiqS\fR] [\fB\-r\fR \fIratio\fR] [\fB\-s\fR \fIseed\fR | \fB\-s\fR \fIstart:stop\fR]
     6.br
     7              [\fB\-F\fR \fIchildren\fR] [\fB\-B\fR \fIbytes\fR] [\fB\-T\fR \fIseconds\fR]
     8.br
     9              [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fICOMMAND\fR [\fIARGS\fR]...
     10.br
     11\fBzzuf \-h\fR | \fB\-\-help\fR
     12.br
     13\fBzzuf \-v\fR | \fB\-\-version\fR
    4314.SH DESCRIPTION
    44 .B Zzuf
    45 is a transparent application input fuzzer. It works by intercepting
    46 file operations and changing random bits in the program's input.
    47 .B Zzuf's
     15.PP
     16\fBZzuf\fR is a transparent application input fuzzer. It works by intercepting
     17file operations and changing random bits in the program's input. \fBZzuf\fR's
    4818behaviour is deterministic, making it easy to reproduce bugs.
    49 .RI
    5019.SH USAGE
    51 .B Zzuf
    52 will run an application specified on its command line, one or several times,
    53 with optional arguments, and will report the application's behaviour on
    54 the standard output.
    55 
    56 If you want to specify arguments for your application, put a
    57 .B \-\-
    58 marker before them on the command line, or
    59 .B zzuf
    60 will try to interpret them as arguments for itself.
    61 .RI
     20.PP
     21\fBZzuf\fR will run an application specified on its command line, one or
     22several times, with optional arguments, and will report the application's
     23behaviour on the standard output.
     24.PP
     25If you want to specify arguments for your application, put a \fB\-\-\fR
     26marker before them on the command line, or \fBzzuf\fR will try to interpret
     27them as arguments for itself.
    6228.SH OPTIONS
    6329.TP
    64 .B \-B, \-\-max\-bytes <n>
    65 Automatically terminate child processes that output more than
    66 .B <n>
    67 bytes on the standard output and standard error channels. This is useful to
    68 detect infinite loops.
     30\fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR
     31Automatically terminate child processes that output more than \fIn\fR bytes
     32on the standard output and standard error channels. This is useful to detect
     33infinite loops. See also the \fB\-T\fR flag.
    6934.TP
    70 .B \-c, \-\-cmdline
     35\fB\-c\fR, \fB\-\-cmdline\fR
    7136Only fuzz files whose name is specified in the target application's command
    7237line. This is mostly a shortcut to avoid specifiying twice the argument:
    73 .B zzuf \-c cat file.txt
    74 has the same effect as
    75 .B zzuf \-I "^file\\.txt$" cat
    76 .BR file.txt .
    77 See the
    78 .B \-I
    79 flag for more information.
     38\fBzzuf \-c cat file.txt\fR has the same effect as \fBzzuf \-I
     39\(dq^file\\.txt$\(dq cat file.txt\fR. See the \fB\-I\fR flag for more
     40information.
    8041.TP
    81 .B \-d, \-\-debug
     42\fB\-d\fR, \fB\-\-debug\fR
    8243Activate the display of debug messages.
    8344.TP
    84 .B \-E, \-\-exclude <regex>
    85 Do not fuzz files whose name matches the
    86 .B <regex>
    87 regular expression. This option supersedes anything that is specified by the
    88 .B \-\-include
    89 flag. Use this for instance if you are unsure of what files your
    90 application is going to read and do not want it to fuzz files in the
    91 .B /etc
    92 directory.
     45\fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR
     46Do not fuzz files whose name matches the \fIregex\fR regular expression. This
     47option supersedes anything that is specified by the \fB\-I\fR flag. Use this
     48for instance if you are unsure of what files your application is going to read
     49and do not want it to fuzz files in the \fB/etc\fR directory.
    9350
    94 Multiple
    95 .B \-E
    96 flags can be specified, in which case files matching any one of the regular
    97 expressions will be ignored.
     51Multiple \fB\-E\fR flags can be specified, in which case files matching any one
     52of the regular expressions will be ignored.
    9853.TP
    99 .B \-F, \-\-fork <children>
     54\fB\-F\fR, \fB\-\-fork\fR=\fIchildren\fR
    10055Specify the number of simultaneous children that can be run. This option is
    101 only useful if the
    102 .B \-s
    103 flag is used with an interval argument.
     56only useful if the \fB\-s\fR flag is used with an interval argument.
    10457.TP
    105 .B \-h, \-\-help
     58\fB\-h\fR, \fB\-\-help\fR
    10659Display a short help message and exit.
    10760.TP
    108 .B \-i, \-\-stdin
    109 Fuzz the application's standard input. By default
    110 .B zzuf
    111 only fuzzes files.
     61\fB\-i\fR, \fB\-\-stdin\fR
     62Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files.
    11263.TP
    113 .B \-I, \-\-include <regex>
    114 Only fuzz files whose name matches the
    115 .B <regex>
    116 regular expression. Use this for instance if your application reads
    117 configuration files at startup and you only want specific files to be fuzzed.
     64\fB\-I\fR, \fB\-\-include\fR=\fIregex\fR
     65Only fuzz files whose name matches the \fIregex\fR regular expression. Use
     66this for instance if your application reads configuration files at startup
     67and you only want specific files to be fuzzed.
    11868
    119 Multiple
    120 .B \-I
    121 flags can be specified, in which case files matching any one of the regular
    122 expressions will be fuzzed. See also the
    123 .B \-c
    124 flag.
     69Multiple \fB\-I\fR flags can be specified, in which case files matching any one
     70of the regular expressions will be fuzzed. See also the \fB\-c\fR flag.
    12571.TP
    126 .B \-q, \-\-quiet
     72\fB\-q\fR, \fB\-\-quiet\fR
    12773Hide the output of the fuzzed application. This is useful if the application
    12874is very verbose but only its exit code or signaled status is really useful to
    12975you.
    13076.TP
    131 .B \-r, \-\-ratio <ratio>
     77\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
    13278Specify the amount of bits that will be randomly fuzzed. A value of 0
    13379will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
     
    13682is 0.004 (fuzz 0.4% of the files' bits).
    13783.TP
    138 .B \-s, \-\-seed <seed>
     84\fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR
    13985.PD 0
    14086.TP
    141 .B \-s, \-\-seed <start:stop>
     87\fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR
    14288.PD
    14389Specify the random seed to use for fuzzing, or an interval of random seeds.
    144 Running
    145 .B zzuf
    146 twice with the same random seed will fuzz the files exactly the same way,
    147 even with a different target application. The purpose of this is to use
    148 simple utilities such as
    149 .B cat
    150 or
    151 .B cp
    152 to generate a file that causes the target application to crash.
     90Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly
     91the same way, even with a different target application. The purpose of this is
     92to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that
     93causes the target application to crash.
    15394
    154 If an interval is specified,
    155 .B zzuf
    156 will run the application several times, each time with a different seed, and
    157 report the behaviour of each run.
     95If an interval is specified, \fBzzuf\fR will run the application several times,
     96each time with a different seed, and report the behaviour of each run.
    15897.TP
    159 .B \-S, \-\-signal
     98\fB\-S\fR, \fB\-\-signal\fR
    16099Prevent children from installing signal handlers for signals that usually
    161 cause coredumps. These signals are
    162 .BR SIGABRT ,
    163 .BR SIGFPE ,
    164 .BR SIGILL ,
    165 .BR SIGQUIT ,
    166 .BR SIGSEGV ,
    167 .B SIGTRAP
    168 and, if available on the running platform,
    169 .BR SIGSYS ,
    170 .BR SIGEMT ,
    171 .BR SIGBUS ,
    172 .B SIGXCPU
    173 and
    174 .BR SIGXFSZ .
    175 Instead of calling the signal handler, the application will simply crash. If
    176 you do not want core dumps, you should set appropriate limits with the
    177 .B limit coredumpsize
    178 command. See your shell's documentation on how to set such limits.
     100cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR,
     101\fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running
     102platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and
     103\fBSIGXFSZ\fR. Instead of calling the signal handler, the application will
     104simply crash. If you do not want core dumps, you should set appropriate limits
     105with the \fBlimit coredumpsize\fR command. See your shell's documentation on
     106how to set such limits.
    179107.TP
    180 .B \-T, \-\-max\-time <n>
    181 Automatically terminate child processes that run for more than
    182 .B <n>
     108\fB\-T\fR, \fB\-\-max\-time\fR=\fIn\fR
     109Automatically terminate child processes that run for more than \fIn\fR
    183110seconds. This is useful to detect infinite loops or processes stuck in other
    184 situations.
     111situations. See also the \fB\-B\fR flag.
    185112.TP
    186 .B \-v, \-\-version
     113\fB\-v\fR, \fB\-\-version\fR
    187114Output version information and exit.
    188 .RI
    189115.SH EXAMPLES
    190 Fuzz the input of the
    191 .B cat
    192 program using default settings:
     116.PP
     117Fuzz the input of the \fBcat\fR program using default settings:
     118.PP
     119.RS
    193120.nf
    194 
    195 .B % zzuf cat /etc/motd
    196 
     121\fB# zzuf cat /etc/motd\fR
    197122.fi
    198 Fuzz 1% of the input bits of the
    199 .B cat
    200 program using seed 94324:
     123.RE
     124.PP
     125Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
     126.PP
     127.RS
    201128.nf
    202 
    203 .B % zzuf -s 94324 -r 0.01 cat /etc/motd
    204 
     129\fB# zzuf -s 94324 -r 0.01 cat /etc/motd\fR
    205130.fi
    206 Fuzz the input of the
    207 .B convert
    208 program, using file
    209 .B foo.jpeg
    210 as the original input and excluding
    211 .B .xml
    212 files from fuzzing (because
    213 .B convert
    214 will also open its own XML configuration files and we do not want
    215 .B zzuf
    216 to fuzz them):
     131.RE
     132.PP
     133Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the
     134original input and excluding \fB.xml\fR files from fuzzing (because
     135\fBconvert\fR will also open its own XML configuration files and we do not
     136want \fBzzuf\fR to fuzz them):
     137.PP
     138.RS
    217139.nf
    218 
    219 .B % zzuf -E "\\.xml$" convert -- foo.jpeg -format tga /dev/null
    220 
     140\fB# zzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
    221141.fi
    222 Fuzz the input of
    223 .BR vlc ,
    224 using file
    225 .B movie.avi
    226 as the original input and restricting fuzzing to filenames that appear on
    227 the command line, then generate
    228 .B fuzzy-movie.avi
    229 which is a file that can be fed to
    230 .B vlc
    231 to reproduce the same behaviour without using
    232 .BR zzuf :
    233 .fn
    234 
    235 .B % zzuf -c -s 87423 -r 0.01 vlc movie.avi
    236 
    237 .B % zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi
    238 
    239 .B % vlc fuzzy-movie.avi
    240 
     142.RE
     143.PP
     144Fuzz the input of \fBvlc\fR, using file \fBmovie.avi\fR as the original input
     145and restricting fuzzing to filenames that appear on the command line
     146(\fB\-c\fR), then generate \fBfuzzy-movie.avi\fR which is a file that can
     147be read by \fBvlc\fR to reproduce the same behaviour without using \fBzzuf\fR:
     148.PP
     149.RS
     150.nf
     151\fB# zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
     152\fB# zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
     153\fB# vlc fuzzy-movie.avi\fR
    241154.fi
    242 Fuzz 2% of
    243 .BR mplayer 's
    244 input bits
    245 .RB  ( \-r
    246 .BR 0.02 )
    247 with seeds 0 to 9999
    248 .RB ( \-s
    249 .BR 0:10000 ),
    250 disabling its standard output messages
    251 .RB ( \-q ),
    252 launching up to three simultaneous child processes
    253 .RB ( \-F
    254 .BR 3 ),
    255 killing
    256 .B mplayer
    257 if it takes more than one minute to read the file
    258 .RB ( \-T
    259 .BR 60 )
    260 and disabling its
    261 .B SIGSEGV
    262 signal handler
    263 .RB ( \-S ):
    264 .fn
    265 
    266 .B % zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 mplayer movie.avi -- -benchmark -vo null -fps 1000
    267 
     155.RE
     156.PP
     157Fuzz 2% of \fBmplayer\fR's input bits (\fB\-r 0.02\fR) with seeds 0 to 9999
     158(\fB\-s 0:10000\fR), disabling its standard output messages (\fB\-q\fR),
     159launching up to three simultaneous child processes (\fB\-F 3\fR), killing
     160\fBmplayer\fR if it takes more than one minute to read the file (\fB\-T 60\fR)
     161and disabling its \fBSIGSEGV\fR signal handler (\fB\-S\fR):
     162.PP
     163.RS
     164.nf
     165\fB# zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
     166\fB    mplayer movie.avi -- -benchmark -vo null -fps 1000\fR
    268167.fi
    269 .RI
     168.RE
    270169.SH BUGS
    271 Only the most common file operations are implemented as of now:
    272 .BR open (),
    273 .BR read (),
    274 .BR fopen (),
    275 .BR fseek (),
    276 etc. One important unimplemented function is
    277 .BR fscanf ().
    278 
     170.PP
     171Only the most common file operations are implemented as of now: \fBopen\fR(),
     172\fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented
     173function is \fBfscanf\fR().
     174.PP
    279175Network fuzzing is not implemented. It is not yet possible to insert or
    280176drop bytes from the input, to fuzz according to the file format, or to do
    281177all these complicated operations. They are planned, though.
    282 
    283 Due to
    284 .B zzuf
    285 using
    286 .B LD_PRELOAD
    287 to run its child processes, it will fail in the presence of any mechanism
    288 that disables preloading. For instance setuid root binaries will not be
    289 fuzzed.
    290 .RI
     178.PP
     179Due to \fBzzuf\fR using \fBLD_PRELOAD\fR to run its child processes, it will
     180fail in the presence of any mechanism that disables preloading. For instance
     181setuid root binaries will not be fuzzed when run as an unprivileged user.
    291182.SH AUTHOR
    292 .B Zzuf
    293 and this manual page were written by Sam Hocevar <sam@zoy.org>. There is a
    294 webpage available at http://sam.zoy.org/zzuf/
     183.PP
     184Copyright \(co 2006, 2007 Sam Hocevar <sam@zoy.org>.
     185.PP
     186\fBZzuf\fR and this manual page are free software. They come without any
     187warranty, to the extent permitted by applicable law. You can redistribute
     188them and/or modify them under the terms of the Do What The Fuck You Want
     189To Public License, Version 2, as published by Sam Hocevar. See
     190\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
     191.PP
     192\fBZzuf\fR's webpage can be found at \fBhttp://sam.zoy.org/zzuf/\fR.
Note: See TracChangeset for help on using the changeset viewer.