source: zzuf/trunk/doc/zzuf.1.in @ 4393

Last change on this file since 4393 was 4393, checked in by Sam Hocevar, 11 years ago

New operating mode "copy". It uses temporary files instead of preloading
libzzuf into the process.

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