source: zzuf/trunk/doc/libzzuf.3.in @ 4236

.TH libzzuf 3 "2010-01-06" "libzzuf @PACKAGE_VERSION@"
.SH NAME
libzzuf \- helper library for the zzuf multiple purpose fuzzer
.SH DESCRIPTION
.PP
\fBlibzzuf\fR is a helper library automatically preloaded by \fBzzuf\fR when
fuzzing applications, but it can also be used alone for debugging purposes or
specific cases that cannot be covered by \fBzzuf\fR.
.SH USAGE
.PP
\fBlibzzuf\fR must be preloaded using the operating system's default way of
preloading libraries. For instance, on a typical Linux installation:
.PP
\fB    LD_PRELOAD=/usr/lib/zzuf/libzzuf.so\fR
.SH ENVIRONMENT VARIABLES
.PP
\fBlibzzuf\fR's initial setup is done through environment variables. After
they are read, no further information can be sent to the fuzzed process.

All environment variables are optional.
.TP
\fBZZUF_DEBUG\fR
This environment variable is set to the debugging level. 0 means no debugging
information is sent to \fBzzuf\fR. 1 logs important information as well as
all diverted functions. 2 logs fuzzing status and all optional file stream
information.
.TP
\fBZZUF_DEBUGFD\fR
This environment variable is set to a file descriptor where \fBlibzzuf\fR will
send debugging information. This is used to send data to the main \fBzzuf\fR
controlling binary.
.TP
\fBZZUF_SEED\fR
This variable is set to the initial random seed. Corresponding \fBzzuf\fR flag:
\fB\-\-seed\fR.
.TP
\fBZZUF_MINRATIO\fR, \fBZZUF_MAXRATIO\fR
These variables are set to the minimal and maximal fuzzing ratios.
Corresponding \fBzzuf\fR flag: \fB\-\-ratio\fR.
.TP
\fBZZUF_AUTOINC\fR
If this variable is set, the random seed is incremented each time a new
file is opened. Corresponding \fBzzuf\fR flag: \fB\-\-autoinc\fR.
.TP
\fBZZUF_BYTES\fR
This variable contains byte ranges to which fuzzing should be restricted.
Corresponding \fBzzuf\fR flag: \fB\-\-bytes\fR.
.TP
\fBZZUF_LIST\fR
This variable contains file descriptor ranges to which fuzzing should be
restricted. Corresponding \fBzzuf\fR flag: \fB\-\-list\fR.
.TP
\fBZZUF_NETWORK\fR
If this variable is set, network mode is activated. Corresponding \fBzzuf\fR
flag: \fB\-\-network\fR.
.TP
\fBZZUF_PORTS\fR
This variable contains port ranges to which fuzzing should be restricted.
Corresponding \fBzzuf\fR flag: \fB\-\-port\fR.
.TP
\fBZZUF_PROTECT\fR, \fBZZUF_REFUSE\fR
These variables contain character ranges to protect or refuse. Corresponding
\fBzzuf\fR flags: \fB\-\-protect\fR, \fB\-\-refuse\fR.
.TP
\fBZZUF_INCLUDE\fR, \fBZZUF_EXCLUDE\fR
These variables contain regular expressions to indicate which files should be
included or excluded from the list of fuzzed files. Corresponding \fBzzuf\fR
flags: \fB\-\-include\fR, \fB\-\-exclude\fR.
.TP
\fBZZUF_SIGNAL\fR
If this variable is set, the fuzzed process will be prevented from installing
signal handlers that usually cause coredumps. Corresponding \fBzzuf\fR flag:
\fB\-\-signal\fR.
.TP
\fBZZUF_MEMORY\fR
This variable contains the maximum amount of memory that the fuzzed process
is allowed to allocate. Corresponding \fBzzuf\fR flag: \fB\-\-max-memory\fR.
.TP
\fBZZUF_STDIN\fR
If this variable is set, standard input will be fuzzed, too. Corresponding
\fBzzuf\fR flag: \fB\-\-stdin\fR.
.SH NOTES
In order to intercept file and network operations, signal handlers and memory
allocations, \fBlibzzuf\fR diverts and reimplements the following functions,
which can sometimes be private C library symbols, too:
.TP
Unix file descriptor handling:
\fBopen\fR(), \fBdup\fR(), \fBdup2\fR(), \fBlseek\fR(), \fBread\fR(),
\fBreadv\fR(), \fBpread\fR(), \fBaccept\fR(), \fBsocket\fR(), \fBrecv\fR(),
\fBrecvfrom\fR(), \fBrecvmsg\fR(), \fBaio_read\fR(), \fBaio_return\fR(),
\fBclose\fR()
.TP
Standard IO streams:
\fBfopen\fR(), \fBfreopen\fR(), \fBfseek\fR(), \fBfseeko\fR(), \fBrewind\fR(),
\fBfread\fR(), \fBgetc\fR(), \fBgetchar\fR(), \fBfgetc\fR(), \fBfgets\fR(),
\fBungetc\fR(), \fBfclose\fR()
.TP
Memory management:
\fBmmap\fR(), \fBmunmap\fR(), \fBmalloc\fR(), \fBcalloc\fR(), \fBvalloc\fR(),
\fBfree\fR(), \fBmemalign\fR(), \fBposix_memalign\fR()
.TP
Required on Linux:
\fBopen64\fR(), \fBlseek64\fR(), \fBmmap64\fR(), \fB_IO_getc\fR(),
\fBgetline\fR(), \fBgetdelim\fR(), \fB__getdelim\fR(), \fBgetc_unlocked\fR(),
\fBgetchar_unlocked\fR(), \fBfgetc_unlocked\fR(), \fBfgets_unlocked\fR(),
\fBfread_unlocked\fR(), \fB__uflow\fR()
.TP
Required on BSD systems:
\fBfgetln\fR(), \fB__srefill\fR(), \fB__srget\fR()
.TP
Required on Mac OS X:
\fBmap_fd\fR()
.TP
Required on HP-UX:
\fB__open64\fR(), \fB__lseek64\fR(), \fB__filbuf\fR()
.TP
Required on OpenSolaris:
\fBfreopen64\fR(), \fBfseeko64\fR(), \fBfsetpos64\fR()
.TP
Signal handling:
\fBsignal\fR(), \fBsigaction\fR()
.PP
If an application manipulates file descriptors (reading data, seeking around)
using functions that are not in that list, \fBlibzzuf\fR will not fuzz its
input consistently and the results should not be trusted. You can use a tool
such as \fBltrace(1)\fR on Linux to know the missing functions.
.PP
On BSD systems, such as FreeBSD or Mac OS X, \fB__srefill\fR() is enough to
monitor all standard IO streams functions. On other systems, such as Linux,
each function is reimplemented on a case by case basis. One important
unimplemented function is \fBfscanf\fR(), because of its complexity. Missing
functions will be added upon user request.
.SH SEE ALSO
.PP
\fBzzuf(1)\fR, \fBld.so(8)\fR
.SH AUTHOR
.PP
Copyright \(co 2002, 2007\-2010 Sam Hocevar <sam@hocevar.net>.
.PP
\fBlibzzuf\fR and this manual page are free software. They come without any
warranty, to the extent permitted by applicable law. You can redistribute
them and/or modify them under the terms of the Do What The Fuck You Want
To Public License, Version 2, as published by Sam Hocevar. See
\fBhttp://sam.zoy.org/wtfpl/COPYING\fR for more details.
.PP
\fBzzuf\fR's webpage can be found at \fBhttp://caca.zoy.org/wiki/zzuf\fR.
An overview of the architecture and inner works is at
\fBhttp://caca.zoy.org/wiki/zzuf/internals\fR.