Changeset 1539 for zzuf/trunk/doc/zzuf.1
- Timestamp:
- Jan 2, 2007, 6:15:34 PM (14 years ago)
- File:
-
- 1 edited
-
zzuf/trunk/doc/zzuf.1 (modified) (2 diffs)
Legend:
- Unmodified
- Added
- Removed
-
zzuf/trunk/doc/zzuf.1
r1536 r1539 3 3 zzuf \- multiple purpose fuzzer 4 4 .SH SYNOPSIS 5 .B zzuf 6 [ 7 .B \-cdhiqSv 8 ] [ 9 .B \-r 10 .I ratio 11 ] [ 12 .B \-s 13 .I seed 14 | 15 .B \-s 16 .I start:stop 17 ] 18 .PD 0 19 .IP 20 .PD 21 [ 22 .B \-F 23 .I children 24 ] [ 25 .B \-B 26 .I bytes 27 ] [ 28 .B \-T 29 .I seconds 30 ] 31 .PD 0 32 .IP 33 .PD 34 [ 35 .B \-I 36 .I include 37 ] [ 38 .B \-E 39 .I exclude 40 ] 41 .I COMMAND [ARGS]... 42 .RI 5 \fBzzuf\fR [\fB\-cdiqS\fR] [\fB\-r\fR \fIratio\fR] [\fB\-s\fR \fIseed\fR | \fB\-s\fR \fIstart:stop\fR] 6 .br 7 [\fB\-F\fR \fIchildren\fR] [\fB\-B\fR \fIbytes\fR] [\fB\-T\fR \fIseconds\fR] 8 .br 9 [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fICOMMAND\fR [\fIARGS\fR]... 10 .br 11 \fBzzuf \-h\fR | \fB\-\-help\fR 12 .br 13 \fBzzuf \-v\fR | \fB\-\-version\fR 43 14 .SH DESCRIPTION 44 .B Zzuf 45 is a transparent application input fuzzer. It works by intercepting 46 file operations and changing random bits in the program's input. 47 .B Zzuf's 15 .PP 16 \fBZzuf\fR is a transparent application input fuzzer. It works by intercepting 17 file operations and changing random bits in the program's input. \fBZzuf\fR's 48 18 behaviour is deterministic, making it easy to reproduce bugs. 49 .RI50 19 .SH USAGE 51 .B Zzuf 52 will run an application specified on its command line, one or several times, 53 with optional arguments, and will report the application's behaviour on 54 the standard output. 55 56 If you want to specify arguments for your application, put a 57 .B \-\- 58 marker before them on the command line, or 59 .B zzuf 60 will try to interpret them as arguments for itself. 61 .RI 20 .PP 21 \fBZzuf\fR will run an application specified on its command line, one or 22 several times, with optional arguments, and will report the application's 23 behaviour on the standard output. 24 .PP 25 If you want to specify arguments for your application, put a \fB\-\-\fR 26 marker before them on the command line, or \fBzzuf\fR will try to interpret 27 them as arguments for itself. 62 28 .SH OPTIONS 63 29 .TP 64 .B \-B, \-\-max\-bytes <n> 65 Automatically terminate child processes that output more than 66 .B <n> 67 bytes on the standard output and standard error channels. This is useful to 68 detect infinite loops. 30 \fB\-B\fR, \fB\-\-max\-bytes\fR=\fIn\fR 31 Automatically terminate child processes that output more than \fIn\fR bytes 32 on the standard output and standard error channels. This is useful to detect 33 infinite loops. See also the \fB\-T\fR flag. 69 34 .TP 70 .B \-c, \-\-cmdline 35 \fB\-c\fR, \fB\-\-cmdline\fR 71 36 Only fuzz files whose name is specified in the target application's command 72 37 line. This is mostly a shortcut to avoid specifiying twice the argument: 73 .B zzuf \-c cat file.txt 74 has the same effect as 75 .B zzuf \-I "^file\\.txt$" cat 76 .BR file.txt . 77 See the 78 .B \-I 79 flag for more information. 38 \fBzzuf \-c cat file.txt\fR has the same effect as \fBzzuf \-I 39 \(dq^file\\.txt$\(dq cat file.txt\fR. See the \fB\-I\fR flag for more 40 information. 80 41 .TP 81 .B \-d, \-\-debug 42 \fB\-d\fR, \fB\-\-debug\fR 82 43 Activate the display of debug messages. 83 44 .TP 84 .B \-E, \-\-exclude <regex> 85 Do not fuzz files whose name matches the 86 .B <regex> 87 regular expression. This option supersedes anything that is specified by the 88 .B \-\-include 89 flag. Use this for instance if you are unsure of what files your 90 application is going to read and do not want it to fuzz files in the 91 .B /etc 92 directory. 45 \fB\-E\fR, \fB\-\-exclude\fR=\fIregex\fR 46 Do not fuzz files whose name matches the \fIregex\fR regular expression. This 47 option supersedes anything that is specified by the \fB\-I\fR flag. Use this 48 for instance if you are unsure of what files your application is going to read 49 and do not want it to fuzz files in the \fB/etc\fR directory. 93 50 94 Multiple 95 .B \-E 96 flags can be specified, in which case files matching any one of the regular 97 expressions will be ignored. 51 Multiple \fB\-E\fR flags can be specified, in which case files matching any one 52 of the regular expressions will be ignored. 98 53 .TP 99 .B \-F, \-\-fork <children> 54 \fB\-F\fR, \fB\-\-fork\fR=\fIchildren\fR 100 55 Specify the number of simultaneous children that can be run. This option is 101 only useful if the 102 .B \-s 103 flag is used with an interval argument. 56 only useful if the \fB\-s\fR flag is used with an interval argument. 104 57 .TP 105 .B \-h, \-\-help 58 \fB\-h\fR, \fB\-\-help\fR 106 59 Display a short help message and exit. 107 60 .TP 108 .B \-i, \-\-stdin 109 Fuzz the application's standard input. By default 110 .B zzuf 111 only fuzzes files. 61 \fB\-i\fR, \fB\-\-stdin\fR 62 Fuzz the application's standard input. By default \fBzzuf\fR only fuzzes files. 112 63 .TP 113 .B \-I, \-\-include <regex> 114 Only fuzz files whose name matches the 115 .B <regex> 116 regular expression. Use this for instance if your application reads 117 configuration files at startup and you only want specific files to be fuzzed. 64 \fB\-I\fR, \fB\-\-include\fR=\fIregex\fR 65 Only fuzz files whose name matches the \fIregex\fR regular expression. Use 66 this for instance if your application reads configuration files at startup 67 and you only want specific files to be fuzzed. 118 68 119 Multiple 120 .B \-I 121 flags can be specified, in which case files matching any one of the regular 122 expressions will be fuzzed. See also the 123 .B \-c 124 flag. 69 Multiple \fB\-I\fR flags can be specified, in which case files matching any one 70 of the regular expressions will be fuzzed. See also the \fB\-c\fR flag. 125 71 .TP 126 .B \-q, \-\-quiet 72 \fB\-q\fR, \fB\-\-quiet\fR 127 73 Hide the output of the fuzzed application. This is useful if the application 128 74 is very verbose but only its exit code or signaled status is really useful to 129 75 you. 130 76 .TP 131 .B \-r, \-\-ratio <ratio> 77 \fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR 132 78 Specify the amount of bits that will be randomly fuzzed. A value of 0 133 79 will not fuzz anything. A value of 0.05 will fuzz 5% of the open files' … … 136 82 is 0.004 (fuzz 0.4% of the files' bits). 137 83 .TP 138 .B \-s, \-\-seed <seed> 84 \fB\-s\fR, \fB\-\-seed\fR=\fIseed\fR 139 85 .PD 0 140 86 .TP 141 .B \-s, \-\-seed <start:stop> 87 \fB\-s\fR, \fB\-\-seed\fR=\fIstart:stop\fR 142 88 .PD 143 89 Specify the random seed to use for fuzzing, or an interval of random seeds. 144 Running 145 .B zzuf 146 twice with the same random seed will fuzz the files exactly the same way, 147 even with a different target application. The purpose of this is to use 148 simple utilities such as 149 .B cat 150 or 151 .B cp 152 to generate a file that causes the target application to crash. 90 Running \fBzzuf\fR twice with the same random seed will fuzz the files exactly 91 the same way, even with a different target application. The purpose of this is 92 to use simple utilities such as \fBcat\fR or \fBcp\fR to generate a file that 93 causes the target application to crash. 153 94 154 If an interval is specified, 155 .B zzuf 156 will run the application several times, each time with a different seed, and 157 report the behaviour of each run. 95 If an interval is specified, \fBzzuf\fR will run the application several times, 96 each time with a different seed, and report the behaviour of each run. 158 97 .TP 159 .B \-S, \-\-signal 98 \fB\-S\fR, \fB\-\-signal\fR 160 99 Prevent children from installing signal handlers for signals that usually 161 cause coredumps. These signals are 162 .BR SIGABRT , 163 .BR SIGFPE , 164 .BR SIGILL , 165 .BR SIGQUIT , 166 .BR SIGSEGV , 167 .B SIGTRAP 168 and, if available on the running platform, 169 .BR SIGSYS , 170 .BR SIGEMT , 171 .BR SIGBUS , 172 .B SIGXCPU 173 and 174 .BR SIGXFSZ . 175 Instead of calling the signal handler, the application will simply crash. If 176 you do not want core dumps, you should set appropriate limits with the 177 .B limit coredumpsize 178 command. See your shell's documentation on how to set such limits. 100 cause coredumps. These signals are \fBSIGABRT\fR, \fBSIGFPE\fR, \fBSIGILL\fR, 101 \fBSIGQUIT\fR, \fBSIGSEGV\fR, \fBSIGTRAP\fR and, if available on the running 102 platform, \fBSIGSYS\fR, \fBSIGEMT\fR, \fBSIGBUS\fR, \fBSIGXCPU\fR and 103 \fBSIGXFSZ\fR. Instead of calling the signal handler, the application will 104 simply crash. If you do not want core dumps, you should set appropriate limits 105 with the \fBlimit coredumpsize\fR command. See your shell's documentation on 106 how to set such limits. 179 107 .TP 180 .B \-T, \-\-max\-time <n> 181 Automatically terminate child processes that run for more than 182 .B <n> 108 \fB\-T\fR, \fB\-\-max\-time\fR=\fIn\fR 109 Automatically terminate child processes that run for more than \fIn\fR 183 110 seconds. This is useful to detect infinite loops or processes stuck in other 184 situations. 111 situations. See also the \fB\-B\fR flag. 185 112 .TP 186 .B \-v, \-\-version 113 \fB\-v\fR, \fB\-\-version\fR 187 114 Output version information and exit. 188 .RI189 115 .SH EXAMPLES 190 Fuzz the input of the 191 .B cat 192 program using default settings: 116 .PP 117 Fuzz the input of the \fBcat\fR program using default settings: 118 .PP 119 .RS 193 120 .nf 194 195 .B % zzuf cat /etc/motd 196 121 \fB# zzuf cat /etc/motd\fR 197 122 .fi 198 Fuzz 1% of the input bits of the 199 .B cat 200 program using seed 94324: 123 .RE 124 .PP 125 Fuzz 1% of the input bits of the \fBcat\fR program using seed 94324: 126 .PP 127 .RS 201 128 .nf 202 203 .B % zzuf -s 94324 -r 0.01 cat /etc/motd 204 129 \fB# zzuf -s 94324 -r 0.01 cat /etc/motd\fR 205 130 .fi 206 Fuzz the input of the 207 .B convert 208 program, using file 209 .B foo.jpeg 210 as the original input and excluding 211 .B .xml 212 files from fuzzing (because 213 .B convert 214 will also open its own XML configuration files and we do not want 215 .B zzuf 216 to fuzz them): 131 .RE 132 .PP 133 Fuzz the input of the \fBconvert\fR program, using file \fBfoo.jpeg\fR as the 134 original input and excluding \fB.xml\fR files from fuzzing (because 135 \fBconvert\fR will also open its own XML configuration files and we do not 136 want \fBzzuf\fR to fuzz them): 137 .PP 138 .RS 217 139 .nf 218 219 .B % zzuf -E "\\.xml$" convert -- foo.jpeg -format tga /dev/null 220 140 \fB# zzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR 221 141 .fi 222 Fuzz the input of 223 .BR vlc , 224 using file 225 .B movie.avi 226 as the original input and restricting fuzzing to filenames that appear on 227 the command line, then generate 228 .B fuzzy-movie.avi 229 which is a file that can be fed to 230 .B vlc 231 to reproduce the same behaviour without using 232 .BR zzuf : 233 .fn 234 235 .B % zzuf -c -s 87423 -r 0.01 vlc movie.avi 236 237 .B % zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi 238 239 .B % vlc fuzzy-movie.avi 240 142 .RE 143 .PP 144 Fuzz the input of \fBvlc\fR, using file \fBmovie.avi\fR as the original input 145 and restricting fuzzing to filenames that appear on the command line 146 (\fB\-c\fR), then generate \fBfuzzy-movie.avi\fR which is a file that can 147 be read by \fBvlc\fR to reproduce the same behaviour without using \fBzzuf\fR: 148 .PP 149 .RS 150 .nf 151 \fB# zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR 152 \fB# zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR 153 \fB# vlc fuzzy-movie.avi\fR 241 154 .fi 242 Fuzz 2% of 243 .BR mplayer 's 244 input bits 245 .RB ( \-r 246 .BR 0.02 ) 247 with seeds 0 to 9999 248 .RB ( \-s 249 .BR 0:10000 ), 250 disabling its standard output messages 251 .RB ( \-q ), 252 launching up to three simultaneous child processes 253 .RB ( \-F 254 .BR 3 ), 255 killing 256 .B mplayer 257 if it takes more than one minute to read the file 258 .RB ( \-T 259 .BR 60 ) 260 and disabling its 261 .B SIGSEGV 262 signal handler 263 .RB ( \-S ): 264 .fn 265 266 .B % zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 mplayer movie.avi -- -benchmark -vo null -fps 1000 267 155 .RE 156 .PP 157 Fuzz 2% of \fBmplayer\fR's input bits (\fB\-r 0.02\fR) with seeds 0 to 9999 158 (\fB\-s 0:10000\fR), disabling its standard output messages (\fB\-q\fR), 159 launching up to three simultaneous child processes (\fB\-F 3\fR), killing 160 \fBmplayer\fR if it takes more than one minute to read the file (\fB\-T 60\fR) 161 and disabling its \fBSIGSEGV\fR signal handler (\fB\-S\fR): 162 .PP 163 .RS 164 .nf 165 \fB# zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR 166 \fB mplayer movie.avi -- -benchmark -vo null -fps 1000\fR 268 167 .fi 269 .R I168 .RE 270 169 .SH BUGS 271 Only the most common file operations are implemented as of now: 272 .BR open (), 273 .BR read (), 274 .BR fopen (), 275 .BR fseek (), 276 etc. One important unimplemented function is 277 .BR fscanf (). 278 170 .PP 171 Only the most common file operations are implemented as of now: \fBopen\fR(), 172 \fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented 173 function is \fBfscanf\fR(). 174 .PP 279 175 Network fuzzing is not implemented. It is not yet possible to insert or 280 176 drop bytes from the input, to fuzz according to the file format, or to do 281 177 all these complicated operations. They are planned, though. 282 283 Due to 284 .B zzuf 285 using 286 .B LD_PRELOAD 287 to run its child processes, it will fail in the presence of any mechanism 288 that disables preloading. For instance setuid root binaries will not be 289 fuzzed. 290 .RI 178 .PP 179 Due to \fBzzuf\fR using \fBLD_PRELOAD\fR to run its child processes, it will 180 fail in the presence of any mechanism that disables preloading. For instance 181 setuid root binaries will not be fuzzed when run as an unprivileged user. 291 182 .SH AUTHOR 292 .B Zzuf 293 and this manual page were written by Sam Hocevar <sam@zoy.org>. There is a 294 webpage available at http://sam.zoy.org/zzuf/ 183 .PP 184 Copyright \(co 2006, 2007 Sam Hocevar <sam@zoy.org>. 185 .PP 186 \fBZzuf\fR and this manual page are free software. They come without any 187 warranty, to the extent permitted by applicable law. You can redistribute 188 them and/or modify them under the terms of the Do What The Fuck You Want 189 To Public License, Version 2, as published by Sam Hocevar. See 190 \fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details. 191 .PP 192 \fBZzuf\fR's webpage can be found at \fBhttp://sam.zoy.org/zzuf/\fR.
Note: See TracChangeset
for help on using the changeset viewer.
