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

Last change on this file since 3001 was 3001, checked in by Sam Hocevar, 12 years ago

Rename --max-cpu into --max-cputime to avoid confusion (fixes #44).

File size: 17.9 KB
Line 
1.TH zzuf 1 "2006-12-22" "zzuf"
2.SH NAME
3zzuf \- multiple purpose fuzzer
4.SH SYNOPSIS
5\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]
6.br
7       [\fB\-f\fR \fIfuzzing\fR] [\fB\-D\fR \fIdelay\fR] [\fB\-j\fR \fIjobs\fR] [\fB\-C\fR \fIcrashes\fR] [\fB\-B\fR \fIbytes\fR]
8.br
9       [\fB\-t\fR \fIseconds\fR] [\fB\-T\fR \fIseconds\fR] [\fB\-M\fR \fImebibytes\fR] [\fB\-b\fR \fIranges\fR] [\fB\-p\fR \fIports\fR]
10.br
11       [\fB\-P\fR \fIprotect\fR] [\fB\-R\fR \fIrefuse\fR] [\fB\-l\fR \fIlist\fR] [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR]
12.br
13       [\fIPROGRAM\fR [\fIARGS\fR]...]
14.br
15\fBzzuf \-h\fR | \fB\-\-help\fR
16.br
17\fBzzuf \-V\fR | \fB\-\-version\fR
18.SH DESCRIPTION
19.PP
20\fBzzuf\fR is a transparent application input fuzzer. It works by intercepting
21file and network operations and changing random bits in the program's input.
22\fBzzuf\fR's behaviour is deterministic, making it easy to reproduce bugs.
23.SH USAGE
24.PP
25\fBzzuf\fR will run an application specified on its command line, one or
26several times, with optional arguments, and will report the application's
27relevant behaviour on the standard error channel, eg:
28.PP
29\fB    zzuf cat /dev/zero\fR
30.PP
31Flags found after the application name are considered arguments for the
32application, not for \fBzzuf\fR. For instance, \fB\-v\fR below is an
33argument for \fBcat\fR:
34.PP
35\fB    zzuf \-B 1000 cat \-v /dev/zero\fR
36.PP
37When no program is specified, \fBzzuf\fR simply fuzzes the standard input, as
38if the \fBcat\fR utility had been called:
39.PP
40\fB    zzuf < /dev/zero\fR
41.SH OPTIONS
42.TP
43\fB\-A\fR, \fB\-\-autoinc\fR
44Increment random seed each time a new file is opened. This is only required
45if one instance of the application is expected to open the same file several
46times and you want to test a different seed each time.
47.TP
48\fB\-b\fR, \fB\-\-bytes\fR=\fIranges\fR
49Restrict fuzzing to bytes whose offsets in the file are within \fIranges\fR.
50
51Range values start at zero and are inclusive. Use dashes between range values
52and commas between ranges. If the right-hand part of a range is ommited, it
53means end of file. For instance, to restrict fuzzing to bytes 0, 3, 4, 5 and
54all bytes after offset 31, use \(oq\fB\-b0,3\-5,31\-\fR\(cq.
55
56This option is useful to preserve file headers or corrupt only a specific
57portion of a file.
58.TP
59\fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR
60Automatically stop after \fIn\fR bytes have been output.
61
62This either terminates child processes that output more than \fIn\fR bytes
63on the standard output and standard error channels, or stop reading from
64standard input if no program is being fuzzed.
65
66This is useful to detect infinite loops. See also the \fB\-t\fR and \fB\-T\fR
67flags.
68.TP
69\fB\-c\fR, \fB\-\-cmdline\fR
70Only fuzz files whose name is specified in the target application's command
71line. This is mostly a shortcut to avoid specifying twice the argument:
72
73\fB    zzuf \-c cat file.txt\fR
74
75has the same effect as
76
77\fB    zzuf \-I \(aq^file\\.txt$\(aq cat file.txt\fR
78
79See the \fB\-I\fR flag for more information on restricting fuzzing to
80specific files.
81.TP
82\fB\-C\fR, \fB\-\-max\-crashes\fR=\fIn\fR
83Stop forking when at least \fIn\fR children have crashed. The default value
84is 1, meaning \fBzzuf\fR will stop as soon as one child has crashed. A value
85of 0 tells \fBzzuf\fR to never stop.
86
87A process is considered to have crashed if any signal (such as, but not limited
88to, \fBSIGSEGV\fR) caused it to exit. If the \fB\-x\fR flag is used, this will
89also include processes that exit with a non-zero status.
90
91This option is only relevant if the \fB\-s\fR flag is used with a range
92argument.
93.TP
94\fB\-d\fR, \fB\-\-debug\fR
95Activate the display of debug messages.
96.TP
97\fB\-D\fR, \fB\-\-delay\fR=\fIdelay\fR
98Do not launch more than one process every \fIdelay\fR seconds. This option
99should be used together with \fB\-j\fR to avoid fork bombs.
100.TP
101\fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR
102Do not fuzz files whose name matches the \fIregex\fR regular expression. This
103option supersedes anything that is specified by the \fB\-I\fR flag. Use this
104for instance if you are unsure of what files your application is going to read
105and do not want it to fuzz files in the \fB/etc\fR directory.
106
107Multiple \fB\-E\fR flags can be specified, in which case files matching any one
108of the regular expressions will be ignored.
109.TP
110\fB\-f\fR, \fB\-\-fuzzing\fR=\fImode\fR
111Select how the input is fuzzed. Valid values for \fImode\fR are:
112.RS
113.TP
114\fBxor\fR
115randomly set and unset bits
116.TP
117\fBset\fR
118only set bits
119.TP
120\fBunset\fR
121only unset bits
122.RE
123.IP
124The default value for \fImode\fR is \fBxor\fR.
125.TP
126\fB\-j\fR, \fB\-\-jobs\fR=\fIjobs\fR
127Specify the number of simultaneous children that can be run. By default,
128\fBzzuf\fR only launches one process at a time.
129
130This option is only relevant if the \fB\-s\fR flag is used with a range
131argument. See also the \fB\-D\fR flag.
132.TP
133\fB\-i\fR, \fB\-\-stdin\fR
134Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files.
135.TP
136\fB\-I\fR, \fB\-\-include\fR=\fIregex\fR
137Only fuzz files whose name matches the \fIregex\fR regular expression. Use
138this for instance if your application reads configuration files at startup
139and you only want specific files to be fuzzed.
140
141Multiple \fB\-I\fR flags can be specified, in which case files matching any one
142of the regular expressions will be fuzzed. See also the \fB\-c\fR flag.
143.TP
144\fB\-l\fR, \fB\-\-list\fR=\fIlist\fR
145Cherry-pick the list of file descriptors that get fuzzed. The Nth descriptor
146will really be fuzzed only if N is in \fIlist\fR.
147
148Values start at 1 and ranges are inclusive. Use dashes between values and
149commas between ranges. If the right-hand part of a range is ommited, it means
150all subsequent file descriptors. For instance, to restrict fuzzing to the
151first opened descriptor and all descriptors starting from the 10th, use
152\(oq\fB\-l1,10\-\fR\(cq.
153
154Note that this option only affects file descriptors that would otherwise be
155fuzzed. Even if 10 write-only descriptors are opened at the beginning of the
156program, only the next descriptor with a read flag will be the first one
157considered by the \fB\-l\fR flag.
158.TP
159\fB\-m\fR, \fB\-\-md5\fR
160Instead of displaying the program's \fIstandard output\fR, just print its MD5
161digest to \fBzzuf\fR's standard output. The standard error channel is left
162untouched.
163.TP
164\fB\-M\fR, \fB\-\-max\-memory\fR=\fImebibytes\fR
165Specify the maximum amount of memory, in mebibytes (1 MiB = 1,048,576 bytes),
166that children are allowed to allocate. This is useful to detect infinite loops
167that eat up a lot of memory.
168
169The value should be set reasonably high so as not to interfer with normal
170program operation. By default, it is set to 1024 MiB in order to avoid
171accidental excessive swapping. To disable the limitation, set the maximum
172memory usage to -1 instead.
173
174\fBzzuf\fR uses the \fBsetrlimit\fR() call to set memory usage limitations and
175relies on the operating system's ability to enforce such limitations.
176.TP
177\fB\-n\fR, \fB\-\-network\fR
178Fuzz the application's network input. By default \fBzzuf\fR only fuzzes files.
179
180Only INET (IPv4) and INET6 (IPv6) connections are fuzzed. Other protocol
181families are not yet supported.
182.TP
183\fB\-p\fR, \fB\-\-ports\fR=\fIranges\fR
184Only fuzz network ports that are in \fIranges\fR. By default \fBzzuf\fR
185fuzzes all ports. The port considered is the listening port if the socket
186is listening and the destination port if the socket is connecting, because
187most of the time the source port cannot be predicted.
188
189Range values start at zero and are inclusive. Use dashes between range values
190and commas between ranges. If the right-hand part of a range is ommited, it
191means end of file. For instance, to restrict fuzzing to the HTTP and HTTPS
192ports and to all unprivileged ports, use \(oq\fB\-p80,443,1024\-\fR\(cq.
193
194This option requires network fuzzing to be activated using \fB\-n\fR.
195.TP
196\fB\-P\fR, \fB\-\-protect\fR=\fIlist\fR
197Protect a list of characters so that if they appear in input data that would
198normally be fuzzed, they are left unmodified instead.
199
200Characters in \fIlist\fR can be expressed verbatim or through escape sequences.
201The sequences interpreted by \fBzzuf\fR are:
202.RS
203.TP
204\fB\\n\fR
205new line
206.TP
207\fB\\r\fR
208return
209.TP
210\fB\\t\fR
211tabulation
212.TP
213\fB\\\fR\fINNN\fR
214the byte whose octal value is \fINNN\fR
215.TP
216\fB\\x\fR\fINN\fR
217the byte whose hexadecimal value is \fINN\fR
218.TP
219\fB\\\\\fR
220backslash (\(oq\\\(cq)
221.RE
222.IP
223You can use \(oq\fB\-\fR\(cq to specify ranges. For instance, to protect all
224bytes from \(oq\\001\(cq to \(oq/\(cq, use \(oq\fB\-P\ \(aq\\001\-/\(aq\fR\(cq.
225
226The statistical outcome of this option should not be overlooked: if characters
227are protected, the effect of the \(oq\fB\-r\fR\(cq flag will vary depending
228on the data being fuzzed. For instance, asking to fuzz 1% of input bits
229(\fB\-r0.01\fR) and to protect lowercase characters (\fB\-P\ a\-z\fR) will
230result in an actual average fuzzing ratio of 0.9% with truly random data,
2310.3% with random ASCII data and 0.2% with standard English text.
232
233See also the \fB\-R\fR flag.
234.TP
235\fB\-q\fR, \fB\-\-quiet\fR
236Hide the output of the fuzzed application. This is useful if the application
237is very verbose but only its exit code or signaled status is really useful to
238you.
239.TP
240\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
241.PD 0
242.TP
243\fB\-r\fR, \fB\-\-ratio\fR=\fImin:max\fR
244.PD
245Specify the proportion of bits that will be randomly fuzzed. A value of 0
246will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
247bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
248the input files undiscernible from random data. The default fuzzing ratio
249is 0.004 (fuzz 0.4% of the files' bits).
250
251A range can also be specified. When doing so, \fBzzuf\fR will pick ratio
252values from the interval. The choice is deterministic and only depends on
253the interval bounds and the current seed.
254.TP
255\fB\-R\fR, \fB\-\-refuse\fR=\fIlist\fR
256Refuse a list of characters by not fuzzing bytes that would otherwise be
257changed to a character that is in \fIlist\fR. This does not prevent characters
258from appearing in the output if the original byte was already in \fIlist\fR.
259
260See the \fB\-P\fR option for a description of \fIlist\fR.
261.TP
262\fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR
263.PD 0
264.TP
265\fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR
266.PD
267Specify the random seed to use for fuzzing, or a range of random seeds.
268Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly
269the same way, even with a different target application. The purpose of this is
270to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that
271causes the target application to crash.
272
273If a range is specified, \fBzzuf\fR will run the application several times,
274each time with a different seed, and report the behaviour of each run. If the
275\(oq:\(cq character is used but the second part of the range is omitted,
276\fBzzuf\fR will increment the seed value indefinitely.
277.TP
278\fB\-S\fR, \fB\-\-signal\fR
279Prevent children from installing signal handlers for signals that usually
280cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR,
281\fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running
282platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and
283\fBSIGXFSZ\fR. Instead of calling the signal handler, the application will
284simply crash. If you do not want core dumps, you should set appropriate limits
285with the \fBlimit coredumpsize\fR command. See your shell's documentation on
286how to set such limits.
287.TP
288\fB\-t\fR, \fB\-\-max\-time\fR=\fIn\fR
289Automatically terminate child processes that run for more than \fIn\fR
290seconds. This is useful to detect infinite loops or processes stuck in other
291situations. See also the \fB\-B\fR and \fB\-T\fR flags.
292.TP
293\fB\-T\fR, \fB\-\-max\-cputime\fR=\fIn\fR
294Automatically terminate child processes that use more than \fIn\fR seconds
295of CPU time.
296
297\fBzzuf\fR uses the \fBsetrlimit\fR() call to set CPU usage limitations and
298relies on the operating system's ability to enforce such limitations. If the
299system sends \fBSIGXCPU\fR signals and the application catches that signal,
300it will receive a \fBSIGKILL\fR signal after 5 seconds.
301
302This is more accurate than \fB\-t\fR because the behaviour should be
303independent from the system load, but it does not detect processes stuck into
304infinite \fBselect\fR() calls because they use very little CPU time. See also
305the \fB\-B\fR and \fB\-t\fR flags.
306.TP
307\fB\-v\fR, \fB\-\-verbose\fR
308Print information during the run, such as the current seed, what processes
309get run, their exit status, etc.
310.TP
311\fB\-x\fR, \fB\-\-check\-exit\fR
312Report processes that exit with a non-zero status. By default only processes
313that crash due to a signal are reported.
314.TP
315\fB\-h\fR, \fB\-\-help\fR
316Display a short help message and exit.
317.TP
318\fB\-V\fR, \fB\-\-version\fR
319Output version information and exit.
320.SH DIAGNOSTICS
321.PP
322Exit status is zero if no child process crashed. If one or several children
323crashed, \fBzzuf\fR exits with status 1.
324.SH EXAMPLES
325.PP
326Fuzz the input of the \fBcat\fR program using default settings:
327.PP
328\fB    zzuf cat /etc/motd\fR
329.PP
330Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324:
331.PP
332\fB    zzuf \-s94324 \-r0.01 cat /etc/motd\fR
333.PP
334Fuzz the input of the \fBcat\fR program but do not fuzz newline characters
335and prevent non-ASCII characters from appearing in the output:
336.PP
337\fB    zzuf \-P \(aq\\n\(aq \-R \(aq\\x00\-\\x1f\\x7f\-\\xff\(aq cat /etc/motd\fR
338.PP
339Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the
340original input and excluding \fB.xml\fR files from fuzzing (because
341\fBconvert\fR will also open its own XML configuration files and we do not
342want \fBzzuf\fR to fuzz them):
343.PP
344\fB    zzuf \-E \(aq\\.xml$\(aq convert foo.jpeg \-format tga /dev/null\fR
345.PP
346Fuzz the input of VLC, using file \fBmovie.avi\fR as the original input
347and restricting fuzzing to filenames that appear on the command line
348(\fB\-c\fR), then generate \fBfuzzy\-movie.avi\fR which is a file that
349can be read by VLC to reproduce the same behaviour without using
350\fBzzuf\fR:
351.PP
352\fB    zzuf \-c \-s87423 \-r0.01 vlc movie.avi\fR
353.br
354\fB    zzuf \-c \-s87423 \-r0.01 <movie.avi >fuzzy\-movie.avi\fR
355.br
356\fB    vlc fuzzy\-movie.avi\fR
357.PP
358Fuzz between 0.1% and 2% of MPlayer's input bits (\fB\-r0.001:0.02\fR)
359with seeds 0 to 9999 (\fB\-s0:10000\fR), preserving the AVI 4-byte header
360by restricting fuzzing to offsets after 4 (\fB\-b4\-\fR), disabling its
361standard output messages (\fB\-q\fR), launching up to five simultaneous child
362processes (\fB\-j5\fR) but waiting at least half a second between launches
363(\fB\-D0.5\fR), killing MPlayer if it takes more than one minute to
364read the file (\fB\-T60\fR) and disabling its \fBSIGSEGV\fR signal handler
365(\fB\-S\fR):
366.PP
367\fB    zzuf \-c \-r0.001:0.02 \-s0:10000 \-b4\- \-q \-j5 \-D0.5 \-T60 \-S \\\fR
368.br
369\fB      mplayer \-benchmark \-vo null \-fps 1000 movie.avi\fR
370.PP
371A more advanced VLC fuzzing example, stopping only at the first crash:
372.PP
373\fB    zzuf \-j4 \-vqc \-r0.000001:0.01 \-s0: vlc \-v \-I dummy movie.avi \\\fR
374.br
375\fB       \-\-sout \(aq#transcode{acodec=s16l,vcodec=I420}:dummy\(aq vlc:quit
376.PP
377Create an HTML-like file that loads 200 times the same \fBhello.jpg\fR image
378and open it in Firefox\(tm in auto-increment mode (\fB\-A\fR):
379.PP
380\fB    seq \-f \(aq<img src="hello.jpg#%g">\(aq 1 200 > hello.html\fR
381.br
382      (or: \fBjot \-w \(aq<img src="hello.jpg#%d">\(aq 200 1 > hello.html\fR)
383.br
384\fB    zzuf \-A \-I \(aqhello[.]jpg\(aq \-r0.001 firefox hello.html\fR
385.PP
386Run a simple HTTP redirector on the local host using \fBsocat\fR and
387corrupt each network connection (\fB\-n\fR) in a different way (\fB\-A\fR)
388after one megabyte of data was received on it (\fB\-b1000000\-\fR):
389.PP
390\fB     zzuf \-n \-A \-b1000000\- \\\fR
391\fB       socat TCP4\-LISTEN:8080,reuseaddr,fork TCP4:192.168.1.42:80\fR
392.PP
393Browse the intarweb (\fB\-n\fR) using Firefox\(tm without fuzzing local files
394(\fB\-E.\fR) or non-HTTP connections (\fB\-p80,8010,8080\fR), preserving
395the beginning of the data sent with each HTTP response (\fB\-b4000\-\fR)
396and using another seed on each connection (\fB\-A\fR):
397.PP
398\fB    zzuf \-r 0.0001 \-n \-E. \-p80,8010,8080 \-b4000\- \-A firefox\fR
399.SH RESTRICTIONS
400.PP
401Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR,
402\fB_RLD_LIST\fB, \fBDYLD_INSERT_LIBRARIES\fR, etc.) to run its child
403processes, it will fail in the presence of any mechanism that disables
404preloading. For instance setuid root binaries will not be fuzzed when run
405as an unprivileged user.
406.PP
407For the same reasons, \fBzzuf\fR will also not work with statically linked
408binaries. Bear this in mind when using \fBzzuf\fR on the OpenBSD platform,
409where \fBcat\fR, \fBcp\fR and \fBdd\fR are static binaries.
410.PP
411Though best efforts are made, identical behaviour for different versions of
412\fBzzuf\fR is not guaranteed. The reproducibility for subsequent calls on
413different operating systems and with different target programs is only
414guaranteed when the same version of \fBzzuf\fR is being used.
415.SH BUGS
416.PP
417\fBzzuf\fR probably does not behave correctly with 64-bit offsets.
418.PP
419It is not yet possible to insert or drop bytes from the input, to fuzz
420according to the file format, to swap bytes, etc. More advanced fuzzing
421methods are planned.
422.PP
423As of now, \fBzzuf\fR does not really support multithreaded applications. The
424behaviour with multithreaded applications where more than one thread does file
425descriptor operations is undefined.
426.SH HISTORY
427.PP
428\fBzzuf\fR started its life in 2002 as the \fBstreamfucker\fR tool, a small
429multimedia stream corrupter used to find bugs in the VLC media player.
430.SH SEE ALSO
431.PP
432\fBlibzzuf(3)\fR
433.SH AUTHOR
434.PP
435Copyright \(co 2002, 2007\-2008 Sam Hocevar <sam@zoy.org>.
436.PP
437\fBzzuf\fR and this manual page are free software. They come without any
438warranty, to the extent permitted by applicable law. You can redistribute
439them and/or modify them under the terms of the Do What The Fuck You Want
440To Public License, Version 2, as published by Sam Hocevar. See
441\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
442.PP
443\fBzzuf\fR's webpage can be found at \fBhttp://libcaca.zoy.org/wiki/zzuf\fR.
Note: See TracBrowser for help on using the repository browser.