source: zzuf/trunk/doc/zzuf.1 @ 1507

Last change on this file since 1507 was 1507, checked in by Sam Hocevar, 14 years ago
  • Wrote a manpage. Phew.
File size: 4.7 KB
Line 
1.TH zzuf 1 "2006-12-22" "zzuf"
2.SH NAME
3zzuf \- multiple purpose fuzzer
4.SH SYNOPSIS
5.B zzuf
6[
7.B \-vqdh
8] [
9.B \-r
10.I ratio
11] [
12.B \-s
13.I seed[:stop]
14] [
15.B \-F
16.I children
17]
18.PD 0
19.IP
20.PD
21[
22.B \-B
23.I bytes
24] [
25.B \-T
26.I seconds
27]
28.PD 0
29.IP
30.PD
31[
32.B \-i
33.I include
34] [
35.B \-e
36.I exclude
37]
38.I COMMAND [ARGS]...
39.RI
40.SH DESCRIPTION
41.B Zzuf
42is a transparent application input fuzzer. It works by intercepting
43file operations and changing random bits in the program's input.
44.B Zzuf's
45behaviour is deterministic, making it easy to reproduce bugs.
46.RI
47.SH USAGE
48.B Zzuf
49will run an application specified on its command line, one or several times,
50with optional arguments, and will report the application's behaviour on
51the standard output.
52
53If you want to specify arguments for your application, put a
54.B \-\-
55marker before them on the command line, or
56.B zzuf
57will try to interpret them as arguments for itself.
58.RI
59.SH OPTIONS
60.TP
61.B \-r, \-\-ratio <ratio>
62Specify the amount of bits that will be randomly fuzzed. A value of 0
63will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
64bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
65the input files undiscernible from random data. The default fuzzing ratio
66is 0.004 (fuzz 0.4% of the files' bits).
67.TP
68.B \-s, \-\-seed <seed>
69.PD 0
70.TP
71.B \-s, \-\-seed <start:stop>
72.PD
73Specify the random seed to use for fuzzing, or an interval of random seeds.
74Running
75.B zzuf
76twice with the same random seed will fuzz the files exactly the same way,
77even with a different target application. The purpose of this is to use
78simple utilities such as
79.B cat
80or
81.B cp
82to generate a file that causes the target application to crash.
83
84If an interval is specified,
85.B zzuf
86will run the application several times, each time with a different seed, and
87report the behaviour of each run.
88.TP
89.B \-F, \-\-fork <children>
90Specify the number of simultaneous children that can be run. This option is
91only useful if the
92.B \-s
93flag is used with an interval argument.
94.TP
95.B \-B, \-\-max\-bytes <n>
96Automatically terminate child processes that output more than
97.B <n>
98bytes on the standard output and standard error channels. This is useful to
99detect infinite loops.
100.TP
101.B \-T, \-\-max\-time <n>
102Automatically terminate child processes that run for more than
103.B <n>
104seconds. This is useful to detect infinite loops or processes stuck in other
105situations.
106.TP
107.B \-q, \-\-quiet
108Hide the output of the fuzzed application. This is useful if the application
109is very verbose but only its exit code is really useful to you.
110.TP
111.B \-i, \-\-include <regex>
112Only fuzz files whose name matches the
113.B <regex>
114regular expression. Use this for instance if your application reads
115configuration files in many places and you do not want them to be fuzzed.
116.TP
117.B \-e, \-\-exclude <regex>
118Do not fuzz files whose name matches the
119.B <regex>
120regular expression. This option supersedes anything that is specified by the
121.B \-\-exclude
122flag. Use this for instance if you do not know for sure what files your
123application is going to read, but do not want it to fuzz files in the
124.B /etc
125directory.
126.TP
127.B \-d, \-\-debug
128Activate the display of debug messages.
129.TP
130.B \-h, \-\-help
131Display a short help message and exit.
132.TP
133.B \-v, \-\-version
134Output version information and exit.
135.RI
136.SH EXAMPLES
137Fuzz the input of the
138.B cat
139program using default settings:
140.nf
141
142.B % zzuf cat /etc/motd
143
144.fi
145Fuzz 1% of the input bits of the
146.B cat
147program using seed 94324:
148.nf
149
150.B % zzuf -s 94324 -r 0.01 cat /etc/motd
151
152.fi
153Fuzz the input of the
154.B convert
155program, using file
156.B foo.jpeg
157as the original input and restricting fuzzing to filenames matching the
158regular expression
159.B "foo[.]jpeg"
160(because
161.B convert
162will also open its own configuration files and we do not want
163.B zzuf
164to fuzz them):
165.nf
166
167.B % zzuf -i "foo[.]jpeg" convert -- foo.jpeg -format tga /dev/null
168
169.fi
170Fuzz the input of
171.BR vlc ,
172using file
173.B movie.avi
174as the original input, and generate
175.B fuzzy-movie.avi
176which is a file that can be fed to
177.B vlc
178to reproduce the same behaviour without using
179.BR zzuf :
180.fn
181
182.B % zzuf -s 87423 -r 0.01 vlc movie.avi
183
184.B % zzuf -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi
185
186.B % vlc fuzzy-movie.avi
187
188.fi
189.RI
190.SH BUGS
191Only the most common file operations are implemented as of now:
192.BR open (),
193.BR read (),
194.BR fopen (),
195.BR fseek (),
196etc. One important unimplemented function is
197.BR fopen ().
198
199Network fuzzing is not implemented. It is not yet possible to insert or
200drop bytes from the input, to fuzz according to the file format, or to do
201all these complicated operations. They are planned, though.
202.RI
203.SH AUTHOR
204.B Zzuf
205and this manual page were written by Sam Hocevar <sam@zoy.org>. There is a
206webpage available at http://sam.zoy.org/zzuf/
Note: See TracBrowser for help on using the repository browser.