1zzuf(1) General Commands Manual zzuf(1)
2
6 zzuf - multiple purpose fuzzer
7
9 zzuf [-aAcdimnqSvx] [-s seed|-s start:stop] [-r ratio|-r min:max] [-f
10 fuzzing] [-D delay] [-j jobs] [-C crashes] [-B bytes] [-t seconds] [-T
11 seconds] [-U seconds] [-M mebibytes] [-b ranges] [-p ports] [-P pro‐
12 tect] [-R refuse] [-l list] [-I include] [-E exclude] [PROGRAM
13 [ARGS]...]
14 zzuf -h | --help
15 zzuf -V | --version
16
18 zzuf is a transparent application input fuzzer. It works by intercept‐
19 ing file and network operations and changing random bits in the pro‐
20 gram's input. zzuf's behaviour is deterministic, making it easy to
21 reproduce bugs.
22
24 zzuf will run an application specified on its command line, one or sev‐
25 eral times, with optional arguments, and will report the application's
26 relevant behaviour on the standard error channel, eg:
27 zzuf cat /dev/zero
29 Flags found after the application name are considered arguments for the
31 application, not for zzuf. For instance, -v below is an argument for
32 cat:
33 zzuf -B 1000 cat -v /dev/zero
35 When no program is specified, zzuf simply fuzzes the standard input, as
37 if the cat utility had been called:
38 zzuf < /dev/zero
40
42 -a, --allow=list
43 Only fuzz network input for IPs in list, a comma-separated list
44 of IP addresses. If the list starts with !, the flag meaning is
45 reversed and all addresses are fuzzed except the ones in the
46 list.
47 As of now, this flag only understands INET (IPv4) addresses.
49 This option requires network fuzzing to be activated using -n.
51 -A, --autoinc
53 Increment random seed each time a new file is opened. This is
54 only required if one instance of the application is expected to
55 open the same file several times and you want to test a differ‐
56 ent seed each time.
57 -b, --bytes=ranges
59 Restrict fuzzing to bytes whose offsets in the file are within
60 ranges.
61 Range values start at zero and are inclusive. Use dashes between
63 range values and commas between ranges. If the right-hand part
64 of a range is ommited, it means end of file. For instance, to
65 restrict fuzzing to bytes 0, 3, 4, 5 and all bytes after offset
66 31, use ‘-b0,3-5,31-’.
67 This option is useful to preserve file headers or corrupt only a
69 specific portion of a file.
70 -B, --max-bytes=n
72 Automatically stop after n bytes have been output.
73 This either terminates child processes that output more than n
75 bytes on the standard output and standard error channels, or
76 stop reading from standard input if no program is being fuzzed.
77 This is useful to detect infinite loops. See also the -U and -T
79 flags.
80 -c, --cmdline
82 Only fuzz files whose name is specified in the target applica‐
83 tion's command line. This is mostly a shortcut to avoid specify‐
84 ing twice the argument:
85 zzuf -c cat file.txt
87 has the same effect as
89 zzuf -I '^file\.txt$' cat file.txt
91 See the -I flag for more information on restricting fuzzing to
93 specific files.
94 -C, --max-crashes=n
96 Stop forking when at least n children have crashed. The default
97 value is 1, meaning zzuf will stop as soon as one child has
98 crashed. A value of 0 tells zzuf to never stop.
99 Note that zzuf will not kill any remaining children once n is
101 reached. To ensure that processes do not last forever, see the
102 -U flag.
103 A process is considered to have crashed if any signal (such as,
105 but not limited to, SIGSEGV) caused it to exit. If the -x flag
106 is used, this will also include processes that exit with a non-
107 zero status.
108 This option is only relevant if the -s flag is used with a range
110 argument. See also the -t flag.
111 -d, --debug
113 Activate the display of debug messages. Can be specified multi‐
114 ple times for increased verbosity.
115 -D, --delay=delay
117 Do not launch more than one process every delay seconds. This
118 option should be used together with -j to avoid fork bombs.
119 -E, --exclude=regex
121 Do not fuzz files whose name matches the regex regular expres‐
122 sion. This option supersedes anything that is specified by the
123 -I flag. Use this for instance if you are unsure of what files
124 your application is going to read and do not want it to fuzz
125 files in the /etc directory.
126 Multiple -E flags can be specified, in which case files matching
128 any one of the regular expressions will be ignored.
129 -f, --fuzzing=mode
131 Select how the input is fuzzed. Valid values for mode are:
132 xor randomly set and unset bits
134 set only set bits
136 unset only unset bits
138 The default value for mode is xor.
140 -j, --jobs=jobs
142 Specify the number of simultaneous children that can be run. By
143 default, zzuf only launches one process at a time.
144 This option is only relevant if the -s flag is used with a range
146 argument. See also the -D flag.
147 -i, --stdin
149 Fuzz the application's standard input. By default zzuf only
150 fuzzes files.
151 -I, --include=regex
153 Only fuzz files whose name matches the regex regular expression.
154 Use this for instance if your application reads configuration
155 files at startup and you only want specific files to be fuzzed.
156 Multiple -I flags can be specified, in which case files matching
158 any one of the regular expressions will be fuzzed. See also the
159 -c flag.
160 -l, --list=list
162 Cherry-pick the list of file descriptors that get fuzzed. The
163 Nth descriptor will really be fuzzed only if N is in list.
164 Values start at 1 and ranges are inclusive. Use dashes between
166 values and commas between ranges. If the right-hand part of a
167 range is ommited, it means all subsequent file descriptors. For
168 instance, to restrict fuzzing to the first opened descriptor and
169 all descriptors starting from the 10th, use ‘-l1,10-’.
170 Note that this option only affects file descriptors that would
172 otherwise be fuzzed. Even if 10 write-only descriptors are
173 opened at the beginning of the program, only the next descriptor
174 with a read flag will be the first one considered by the -l
175 flag.
176 -m, --md5
178 Instead of displaying the program's standard output, just print
179 its MD5 digest to zzuf's standard output. The standard error
180 channel is left untouched.
181 -M, --max-memory=mebibytes
183 Specify the maximum amount of memory, in mebibytes (1 MiB =
184 1,048,576 bytes), that children are allowed to allocate. This is
185 useful to detect infinite loops that eat up a lot of memory.
186 The value should be set reasonably high so as not to interfer
188 with normal program operation. By default, it is set to 1024 MiB
189 in order to avoid accidental excessive swapping. To disable the
190 limitation, set the maximum memory usage to -1 instead.
191 zzuf uses the setrlimit() call to set memory usage limitations
193 and relies on the operating system's ability to enforce such
194 limitations.
195 -n, --network
197 Fuzz the application's network input. By default zzuf only
198 fuzzes files.
199 Only INET (IPv4) and INET6 (IPv6) connections are fuzzed. Other
201 protocol families are not yet supported.
202 -p, --ports=ranges
204 Only fuzz network ports that are in ranges. By default zzuf
205 fuzzes all ports. The port considered is the listening port if
206 the socket is listening and the destination port if the socket
207 is connecting, because most of the time the source port cannot
208 be predicted.
209 Range values start at zero and are inclusive. Use dashes between
211 range values and commas between ranges. If the right-hand part
212 of a range is ommited, it means end of file. For instance, to
213 restrict fuzzing to the HTTP and HTTPS ports and to all unprivi‐
214 leged ports, use ‘-p80,443,1024-’.
215 This option requires network fuzzing to be activated using -n.
217 -P, --protect=list
219 Protect a list of characters so that if they appear in input
220 data that would normally be fuzzed, they are left unmodified
221 instead.
222 Characters in list can be expressed verbatim or through escape
224 sequences. The sequences interpreted by zzuf are:
225 \n new line
227 \r return
229 \t tabulation
231 \NNN the byte whose octal value is NNN
233 \xNN the byte whose hexadecimal value is NN
235 \\ backslash (‘\’)
237 You can use ‘-’ to specify ranges. For instance, to protect all
239 bytes from ‘\001’ to ‘/’, use ‘-P '\001-/'’.
240 The statistical outcome of this option should not be overlooked:
242 if characters are protected, the effect of the ‘-r’ flag will
243 vary depending on the data being fuzzed. For instance, asking to
244 fuzz 1% of input bits (-r0.01) and to protect lowercase charac‐
245 ters (-P a-z) will result in an actual average fuzzing ratio of
246 0.9% with truly random data, 0.3% with random ASCII data and
247 0.2% with standard English text.
248 See also the -R flag.
250 -q, --quiet
252 Hide the output of the fuzzed application. This is useful if the
253 application is very verbose but only its exit code or signaled
254 status is really useful to you.
255 -r, --ratio=ratio
257 -r, --ratio=min:max
258 Specify the proportion of bits that will be randomly fuzzed. A
259 value of 0 will not fuzz anything. A value of 0.05 will fuzz 5%
260 of the open files' bits. A value of 1.0 or more will fuzz all
261 the bytes, theoretically making the input files undiscernible
262 from random data. The default fuzzing ratio is 0.004 (fuzz 0.4%
263 of the files' bits).
264 A range can also be specified. When doing so, zzuf will pick
266 ratio values from the interval. The choice is deterministic and
267 only depends on the interval bounds and the current seed.
268 -R, --refuse=list
270 Refuse a list of characters by not fuzzing bytes that would oth‐
271 erwise be changed to a character that is in list. This does not
272 prevent characters from appearing in the output if the original
273 byte was already in list.
274 See the -P option for a description of list.
276 -s, --seed=seed
278 -s, --seed=start:stop
279 Specify the random seed to use for fuzzing, or a range of random
280 seeds. Running zzuf twice with the same random seed will fuzz
281 the files exactly the same way, even with a different target
282 application. The purpose of this is to use simple utilities such
283 as cat or cp to generate a file that causes the target applica‐
284 tion to crash.
285 If a range is specified, zzuf will run the application several
287 times, each time with a different seed, and report the behaviour
288 of each run. If the ‘:’ character is used but the second part of
289 the range is omitted, zzuf will increment the seed value indefi‐
290 nitely.
291 -S, --signal
293 Prevent children from installing signal handlers for signals
294 that usually cause coredumps. These signals are SIGABRT, SIGFPE,
295 SIGILL, SIGQUIT, SIGSEGV, SIGTRAP and, if available on the run‐
296 ning platform, SIGSYS, SIGEMT, SIGBUS, SIGXCPU and SIGXFSZ.
297 Instead of calling the signal handler, the application will sim‐
298 ply crash. If you do not want core dumps, you should set appro‐
299 priate limits with the limit coredumpsize command. See your
300 shell's documentation on how to set such limits.
301 -t, --max-time=n
303 Stop forking after n seconds. By default, zzuf runs until the
304 end of the seed range is reached.
305 Note that zzuf will not kill any remaining children once n is
307 reached. To ensure that processes do not last forever, see the
308 -U flag.
309 This option is only relevant if the -s flag is used with a range
311 argument. See also the -C flag.
312 -T, --max-cputime=n
314 Automatically terminate child processes that use more than n
315 seconds of CPU time.
316 zzuf uses the setrlimit() call to set CPU usage limitations and
318 relies on the operating system's ability to enforce such limita‐
319 tions. If the system sends SIGXCPU signals and the application
320 catches that signal, it will receive a SIGKILL signal after 5
321 seconds.
322 This is more accurate than -U because the behaviour should be
324 independent from the system load, but it does not detect pro‐
325 cesses stuck into infinite select() calls because they use very
326 little CPU time. See also the -B and -U flags.
327 -U, --max-usertime=n
329 Automatically terminate child processes that run for more than n
330 seconds. This is useful to detect infinite loops or processes
331 stuck in other situations. See also the -B and -T flags.
332 -v, --verbose
334 Print information during the run, such as the current seed, what
335 processes get run, their exit status, etc.
336 -x, --check-exit
338 Report processes that exit with a non-zero status. By default
339 only processes that crash due to a signal are reported.
340 -h, --help
342 Display a short help message and exit.
343 -V, --version
345 Output version information and exit.
346
348 Exit status is zero if no child process crashed. If one or several
349 children crashed, zzuf exits with status 1.
350
352 Fuzz the input of the cat program using default settings:
353 zzuf cat /etc/motd
355 Fuzz 1% of the input bits of the cat program using seed 94324:
357 zzuf -s94324 -r0.01 cat /etc/motd
359 Fuzz the input of the cat program but do not fuzz newline characters
361 and prevent non-ASCII characters from appearing in the output:
362 zzuf -P '\n' -R '\x00-\x1f\x7f-\xff' cat /etc/motd
364 Fuzz the input of the convert program, using file foo.jpeg as the orig‐
366 inal input and excluding .xml files from fuzzing (because convert will
367 also open its own XML configuration files and we do not want zzuf to
368 fuzz them):
369 zzuf -E '\.xml$' convert foo.jpeg -format tga /dev/null
371 Fuzz the input of VLC, using file movie.avi as the original input and
373 restricting fuzzing to filenames that appear on the command line (-c),
374 then generate fuzzy-movie.avi which is a file that can be read by VLC
375 to reproduce the same behaviour without using zzuf:
376 zzuf -c -s87423 -r0.01 vlc movie.avi
378 zzuf -c -s87423 -r0.01 <movie.avi >fuzzy-movie.avi
379 vlc fuzzy-movie.avi
380 Fuzz between 0.1% and 2% of MPlayer's input bits (-r0.001:0.02) with
382 seeds 0 to 9999 (-s0:10000), preserving the AVI 4-byte header by
383 restricting fuzzing to offsets after 4 (-b4-), disabling its standard
384 output messages (-q), launching up to five simultaneous child processes
385 (-j5) but waiting at least half a second between launches (-D0.5),
386 killing MPlayer if it takes more than one minute to read the file
387 (-T60) and disabling its SIGSEGV signal handler (-S):
388 zzuf -c -r0.001:0.02 -s0:10000 -b4- -q -j5 -D0.5 -T60 -S \
390 mplayer -benchmark -vo null -fps 1000 movie.avi
391 A more advanced VLC fuzzing example, stopping only at the first crash:
393 zzuf -j4 -vqc -r0.000001:0.01 -s0: vlc -v -I dummy movie.avi \
395 --sout '#transcode{acodec=s16l,vcodec=I420}:dummy' vlc:quit
396 Create an HTML-like file that loads 200 times the same hello.jpg image
398 and open it in Firefox™ in auto-increment mode (-A):
399 seq -f '<img src="hello.jpg#%g">' 1 200 > hello.html
401 (or: jot -w '<img src="hello.jpg#%d">' 200 1 > hello.html)
402 zzuf -A -I 'hello[.]jpg' -r0.001 firefox hello.html
403 Run a simple HTTP redirector on the local host using socat and corrupt
405 each network connection (-n) in a different way (-A) after one megabyte
406 of data was received on it (-b1000000-):
407 zzuf -n -A -b1000000- \
409 socat TCP4-LISTEN:8080,reuseaddr,fork TCP4:192.168.1.42:80
410 Browse the intarweb (-n) using Firefox™ without fuzzing local files
412 (-E.) or non-HTTP connections (-p80,8010,8080), preserving the begin‐
413 ning of the data sent with each HTTP response (-b4000-) and using
414 another seed on each connection (-A):
415 zzuf -r 0.0001 -n -E. -p80,8010,8080 -b4000- -A firefox
417
419 Due to zzuf using shared object preloading (LD_PRELOAD, _RLD_LIST,
420 DYLD_INSERT_LIBRARIES, etc.) to run its child processes, it will fail
421 in the presence of any mechanism that disables preloading. For instance
422 setuid root binaries will not be fuzzed when run as an unprivileged
423 user.
424 For the same reasons, zzuf will also not work with statically linked
426 binaries. Bear this in mind when using zzuf on the OpenBSD platform,
427 where cat, cp and dd are static binaries.
428 Though best efforts are made, identical behaviour for different ver‐
430 sions of zzuf is not guaranteed. The reproducibility for subsequent
431 calls on different operating systems and with different target programs
432 is only guaranteed when the same version of zzuf is being used.
433
435 zzuf probably does not behave correctly with 64-bit offsets.
436 It is not yet possible to insert or drop bytes from the input, to fuzz
438 according to the file format, to swap bytes, etc. More advanced fuzzing
439 methods are planned.
440 As of now, zzuf does not really support multithreaded applications. The
442 behaviour with multithreaded applications where more than one thread
443 does file descriptor operations is undefined.
444
446 zzuf started its life in 2002 as the streamfucker tool, a small multi‐
447 media stream corrupter used to find bugs in the VLC media player.
448
450 libzzuf(3), zzcat(1)
451
453 Copyright © 2002-2010 Sam Hocevar <sam@hocevar.net>.
454 zzuf and this manual page are free software. They come without any war‐
456 ranty, to the extent permitted by applicable law. You can redistribute
457 them and/or modify them under the terms of the Do What The Fuck You
458 Want To Public License, Version 2, as published by Sam Hocevar. See
459 http://sam.zoy.org/wtfpl/COPYING for more details.
460 zzuf's webpage can be found at http://caca.zoy.org/wiki/zzuf. An over‐
462 view of the architecture and inner works is at
463 http://caca.zoy.org/wiki/zzuf/internals.
464zzuf 0.13 2010-01-31 zzuf(1)