You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
282 lines
12 KiB
282 lines
12 KiB
=======================
|
|
Environmental variables
|
|
=======================
|
|
|
|
This document discusses the environment variables used by American Fuzzy Lop
|
|
to expose various exotic functions that may be (rarely) useful for power
|
|
users or for some types of custom fuzzing setups. See README for the general
|
|
instruction manual.
|
|
|
|
1) Settings for afl-gcc, afl-clang, and afl-as
|
|
----------------------------------------------
|
|
|
|
Because they can't directly accept command-line options, the compile-time
|
|
tools make fairly broad use of environmental variables:
|
|
|
|
- Setting AFL_HARDEN automatically adds code hardening options when invoking
|
|
the downstream compiler. This currently includes -D_FORTIFY_SOURCE=2 and
|
|
-fstack-protector-all. The setting is useful for catching non-crashing
|
|
memory bugs at the expense of a very slight (sub-5%) performance loss.
|
|
|
|
- By default, the wrapper appends -O3 to optimize builds. Very rarely, this
|
|
will cause problems in programs built with -Werror, simply because -O3
|
|
enables more thorough code analysis and can spew out additional warnings.
|
|
To disable optimizations, set AFL_DONT_OPTIMIZE.
|
|
|
|
- Setting AFL_USE_ASAN automatically enables ASAN, provided that your
|
|
compiler supports that. Note that fuzzing with ASAN is mildly challenging
|
|
- see notes_for_asan.txt.
|
|
|
|
(You can also enable MSAN via AFL_USE_MSAN; ASAN and MSAN come with the
|
|
same gotchas; the modes are mutually exclusive. UBSAN and other exotic
|
|
sanitizers are not officially supported yet, but are easy to get to work
|
|
by hand.)
|
|
|
|
- Setting AFL_CC, AFL_CXX, and AFL_AS lets you use alternate downstream
|
|
compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries
|
|
in your $PATH.
|
|
|
|
- AFL_PATH can be used to point afl-gcc to an alternate location of afl-as.
|
|
One possible use of this is experimental/clang_asm_normalize/, which lets
|
|
you instrument hand-written assembly when compiling clang code by plugging
|
|
a normalizer into the chain. (There is no equivalent feature for GCC.)
|
|
|
|
- Setting AFL_INST_RATIO to a percentage between 0 and 100% controls the
|
|
probability of instrumenting every branch. This is (very rarely) useful
|
|
when dealing with exceptionally complex programs that saturate the output
|
|
bitmap. Examples include v8, ffmpeg, and perl.
|
|
|
|
(If this ever happens, afl-fuzz will warn you ahead of the time by
|
|
displaying the "bitmap density" field in fiery red.)
|
|
|
|
Setting AFL_INST_RATIO to 0 is a valid choice. This will instrument only
|
|
the transitions between function entry points, but not individual branches.
|
|
|
|
- AFL_NO_BUILTIN causes the compiler to generate code suitable for use with
|
|
libtokencap.so (but perhaps running a bit slower than without the flag).
|
|
|
|
- TMPDIR is used by afl-as for temporary files; if this variable is not set,
|
|
the tool defaults to /tmp.
|
|
|
|
- Setting AFL_KEEP_ASSEMBLY prevents afl-as from deleting instrumented
|
|
assembly files. Useful for troubleshooting problems or understanding how
|
|
the tool works. To get them in a predictable place, try something like:
|
|
|
|
mkdir assembly_here
|
|
TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all
|
|
|
|
- Setting AFL_QUIET will prevent afl-cc and afl-as banners from being
|
|
displayed during compilation, in case you find them distracting.
|
|
|
|
2) Settings for afl-clang-fast
|
|
------------------------------
|
|
|
|
The native LLVM instrumentation helper accepts a subset of the settings
|
|
discussed in section #1, with the exception of:
|
|
|
|
- AFL_AS, since this toolchain does not directly invoke GNU as.
|
|
|
|
- TMPDIR and AFL_KEEP_ASSEMBLY, since no temporary assembly files are
|
|
created.
|
|
|
|
Note that AFL_INST_RATIO will behave a bit differently than for afl-gcc,
|
|
because functions are *not* instrumented unconditionally - so low values
|
|
will have a more striking effect. For this tool, 0 is not a valid choice.
|
|
|
|
3) Settings for afl-fuzz
|
|
------------------------
|
|
|
|
The main fuzzer binary accepts several options that disable a couple of sanity
|
|
checks or alter some of the more exotic semantics of the tool:
|
|
|
|
- Setting AFL_SKIP_CPUFREQ skips the check for CPU scaling policy. This is
|
|
useful if you can't change the defaults (e.g., no root access to the
|
|
system) and are OK with some performance loss.
|
|
|
|
- Setting AFL_NO_FORKSRV disables the forkserver optimization, reverting to
|
|
fork + execve() call for every tested input. This is useful mostly when
|
|
working with unruly libraries that create threads or do other crazy
|
|
things when initializing (before the instrumentation has a chance to run).
|
|
|
|
Note that this setting inhibits some of the user-friendly diagnostics
|
|
normally done when starting up the forkserver and causes a pretty
|
|
significant performance drop.
|
|
|
|
- AFL_EXIT_WHEN_DONE causes afl-fuzz to terminate when all existing paths
|
|
have been fuzzed and there were no new finds for a while. This would be
|
|
normally indicated by the cycle counter in the UI turning green. May be
|
|
convenient for some types of automated jobs.
|
|
|
|
- Setting AFL_NO_AFFINITY disables attempts to bind to a specific CPU core
|
|
on Linux systems. This slows things down, but lets you run more instances
|
|
of afl-fuzz than would be prudent (if you really want to).
|
|
|
|
- AFL_SKIP_CRASHES causes AFL to tolerate crashing files in the input
|
|
queue. This can help with rare situations where a program crashes only
|
|
intermittently, but it's not really recommended under normal operating
|
|
conditions.
|
|
|
|
- Setting AFL_HANG_TMOUT allows you to specify a different timeout for
|
|
deciding if a particular test case is a "hang". The default is 1 second
|
|
or the value of the -t parameter, whichever is larger. Dialing the value
|
|
down can be useful if you are very concerned about slow inputs, or if you
|
|
don't want AFL to spend too much time classifying that stuff and just
|
|
rapidly put all timeouts in that bin.
|
|
|
|
- AFL_NO_ARITH causes AFL to skip most of the deterministic arithmetics.
|
|
This can be useful to speed up the fuzzing of text-based file formats.
|
|
|
|
- AFL_SHUFFLE_QUEUE randomly reorders the input queue on startup. Requested
|
|
by some users for unorthodox parallelized fuzzing setups, but not
|
|
advisable otherwise.
|
|
|
|
- When developing custom instrumentation on top of afl-fuzz, you can use
|
|
AFL_SKIP_BIN_CHECK to inhibit the checks for non-instrumented binaries
|
|
and shell scripts; and AFL_DUMB_FORKSRV in conjunction with the -n
|
|
setting to instruct afl-fuzz to still follow the fork server protocol
|
|
without expecting any instrumentation data in return.
|
|
|
|
- When running in the -M or -S mode, setting AFL_IMPORT_FIRST causes the
|
|
fuzzer to import test cases from other instances before doing anything
|
|
else. This makes the "own finds" counter in the UI more accurate.
|
|
Beyond counter aesthetics, not much else should change.
|
|
|
|
- Setting AFL_POST_LIBRARY allows you to configure a postprocessor for
|
|
mutated files - say, to fix up checksums. See experimental/post_library/
|
|
for more.
|
|
|
|
- AFL_FAST_CAL keeps the calibration stage about 2.5x faster (albeit less
|
|
precise), which can help when starting a session against a slow target.
|
|
|
|
- The CPU widget shown at the bottom of the screen is fairly simplistic and
|
|
may complain of high load prematurely, especially on systems with low core
|
|
counts. To avoid the alarming red color, you can set AFL_NO_CPU_RED.
|
|
|
|
- In QEMU mode (-Q), AFL_PATH will be searched for afl-qemu-trace.
|
|
|
|
- Setting AFL_PRELOAD causes AFL to set LD_PRELOAD for the target binary
|
|
without disrupting the afl-fuzz process itself. This is useful, among other
|
|
things, for bootstrapping libdislocator.so.
|
|
|
|
- Setting AFL_NO_UI inhibits the UI altogether, and just periodically prints
|
|
some basic stats. This behavior is also automatically triggered when the
|
|
output from afl-fuzz is redirected to a file or to a pipe.
|
|
|
|
- If you are Jakub, you may need AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES.
|
|
Others need not apply.
|
|
|
|
- Benchmarking only: AFL_BENCH_JUST_ONE causes the fuzzer to exit after
|
|
processing the first queue entry; and AFL_BENCH_UNTIL_CRASH causes it to
|
|
exit soon after the first crash is found.
|
|
|
|
4) Settings for afl-qemu-trace
|
|
------------------------------
|
|
|
|
The QEMU wrapper used to instrument binary-only code supports several settings:
|
|
|
|
- It is possible to set AFL_INST_RATIO to skip the instrumentation on some
|
|
of the basic blocks, which can be useful when dealing with very complex
|
|
binaries.
|
|
|
|
- Setting AFL_INST_LIBS causes the translator to also instrument the code
|
|
inside any dynamically linked libraries (notably including glibc).
|
|
|
|
- The underlying QEMU binary will recognize any standard "user space
|
|
emulation" variables (e.g., QEMU_STACK_SIZE), but there should be no
|
|
reason to touch them.
|
|
|
|
5) Settings for afl-cmin
|
|
------------------------
|
|
|
|
The corpus minimization script offers very little customization:
|
|
|
|
- Setting AFL_PATH offers a way to specify the location of afl-showmap
|
|
and afl-qemu-trace (the latter only in -Q mode).
|
|
|
|
- AFL_KEEP_TRACES makes the tool keep traces and other metadata used for
|
|
minimization and normally deleted at exit. The files can be found in the
|
|
<out_dir>/.traces/*.
|
|
|
|
- AFL_ALLOW_TMP permits this and some other scripts to run in /tmp. This is
|
|
a modest security risk on multi-user systems with rogue users, but should
|
|
be safe on dedicated fuzzing boxes.
|
|
|
|
6) Settings for afl-tmin
|
|
------------------------
|
|
|
|
Virtually nothing to play with. Well, in QEMU mode (-Q), AFL_PATH will be
|
|
searched for afl-qemu-trace. In addition to this, TMPDIR may be used if a
|
|
temporary file can't be created in the current working directory.
|
|
|
|
You can specify AFL_TMIN_EXACT if you want afl-tmin to require execution paths
|
|
to match when minimizing crashes. This will make minimization less useful, but
|
|
may prevent the tool from "jumping" from one crashing condition to another in
|
|
very buggy software. You probably want to combine it with the -e flag.
|
|
|
|
7) Settings for afl-analyze
|
|
---------------------------
|
|
|
|
You can set AFL_ANALYZE_HEX to get file offsets printed as hexadecimal instead
|
|
of decimal.
|
|
|
|
8) Settings for libdislocator.so
|
|
--------------------------------
|
|
|
|
The library honors three environmental variables:
|
|
|
|
- AFL_LD_LIMIT_MB caps the size of the maximum heap usage permitted by the
|
|
library, in megabytes. The default value is 1 GB. Once this is exceeded,
|
|
allocations will return NULL.
|
|
|
|
- AFL_LD_HARD_FAIL alters the behavior by calling abort() on excessive
|
|
allocations, thus causing what AFL would perceive as a crash. Useful for
|
|
programs that are supposed to maintain a specific memory footprint.
|
|
|
|
- AFL_LD_VERBOSE causes the library to output some diagnostic messages
|
|
that may be useful for pinpointing the cause of any observed issues.
|
|
|
|
- AFL_LD_NO_CALLOC_OVER inhibits abort() on calloc() overflows. Most
|
|
of the common allocators check for that internally and return NULL, so
|
|
it's a security risk only in more exotic setups.
|
|
|
|
9) Settings for libtokencap.so
|
|
------------------------------
|
|
|
|
This library accepts AFL_TOKEN_FILE to indicate the location to which the
|
|
discovered tokens should be written.
|
|
|
|
10) Third-party variables set by afl-fuzz & other tools
|
|
-------------------------------------------------------
|
|
|
|
Several variables are not directly interpreted by afl-fuzz, but are set to
|
|
optimal values if not already present in the environment:
|
|
|
|
- By default, LD_BIND_NOW is set to speed up fuzzing by forcing the
|
|
linker to do all the work before the fork server kicks in. You can
|
|
override this by setting LD_BIND_LAZY beforehand, but it is almost
|
|
certainly pointless.
|
|
|
|
- By default, ASAN_OPTIONS are set to:
|
|
|
|
abort_on_error=1
|
|
detect_leaks=0
|
|
symbolize=0
|
|
allocator_may_return_null=1
|
|
|
|
If you want to set your own options, be sure to include abort_on_error=1 -
|
|
otherwise, the fuzzer will not be able to detect crashes in the tested
|
|
app. Similarly, include symbolize=0, since without it, AFL may have
|
|
difficulty telling crashes and hangs apart.
|
|
|
|
- In the same vein, by default, MSAN_OPTIONS are set to:
|
|
|
|
exit_code=86 (required for legacy reasons)
|
|
abort_on_error=1
|
|
symbolize=0
|
|
msan_track_origins=0
|
|
allocator_may_return_null=1
|
|
|
|
Be sure to include the first one when customizing anything, since some
|
|
MSAN versions don't call abort() on error, and we need a way to detect
|
|
faults.
|