Changeset 1557 for zzuf/trunk/doc


Ignore:
Timestamp:
Jan 4, 2007, 2:28:35 PM (14 years ago)
Author:
Sam Hocevar
Message:
  • Improved manpage, especially the statistical effect of using -R.
File:
1 edited

Legend:

Unmodified
Added
Removed
  • zzuf/trunk/doc/zzuf.1

    r1555 r1557  
    99              [\fB\-P\fR \fIlist\fR] [\fB\-R\fR \fIlist\fR]
    1010.br
    11               [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fICOMMAND\fR [\fIARGS\fR]...
     11              [\fB\-I\fR \fIinclude\fR] [\fB\-E\fR \fIexclude\fR] \fIPROGRAM\fR [\fIARGS\fR]...
    1212.br
    1313\fBzzuf \-h\fR | \fB\-\-help\fR
     
    2323\fBZzuf\fR will run an application specified on its command line, one or
    2424several times, with optional arguments, and will report the application's
    25 behaviour on the standard output.
    26 .PP
    27 If you want to specify arguments for your application, put a \fB\-\-\fR
    28 marker before them on the command line, or \fBzzuf\fR will try to interpret
    29 them as arguments for itself.
     25relevant behaviour on the standard output, eg:
     26.PP
     27.RS
     28.nf
     29\fBzzuf cat /dev/zero\fR
     30.fi
     31.RE
     32.PP
     33If you want to specify flags for your application, put a '\fB\-\-\fR'
     34marker before them on the command line (otherwise \fBzzuf\fR will try to
     35interpret them as arguments for itself), eg:
     36.PP
     37.RS
     38.nf
     39\fBzzuf \-B 1000 cat \-\- \-v /dev/zero\fR
     40.fi
     41.RE
    3042.SH OPTIONS
    3143.TP
     
    7789.RS
    7890.TP
     91\fB\\0\fR
     92null byte
     93.TP
    7994\fB\\n\fR
    8095new line
     
    86101tabulation
    87102.TP
    88 \fB\\0\fR
    89 the null character
    90 .TP
    91103\fB\\x\fR\fINN\fR
    92104the byte whose hexadecimal value is \fINN\fR
     
    97109.IP
    98110You can use '\fB-\fR' to specify ranges. For instance, to protect all bytes
    99 from '\fB\\x01\fR' to ' ', use \fB\-P \(dq\\x01- \(dq\fR.
     111from '\fB\\x01\fR' to ' ', use '\fB\-P \(dq\\x01- \(dq\fR'.
     112
     113The statistical outcome of this option should not be overlooked. Because
     114\fBzzuf\fR cannot know the nature of the input data beforehands and must
     115fuzz it even if only one byte of data was received, protecting characters
     116may change the meaning of the \fB\-r\fR flag depending on the data being
     117fuzzed. For instance, asking to fuzz 1% of input bits and to protect
     118lowercase characters (using '\fB\-r 0.01 \-P a-z\fR') will result in an
     119actual average fuzzing ratio of 0.9% with truly random data, 0.3% with
     120random ASCII data and 0.2% with a normal English text.
    100121
    101122See also the \fB\-R\fR flag.
     
    107128.TP
    108129\fB\-r\fR, \fB\-\-ratio\fR=\fIratio\fR
    109 Specify the amount of bits that will be randomly fuzzed. A value of 0
     130Specify the proportion of bits that will be randomly fuzzed. A value of 0
    110131will not fuzz anything. A value of 0.05 will fuzz 5% of the open files'
    111132bits. A value of 1.0 or more will fuzz all the bytes, theoretically making
     
    160181.RS
    161182.nf
    162 \fB# zzuf cat /etc/motd\fR
     183\fBzzuf cat /etc/motd\fR
    163184.fi
    164185.RE
     
    168189.RS
    169190.nf
    170 \fB# zzuf -s 94324 -r 0.01 cat /etc/motd\fR
     191\fBzzuf -s 94324 -r 0.01 cat /etc/motd\fR
    171192.fi
    172193.RE
     
    177198.RS
    178199.nf
    179 \fB# zzuf -P \(dq\\n\(dq -R \(dq\\0-\\x1f\\x7f-\\xff\(dq cat /etc/motd\fR
     200\fBzzuf -P \(dq\\n\(dq -R \(dq\\0-\\x1f\\x7f-\\xff\(dq cat /etc/motd\fR
    180201.fi
    181202.RE
     
    188209.RS
    189210.nf
    190 \fB# zzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
     211\fBzzuf -E \(dq\\.xml$\(dq convert -- foo.jpeg -format tga /dev/null\fR
    191212.fi
    192213.RE
     
    199220.RS
    200221.nf
    201 \fB# zzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
    202 \fB# zzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
    203 \fB# vlc fuzzy-movie.avi\fR
     222\fBzzuf -c -s 87423 -r 0.01 vlc movie.avi\fR
     223\fBzzuf -c -s 87423 -r 0.01 cp movie.avi fuzzy-movie.avi\fR
     224\fBvlc fuzzy-movie.avi\fR
    204225.fi
    205226.RE
     
    213234.RS
    214235.nf
    215 \fB# zzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
    216 \fB    mplayer movie.avi -- -benchmark -vo null -fps 1000\fR
     236\fBzzuf -c -q -s 0:10000 -F 3 -T 60 -r 0.02 \\\fR
     237\fB  mplayer -- -benchmark -vo null -fps 1000 movie.avi\fR
    217238.fi
    218239.RE
    219240.SH BUGS
    220241.PP
    221 Only the most common file operations are implemented as of now: \fBopen\fR(),
     242Due to \fBzzuf\fR using shared object preloading (\fBLD_PRELOAD\fR on most
     243Unix systems, \fBDYLD_INSERT_LIBRARIES\fR on Mac OS X) to run its child
     244processes, it will fail in the presence of any mechanism that disables
     245preloading. For instance setuid root binaries will not be fuzzed when run
     246as an unprivileged user. This limitation will probably not be addressed.
     247.PP
     248Network fuzzing is not implemented. This feature will be added.
     249.PP
     250It is not yet possible to insert or drop bytes from the input, to fuzz
     251according to the file format, or to do all these complicated operations. These
     252features are planned.
     253.PP
     254Only the most common file operations are implemented: \fBopen\fR(),
    222255\fBread\fR(), \fBfopen\fR(), \fBfseek\fR(), etc. One important unimplemented
    223 function is \fBfscanf\fR().
    224 .PP
    225 Network fuzzing is not implemented. It is not yet possible to insert or
    226 drop bytes from the input, to fuzz according to the file format, or to do
    227 all these complicated operations. They are planned, though.
    228 .PP
    229 Due to \fBzzuf\fR using \fBLD_PRELOAD\fR to run its child processes, it will
    230 fail in the presence of any mechanism that disables preloading. For instance
    231 setuid root binaries will not be fuzzed when run as an unprivileged user.
     256function is \fBfscanf\fR(). These features will be implemented based on user
     257request.
    232258.PP
    233259As of now, \fBzzuf\fR does not really support multithreaded applications. The
    234 behaviour with multithreaded applications where more than one thread do file
    235 descriptor operations is undefined.
     260behaviour with multithreaded applications where more than one thread does file
     261descriptor operations is undefined. This bug will be fixed.
     262.PP
     263Though best efforts are made, the reproducibility of \fBzzuf\fR's behaviour
     264is guaranteed for subsequent calls with the same arguments but not for calls
     265with different \fBzzuf\fR versions.
    236266.SH AUTHOR
    237267.PP
Note: See TracChangeset for help on using the changeset viewer.