1 | .TH zzuf 1 "2006-12-22" "zzuf" |
---|
2 | .SH NAME |
---|
3 | zzuf \- multiple purpose fuzzer |
---|
4 | .SH SYNOPSIS |
---|
5 | \fBzzuf\fR [\fB\-cdinqS\fR] [\fB\-r\fR \fIratio\fR] [\fB\-s\fR \fIseed\fR | \fB\-s\fR \fIstart:stop\fR] |
---|
6 | .br |
---|
7 | [\fB\-F\fR \fIforks\fR] [\fB\-C\fR \fIcrashes\fR] [\fB\-B\fR \fIbytes\fR] [\fB\-T\fR \fIseconds\fR] |
---|
8 | .br |
---|
9 | [\fB\-P\fR \fIprotect\fR] [\fB\-R\fR \fIrefuse\fR] |
---|
10 | .br |
---|
11 | [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fIPROGRAM\fR [\fIARGS\fR]... |
---|
12 | .br |
---|
13 | \fBzzuf \-h\fR | \fB\-\-help\fR |
---|
14 | .br |
---|
15 | \fBzzuf \-v\fR | \fB\-\-version\fR |
---|
16 | .SH DESCRIPTION |
---|
17 | .PP |
---|
18 | \fBZzuf\fR is a transparent application input fuzzer. It works by intercepting |
---|
19 | file and network operations and changing random bits in the program's input. |
---|
20 | \fBZzuf\fR's behaviour is deterministic, making it easy to reproduce bugs. |
---|
21 | .SH USAGE |
---|
22 | .PP |
---|
23 | \fBZzuf\fR will run an application specified on its command line, one or |
---|
24 | several times, with optional arguments, and will report the application's |
---|
25 | relevant behaviour on the standard output, eg: |
---|
26 | .PP |
---|
27 | \fB zzuf cat /dev/zero\fR |
---|
28 | .PP |
---|
29 | If you want to specify flags for your application, put a \(oq\fB\-\-\fR\(cq |
---|
30 | marker before them on the command line (otherwise \fBzzuf\fR will try to |
---|
31 | interpret them as arguments for itself), eg: |
---|
32 | .PP |
---|
33 | \fB zzuf \-B 1000 cat \-\- \-v /dev/zero\fR |
---|
34 | .SH OPTIONS |
---|
35 | .TP |
---|
36 | \fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR |
---|
37 | Automatically terminate child processes that output more than \fIn\fR bytes |
---|
38 | on the standard output and standard error channels. This is useful to detect |
---|
39 | infinite loops. See also the \fB\-T\fR flag. |
---|
40 | .TP |
---|
41 | \fB\-c\fR, \fB\-\-cmdline\fR |
---|
42 | Only fuzz files whose name is specified in the target application's command |
---|
43 | line. This is mostly a shortcut to avoid specifiying twice the argument: |
---|
44 | |
---|
45 | \fB zzuf \-c cat file.txt\fR |
---|
46 | |
---|
47 | has the same effect as |
---|
48 | |
---|
49 | \fB zzuf \-I \(aq^file\\.txt$\(aq cat file.txt\fR |
---|
50 | |
---|
51 | See the \fB\-I\fR flag for more information on restricting fuzzing to |
---|
52 | specific files. |
---|
53 | .TP |
---|
54 | \fB\-C\fR, \fB\-\-max\-crashes\fR=\fIn\fR |
---|
55 | Stop forking when at least \fIn\fR children have crashed. The default value |
---|
56 | is 1, meaning \fBzzuf\fR will stop as soon as one child has crashed. A process |
---|
57 | is considered to have crashed if any signal (such as, but not limited to, |
---|
58 | \fBSIGSEGV\fR) caused it to exit. |
---|
59 | |
---|
60 | This option is only relevant if the \fB\-s\fR flag is used with an interval |
---|
61 | argument. |
---|
62 | .TP |
---|
63 | \fB\-d\fR, \fB\-\-debug\fR |
---|
64 | Activate the display of debug messages. |
---|
65 | .TP |
---|
66 | \fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR |
---|
67 | Do not fuzz files whose name matches the \fIregex\fR regular expression. This |
---|
68 | option supersedes anything that is specified by the \fB\-I\fR flag. Use this |
---|
69 | for instance if you are unsure of what files your application is going to read |
---|
70 | and do not want it to fuzz files in the \fB/etc\fR directory. |
---|
71 | |
---|
72 | Multiple \fB\-E\fR flags can be specified, in which case files matching any one |
---|
73 | of the regular expressions will be ignored. |
---|
74 | .TP |
---|
75 | \fB\-F\fR, \fB\-\-max-forks\fR=\fIforks\fR |
---|
76 | Specify the number of simultaneous children that can be run. |
---|
77 | |
---|
78 | This option is only relevant if the \fB\-s\fR flag is used with an interval |
---|
79 | argument. |
---|
80 | .TP |
---|
81 | \fB\-i\fR, \fB\-\-stdin\fR |
---|
82 | Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files. |
---|
83 | .TP |
---|
84 | \fB\-I\fR, \fB\-\-include\fR=\fIregex\fR |
---|
85 | Only fuzz files whose name matches the \fIregex\fR regular expression. Use |
---|
86 | this for instance if your application reads configuration files at startup |
---|
87 | and you only want specific files to be fuzzed. |
---|
88 | |
---|
89 | Multiple \fB\-I\fR flags can be specified, in which case files matching any one |
---|
90 | of the regular expressions will be fuzzed. See also the \fB\-c\fR flag. |
---|
91 | .TP |
---|
92 | \fB\-n\fR, \fB\-\-network\fR |
---|
93 | Fuzz the application's network input. By default \fBzzuf\fR only fuzzes files. |
---|
94 | .TP |
---|
95 | \fB\-P\fR, \fB\-\-protect\fR=\fIlist\fR |
---|
96 | Protect a list of characters so that if they appear in input data that would |
---|
97 | normally be fuzzed, they are left unmodified instead. |
---|
98 | |
---|
99 | Characters in \fIlist\fR can be expressed verbatim or through escape sequences. |
---|
100 | The sequences interpreted by \fBzzuf\fR are: |
---|
101 | .RS |
---|
102 | .TP |
---|
103 | \fB\\n\fR |
---|
104 | new line |
---|
105 | .TP |
---|
106 | \fB\\r\fR |
---|
107 | return |
---|
108 | .TP |
---|
109 | \fB\\t\fR |
---|
110 | tabulation |
---|
111 | .TP |
---|
112 | \fB\\\fR\fINNN\fR |
---|
113 | the byte whose octal value is \fINNN\fR |
---|
114 | .TP |
---|
115 | \fB\\x\fR\fINN\fR |
---|
116 | the byte whose hexadecimal value is \fINN\fR |
---|
117 | .TP |
---|
118 | \fB\\\\\fR |
---|
119 | backslash (\(oq\\\(cq) |
---|
120 | .RE |
---|
121 | .IP |
---|
122 | You can use \(oq\fB-\fR\(cq to specify ranges. For instance, to protect all |
---|
123 | bytes from \(oq\\001\(cq to \(oq/\(cq, use \(oq\fB\-P\ \(dq\\001-/\(dq\fR\(cq. |
---|
124 | |
---|
125 | The statistical outcome of this option should not be overlooked: if characters |
---|
126 | are protected, the effect of the \(oq\fB\-r\fR\(cq flag will vary depending |
---|
127 | on the data being fuzzed. For instance, asking to fuzz 1% of input bits |
---|
128 | (\fB\-r\ 0.01\fR) and to protect lowercase characters (\fB\-P\ a-z\fR) will |
---|
129 | result in an actual average fuzzing ratio of 0.9% with truly random data, |
---|
130 | 0.3% with random ASCII data and 0.2% with standard English text. |
---|
131 | |
---|
132 | See also the \fB\-R\fR flag. |
---|
133 | .TP |
---|
134 | \fB\-q\fR, \fB\-\-quiet\fR |
---|
135 | Hide the output of the fuzzed application. This is useful if the application |
---|
136 | is very verbose but only its exit code or signaled status is really useful to |
---|
137 | you. |
---|
138 | .TP |
---|
139 | \fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR |
---|
140 | Specify the proportion of bits that will be randomly fuzzed. A value of 0 |
---|
141 | will not fuzz anything. A value of 0.05 will fuzz 5% of the open files' |
---|
142 | bits. A value of 1.0 or more will fuzz all the bytes, theoretically making |
---|
143 | the input files undiscernible from random data. The default fuzzing ratio |
---|
144 | is 0.004 (fuzz 0.4% of the files' bits). |
---|
145 | .TP |
---|
146 | \fB\-R\fR, \fB\-\-refuse\fR=\fIlist\fR |
---|
147 | Refuse a list of characters by not fuzzing bytes that would otherwise be |
---|
148 | changed to a character that is in \fIlist\fR. If the original byte is already |
---|
149 | in \fIlist\fR, it is left unchanged. |
---|
150 | |
---|
151 | See the \fB\-P\fR option for a description of \fIlist\fR. |
---|
152 | .TP |
---|
153 | \fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR |
---|
154 | .PD 0 |
---|
155 | .TP |
---|
156 | \fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR |
---|
157 | .PD |
---|
158 | Specify the random seed to use for fuzzing, or an interval of random seeds. |
---|
159 | Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly |
---|
160 | the same way, even with a different target application. The purpose of this is |
---|
161 | to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that |
---|
162 | causes the target application to crash. |
---|
163 | |
---|
164 | If an interval is specified, \fBzzuf\fR will run the application several times, |
---|
165 | each time with a different seed, and report the behaviour of each run. |
---|
166 | .TP |
---|
167 | \fB\-S\fR, \fB\-\-signal\fR |
---|
168 | Prevent children from installing signal handlers for signals that usually |
---|
169 | cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR, |
---|
170 | \fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running |
---|
171 | platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and |
---|
172 | \fBSIGXFSZ\fR. Instead of calling the signal handler, the application will |
---|
173 | simply crash. If you do not want core dumps, you should set appropriate limits |
---|
174 | with the \fBlimit coredumpsize\fR command. See your shell's documentation on |
---|
175 | how to set such limits. |
---|
176 | .TP |
---|
177 | \fB\-T\fR, \fB\-\-max\-time\fR=\fIn\fR |
---|
178 | Automatically terminate child processes that run for more than \fIn\fR |
---|
179 | seconds. This is useful to detect infinite loops or processes stuck in other |
---|
180 | situations. See also the \fB\-B\fR flag. |
---|
181 | .TP |
---|
182 | \fB\-h\fR, \fB\-\-help\fR |
---|
183 | Display a short help message and exit. |
---|
184 | .TP |
---|
185 | \fB\-v\fR, \fB\-\-version\fR |
---|
186 | Output version information and exit. |
---|
187 | .SH EXAMPLES |
---|
188 | .PP |
---|
189 | Fuzz the input of the \fBcat\fR program using default settings: |
---|
190 | .PP |
---|
191 | \fB zzuf cat /etc/motd\fR |
---|
192 | .PP |
---|
193 | Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324: |
---|
194 | .PP |
---|
195 | \fB zzuf -s 94324 -r 0.01 cat /etc/motd\fR |
---|
196 | .PP |
---|
197 | Fuzz the input of the \fBcat\fR program but do not fuzz newline characters |
---|
198 | and prevent non-ASCII characters from appearing in the output: |
---|
199 | .PP |
---|
200 | \fB zzuf -P \(aq\\n\(aq -R \(aq\\x00-\\x1f\\x7f-\\xff\(aq cat /etc/motd\fR |
---|
201 | .PP |
---|
202 | Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the |
---|
203 | original input and excluding \fB.xml\fR files from fuzzing (because |
---|
204 | \fBconvert\fR will also open its own XML configuration files and we do not |
---|
205 | want \fBzzuf\fR to fuzz them): |
---|
206 | .PP |
---|
207 | \fB zzuf -E \(aq\\.xml$\(aq convert -- foo.jpeg -format tga /dev/null\fR |
---|
208 | .PP |
---|
209 | Fuzz the input of \fBVLC\fR, using file \fBmovie.avi\fR as the original input |
---|
210 | and restricting fuzzing to filenames that appear on the command line |
---|
211 | (\fB\-c\fR), then generate \fBfuzzy-movie.avi\fR which is a file that |
---|
212 | can be read by \fBVLC\fR to reproduce the same behaviour without using |
---|
213 | \fBzzuf\fR: |
---|
214 | .PP |
---|
215 | \fB zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR |
---|
216 | \fB zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR |
---|
217 | \fB vlc fuzzy-movie.avi\fR |
---|
218 | .PP |
---|
219 | Fuzz 2% of \fBMPlayer\fR's input bits (\fB\-r\ 0.02\fR) with seeds 0 to 9999 |
---|
220 | (\fB\-s\ 0:10000\fR), disabling its standard output messages (\fB\-q\fR), |
---|
221 | launching up to three simultaneous child processes (\fB\-F\ 3\fR), killing |
---|
222 | \fBMPlayer\fR if it takes more than one minute to read the file (\fB\-T\ 60\fR) |
---|
223 | and disabling its \fBSIGSEGV\fR signal handler (\fB\-S\fR): |
---|
224 | .PP |
---|
225 | \fB zzuf -c -r 0.02 -q -s 0:10000 -F 3 -T 60 -S \\\fR |
---|
226 | \fB mplayer -- -benchmark -vo null -fps 1000 movie.avi\fR |
---|
227 | .SH RESTRICTIONS |
---|
228 | .PP |
---|
229 | Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR on most |
---|
230 | Unix systems, \fBDYLD_INSERT_LIBRARIES\fR on Mac OS X) to run its child |
---|
231 | processes, it will fail in the presence of any mechanism that disables |
---|
232 | preloading. For instance setuid root binaries will not be fuzzed when run |
---|
233 | as an unprivileged user. |
---|
234 | .PP |
---|
235 | Though best efforts are made, identical behaviour for different versions of |
---|
236 | \fBzzuf\fR is not guaranteed. The reproducibility for subsequent calls on |
---|
237 | different operating systems and with different target programs is only |
---|
238 | guaranteed when the same version of \fBzzuf\fR is being used. |
---|
239 | .SH BUGS |
---|
240 | .PP |
---|
241 | It is not yet possible to insert or drop bytes from the input, to fuzz |
---|
242 | according to the file format, to swap bytes, etc. More advanced fuzzing |
---|
243 | methods are planned. |
---|
244 | .PP |
---|
245 | As of now, \fBzzuf\fR does not really support multithreaded applications. The |
---|
246 | behaviour with multithreaded applications where more than one thread does file |
---|
247 | descriptor operations is undefined. |
---|
248 | .SH NOTES |
---|
249 | In order to intercept file and network operations and signal handlers, |
---|
250 | \fBzzuf\fR diverts and reimplements the following functions: |
---|
251 | .TP |
---|
252 | Unix file descriptor handling: |
---|
253 | \fBopen\fR(), \fBlseek\fR(), \fBread\fR(), \fBaccept\fR(), \fBsocket\fR(), |
---|
254 | \fBmmap\fR(), \fBmunmap\fR(), \fBclose\fR() |
---|
255 | .TP |
---|
256 | Standard IO streams: |
---|
257 | \fBfopen\fR(), \fBfseek\fR(), \fBrewind\fR(), \fBfread\fR(), \fBgetc\fR(), |
---|
258 | \fBfgetc\fR(), \fBfgets\fR(), \fBungetc\fR(), \fBfclose\fR() |
---|
259 | .TP |
---|
260 | GNU libc specific: |
---|
261 | \fBopen64\fR(), \fBlseek64\fR(), \fBmmap64\fR(), \fBgetline\fR(), |
---|
262 | \fBgetdelim\fR(), \fB__getdelim\fR() |
---|
263 | .TP |
---|
264 | BSD specific: |
---|
265 | \fBfgetln\fR() |
---|
266 | .TP |
---|
267 | Signal handling: |
---|
268 | \fBsignal\fR(), \fBsigaction\fR() |
---|
269 | .PP |
---|
270 | If an application manipulates file descriptors (reading data, seeking around) |
---|
271 | using functions that are not in that list, \fBzzuf\fR will not fuzz its |
---|
272 | input consistently and the results should not be trusted. You can use a tool |
---|
273 | such as \fBltrace(1)\fR on Linux to know the missing functions. |
---|
274 | .PP |
---|
275 | One important unimplemented function is \fBfscanf\fR(), because of its |
---|
276 | complexity. Missing functions will be implemented based upon user request. |
---|
277 | .SH HISTORY |
---|
278 | .PP |
---|
279 | \fBZzuf\fR started its life in 2002 as the \fBstreamfucker\fR tool, a small |
---|
280 | multimedia stream corrupter used to find bugs in the \fBVLC\fR media player. |
---|
281 | .SH AUTHOR |
---|
282 | .PP |
---|
283 | Copyright \(co 2002, 2007 Sam Hocevar <sam@zoy.org>. |
---|
284 | .PP |
---|
285 | \fBZzuf\fR and this manual page are free software. They come without any |
---|
286 | warranty, to the extent permitted by applicable law. You can redistribute |
---|
287 | them and/or modify them under the terms of the Do What The Fuck You Want |
---|
288 | To Public License, Version 2, as published by Sam Hocevar. See |
---|
289 | \fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details. |
---|
290 | .PP |
---|
291 | \fBZzuf\fR's webpage can be found at \fBhttp://sam.zoy.org/zzuf/\fR. |
---|