1zzuf(1) General Commands Manual zzuf(1)
2
6 zzuf - multiple purpose fuzzer
7
9 zzuf [-AcdimnqSvx] [-s seed|-s start:stop] [-r ratio|-r min:max]
10 [-f fuzzing] [-D delay] [-F forks] [-C crashes] [-B bytes]
11 [-T seconds] [-M megabytes] [-P protect] [-R refuse]
12 [-b ranges] [-I include] [-E exclude] [PROGRAM [--] [ARGS]...]
13 zzuf -h | --help
14 zzuf -V | --version
15
17 zzuf is a transparent application input fuzzer. It works by intercept‐
18 ing file and network operations and changing random bits in the pro‐
19 gram's input. zzuf's behaviour is deterministic, making it easy to
20 reproduce bugs.
21
23 zzuf will run an application specified on its command line, one or sev‐
24 eral times, with optional arguments, and will report the application's
25 relevant behaviour on the standard error channel, eg:
26 zzuf cat /dev/zero
28 If you want to specify flags for your application, put a ‘--’ marker
30 before them on the command line (otherwise zzuf will try to interpret
31 them as arguments for itself), eg:
32 zzuf -B 1000 cat -- -v /dev/zero
34 When no program is specified, zzuf simply fuzzes the standard input, as
36 if the cat utility had been called:
37 zzuf < /dev/zero
39
41 -A, --autoinc
42 Increment random seed each time a new file is opened. This is
43 only required if one instance of the application is expected to
44 open the same file several times and you want to test a differ‐
45 ent seed each time.
46 -b, --bytes=ranges
48 Restrict fuzzing to bytes whose offsets in the file are within
49 ranges.
50 Range values start at zero and are inclusive. Use dashes between
52 range values and commas between ranges. If the right-hand part
53 of a range is ommited, it means end of file. For instance, to
54 restrict fuzzing to bytes 0, 3, 4, 5 and all bytes after offset
55 31, use ‘-r0,3-5,31-’.
56 This option is useful to preserve file headers or corrupt only a
58 specific portion of a file.
59 -B, --max-bytes=n
61 Automatically terminate child processes that output more than n
62 bytes on the standard output and standard error channels. This
63 is useful to detect infinite loops. See also the -T flag.
64 -c, --cmdline
66 Only fuzz files whose name is specified in the target applica‐
67 tion's command line. This is mostly a shortcut to avoid specify‐
68 ing twice the argument:
69 zzuf -c cat file.txt
71 has the same effect as
73 zzuf -I '^file\.txt$' cat file.txt
75 See the -I flag for more information on restricting fuzzing to
77 specific files.
78 -C, --max-crashes=n
80 Stop forking when at least n children have crashed. The default
81 value is 1, meaning zzuf will stop as soon as one child has
82 crashed. A process is considered to have crashed if any signal
83 (such as, but not limited to, SIGSEGV) caused it to exit. If the
84 -x flag is used, this will also include processes that exit with
85 a non-zero status.
86 This option is only relevant if the -s flag is used with a range
88 argument.
89 -d, --debug
91 Activate the display of debug messages.
92 -D, --delay=delay
94 Do not launch more than one process every delay seconds. This
95 option should be used together with -F to avoid fork bombs.
96 -E, --exclude=regex
98 Do not fuzz files whose name matches the regex regular expres‐
99 sion. This option supersedes anything that is specified by the
100 -I flag. Use this for instance if you are unsure of what files
101 your application is going to read and do not want it to fuzz
102 files in the /etc directory.
103 Multiple -E flags can be specified, in which case files matching
105 any one of the regular expressions will be ignored.
106 -f, --fuzzing=mode
108 Select how the input is fuzzed. Valid values for mode are:
109 xor randomly set and unset bits
111 set only set bits
113 unset only unset bits
115 The default value for mode is xor.
117 -F, --max-forks=forks
119 Specify the number of simultaneous children that can be run.
120 This option is only relevant if the -s flag is used with a range
122 argument. See also the -D flag.
123 -i, --stdin
125 Fuzz the application's standard input. By default zzuf only
126 fuzzes files.
127 -I, --include=regex
129 Only fuzz files whose name matches the regex regular expression.
130 Use this for instance if your application reads configuration
131 files at startup and you only want specific files to be fuzzed.
132 Multiple -I flags can be specified, in which case files matching
134 any one of the regular expressions will be fuzzed. See also the
135 -c flag.
136 -m, --md5
138 Instead of displaying the program's standard output, just print
139 its MD5 digest to zzuf's standard output. The standard error
140 channel is left untouched.
141 -M, --max-memory=megabytes
143 Specify the maximum amount of memory, in megabytes, that chil‐
144 dren are allowed to allocate. This is useful to detect infinite
145 loops that eat up a lot of memory. The value should set reason‐
146 ably high so as not to interfer with normal program operation.
147 zzuf uses the setrlimit() call to set memory usage limitations
149 and relies on the operating system's ability to enforce such
150 limitations.
151 -n, --network
153 Fuzz the application's network input. By default zzuf only
154 fuzzes files.
155 -P, --protect=list
157 Protect a list of characters so that if they appear in input
158 data that would normally be fuzzed, they are left unmodified
159 instead.
160 Characters in list can be expressed verbatim or through escape
162 sequences. The sequences interpreted by zzuf are:
163 \n new line
165 \r return
167 \t tabulation
169 \NNN the byte whose octal value is NNN
171 \xNN the byte whose hexadecimal value is NN
173 \\ backslash (‘\’)
175 You can use ‘-’ to specify ranges. For instance, to protect all
177 bytes from ‘\001’ to ‘/’, use ‘-P '\001-/'’.
178 The statistical outcome of this option should not be overlooked:
180 if characters are protected, the effect of the ‘-r’ flag will
181 vary depending on the data being fuzzed. For instance, asking to
182 fuzz 1% of input bits (-r0.01) and to protect lowercase charac‐
183 ters (-P a-z) will result in an actual average fuzzing ratio of
184 0.9% with truly random data, 0.3% with random ASCII data and
185 0.2% with standard English text.
186 See also the -R flag.
188 -q, --quiet
190 Hide the output of the fuzzed application. This is useful if the
191 application is very verbose but only its exit code or signaled
192 status is really useful to you.
193 -r, --ratio=ratio
195 -r, --ratio=min:max
196 Specify the proportion of bits that will be randomly fuzzed. A
197 value of 0 will not fuzz anything. A value of 0.05 will fuzz 5%
198 of the open files' bits. A value of 1.0 or more will fuzz all
199 the bytes, theoretically making the input files undiscernible
200 from random data. The default fuzzing ratio is 0.004 (fuzz 0.4%
201 of the files' bits).
202 A range can also be specified. When doing so, zzuf will pick
204 ratio values from the interval. The choice is deterministic and
205 only depends on the interval bounds and the current seed.
206 -R, --refuse=list
208 Refuse a list of characters by not fuzzing bytes that would oth‐
209 erwise be changed to a character that is in list. If the origi‐
210 nal byte is already in list, it is left unchanged.
211 See the -P option for a description of list.
213 -s, --seed=seed
215 -s, --seed=start:stop
216 Specify the random seed to use for fuzzing, or a range of random
217 seeds. Running zzuf twice with the same random seed will fuzz
218 the files exactly the same way, even with a different target
219 application. The purpose of this is to use simple utilities such
220 as cat or cp to generate a file that causes the target applica‐
221 tion to crash.
222 If a range is specified, zzuf will run the application several
224 times, each time with a different seed, and report the behaviour
225 of each run.
226 -S, --signal
228 Prevent children from installing signal handlers for signals
229 that usually cause coredumps. These signals are SIGABRT, SIGFPE,
230 SIGILL, SIGQUIT, SIGSEGV, SIGTRAP and, if available on the run‐
231 ning platform, SIGSYS, SIGEMT, SIGBUS, SIGXCPU and SIGXFSZ.
232 Instead of calling the signal handler, the application will sim‐
233 ply crash. If you do not want core dumps, you should set appro‐
234 priate limits with the limit coredumpsize command. See your
235 shell's documentation on how to set such limits.
236 -T, --max-time=n
238 Automatically terminate child processes that run for more than n
239 seconds. This is useful to detect infinite loops or processes
240 stuck in other situations. See also the -B flag.
241 -v, --verbose
243 Print information during the run, such as the current seed, what
244 processes get run, their exit status, etc.
245 -x, --check-exit
247 Report processes that exit with a non-zero status. By default
248 only processes that crash due to a signal are reported.
249 -h, --help
251 Display a short help message and exit.
252 -V, --version
254 Output version information and exit.
255
257 Exit status is zero if no child process crashed. If one or several
258 children crashed, zzuf exits with status 1.
259
261 Fuzz the input of the cat program using default settings:
262 zzuf cat /etc/motd
264 Fuzz 1% of the input bits of the cat program using seed 94324:
266 zzuf -s94324 -r0.01 cat /etc/motd
268 Fuzz the input of the cat program but do not fuzz newline characters
270 and prevent non-ASCII characters from appearing in the output:
271 zzuf -P '\n' -R '\x00-\x1f\x7f-\xff' cat /etc/motd
273 Fuzz the input of the convert program, using file foo.jpeg as the orig‐
275 inal input and excluding .xml files from fuzzing (because convert will
276 also open its own XML configuration files and we do not want zzuf to
277 fuzz them):
278 zzuf -E '\.xml$' convert -- foo.jpeg -format tga /dev/null
280 Fuzz the input of VLC, using file movie.avi as the original input and
282 restricting fuzzing to filenames that appear on the command line (-c),
283 then generate fuzzy-movie.avi which is a file that can be read by VLC
284 to reproduce the same behaviour without using zzuf:
285 zzuf -c -s87423 -r0.01 vlc movie.avi
287 zzuf -c -s87423 -r0.01 <movie.avi >fuzzy-movie.avi
288 vlc fuzzy-movie.avi
289 Fuzz between 0.1% and 2% of MPlayer's input bits (-r0.001:0.02) with
291 seeds 0 to 9999 (-s0:10000), preserving the AVI 4-byte header by
292 restricting fuzzing to offsets after 4 (-b4-), disabling its standard
293 output messages (-q), launching up to five simultaneous child processes
294 (-F5) but waiting at least half a second between launches (-D0.5),
295 killing MPlayer if it takes more than one minute to read the file
296 (-T60) and disabling its SIGSEGV signal handler (-S):
297 zzuf -c -r0.001:0.02 -s0:10000 -b4- -q -F5 -D0.5 -T60 -S \
299 mplayer -- -benchmark -vo null -fps 1000 movie.avi
300 Create an HTML-like file that loads 200 times the same hello.jpg image
302 and open it in Firefox™ in auto-increment mode (-A):
303 seq -f '<img src="hello.jpg#%g">' 1 200 > hello.html
305 (or: jot -w '<img src="hello.jpg#%d">' 200 1 > hello.html)
306 zzuf -A -I 'hello[.]jpg' -r0.001 firefox hello.html
307 Run a simple HTTP redirector on the local host using socat and corrupt
309 each network connection (-n) in a different way (-A) after one megabyte
310 of data was received on it (-b1000000-):
311 zzuf -n -A -b1000000- \
313 socat TCP4-LISTEN:8080,reuseaddr,fork TCP4:192.168.1.42:80
314
316 Due to zzuf using shared object preloading (LD_PRELOAD, _RLD_LIST,
317 DYLD_INSERT_LIBRARIES, etc.) to run its child processes, it will fail
318 in the presence of any mechanism that disables preloading. For instance
319 setuid root binaries will not be fuzzed when run as an unprivileged
320 user.
321 For the same reasons, zzuf will also not work with statically linked
323 binaries. Bear this in mind when using zzuf on the OpenBSD platform,
324 where cat, cp and dd are static binaries.
325 Though best efforts are made, identical behaviour for different ver‐
327 sions of zzuf is not guaranteed. The reproducibility for subsequent
328 calls on different operating systems and with different target programs
329 is only guaranteed when the same version of zzuf is being used.
330
332 zzuf probably does not behave correctly with 64-bit offsets.
333 It is not yet possible to insert or drop bytes from the input, to fuzz
335 according to the file format, to swap bytes, etc. More advanced fuzzing
336 methods are planned.
337 As of now, zzuf does not really support multithreaded applications. The
339 behaviour with multithreaded applications where more than one thread
340 does file descriptor operations is undefined.
341
343 In order to intercept file and network operations, signal handlers and
344 memory allocations, zzuf diverts and reimplements the following func‐
345 tions, which can be private libc symbols, too:
346 Unix file descriptor handling:
348 open(), lseek(), read(), readv(), pread(), accept(), socket(),
349 recv(), recvfrom(), recvmsg(), aio_read(), aio_return(), close()
350 Standard IO streams:
352 fopen(), freopen(), fseek(), fseeko(), rewind(), fread(),
353 getc(), fgetc(), fgets(), ungetc(), fclose()
354 Memory management:
356 mmap(), munmap(), malloc(), calloc(), valloc(), free(), mema‐
357 lign(), posix_memalign()
358 Linux-specific:
360 open64(), lseek64(), mmap64(), _IO_getc(), getline(), getde‐
361 lim(), __getdelim()
362 BSD-specific:
364 fgetln(), __srefill()
365 Mac OS X-specific:
367 map_fd()
368 Signal handling:
370 signal(), sigaction()
371 If an application manipulates file descriptors (reading data, seeking
373 around) using functions that are not in that list, zzuf will not fuzz
374 its input consistently and the results should not be trusted. You can
375 use a tool such as ltrace(1) on Linux to know the missing functions.
376 On BSD systems, such as FreeBSD or Mac OS X, __srefill() is enough to
378 monitor all standard IO streams functions. On other systems, such as
379 Linux, each function is reimplemented on a case by case basis. One
380 important unimplemented function is fscanf(), because of its complex‐
381 ity. Missing functions will be added upon user request.
382
384 zzuf started its life in 2002 as the streamfucker tool, a small multi‐
385 media stream corrupter used to find bugs in the VLC media player.
386
388 Copyright © 2002, 2007 Sam Hocevar <sam@zoy.org>.
389 zzuf and this manual page are free software. They come without any war‐
391 ranty, to the extent permitted by applicable law. You can redistribute
392 them and/or modify them under the terms of the Do What The Fuck You
393 Want To Public License, Version 2, as published by Sam Hocevar. See
394 http://sam.zoy.org/wtfpl/COPYING for more details.
395 zzuf's webpage can be found at http://sam.zoy.org/zzuf/.
397zzuf 2006-12-22 zzuf(1)