source: zzuf/trunk/doc/zzuf.1 @ 1569

Last change on this file since 1569 was 1569, checked in by Sam Hocevar, 15 years ago
  • Split the bugs manpage section into bugs and restrictions.
  • Listed diverted functions.
File size: 10.7 KB
Line 
1.TH zzuf 1 "2006-12-22" "zzuf"
2.SH NAME
3zzuf \- multiple purpose fuzzer
4.SH SYNOPSIS
5\fBzzuf\fR [\fB\-cdinqS\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\-P\fR \fIlist\fR] [\fB\-R\fR \fIlist\fR]
10.br
11               [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fIPROGRAM\fR [\fIARGS\fR]...
12.br
13\fBzzuf \-h\fR | \fB\-\-help\fR
14.br
15\fBzzuf \-v\fR | \fB\-\-version\fR
16.SH DESCRIPTION
17.PP
18\fBZzuf\fR is a transparent application input fuzzer. It works by intercepting
19file and network operations and changing random bits in the program's input.
20\fBZzuf\fR's behaviour is deterministic, making it easy to reproduce bugs.
21.SH USAGE
22.PP
23\fBZzuf\fR will run an application specified on its command line, one or
24several times, with optional arguments, and will report the application's
25relevant behaviour on the standard output, eg:
26.PP
27\fB    zzuf cat /dev/zero\fR
28.PP
29If you want to specify flags for your application, put a \(oq\fB\-\-\fR\(cq
30marker before them on the command line (otherwise \fBzzuf\fR will try to
31interpret them as arguments for itself), eg:
32.PP
33\fB    zzuf \-B 1000 cat \-\- \-v /dev/zero\fR
34.SH OPTIONS
35.TP
36\fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR
37Automatically terminate child processes that output more than \fIn\fR bytes
38on the standard output and standard error channels. This is useful to detect
39infinite loops. See also the \fB\-T\fR flag.
40.TP
41\fB\-c\fR, \fB\-\-cmdline\fR
42Only fuzz files whose name is specified in the target application's command
43line. This is mostly a shortcut to avoid specifiying twice the argument:
44
45\fB    zzuf \-c cat file.txt\fR
46
47has the same effect as
48
49\fB    zzuf \-I \(aq^file\\.txt$\(aq cat file.txt\fR
50
51See the \fB\-I\fR flag for more information on restricting fuzzing to
52specific files.
53.TP
54\fB\-d\fR, \fB\-\-debug\fR
55Activate the display of debug messages.
56.TP
57\fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR
58Do not fuzz files whose name matches the \fIregex\fR regular expression. This
59option supersedes anything that is specified by the \fB\-I\fR flag. Use this
60for instance if you are unsure of what files your application is going to read
61and do not want it to fuzz files in the \fB/etc\fR directory.
62
63Multiple \fB\-E\fR flags can be specified, in which case files matching any one
64of the regular expressions will be ignored.
65.TP
66\fB\-F\fR, \fB\-\-fork\fR=\fIchildren\fR
67Specify the number of simultaneous children that can be run. This option is
68only useful if the \fB\-s\fR flag is used with an interval argument.
69.TP
70\fB\-i\fR, \fB\-\-stdin\fR
71Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files.
72.TP
73\fB\-I\fR, \fB\-\-include\fR=\fIregex\fR
74Only fuzz files whose name matches the \fIregex\fR regular expression. Use
75this for instance if your application reads configuration files at startup
76and you only want specific files to be fuzzed.
77
78Multiple \fB\-I\fR flags can be specified, in which case files matching any one
79of the regular expressions will be fuzzed. See also the \fB\-c\fR flag.
80.TP
81\fB\-n\fR, \fB\-\-network\fR
82Fuzz the application's network input. By default \fBzzuf\fR only fuzzes files.
83.TP
84\fB\-P\fR, \fB\-\-protect\fR=\fIlist\fR
85Protect a list of characters so that if they appear in input data that would
86normally be fuzzed, they are left unmodified instead.
87
88Characters in \fIlist\fR can be expressed verbatim or through escape sequences.
89The sequences interpreted by \fBzzuf\fR are:
90.RS
91.TP
92\fB\\n\fR
93new line
94.TP
95\fB\\r\fR
96return
97.TP
98\fB\\t\fR
99tabulation
100.TP
101\fB\\\fR\fINNN\fR
102the byte whose octal value is \fINNN\fR
103.TP
104\fB\\x\fR\fINN\fR
105the byte whose hexadecimal value is \fINN\fR
106.TP
107\fB\\\\\fR
108backslash (\(oq\\\(cq)
109.RE
110.IP
111You can use \(oq\fB-\fR\(cq to specify ranges. For instance, to protect all
112bytes from '\\001' to '/', use \(oq\fB\-P\ \(dq\\001-/\(dq\fR\(cq.
113
114The statistical outcome of this option should not be overlooked: if characters
115are protected, the effect of the \(oq\fB\-r\fR\(cq flag will vary depending
116on the data being fuzzed. For instance, asking to fuzz 1% of input bits
117(\fB\-r\ 0.01\fR) and to protect lowercase characters (\fB\-P\ a-z\fR) will
118result in an actual average fuzzing ratio of 0.9% with truly random data,
1190.3% with random ASCII data and 0.2% with standard English text.
120
121See also the \fB\-R\fR flag.
122.TP
123\fB\-q\fR, \fB\-\-quiet\fR
124Hide the output of the fuzzed application. This is useful if the application
125is very verbose but only its exit code or signaled status is really useful to
126you.
127.TP
128\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
129Specify the proportion of bits that will be randomly fuzzed. A value of 0
130will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
131bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
132the input files undiscernible from random data. The default fuzzing ratio
133is 0.004 (fuzz 0.4% of the files' bits).
134.TP
135\fB\-R\fR, \fB\-\-refuse\fR=\fIlist\fR
136Refuse a list of characters by not fuzzing bytes that would otherwise be
137changed to a character that is in \fIlist\fR. If the original byte is already
138in \fIlist\fR, it is left unchanged.
139
140See the \fB\-P\fR option for a description of \fIlist\fR.
141.TP
142\fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR
143.PD 0
144.TP
145\fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR
146.PD
147Specify the random seed to use for fuzzing, or an interval of random seeds.
148Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly
149the same way, even with a different target application. The purpose of this is
150to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that
151causes the target application to crash.
152
153If an interval is specified, \fBzzuf\fR will run the application several times,
154each time with a different seed, and report the behaviour of each run.
155.TP
156\fB\-S\fR, \fB\-\-signal\fR
157Prevent children from installing signal handlers for signals that usually
158cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR,
159\fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running
160platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and
161\fBSIGXFSZ\fR. Instead of calling the signal handler, the application will
162simply crash. If you do not want core dumps, you should set appropriate limits
163with the \fBlimit coredumpsize\fR command. See your shell's documentation on
164how to set such limits.
165.TP
166\fB\-T\fR, \fB\-\-max\-time\fR=\fIn\fR
167Automatically terminate child processes that run for more than \fIn\fR
168seconds. This is useful to detect infinite loops or processes stuck in other
169situations. See also the \fB\-B\fR flag.
170.TP
171\fB\-h\fR, \fB\-\-help\fR
172Display a short help message and exit.
173.TP
174\fB\-v\fR, \fB\-\-version\fR
175Output version information and exit.
176.SH EXAMPLES
177.PP
178Fuzz the input of the \fBcat\fR program using default settings:
179.PP
180\fB    zzuf cat /etc/motd\fR
181.PP
182Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
183.PP
184\fB    zzuf -s 94324 -r 0.01 cat /etc/motd\fR
185.PP
186Fuzz the input of the \fBcat\fR program but do not fuzz newline characters
187and prevent non-ASCII characters from appearing in the output:
188.PP
189\fB    zzuf -P \(aq\\n\(aq -R \(aq\\x00-\\x1f\\x7f-\\xff\(aq cat /etc/motd\fR
190.PP
191Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the
192original input and excluding \fB.xml\fR files from fuzzing (because
193\fBconvert\fR will also open its own XML configuration files and we do not
194want \fBzzuf\fR to fuzz them):
195.PP
196\fB    zzuf -E \(aq\\.xml$\(aq convert -- foo.jpeg -format tga /dev/null\fR
197.PP
198Fuzz the input of \fBVLC\fR, using file \fBmovie.avi\fR as the original input
199and restricting fuzzing to filenames that appear on the command line
200(\fB\-c\fR), then generate \fBfuzzy-movie.avi\fR which is a file that
201can be read by \fBVLC\fR to reproduce the same behaviour without using
202\fBzzuf\fR:
203.PP
204\fB    zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
205\fB    zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
206\fB    vlc fuzzy-movie.avi\fR
207.PP
208Fuzz 2% of \fBMPlayer\fR's input bits (\fB\-r\ 0.02\fR) with seeds 0 to 9999
209(\fB\-s\ 0:10000\fR), disabling its standard output messages (\fB\-q\fR),
210launching up to three simultaneous child processes (\fB\-F\ 3\fR), killing
211\fBMPlayer\fR if it takes more than one minute to read the file (\fB\-T\ 60\fR)
212and disabling its \fBSIGSEGV\fR signal handler (\fB\-S\fR):
213.PP
214\fB    zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
215\fB      mplayer -- -benchmark -vo null -fps 1000 movie.avi\fR
216.SH RESTRICTIONS
217.PP
218Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR on most
219Unix systems, \fBDYLD_INSERT_LIBRARIES\fR on Mac OS X) to run its child
220processes, it will fail in the presence of any mechanism that disables
221preloading. For instance setuid root binaries will not be fuzzed when run
222as an unprivileged user.
223.PP
224Though best efforts are made, identical behaviour for different versions of
225\fBzzuf\fR is not guaranteed. The reproducibility for subsequent calls on
226different operating systems and with different target programs is only
227guaranteed when the same version of \fBzzuf\fR is being used.
228.SH BUGS
229.PP
230It is not yet possible to insert or drop bytes from the input, to fuzz
231according to the file format, to swap bytes, etc. More advanced fuzzing
232methods are planned.
233.PP
234As of now, \fBzzuf\fR does not really support multithreaded applications. The
235behaviour with multithreaded applications where more than one thread does file
236descriptor operations is undefined.
237.SH NOTES
238In order to intercept file and network operations, \fBzzuf\fR diverts and
239reimplements the following functions:
240.TP
241Unix low-level file and socket handling:
242\fBopen\fR(), \fBlseek\fR(), \fBread\fR(), \fBaccept\fR(), \fBsocket\fR(),
243\fBclose\fR()
244.TP
245Standard IO streams:
246\fBfopen\fR(), \fBfseek\fR(), \fBfread\fR(), \fBgetc\fR(), \fBfgetc\fR(),
247\fBfgets\fR(), \fBungetc\fR(), \fBfclose\fR()
248.TP
249GNU libc specific:
250\fBopen64\fR(), \fBlseek64\fR(), \fBgetline\fR(), \fBgetdelim\fR(),
251\fB__getdelim\fR()
252.TP
253BSD specific:
254\fBfgetln\fR()
255.PP
256One important unimplemented function is \fBfscanf\fR() because of its
257important complexity. Missing functions will be implemented based upon user
258request.
259.SH HISTORY
260.PP
261\fBZzuf\fR started its life in 2002 as the \fBstreamfucker\fR tool, a small
262multimedia stream corrupter used to find bugs in the \fBVLC\fR media player.
263.SH AUTHOR
264.PP
265Copyright \(co 2006, 2007 Sam Hocevar <sam@zoy.org>.
266.PP
267\fBZzuf\fR and this manual page are free software. They come without any
268warranty, to the extent permitted by applicable law. You can redistribute
269them and/or modify them under the terms of the Do What The Fuck You Want
270To Public License, Version 2, as published by Sam Hocevar. See
271\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
272.PP
273\fBZzuf\fR's webpage can be found at \fBhttp://sam.zoy.org/zzuf/\fR.
Note: See TracBrowser for help on using the repository browser.