1zzuf(1) General Commands Manual zzuf(1)
2
6 zzuf - multiple purpose fuzzer
7
9 zzuf [-AcdimnqSvxX] [-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] [-a list] [-l list] [-I include] [-E exclude] [-O
13 opmode] [PROGRAM [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 Generic program information
43 -h, --help
44 Display a short help message and exit.
45 -V, --version
47 Output version information and exit.
48 Operating mode
50 -f, --fuzzing=mode
51 Select how the input is fuzzed. Valid values for mode are:
52 xor randomly set and unset bits
54 set only set bits
56 unset only unset bits
58 The default value for mode is xor.
60 -O, --opmode=mode
62 Use operating mode mode. Valid values for mode are:
63 preload
65 override functions by preloading libzzuf into the exe‐
66 cutable using the system's dynamic linker
67 copy temporarily copy files that need to be fuzzed
69 The default value for mode is preload. copy is useful on plat‐
71 forms that do not support dynamic linker injection, for instance
72 when fuzzing a Cocoa application on Mac OS X.
73 -s, --seed=seed
75 -s, --seed=start:
76 -s, --seed=start:stop
77 Specify the random seed to use for fuzzing, or a range of random
78 seeds. Running zzuf twice with the same random seed will fuzz
79 the files exactly the same way, even with a different target
80 application. The purpose of this is to use simple utilities such
81 as cat or cp to generate a file that causes the target applica‐
82 tion to crash.
83 If a range is specified, zzuf will run the application several
85 times, each time with a different seed, and report the behaviour
86 of each run. If no ‘stop’ is specified after ‘:’, zzuf will
87 increment the seed value indefinitely.
88 -r, --ratio=ratio
90 -r, --ratio=min:max
91 Specify the proportion of bits that will be randomly fuzzed. A
92 value of 0 will not fuzz anything. A value of 0.05 will fuzz 5%
93 of the open files' bits. A value of 1.0 or more will fuzz all
94 the bytes, theoretically making the input files undiscernible
95 from random data. The default fuzzing ratio is 0.004 (fuzz 0.4%
96 of the files' bits).
97 A range can also be specified. When doing so, zzuf will pick
99 ratio values from the interval. The choice is deterministic and
100 only depends on the interval bounds and the current seed.
101 -A, --autoinc
103 Increment random seed each time a new file is opened. This is
104 only required if one instance of the application is expected to
105 open the same file several times and you want to test a differ‐
106 ent seed each time.
107 Output
109 -d, --debug
110 Activate the display of debug messages. Can be specified multi‐
111 ple times for increased verbosity.
112 -q, --quiet
114 Hide the output of the fuzzed application. This is useful if the
115 application is very verbose but only its exit code or signaled
116 status is really useful to you.
117 -v, --verbose
119 Print information during the run, such as the current seed, what
120 processes get run, their exit status, etc.
121 -m, --md5
123 Instead of displaying the program's standard output, just print
124 its MD5 digest to zzuf's standard output. The standard error
125 channel is left untouched. See also the -X flag.
126 -X, --hex
128 Convert the fuzzed program's standard output to hexadecimal. The
129 standard error channel is left untouched. See also the -m flag.
130 Process control
132 -B, --max-bytes=n
133 Automatically stop after n bytes have been output.
134 This either terminates child processes that output more than n
136 bytes on the standard output and standard error channels, or
137 stop reading from standard input if no program is being fuzzed.
138 This is useful to detect infinite loops. See also the -U and -T
140 flags.
141 -C, --max-crashes=n
143 Stop forking when at least n children have crashed. The default
144 value is 1, meaning zzuf will stop as soon as one child has
145 crashed. A value of 0 tells zzuf to never stop.
146 Note that zzuf will not kill any remaining children once n is
148 reached. To ensure that processes do not last forever, see the
149 -U flag.
150 A process is considered to have crashed if any signal (such as,
152 but not limited to, SIGSEGV) caused it to exit. If the -x flag
153 is used, this will also include processes that exit with a non-
154 zero status.
155 This option is only relevant if the -s flag is used with a range
157 argument. See also the -t flag.
158 -D, --delay=delay
160 Do not launch more than one process every delay seconds. This
161 option should be used together with -j to avoid fork bombs.
162 -j, --jobs=jobs
164 Specify the number of simultaneous children that can be run. By
165 default, zzuf only launches one process at a time.
166 This option is only relevant if the -s flag is used with a range
168 argument. See also the -D flag.
169 -M, --max-memory=mebibytes
171 Specify the maximum amount of memory, in mebibytes (1 MiB =
172 1,048,576 bytes), that children are allowed to allocate. This is
173 useful to detect infinite loops that eat up a lot of memory.
174 The value should be set reasonably high so as not to interfer
176 with normal program operation. By default, it is set to 1024 MiB
177 in order to avoid accidental excessive swapping. To disable the
178 limitation, set the maximum memory usage to -1 instead.
179 zzuf uses the setrlimit() call to set memory usage limitations
181 and relies on the operating system's ability to enforce such
182 limitations.
183 -S, --signal
185 Prevent children from installing signal handlers for signals
186 that usually cause coredumps. These signals are SIGABRT, SIGFPE,
187 SIGILL, SIGQUIT, SIGSEGV, SIGTRAP and, if available on the run‐
188 ning platform, SIGSYS, SIGEMT, SIGBUS, SIGXCPU and SIGXFSZ.
189 Instead of calling the signal handler, the application will sim‐
190 ply crash. If you do not want core dumps, you should set appro‐
191 priate limits with the limit coredumpsize command. See your
192 shell's documentation on how to set such limits.
193 -t, --max-time=n
195 Stop forking after n seconds. By default, zzuf runs until the
196 end of the seed range is reached.
197 Note that zzuf will not kill any remaining children once n is
199 reached. To ensure that processes do not last forever, see the
200 -U flag.
201 This option is only relevant if the -s flag is used with a range
203 argument. See also the -C flag.
204 -T, --max-cputime=n
206 Automatically terminate child processes that use more than n
207 seconds of CPU time.
208 zzuf uses the setrlimit() call to set CPU usage limitations and
210 relies on the operating system's ability to enforce such limita‐
211 tions. If the system sends SIGXCPU signals and the application
212 catches that signal, it will receive a SIGKILL signal after 5
213 seconds.
214 This is more accurate than -U because the behaviour should be
216 independent from the system load, but it does not detect pro‐
217 cesses stuck into infinite select() calls because they use very
218 little CPU time. See also the -B and -U flags.
219 -U, --max-usertime=n
221 Automatically terminate child processes that run for more than n
222 seconds. This is useful to detect infinite loops or processes
223 stuck in other situations. See also the -B and -T flags.
224 -x, --check-exit
226 Report processes that exit with a non-zero status. By default
227 only processes that crash due to a signal are reported.
228 Filtering
230 -a, --allow=list
231 Only fuzz network input for IPs in list, a comma-separated list
232 of IP addresses. If the list starts with !, the flag meaning is
233 reversed and all addresses are fuzzed except the ones in the
234 list.
235 As of now, this flag only understands INET (IPv4) addresses.
237 This option requires network fuzzing to be activated using -n.
239 -b, --bytes=ranges
241 Restrict fuzzing to bytes whose offsets in the file are within
242 ranges.
243 Range values start at zero and are inclusive. Use dashes between
245 range values and commas between ranges. If the right-hand part
246 of a range is ommited, it means end of file. For instance, to
247 restrict fuzzing to bytes 0, 3, 4, 5 and all bytes after offset
248 31, use ‘-b0,3-5,31-’.
249 This option is useful to preserve file headers or corrupt only a
251 specific portion of a file.
252 -c, --cmdline
254 Only fuzz files whose name is specified in the target applica‐
255 tion's command line. This is mostly a shortcut to avoid specify‐
256 ing the argument twice:
257 zzuf -c cat file.txt
259 has the same effect as
261 zzuf -I '^file\.txt$' cat file.txt
263 See the -I flag for more information on restricting fuzzing to
265 specific files.
266 -E, --exclude=regex
268 Do not fuzz files whose name matches the regex regular expres‐
269 sion. This option supersedes anything that is specified by the
270 -I flag. Use this for instance if you are unsure of what files
271 your application is going to read and do not want it to fuzz
272 files in the /etc directory.
273 Multiple -E flags can be specified, in which case files matching
275 any one of the regular expressions will be ignored.
276 -i, --stdin
278 Fuzz the application's standard input. By default zzuf only
279 fuzzes files.
280 -I, --include=regex
282 Only fuzz files whose name matches the regex regular expression.
283 Use this for instance if your application reads configuration
284 files at startup and you only want specific files to be fuzzed.
285 Multiple -I flags can be specified, in which case files matching
287 any one of the regular expressions will be fuzzed. See also the
288 -c flag.
289 -l, --list=list
291 Cherry-pick the list of file descriptors that get fuzzed. The
292 Nth descriptor will really be fuzzed only if N is in list.
293 Values start at 1 and ranges are inclusive. Use dashes between
295 values and commas between ranges. If the right-hand part of a
296 range is ommited, it means all subsequent file descriptors. For
297 instance, to restrict fuzzing to the first opened descriptor and
298 all descriptors starting from the 10th, use ‘-l1,10-’.
299 Note that this option only affects file descriptors that would
301 otherwise be fuzzed. Even if 10 write-only descriptors are
302 opened at the beginning of the program, only the next descriptor
303 with a read flag will be the first one considered by the -l
304 flag.
305 -P, --protect=list
307 Protect a list of characters so that if they appear in input
308 data that would normally be fuzzed, they are left unmodified
309 instead.
310 Characters in list can be expressed verbatim or through escape
312 sequences. The sequences interpreted by zzuf are:
313 \n new line
315 \r return
317 \t tabulation
319 \NNN the byte whose octal value is NNN
321 \xNN the byte whose hexadecimal value is NN
323 \\ backslash (‘\’)
325 You can use ‘-’ to specify ranges. For instance, to protect all
327 bytes from ‘\001’ to ‘/’, use ‘-P '\001-/'’.
328 The statistical outcome of this option should not be overlooked:
330 if characters are protected, the effect of the ‘-r’ flag will
331 vary depending on the data being fuzzed. For instance, asking to
332 fuzz 1% of input bits (-r0.01) and to protect lowercase charac‐
333 ters (-P a-z) will result in an actual average fuzzing ratio of
334 0.9% with truly random data, 0.3% with random ASCII data and
335 0.2% with standard English text.
336 See also the -R flag.
338 -R, --refuse=list
340 Refuse a list of characters by not fuzzing bytes that would oth‐
341 erwise be changed to a character that is in list. This does not
342 prevent characters from appearing in the output if the original
343 byte was already in list.
344 See the -P option for a description of list.
346 Network
348 -n, --network
349 Fuzz the application's network input. By default zzuf only
350 fuzzes files.
351 Only INET (IPv4) and INET6 (IPv6) connections are fuzzed. Other
353 protocol families are not yet supported.
354 -p, --ports=ranges
356 Only fuzz network ports that are in ranges. By default zzuf
357 fuzzes all ports. The port considered is the listening port if
358 the socket is listening and the destination port if the socket
359 is connecting, because most of the time the source port cannot
360 be predicted.
361 Range values start at zero and are inclusive. Use dashes between
363 range values and commas between ranges. If the right-hand part
364 of a range is ommited, it means end of file. For instance, to
365 restrict fuzzing to the HTTP and HTTPS ports and to all unprivi‐
366 leged ports, use ‘-p80,443,1024-’.
367 This option requires network fuzzing to be activated using -n.
369
371 Exit status is zero if no child process crashed. If one or several
372 children crashed, zzuf exits with status 1.
373
375 Fuzz the input of the cat program using default settings:
376 zzuf cat /etc/motd
378 Fuzz 1% of the input bits of the cat program using seed 94324:
380 zzuf -s94324 -r0.01 cat /etc/motd
382 Fuzz the input of the cat program but do not fuzz newline characters
384 and prevent non-ASCII characters from appearing in the output:
385 zzuf -P '\n' -R '\x00-\x1f\x7f-\xff' cat /etc/motd
387 Fuzz the input of the convert program, using file foo.jpeg as the orig‐
389 inal input and excluding .xml files from fuzzing (because convert will
390 also open its own XML configuration files and we do not want zzuf to
391 fuzz them):
392 zzuf -E '\.xml$' convert foo.jpeg -format tga /dev/null
394 Fuzz the input of VLC, using file movie.avi as the original input and
396 restricting fuzzing to filenames that appear on the command line (-c),
397 then generate fuzzy-movie.avi which is a file that can be read by VLC
398 to reproduce the same behaviour without using zzuf:
399 zzuf -c -s87423 -r0.01 vlc movie.avi
401 zzuf -c -s87423 -r0.01 <movie.avi >fuzzy-movie.avi
402 vlc fuzzy-movie.avi
403 Fuzz between 0.1% and 2% of MPlayer's input bits (-r0.001:0.02) with
405 seeds 0 to 9999 (-s0:10000), preserving the AVI 4-byte header by
406 restricting fuzzing to offsets after 4 (-b4-), disabling its standard
407 output messages (-q), launching up to five simultaneous child processes
408 (-j5) but waiting at least half a second between launches (-D0.5),
409 killing MPlayer if it takes more than one minute to read the file
410 (-T60) and disabling its SIGSEGV signal handler (-S):
411 zzuf -c -r0.001:0.02 -s0:10000 -b4- -q -j5 -D0.5 -T60 -S \
413 mplayer -benchmark -vo null -fps 1000 movie.avi
414 A more advanced VLC fuzzing example, stopping only at the first crash:
416 zzuf -j4 -vqc -r0.000001:0.01 -s0: vlc -v -I dummy movie.avi \
418 --sout '#transcode{acodec=s16l,vcodec=I420}:dummy' vlc:quit
419 Create an HTML-like file that loads 200 times the same hello.jpg image
421 and open it in Firefox™ in auto-increment mode (-A):
422 seq -f '<img src="hello.jpg#%g">' 1 200 > hello.html
424 (or: jot -w '<img src="hello.jpg#%d">' 200 1 > hello.html)
425 zzuf -A -I 'hello[.]jpg' -r0.001 firefox hello.html
426 Run a simple HTTP redirector on the local host using socat and corrupt
428 each network connection (-n) in a different way (-A) after one megabyte
429 of data was received on it (-b1000000-):
430 zzuf -n -A -b1000000- \
432 socat TCP4-LISTEN:8080,reuseaddr,fork TCP4:192.168.1.42:80
433 Browse the intarweb (-n) using Firefox™ without fuzzing local files
435 (-E.) or non-HTTP connections (-p80,8010,8080), preserving the begin‐
436 ning of the data sent with each HTTP response (-b4000-) and using
437 another seed on each connection (-A):
438 zzuf -r 0.0001 -n -E. -p80,8010,8080 -b4000- -A firefox
440
442 Due to zzuf using shared object preloading (LD_PRELOAD, _RLD_LIST,
443 DYLD_INSERT_LIBRARIES, etc.) to run its child processes, it will fail
444 in the presence of any mechanism that disables preloading. For instance
445 setuid root binaries will not be fuzzed when run as an unprivileged
446 user.
447 For the same reasons, zzuf will also not work with statically linked
449 binaries. Bear this in mind when using zzuf on the OpenBSD platform,
450 where cat, cp and dd are static binaries.
451 Though best efforts are made, identical behaviour for different ver‐
453 sions of zzuf is not guaranteed. The reproducibility for subsequent
454 calls on different operating systems and with different target programs
455 is only guaranteed when the same version of zzuf is being used.
456
458 zzuf probably does not behave correctly with 64-bit offsets.
459 It is not yet possible to insert or drop bytes from the input, to fuzz
461 according to the file format, to swap bytes, etc. More advanced fuzzing
462 methods are planned.
463 As of now, zzuf does not really support multithreaded applications. The
465 behaviour with multithreaded applications where more than one thread
466 does file descriptor operations is undefined.
467
469 zzuf started its life in 2002 as the streamfucker tool, a small multi‐
470 media stream corrupter used to find bugs in the VLC media player.
471
473 libzzuf(3), zzat(1)
474
476 Copyright © 2002-2015 Sam Hocevar <sam@hocevar.net>.
477 zzuf and this manual page are free software. They come without any war‐
479 ranty, to the extent permitted by applicable law. You can redistribute
480 them and/or modify them under the terms of the Do What the Fuck You
481 Want to Public License, Version 2, as published by the WTFPL Task
482 Force. See http://www.wtfpl.net/ for more details.
483 zzuf's webpage can be found at http://caca.zoy.org/wiki/zzuf. An over‐
485 view of the architecture and inner works is at
486 http://caca.zoy.org/wiki/zzuf/internals.
487zzuf 0.15 2015-01-06 zzuf(1)