ExternalVendorCode/AFLplusplus
1
0
Fork 0
mirror of https://github.com/AFLplusplus/AFLplusplus.git synced 2025-06-17 12:18:08 +00:00
Code Issues Packages Projects Releases Wiki Activity

Edit list of environment variables

Browse Source
This commit is contained in:
llzmb
2021-10-30 21:38:13 +02:00
parent 873f5a979e
commit b1aecf4ff0
1 changed files with 372 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

699
docs/env_variables.md
View File

@ -1,33 +1,30 @@
# Environmental variables # Environment variables
This document discusses the environment variables used by American Fuzzy Lop++ This document discusses the environment variables used by AFL++ to expose various exotic functions that may be (rarely) useful for power users or for some types of custom fuzzing setups.
to expose various exotic functions that may be (rarely) useful for power For general information about AFL++, see [README.md](../README.md).
users or for some types of custom fuzzing setups. See [../README.md](../README.md) for the general
instruction manual.
Note that most tools will warn on any unknown AFL environment variables. Note: Most tools will warn on any unknown AFL++ environment variables; for example, because of typos. If you want to disable this check, then set the `AFL_IGNORE_UNKNOWN_ENVS` environment variable.
This is for warning on typos that can happen. If you want to disable this
check then set the `AFL_IGNORE_UNKNOWN_ENVS` environment variable.
## 1) Settings for all compilers ## 1) Settings for all compilers
Starting with AFL++ 3.0 there is only one compiler: afl-cc Starting with AFL++ 3.0, there is only one compiler: afl-cc.
To select the different instrumentation modes this can be done by
1. passing the --afl-MODE command line option to the compiler
2. or using a symlink to afl-cc: afl-gcc, afl-g++, afl-clang, afl-clang++,
afl-clang-fast, afl-clang-fast++, afl-clang-lto, afl-clang-lto++,
afl-gcc-fast, afl-g++-fast
3. or using the environment variable `AFL_CC_COMPILER` with `MODE`
`MODE` can be one of `LTO` (afl-clang-lto*), `LLVM` (afl-clang-fast*), `GCC_PLUGIN` To select the different instrumentation modes, use one of the following options:
(afl-g*-fast) or `GCC` (afl-gcc/afl-g++).
Because (with the exception of the --afl-MODE command line option) the - Pass the --afl-MODE command-line option to the compiler. Only this option accepts further AFL-specific command-line options.
compile-time tools do not accept AFL specific command-line options, they - Use a symlink to afl-cc: afl-clang, afl-clang++, afl-clang-fast, afl-clang-fast++, afl-clang-lto, afl-clang-lto++, afl-gcc, afl-g++, afl-gcc-fast, afl-g++-fast. This option does not accept AFL-specific command-line options. Instead, use environment variables.
make fairly broad use of environmental variables instead: - Use the `AFL_CC_COMPILER` environment variable with `MODE`. To select `MODE`, use one of the following values:
- `GCC` (afl-gcc/afl-g++)
- `GCC_PLUGIN` (afl-g*-fast)
- `LLVM` (afl-clang-fast*)
- `LTO` (afl-clang-lto*).
The compile-time tools do not accept AFL-specific command-line options. The --afl-MODE command line option is the only exception. The other options make fairly broad use of environment variables instead:
- Some build/configure scripts break with AFL++ compilers.
To be able to pass them, do:
- Some build/configure scripts break with AFL++ compilers. To be able to
pass them, do:
``` ```
export CC=afl-cc export CC=afl-cc
export CXX=afl-c++ export CXX=afl-c++
@ -37,47 +34,30 @@ make fairly broad use of environmental variables instead:
make make
``` ```
- Most AFL tools do not print any output if stdout/stderr are redirected. - If you are a weird person that wants to compile and instrument asm
If you want to get the output into a file then set the `AFL_DEBUG` text files, then use the `AFL_AS_FORCE_INSTRUMENT` variable:
environment variable. `AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo`
This is sadly necessary for various build processes which fail otherwise.
- 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`.
However if `-O...` and/or `-fno-unroll-loops` are set, these are not
overridden.
- Setting `AFL_USE_ASAN` automatically enables ASAN, provided that your
compiler supports it.
(You can also enable MSAN via `AFL_USE_MSAN`; ASAN and MSAN come with the
same gotchas; the modes are mutually exclusive. UBSAN can be enabled
similarly by setting the environment variable `AFL_USE_UBSAN=1`. Finally
there is the Control Flow Integrity sanitizer that can be activated by
`AFL_USE_CFISAN=1`)
- Setting `AFL_USE_LSAN` automatically enables Leak-Sanitizer, provided
that your compiler supports it. To perform a leak check within your
program at a certain point (such as at the end of an __AFL_LOOP),
you can run the macro __AFL_LEAK_CHECK(); which will cause
an abort if any memory is leaked (you can combine this with the
LSAN_OPTIONS=suppressions option to supress some known leaks).
- Setting `AFL_CC`, `AFL_CXX`, and `AFL_AS` lets you use alternate downstream - Setting `AFL_CC`, `AFL_CXX`, and `AFL_AS` lets you use alternate downstream
compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries compilation tools, rather than the default 'clang', 'gcc', or 'as' binaries
in your `$PATH`. in your `$PATH`.
- `AFL_PATH` can be used to point afl-gcc to an alternate location of afl-as. - Most AFL tools do not print any output if stdout/stderr are redirected.
One possible use of this is utils/clang_asm_normalize/, which lets If you want to get the output into a file, then set the `AFL_DEBUG`
you instrument hand-written assembly when compiling clang code by plugging environment variable.
a normalizer into the chain. (There is no equivalent feature for GCC.) This is sadly necessary for various build processes which fail otherwise.
- 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`.
However, if `-O...` and/or `-fno-unroll-loops` are set, these are not
overridden.
- 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.
- Setting `AFL_INST_RATIO` to a percentage between 0 and 100 controls the - Setting `AFL_INST_RATIO` to a percentage between 0 and 100 controls the
probability of instrumenting every branch. This is (very rarely) useful probability of instrumenting every branch. This is (very rarely) useful
@ -97,20 +77,37 @@ make fairly broad use of environmental variables instead:
- `AFL_NO_BUILTIN` causes the compiler to generate code suitable for use with - `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). 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, - `AFL_PATH` can be used to point afl-gcc to an alternate location of afl-as.
the tool defaults to /tmp. One possible use of this is utils/clang_asm_normalize/, which lets
you instrument hand-written assembly when compiling clang code by plugging
- If you are a weird person that wants to compile and instrument asm a normalizer into the chain.
text files then use the `AFL_AS_FORCE_INSTRUMENT` variable: (There is no equivalent feature for GCC.)
`AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo`
- Setting `AFL_QUIET` will prevent afl-cc and afl-as banners from being - Setting `AFL_QUIET` will prevent afl-cc and afl-as banners from being
displayed during compilation, in case you find them distracting. displayed during compilation, in case you find them distracting.
- Setting `AFL_USE_ASAN` automatically enables ASAN, provided that your
compiler supports it.
(You can also enable MSAN via `AFL_USE_MSAN`; ASAN and MSAN come with the
same gotchas; the modes are mutually exclusive. UBSAN can be enabled
similarly by setting the environment variable `AFL_USE_UBSAN=1`. Finally,
there is the Control Flow Integrity sanitizer that can be activated by
`AFL_USE_CFISAN=1`.)
- Setting `AFL_USE_LSAN` automatically enables Leak-Sanitizer, provided
that your compiler supports it. To perform a leak check within your
program at a certain point (such as at the end of an __AFL_LOOP),
you can run the macro __AFL_LEAK_CHECK(); which will cause
an abort if any memory is leaked (you can combine this with the
LSAN_OPTIONS=suppressions option to supress some known leaks).
- `TMPDIR` is used by afl-as for temporary files; if this variable is not set,
the tool defaults to /tmp.
## 2) Settings for LLVM and LTO: afl-clang-fast / afl-clang-fast++ / afl-clang-lto / afl-clang-lto++ ## 2) Settings for LLVM and LTO: afl-clang-fast / afl-clang-fast++ / afl-clang-lto / afl-clang-lto++
The native instrumentation helpers (instrumentation and gcc_plugin) accept a subset The native instrumentation helpers (instrumentation and gcc_plugin) accept a subset of the settings discussed in section 1, with the exception of:
of the settings discussed in section 1, with the exception of:
- LLVM modes support `AFL_LLVM_DICT2FILE=/absolute/path/file.txt` which will - LLVM modes support `AFL_LLVM_DICT2FILE=/absolute/path/file.txt` which will
write all constant string comparisons to this file to be used later with write all constant string comparisons to this file to be used later with
@ -121,45 +118,48 @@ of the settings discussed in section 1, with the exception of:
- `TMPDIR` and `AFL_KEEP_ASSEMBLY`, since no temporary assembly files are - `TMPDIR` and `AFL_KEEP_ASSEMBLY`, since no temporary assembly files are
created. created.
- `AFL_INST_RATIO`, as we by default use collision free instrumentation. - `AFL_INST_RATIO`, as we use collision free instrumentation by default.
Not all passes support this option though as it is an outdated feature. Not all passes support this option though as it is an outdated feature.
Then there are a few specific features that are only available in instrumentation mode: Then there are a few specific features that are only available in instrumentation mode:
### Select the instrumentation mode ### Select the instrumentation mode
- `AFL_LLVM_INSTRUMENT` - this configures the instrumentation mode. `AFL_LLVM_INSTRUMENT` - this configures the instrumentation mode.
Available options: Available options:
PCGUARD - our own pcgard based instrumentation (default)
NATIVE - clang's original pcguard based instrumentation
CLASSIC - classic AFL (map[cur_loc ^ prev_loc >> 1]++) (default)
LTO - LTO instrumentation (see below)
CTX - context sensitive instrumentation (see below)
NGRAM-x - deeper previous location coverage (from NGRAM-2 up to NGRAM-16)
GCC - outdated gcc instrumentation
CLANG - outdated clang instrumentation
In CLASSIC you can also specify CTX and/or NGRAM, seperate the options
with a comma "," then, e.g.:
`AFL_LLVM_INSTRUMENT=CLASSIC,CTX,NGRAM-4`
Note that this is actually not a good idea to use both CTX and NGRAM :)
### LTO - CLANG - outdated clang instrumentation
- CLASSIC - classic AFL (map[cur_loc ^ prev_loc >> 1]++) (default)
This is a different kind way of instrumentation: first it compiles all You can also specify CTX and/or NGRAM, seperate the options with a comma "," then, e.g.: `AFL_LLVM_INSTRUMENT=CLASSIC,CTX,NGRAM-4`
code in LTO (link time optimization) and then performs an edge inserting
instrumentation which is 100% collision free (collisions are a big issue Note: It is actually not a good idea to use both CTX and NGRAM. :)
in AFL and AFL-like instrumentations). This is performed by using - CTX - context sensitive instrumentation (see below)
afl-clang-lto/afl-clang-lto++ instead of afl-clang-fast, but is only - GCC - outdated gcc instrumentation
built if LLVM 11 or newer is used. - LTO - LTO instrumentation (see below)
- NATIVE - clang's original pcguard based instrumentation
- NGRAM-x - deeper previous location coverage (from NGRAM-2 up to NGRAM-16)
- PCGUARD - our own pcgard based instrumentation (default)
#### CTX
Setting `AFL_LLVM_CTX` or `AFL_LLVM_INSTRUMENT=CTX` activates context sensitive branch coverage - meaning that each edge is additionally combined with its caller.
It is highly recommended to increase the `MAP_SIZE_POW2` definition in config.h to at least 18 and maybe up to 20 for this as otherwise too many map collisions occur.
For more information, see [instrumentation/README.ctx.md](../instrumentation/README.ctx.md).
#### LTO
This is a different kind way of instrumentation: first it compiles all code in LTO (link time optimization) and then performs an edge inserting instrumentation which is 100% collision free (collisions are a big issue in AFL and AFL-like instrumentations).
This is performed by using afl-clang-lto/afl-clang-lto++ instead of afl-clang-fast, but is only built if LLVM 11 or newer is used.
- `AFL_LLVM_INSTRUMENT=CFG` will use Control Flow Graph instrumentation. - `AFL_LLVM_INSTRUMENT=CFG` will use Control Flow Graph instrumentation.
(not recommended for afl-clang-fast, default for afl-clang-lto as there (not recommended for afl-clang-fast, default for afl-clang-lto as there
it is a different and better kind of instrumentation.) it is a different and better kind of instrumentation.)
None of the following options are necessary to be used and are rather for None of the following options are necessary to be used and are rather for manual use (which only ever the author of this LTO implementation will use).
manual use (which only ever the author of this LTO implementation will use). These are used if several separated instrumentations are performed which are then later combined.
These are used if several separated instrumentations are performed which
are then later combined.
- `AFL_LLVM_DOCUMENT_IDS=file` will document to a file which edge ID was given - `AFL_LLVM_DOCUMENT_IDS=file` will document to a file which edge ID was given
to which function. This helps to identify functions with variable bytes to which function. This helps to identify functions with variable bytes
@ -173,35 +173,19 @@ Then there are a few specific features that are only available in instrumentatio
- `AFL_LLVM_LTO_DONTWRITEID` prevents that the highest location ID written - `AFL_LLVM_LTO_DONTWRITEID` prevents that the highest location ID written
into the instrumentation is set in a global variable into the instrumentation is set in a global variable
See [instrumentation/README.lto.md](../instrumentation/README.lto.md) for more information. For more information, see [instrumentation/README.lto.md](../instrumentation/README.lto.md).
### NGRAM #### NGRAM
- Setting `AFL_LLVM_NGRAM_SIZE` or `AFL_LLVM_INSTRUMENT=NGRAM-{value}` Setting `AFL_LLVM_NGRAM_SIZE` or `AFL_LLVM_INSTRUMENT=NGRAM-{value}` activates ngram prev_loc coverage, good values are 2, 4 or 8 (any value between 2 and 16 is valid).
activates ngram prev_loc coverage, good values are 2, 4 or 8 It is highly recommended to increase the `MAP_SIZE_POW2` definition in config.h to at least 18 and maybe up to 20 for this as otherwise too many map collisions occur.
(any value between 2 and 16 is valid).
It is highly recommended to increase the `MAP_SIZE_POW2` definition in
config.h to at least 18 and maybe up to 20 for this as otherwise too
many map collisions occur.
See [instrumentation/README.ngram.md](../instrumentation/README.ngram.md) For more information, see [instrumentation/README.ngram.md](../instrumentation/README.ngram.md).
### CTX
- Setting `AFL_LLVM_CTX` or `AFL_LLVM_INSTRUMENT=CTX`
activates context sensitive branch coverage - meaning that each edge
is additionally combined with its caller.
It is highly recommended to increase the `MAP_SIZE_POW2` definition in
config.h to at least 18 and maybe up to 20 for this as otherwise too
many map collisions occur.
See [instrumentation/README.ctx.md](../instrumentation/README.ctx.md)
### LAF-INTEL ### LAF-INTEL
This great feature will split compares into series of single byte comparisons This great feature will split compares into series of single byte comparisons to allow afl-fuzz to find otherwise rather impossible paths.
to allow afl-fuzz to find otherwise rather impossible paths. It is not It is not restricted to Intel CPUs. ;-)
restricted to Intel CPUs ;-)
- Setting `AFL_LLVM_LAF_TRANSFORM_COMPARES` will split string compare functions - Setting `AFL_LLVM_LAF_TRANSFORM_COMPARES` will split string compare functions
@ -215,21 +199,19 @@ Then there are a few specific features that are only available in instrumentatio
- Setting `AFL_LLVM_LAF_ALL` sets all of the above - Setting `AFL_LLVM_LAF_ALL` sets all of the above
See [instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md) for more information. For more information, see [instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md).
### INSTRUMENT LIST (selectively instrument files and functions) ### INSTRUMENT LIST (selectively instrument files and functions)
This feature allows selective instrumentation of the source This feature allows selective instrumentation of the source.
- Setting `AFL_LLVM_ALLOWLIST` or `AFL_LLVM_DENYLIST` with a filenames and/or Setting `AFL_LLVM_ALLOWLIST` or `AFL_LLVM_DENYLIST` with a filenames and/or function will only instrument (or skip) those files that match the names listed in the specified file.
function will only instrument (or skip) those files that match the names
listed in the specified file.
See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) for more information. For more information, see [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md).
### Thread safe instrumentation counters (in all modes) ### Thread safe instrumentation counters (in all modes)
- Setting `AFL_LLVM_THREADSAFE_INST` will inject code that implements thread Setting `AFL_LLVM_THREADSAFE_INST` will inject code that implements thread
safe counters. The overhead is a little bit higher compared to the older safe counters. The overhead is a little bit higher compared to the older
non-thread safe case. Note that this disables neverzero (see below). non-thread safe case. Note that this disables neverzero (see below).
@ -237,137 +219,66 @@ Then there are a few specific features that are only available in instrumentatio
- Setting `AFL_LLVM_NOT_ZERO=1` during compilation will use counters - Setting `AFL_LLVM_NOT_ZERO=1` during compilation will use counters
that skip zero on overflow. This is the default for llvm >= 9, that skip zero on overflow. This is the default for llvm >= 9,
however for llvm versions below that this will increase an unnecessary however, for llvm versions below that this will increase an unnecessary
slowdown due a performance issue that is only fixed in llvm 9+. slowdown due a performance issue that is only fixed in llvm 9+.
This feature increases path discovery by a little bit. This feature increases path discovery by a little bit.
- Setting `AFL_LLVM_SKIP_NEVERZERO=1` will not implement the skip zero - Setting `AFL_LLVM_SKIP_NEVERZERO=1` will not implement the skip zero
test. If the target performs only few loops then this will give a test. If the target performs only few loops, then this will give a
small performance boost. small performance boost.
See [instrumentation/README.neverzero.md](../instrumentation/README.neverzero.md) For more information, see [instrumentation/README.neverzero.md](../instrumentation/README.neverzero.md).
### CMPLOG ### CMPLOG
- Setting `AFL_LLVM_CMPLOG=1` during compilation will tell afl-clang-fast to - Setting `AFL_LLVM_CMPLOG=1` during compilation will tell afl-clang-fast to
produce a CmpLog binary. produce a CmpLog binary.
See [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md) For more information, see [instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md).
## 3) Settings for GCC / GCC_PLUGIN modes ## 3) Settings for GCC / GCC_PLUGIN modes
Then there are a few specific features that are only available in GCC and Then there are a few specific features that are only available in GCC and
GCC_PLUGIN mode. GCC_PLUGIN mode.
- Setting `AFL_KEEP_ASSEMBLY` prevents afl-as from deleting instrumented
assembly files. Useful for troubleshooting problems or understanding how
the tool works. (GCC mode only)
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_GCC_INSTRUMENT_FILE` with a filename will only instrument those - Setting `AFL_GCC_INSTRUMENT_FILE` with a filename will only instrument those
files that match the names listed in this file (one filename per line). files that match the names listed in this file (one filename per line).
See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) for more information. See [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) for more information.
(GCC_PLUGIN mode only) (GCC_PLUGIN mode only)
- Setting `AFL_KEEP_ASSEMBLY` prevents afl-as from deleting instrumented
assembly files. Useful for troubleshooting problems or understanding how
the tool works. (GCC mode only)
To get them in a predictable place, try something like:
```
mkdir assembly_here
TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all
```
## 4) Settings for afl-fuzz ## 4) Settings for afl-fuzz
The main fuzzer binary accepts several options that disable a couple of sanity 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: 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 - Setting `AFL_AUTORESUME` will resume a fuzz run (same as providing `-i -`)
useful if you can't change the defaults (e.g., no root access to the for an existing out folder, even if a different `-i` was provided.
system) and are OK with some performance loss. Without this setting, afl-fuzz will refuse execution for a long-fuzzed out dir.
- `AFL_EXIT_WHEN_DONE` causes afl-fuzz to terminate when all existing paths - Benchmarking only: `AFL_BENCH_JUST_ONE` causes the fuzzer to exit after
have been fuzzed and there were no new finds for a while. This would be processing the first queue entry; and `AFL_BENCH_UNTIL_CRASH` causes it to
normally indicated by the cycle counter in the UI turning green. May be exit soon after the first crash is found.
convenient for some types of automated jobs.
- `AFL_EXIT_ON_TIME` Causes afl-fuzz to terminate if no new paths were
found within a specified period of time (in seconds). May be convenient
for some types of automated jobs.
- `AFL_EXIT_ON_SEED_ISSUES` will restore the vanilla afl-fuzz behaviour
which does not allow crashes or timeout seeds in the initial -i corpus.
- `AFL_MAP_SIZE` sets the size of the shared map that afl-fuzz, afl-showmap,
afl-tmin and afl-analyze create to gather instrumentation data from
the target. This must be equal or larger than the size the target was
compiled with.
- `AFL_CMPLOG_ONLY_NEW` will only perform the expensive cmplog feature for - `AFL_CMPLOG_ONLY_NEW` will only perform the expensive cmplog feature for
newly found testcases and not for testcases that are loaded on startup newly found testcases and not for testcases that are loaded on startup
(`-i in`). This is an important feature to set when resuming a fuzzing (`-i in`).
session. This is an important feature to set when resuming a fuzzing session.
- `AFL_TESTCACHE_SIZE` allows you to override the size of `#define TESTCASE_CACHE` - Setting `AFL_CRASH_EXITCODE` sets the exit code AFL treats as crash.
in config.h. Recommended values are 50-250MB - or more if your fuzzing For example, if `AFL_CRASH_EXITCODE='-1'` is set, each input resulting
finds a huge amount of paths for large inputs. in an `-1` return code (i.e. `exit(-1)` got called), will be treated
as if a crash had ocurred.
- Setting `AFL_DISABLE_TRIM` tells afl-fuzz not to trim test cases. This is This may be beneficial if you look for higher-level faulty conditions in which your target still exits gracefully.
usually a bad idea!
- 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).
- Setting `AFL_TRY_AFFINITY` tries to attempt binding to a specific CPU core
on Linux systems, but will not terminate if that fails.
- Setting `AFL_NO_AUTODICT` will not load an LTO generated auto dictionary
that is compiled into the target.
- 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.
- Setting `AFL_FORKSRV_INIT_TMOUT` allows you to specify a different timeout
to wait for the forkserver to spin up. The default is the `-t` value times
`FORK_WAIT_MULT` from `config.h` (usually 10), so for a `-t 100`, the
default would wait for `1000` milliseconds. Setting a different time here is useful
if the target has a very slow startup time, for example when doing
full-system fuzzing or emulation, but you don't want the actual runs
to wait too long for timeouts.
- `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_NO_SNAPSHOT` will advice afl-fuzz not to use the snapshot feature
if the snapshot lkm is loaded
- `AFL_SHUFFLE_QUEUE` randomly reorders the input queue on startup. Requested
by some users for unorthodox parallelized fuzzing setups, but not
advisable otherwise.
- `AFL_TMPDIR` is used to write the `.cur_input` file to if exists, and in
the normal output directory otherwise. You would use this to point to
a ramdisk/tmpfs. This increases the speed by a small value but also
reduces the stress on SSDs.
- 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.
Note that this also turns off auto map size detection.
- 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.
- Note that `AFL_POST_LIBRARY` is deprecated, use `AFL_CUSTOM_MUTATOR_LIBRARY`
instead (see below).
- `AFL_KILL_SIGNAL`: Set the signal ID to be delivered to child processes on timeout.
Unless you implement your own targets or instrumentation, you likely don't have to set it.
By default, on timeout and on exit, `SIGKILL` (`AFL_KILL_SIGNAL=9`) will be delivered to the child.
- Setting `AFL_CUSTOM_MUTATOR_LIBRARY` to a shared library with - Setting `AFL_CUSTOM_MUTATOR_LIBRARY` to a shared library with
afl_custom_fuzz() creates additional mutations through this library. afl_custom_fuzz() creates additional mutations through this library.
@ -380,70 +291,9 @@ checks or alter some of the more exotic semantics of the tool:
e.g. fuzzing XML or other highly flexible structured input. e.g. fuzzing XML or other highly flexible structured input.
Please see [custom_mutators.md](custom_mutators.md). Please see [custom_mutators.md](custom_mutators.md).
- `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.
`AFL_CAL_FAST` works too.
- 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) and Frida mode (-O), `AFL_PATH` will
be searched for afl-qemu-trace and afl-frida-trace.so.
- In QEMU mode (-Q), setting `AFL_QEMU_CUSTOM_BIN` cause afl-fuzz to skip
prepending `afl-qemu-trace` to your command line. Use this if you wish to use a
custom afl-qemu-trace or if you need to modify the afl-qemu-trace arguments.
- Setting `AFL_CYCLE_SCHEDULES` will switch to a different schedule everytime - Setting `AFL_CYCLE_SCHEDULES` will switch to a different schedule everytime
a cycle is finished. a cycle is finished.
- Setting `AFL_EXPAND_HAVOC_NOW` will start in the extended havoc mode that
includes costly mutations. afl-fuzz automatically enables this mode when
deemed useful otherwise.
- 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_TARGET_ENV` causes AFL++ to set extra environment variables
for the target binary. Example: `AFL_TARGET_ENV="VAR1=1 VAR2='a b c'" afl-fuzz ... `
This exists mostly for things like `LD_LIBRARY_PATH` but it would theoretically
allow fuzzing of AFL++ itself (with 'target' AFL++ using some AFL_ vars that
would disrupt work of 'fuzzer' AFL++).
- 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.
- Setting `AFL_NO_COLOR` or `AFL_NO_COLOUR` will omit control sequences for
coloring console output when configured with USE_COLOR and not ALWAYS_COLORED.
- Setting `AFL_FORCE_UI` will force painting the UI on the screen even if
no valid terminal was detected (for virtual consoles)
- If you are using persistent mode (you should, see [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md))
some targets keep inherent state due which a detected crash testcase does
not crash the target again when the testcase is given. To be able to still
re-trigger these crashes you can use the `AFL_PERSISTENT_RECORD` variable
with a value of how many previous fuzz cases to keep prio a crash.
if set to e.g. 10, then the 9 previous inputs are written to
out/default/crashes as RECORD:000000,cnt:000000 to RECORD:000000,cnt:000008
and RECORD:000000,cnt:000009 being the crash case.
NOTE: This option needs to be enabled in config.h first!
- If afl-fuzz encounters an incorrect fuzzing setup during a fuzzing session
(not at startup), it will terminate. If you do not want this then you can
set `AFL_IGNORE_PROBLEMS`.
- If you are Jakub, you may need `AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES`.
Others need not apply, unless they also want to disable the
`/proc/sys/kernel/core_pattern` check.
- 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.
- Setting `AFL_DEBUG_CHILD` will not suppress the child output. - Setting `AFL_DEBUG_CHILD` will not suppress the child output.
This lets you see all output of the child, making setup issues obvious. This lets you see all output of the child, making setup issues obvious.
For example, in an unicornafl harness, you might see python stacktraces. For example, in an unicornafl harness, you might see python stacktraces.
@ -451,64 +301,175 @@ checks or alter some of the more exotic semantics of the tool:
Not pretty but good for debugging purposes. Not pretty but good for debugging purposes.
Note that `AFL_DEBUG_CHILD_OUTPUT` is deprecated. Note that `AFL_DEBUG_CHILD_OUTPUT` is deprecated.
- Setting `AFL_NO_CPU_RED` will not display very high cpu usages in red color. - Setting `AFL_DISABLE_TRIM` tells afl-fuzz not to trim test cases. This is
usually a bad idea!
- Setting `AFL_AUTORESUME` will resume a fuzz run (same as providing `-i -`) - `AFL_EXIT_ON_SEED_ISSUES` will restore the vanilla afl-fuzz behaviour
for an existing out folder, even if a different `-i` was provided. which does not allow crashes or timeout seeds in the initial -i corpus.
Without this setting, afl-fuzz will refuse execution for a long-fuzzed out dir.
- Setting `AFL_MAX_DET_EXRAS` will change the threshold at what number of elements - `AFL_EXIT_ON_TIME` Causes afl-fuzz to terminate if no new paths were
in the `-x` dictionary and LTO autodict (combined) the probabilistic mode will found within a specified period of time (in seconds). May be convenient
kick off. In probabilistic mode, not all dictionary entries will be used all for some types of automated jobs.
of the time for fuzzing mutations to not slow down fuzzing.
The default count is `200` elements. So for the 200 + 1st element, there is a - `AFL_EXIT_WHEN_DONE` causes afl-fuzz to terminate when all existing paths
1 in 201 chance, that one of the dictionary entries will not be used directly. 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_EXPAND_HAVOC_NOW` will start in the extended havoc mode that
includes costly mutations. afl-fuzz automatically enables this mode when
deemed useful otherwise.
- `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.
`AFL_CAL_FAST` works too.
- Setting `AFL_FORCE_UI` will force painting the UI on the screen even if
no valid terminal was detected (for virtual consoles).
- Setting `AFL_FORKSRV_INIT_TMOUT` allows you to specify a different timeout
to wait for the forkserver to spin up.
The default is the `-t` value times `FORK_WAIT_MULT` from `config.h` (usually 10), so for a `-t 100`, the default would wait for `1000` milliseconds.
Setting a different time here is useful if the target has a very slow startup time, for example when doing full-system fuzzing or emulation, but you don't want the actual runs to wait too long for timeouts.
- 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.
- If you are Jakub, you may need `AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES`.
Others need not apply, unless they also want to disable the
`/proc/sys/kernel/core_pattern` check.
- If afl-fuzz encounters an incorrect fuzzing setup during a fuzzing session
(not at startup), it will terminate. If you do not want this, then you can
set `AFL_IGNORE_PROBLEMS`.
- 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.
- `AFL_KILL_SIGNAL`: Set the signal ID to be delivered to child processes on timeout.
Unless you implement your own targets or instrumentation, you likely don't have to set it.
By default, on timeout and on exit, `SIGKILL` (`AFL_KILL_SIGNAL=9`) will be delivered to the child.
- `AFL_MAP_SIZE` sets the size of the shared map that afl-fuzz, afl-showmap,
afl-tmin and afl-analyze create to gather instrumentation data from
the target. This must be equal or larger than the size the target was
compiled with.
- Setting `AFL_MAX_DET_EXRAS` will change the threshold at what number of elements in the `-x` dictionary and LTO autodict (combined) the probabilistic mode will kick off.
In probabilistic mode, not all dictionary entries will be used all of the time for fuzzing mutations to not slow down fuzzing.
The default count is `200` elements.
So for the 200 + 1st element, there is a 1 in 201 chance, that one of the dictionary entries will not be used directly.
- 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_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.
- Setting `AFL_NO_AUTODICT` will not load an LTO generated auto dictionary
that is compiled into the 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 for very high cpu usages, you can set `AFL_NO_CPU_RED`.
- Setting `AFL_NO_COLOR` or `AFL_NO_COLOUR` will omit control sequences for
coloring console output when configured with USE_COLOR and not ALWAYS_COLORED.
- Setting `AFL_NO_FORKSRV` disables the forkserver optimization, reverting to - Setting `AFL_NO_FORKSRV` disables the forkserver optimization, reverting to
fork + execve() call for every tested input. This is useful mostly when fork + execve() call for every tested input.
working with unruly libraries that create threads or do other crazy 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).
things when initializing (before the instrumentation has a chance to run).
Note that this setting inhibits some of the user-friendly diagnostics Note that this setting inhibits some of the user-friendly diagnostics
normally done when starting up the forkserver and causes a pretty normally done when starting up the forkserver and causes a pretty
significant performance drop. significant performance drop.
- `AFL_NO_SNAPSHOT` will advice afl-fuzz not to use the snapshot feature
if the snapshot lkm is loaded.
- 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.
- In QEMU mode (-Q) and Frida mode (-O), `AFL_PATH` will be searched for afl-qemu-trace and afl-frida-trace.so.
- If you are using persistent mode (you should, see [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md)), some targets keep inherent state due which a detected crash testcase does not crash the target again when the testcase is given.
To be able to still re-trigger these crashes you can use the `AFL_PERSISTENT_RECORD` variable with a value of how many previous fuzz cases to keep prio a crash.
If set to e.g. 10, then the 9 previous inputs are written to out/default/crashes as RECORD:000000,cnt:000000 to RECORD:000000,cnt:000008 and RECORD:000000,cnt:000009 being the crash case.
NOTE: This option needs to be enabled in config.h first!
- Note that `AFL_POST_LIBRARY` is deprecated, use `AFL_CUSTOM_MUTATOR_LIBRARY`
instead (see below).
- 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.
- In QEMU mode (-Q), setting `AFL_QEMU_CUSTOM_BIN` will cause afl-fuzz to skip
prepending `afl-qemu-trace` to your command line.
Use this if you wish to use a custom afl-qemu-trace or if you need to modify the afl-qemu-trace arguments.
- `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.
Note that this also turns off auto map size detection.
- 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_STATSD` enables StatsD metrics collection. - Setting `AFL_STATSD` enables StatsD metrics collection.
By default AFL++ will send these metrics over UDP to 127.0.0.1:8125. By default, AFL++ will send these metrics over UDP to 127.0.0.1:8125.
The host and port are configurable with `AFL_STATSD_HOST` and `AFL_STATSD_PORT` respectively. The host and port are configurable with `AFL_STATSD_HOST` and `AFL_STATSD_PORT` respectively.
To enable tags (banner and afl_version) you should provide `AFL_STATSD_TAGS_FLAVOR` that matches To enable tags (banner and afl_version), you should provide `AFL_STATSD_TAGS_FLAVOR` that matches your StatsD server (see `AFL_STATSD_TAGS_FLAVOR`).
your StatsD server (see `AFL_STATSD_TAGS_FLAVOR`)
- Setting `AFL_STATSD_TAGS_FLAVOR` to one of `dogstatsd`, `librato`, `signalfx` or `influxdb` - Setting `AFL_STATSD_TAGS_FLAVOR` to one of `dogstatsd`, `librato`, `signalfx` or `influxdb` allows you to add tags to your fuzzing instances.
allows you to add tags to your fuzzing instances. This is especially useful when running This is especially useful when running multiple instances (`-M/-S` for example).
multiple instances (`-M/-S` for example). Applied tags are `banner` and `afl_version`. Applied tags are `banner` and `afl_version`.
`banner` corresponds to the name of the fuzzer provided through `-M/-S`. `banner` corresponds to the name of the fuzzer provided through `-M/-S`.
`afl_version` corresponds to the currently running AFL version (e.g `++3.0c`). `afl_version` corresponds to the currently running AFL version (e.g. `++3.0c`).
Default (empty/non present) will add no tags to the metrics. Default (empty/non present) will add no tags to the metrics.
See [rpc_statsd.md](rpc_statsd.md) for more information. For more information, see [rpc_statsd.md](rpc_statsd.md).
- Setting `AFL_CRASH_EXITCODE` sets the exit code AFL treats as crash. - Setting `AFL_TARGET_ENV` causes AFL++ to set extra environment variables
For example, if `AFL_CRASH_EXITCODE='-1'` is set, each input resulting for the target binary. Example: `AFL_TARGET_ENV="VAR1=1 VAR2='a b c'" afl-fuzz ... `.
in an `-1` return code (i.e. `exit(-1)` got called), will be treated This exists mostly for things like `LD_LIBRARY_PATH` but it would theoretically allow fuzzing of AFL++ itself (with 'target' AFL++ using some AFL_ vars that would disrupt work of 'fuzzer' AFL++).
as if a crash had ocurred.
This may be beneficial if you look for higher-level faulty conditions in which your - `AFL_TESTCACHE_SIZE` allows you to override the size of `#define TESTCASE_CACHE`
target still exits gracefully. in config.h. Recommended values are 50-250MB - or more if your fuzzing
finds a huge amount of paths for large inputs.
- `AFL_TMPDIR` is used to write the `.cur_input` file to if exists, and in
the normal output directory otherwise.
You would use this to point to a ramdisk/tmpfs.
This increases the speed by a small value but also reduces the stress on SSDs.
- Setting `AFL_TRY_AFFINITY` tries to attempt binding to a specific CPU core
on Linux systems, but will not terminate if that fails.
- Outdated environment variables that are not supported anymore: - Outdated environment variables that are not supported anymore:
`AFL_DEFER_FORKSRV` - `AFL_DEFER_FORKSRV`
`AFL_PERSISTENT` - `AFL_PERSISTENT`
## 5) Settings for afl-qemu-trace ## 5) Settings for afl-qemu-trace
The QEMU wrapper used to instrument binary-only code supports several settings: 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).
- Setting `AFL_COMPCOV_LEVEL` enables the CompareCoverage tracing of all cmp - Setting `AFL_COMPCOV_LEVEL` enables the CompareCoverage tracing of all cmp
and sub in x86 and x86_64 and memory comparions functions (e.g. strcmp, and sub in x86 and x86_64 and memory comparions functions (e.g. strcmp,
memcmp, ...) when libcompcov is preloaded using `AFL_PRELOAD`. memcmp, ...) when libcompcov is preloaded using `AFL_PRELOAD`.
@ -518,74 +479,77 @@ The QEMU wrapper used to instrument binary-only code supports several settings:
`AFL_COMPCOV_LEVEL=2` that instruments all the comparions. Level 2 is more `AFL_COMPCOV_LEVEL=2` that instruments all the comparions. Level 2 is more
accurate but may need a larger shared memory. accurate but may need a larger shared memory.
- Setting `AFL_QEMU_COMPCOV` enables the CompareCoverage tracing of all
cmp and sub in x86 and x86_64.
This is an alias of `AFL_COMPCOV_LEVEL=1` when `AFL_COMPCOV_LEVEL` is
not specified.
- 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.
- `AFL_DEBUG` will print the found entrypoint for the binary to stderr. - `AFL_DEBUG` will print the found entrypoint for the binary to stderr.
Use this if you are unsure if the entrypoint might be wrong - but Use this if you are unsure if the entrypoint might be wrong - but
use it directly, e.g. `afl-qemu-trace ./program` use it directly, e.g. `afl-qemu-trace ./program`.
- `AFL_ENTRYPOINT` allows you to specify a specific entrypoint into the - `AFL_ENTRYPOINT` allows you to specify a specific entrypoint into the
binary (this can be very good for the performance!). binary (this can be very good for the performance!).
The entrypoint is specified as hex address, e.g. `0x4004110` The entrypoint is specified as hex address, e.g. `0x4004110`
Note that the address must be the address of a basic block. Note that the address must be the address of a basic block.
- Setting `AFL_INST_LIBS` causes the translator to also instrument the code
inside any dynamically linked libraries (notably including glibc).
- 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_QEMU_COMPCOV` enables the CompareCoverage tracing of all
cmp and sub in x86 and x86_64.
This is an alias of `AFL_COMPCOV_LEVEL=1` when `AFL_COMPCOV_LEVEL` is
not specified.
- With `AFL_QEMU_FORCE_DFL` you force QEMU to ignore the registered signal
handlers of the target.
- When the target is i386/x86_64 you can specify the address of the function - When the target is i386/x86_64 you can specify the address of the function
that has to be the body of the persistent loop using that has to be the body of the persistent loop using
`AFL_QEMU_PERSISTENT_ADDR=start addr`. `AFL_QEMU_PERSISTENT_ADDR=start addr`.
- `AFL_QEMU_PERSISTENT_GPR=1` QEMU will save the original value of general
purpose registers and restore them in each persistent cycle.
- Another modality to execute the persistent loop is to specify also the - Another modality to execute the persistent loop is to specify also the
`AFL_QEMU_PERSISTENT_RET=end addr` env variable. `AFL_QEMU_PERSISTENT_RET=end addr` env variable.
With this variable assigned, instead of patching the return address, the With this variable assigned, instead of patching the return address, the
specified instruction is transformed to a jump towards `start addr`. specified instruction is transformed to a jump towards `start addr`.
- `AFL_QEMU_PERSISTENT_GPR=1` QEMU will save the original value of general - With `AFL_QEMU_PERSISTENT_RETADDR_OFFSET` you can specify the offset from the stack pointer in which QEMU can find the return address when `start addr` is hit.
purpose registers and restore them in each persistent cycle.
- With `AFL_QEMU_PERSISTENT_RETADDR_OFFSET` you can specify the offset from the
stack pointer in which QEMU can find the return address when `start addr` is
hit.
- With `AFL_USE_QASAN` you can enable QEMU AddressSanitizer for dynamically - With `AFL_USE_QASAN` you can enable QEMU AddressSanitizer for dynamically
linked binaries. linked binaries.
- With `AFL_QEMU_FORCE_DFL` you force QEMU to ignore the registered signal - The underlying QEMU binary will recognize any standard "user space
handlers of the target. emulation" variables (e.g., `QEMU_STACK_SIZE`), but there should be no
reason to touch them.
## 6) Settings for afl-cmin ## 6) Settings for afl-cmin
The corpus minimization script offers very little customization: The corpus minimization script offers very little customization:
- Setting `AFL_PATH` offers a way to specify the location of afl-showmap - `AFL_ALLOW_TMP` permits this and some other scripts to run in /tmp.
and afl-qemu-trace (the latter only in `-Q` mode). This is a modest security risk on multi-user systems with rogue users, but should be safe on dedicated fuzzing boxes.
- `AFL_KEEP_TRACES` makes the tool keep traces and other metadata used for - `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 minimization and normally deleted at exit.
`<out_dir>/.traces/` directory. The files can be found in the `<out_dir>/.traces/` directory.
- `AFL_ALLOW_TMP` permits this and some other scripts to run in /tmp. This is - Setting `AFL_PATH` offers a way to specify the location of afl-showmap
a modest security risk on multi-user systems with rogue users, but should and afl-qemu-trace (the latter only in `-Q` mode).
be safe on dedicated fuzzing boxes.
- `AFL_PRINT_FILENAMES` prints each filename to stdout, as it gets processed. - `AFL_PRINT_FILENAMES` prints each filename to stdout, as it gets processed.
This can help when embedding `afl-cmin` or `afl-showmap` in other scripts scripting. This can help when embedding `afl-cmin` or `afl-showmap` in other scripts scripting.
## 7) Settings for afl-tmin ## 7) Settings for afl-tmin
Virtually nothing to play with. Well, in QEMU mode (`-Q`), `AFL_PATH` will be Virtually nothing to play with.
searched for afl-qemu-trace. In addition to this, `TMPDIR` may be used if a Well, in QEMU mode (`-Q`), `AFL_PATH` will be searched for afl-qemu-trace.
temporary file can't be created in the current working directory. 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 You can specify `AFL_TMIN_EXACT` if you want afl-tmin to require execution paths to match when minimizing crashes.
to match when minimizing crashes. This will make minimization less useful, but This will make minimization less useful, but may prevent the tool from "jumping" from one crashing condition to another in very buggy software.
may prevent the tool from "jumping" from one crashing condition to another in You probably want to combine it with the `-e` flag.
very buggy software. You probably want to combine it with the `-e` flag.
## 8) Settings for afl-analyze ## 8) Settings for afl-analyze
@ -596,23 +560,23 @@ of decimal.
The library honors these environmental variables: The library honors these environmental variables:
- `AFL_LD_LIMIT_MB` caps the size of the maximum heap usage permitted by the - `AFL_ALIGNED_ALLOC=1` will force the alignment of the allocation size to
library, in megabytes. The default value is 1 GB. Once this is exceeded, `max_align_t` to be compliant with the C standard.
allocations will return NULL.
- `AFL_LD_HARD_FAIL` alters the behavior by calling `abort()` on excessive - `AFL_LD_HARD_FAIL` alters the behavior by calling `abort()` on excessive
allocations, thus causing what AFL++ would perceive as a crash. Useful for allocations, thus causing what AFL++ would perceive as a crash. Useful for
programs that are supposed to maintain a specific memory footprint. programs that are supposed to maintain a specific memory footprint.
- `AFL_LD_VERBOSE` causes the library to output some diagnostic messages - `AFL_LD_LIMIT_MB` caps the size of the maximum heap usage permitted by the
that may be useful for pinpointing the cause of any observed issues. library, in megabytes. The default value is 1 GB. Once this is exceeded,
allocations will return NULL.
- `AFL_LD_NO_CALLOC_OVER` inhibits `abort()` on `calloc()` overflows. Most - `AFL_LD_NO_CALLOC_OVER` inhibits `abort()` on `calloc()` overflows. Most
of the common allocators check for that internally and return NULL, so of the common allocators check for that internally and return NULL, so
it's a security risk only in more exotic setups. it's a security risk only in more exotic setups.
- `AFL_ALIGNED_ALLOC=1` will force the alignment of the allocation size to - `AFL_LD_VERBOSE` causes the library to output some diagnostic messages
`max_align_t` to be compliant with the C standard. that may be useful for pinpointing the cause of any observed issues.
## 10) Settings for libtokencap ## 10) Settings for libtokencap
@ -630,6 +594,7 @@ optimal values if not already present in the environment:
certainly pointless. certainly pointless.
- By default, `ASAN_OPTIONS` are set to (among others): - By default, `ASAN_OPTIONS` are set to (among others):
``` ```
abort_on_error=1 abort_on_error=1
detect_leaks=0 detect_leaks=0
@ -637,12 +602,25 @@ optimal values if not already present in the environment:
symbolize=0 symbolize=0
allocator_may_return_null=1 allocator_may_return_null=1
``` ```
If you want to set your own options, be sure to include `abort_on_error=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 otherwise, the fuzzer will not be able to detect crashes in the tested
app. Similarly, include `symbolize=0`, since without it, AFL++ may have app. Similarly, include `symbolize=0`, since without it, AFL++ may have
difficulty telling crashes and hangs apart. difficulty telling crashes and hangs apart.
- Similarly, the default `LSAN_OPTIONS` are set to:
```
exit_code=23
fast_unwind_on_malloc=0
symbolize=0
print_suppressions=0
```
Be sure to include the first ones for LSAN and MSAN when customizing anything, since some MSAN and LSAN versions don't call `abort()` on error, and we need a way to detect faults.
- In the same vein, by default, `MSAN_OPTIONS` are set to: - In the same vein, by default, `MSAN_OPTIONS` are set to:
``` ```
exit_code=86 (required for legacy reasons) exit_code=86 (required for legacy reasons)
abort_on_error=1 abort_on_error=1
@ -650,14 +628,3 @@ optimal values if not already present in the environment:
msan_track_origins=0 msan_track_origins=0
allocator_may_return_null=1 allocator_may_return_null=1
``` ```
- Similarly, the default `LSAN_OPTIONS` are set to:
```
exit_code=23
fast_unwind_on_malloc=0
symbolize=0
print_suppressions=0
```
Be sure to include the first ones for LSAN and MSAN when customizing
anything, since some MSAN and LSAN versions don't call `abort()` on
error, and we need a way to detect faults.