diff options
Diffstat (limited to 'docs/env_variables.md')
| -rw-r--r-- | docs/env_variables.md | 406 |
1 files changed, 406 insertions, 0 deletions
diff --git a/docs/env_variables.md b/docs/env_variables.md new file mode 100644 index 00000000..d38a4bc3 --- /dev/null +++ b/docs/env_variables.md @@ -0,0 +1,406 @@ +# 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 - and gcc_plugin afl-gcc-fast + +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 + + - If you are a weird person that wants to compile and instrument asm + text files then use the AFL_AS_FORCE_INSTRUMENT variable: + AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo + + - Setting AFL_QUIET will prevent afl-cc and afl-as banners from being + displayed during compilation, in case you find them distracting. + + - Setting AFL_CAL_FAST will speed up the initial calibration, if the + application is very slow + +## 2) Settings for afl-clang-fast / afl-clang-fast++ / afl-gcc-fast / afl-g++-fast + +The native instrumentation helpers (llvm_mode and gcc_plugin) accept 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. + + - AFL_INST_RATIO, as we switched for instrim instrumentation which + is more effective but makes not much sense together with this option. + +Then there are a few specific features that are only available in llvm_mode: + +### LAF-INTEL + + This great feature will split compares to series of single byte comparisons + to allow afl-fuzz to find otherwise rather impossible paths. It is not + restricted to Intel CPUs ;-) + + - Setting AFL_LLVM_LAF_SPLIT_SWITCHES will split switch()es + + - Setting AFL_LLVM_LAF_TRANSFORM_COMPARES will split string compare functions + + - Setting AFL_LLVM_LAF_SPLIT_COMPARES will split all floating point and + 64, 32 and 16 bit integer CMP instructions + + See llvm_mode/README.laf-intel.md for more information. + +### WHITELIST + + This feature allows selectively instrumentation of the source + + - Setting AFL_LLVM_WHITELIST with a filename will only instrument those + files that match the names listed in this file. + + See llvm_mode/README.whitelist.md for more information. + +### INSTRIM + + This feature increases the speed by whopping 20% but at the cost of a + lower path discovery and therefore coverage. + + - Setting AFL_LLVM_INSTRIM activates this mode + + - Setting AFL_LLVM_INSTRIM_LOOPHEAD=1 expands on INSTRIM to optimize loops. + afl-fuzz will only be able to see the path the loop took, but not how + many times it was called (unless it is a complex loop). + + See llvm_mode/README.instrim.md + +### NOT_ZERO + + - Setting AFL_LLVM_NOT_ZERO=1 during compilation will use counters + that skip zero on overflow. This is the default for llvm >= 9, + however for llvm versions below that this will increase an unnecessary + slowdown due a performance issue that is only fixed in llvm 9+. + This feature increases path discovery by a little bit. + + See llvm_mode/README.neverzero.md + +### CMPLOG + + - Setting AFL_LLVM_CMPLOG=1 during compilation will tell afl-clang-fast to + produce a CmpLog binary. See llvm_mode/README.cmplog.md + + See llvm_mode/README.neverzero.md + +Then there are a few specific features that are only available in the gcc_plugin: + +### WHITELIST + + This feature allows selective instrumentation of the source + + - Setting AFL_GCC_WHITELIST with a filename will only instrument those + files that match the names listed in this file (one filename per line). + + See gcc_plugin/README.whitelist.md for more information. + +## 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. + + - 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. + + - 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. + + - Setting AFL_CUSTOM_MUTATOR_LIBRARY to a shared library with + afl_custom_mutator() export run additional mutations though this library. + If AFL_CUSTOM_MUTATOR_ONLY is also set, all mutations will solely be + performed with/from the libary. see docs/custom_mutator.txt + + - For AFL_PYTHON_MODULE and AFL_PYTHON_ONLY - they require to be compiled + with -DUSE_PYTHON. Please see docs/python_mutators.txt + This feature allows to configure custom mutators which can be very helpful + in e.g. fuzzing XML or other highly flexible structured input. + + - 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. + + - 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 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. + + - Setting AFL_DEBUG_CHILD_OUTPUT will not suppress the child output. + Not pretty but good for debugging purposes. + +## 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). + + - 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, + memcmp, ...) when libcompcov is preloaded using AFL_PRELOAD. + More info at qemu_mode/libcompcov/README.md. + There are two levels at the moment, AFL_COMPCOV_LEVEL=1 that instruments + only comparisons with immediate values / read-only memory and + AFL_COMPCOV_LEVEL=2 that instruments all the comparions. Level 2 is more + 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. + Use this if you are unsure if the entrypoint might be wrong - but + use it directly, e.g. afl-qemu-trace ./program + + - AFL_ENTRYPOINT allows you to specify a specific entrypoint into the + binary (this can be very good for the performance!). + The entrypoint is specified as hex address, e.g. 0x4004110 + Note that the address must be the address of a basic block. + + - 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 + AFL_QEMU_PERSISTENT_ADDR=`start addr`. + + - Another modality to execute the persistent loop is to specify also the + AFL_QEMU_PERSISTENT_RET=`end addr` env variable. + With this variable assigned, instead of patching the return address, the + specified instruction is transformed to a jump towards `start addr`. + + - AFL_QEMU_PERSISTENT_GPR=1 QEMU will save the original value of general + 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 + hitted. + +## 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 + +The library honors these 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. + + - AFL_ALIGNED_ALLOC=1 will force the alignment of the allocation size to + max_align_t to be compliant with the C standard. + +## 9) Settings for libtokencap + +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 + malloc_context_size=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. |