1# Environment variables 2 3 This document discusses the environment variables used by AFL++ to expose 4 various exotic functions that may be (rarely) useful for power users or for 5 some types of custom fuzzing setups. For general information about AFL++, see 6 [README.md](../README.md). 7 8 Note: Most tools will warn on any unknown AFL++ environment variables; for 9 example, because of typos. If you want to disable this check, then set the 10 `AFL_IGNORE_UNKNOWN_ENVS` environment variable. 11 12## 1) Settings for all compilers 13 14Starting with AFL++ 3.0, there is only one compiler: afl-cc. 15 16To select the different instrumentation modes, use one of the following options: 17 18 - Pass the --afl-MODE command-line option to the compiler. Only this option 19 accepts further AFL-specific command-line options. 20 - Use a symlink to afl-cc: afl-clang, afl-clang++, afl-clang-fast, 21 afl-clang-fast++, afl-clang-lto, afl-clang-lto++, afl-g++, afl-g++-fast, 22 afl-gcc, afl-gcc-fast. This option does not accept AFL-specific command-line 23 options. Instead, use environment variables. 24 - Use the `AFL_CC_COMPILER` environment variable with `MODE`. To select 25 `MODE`, use one of the following values: 26 27 - `GCC` (afl-gcc/afl-g++) 28 - `GCC_PLUGIN` (afl-g*-fast) 29 - `LLVM` (afl-clang-fast*) 30 - `LTO` (afl-clang-lto*). 31 32The compile-time tools do not accept AFL-specific command-line options. The 33--afl-MODE command line option is the only exception. The other options make 34fairly broad use of environment variables instead: 35 36 - Some build/configure scripts break with AFL++ compilers. To be able to pass 37 them, do: 38 39 ``` 40 export CC=afl-cc 41 export CXX=afl-c++ 42 export AFL_NOOPT=1 43 ./configure --disable-shared --disabler-werror 44 unset AFL_NOOPT 45 make 46 ``` 47 48 - Setting `AFL_AS`, `AFL_CC`, and `AFL_CXX` lets you use alternate downstream 49 compilation tools, rather than the default 'as', 'clang', or 'gcc' binaries 50 in your `$PATH`. 51 52 - If you are a weird person that wants to compile and instrument asm text 53 files, then use the `AFL_AS_FORCE_INSTRUMENT` variable: 54 `AFL_AS_FORCE_INSTRUMENT=1 afl-gcc foo.s -o foo` 55 56 - Most AFL tools do not print any output if stdout/stderr are redirected. If 57 you want to get the output into a file, then set the `AFL_DEBUG` environment 58 variable. This is sadly necessary for various build processes which fail 59 otherwise. 60 61 - By default, the wrapper appends `-O3` to optimize builds. Very rarely, this 62 will cause problems in programs built with -Werror, because `-O3` enables 63 more thorough code analysis and can spew out additional warnings. To disable 64 optimizations, set `AFL_DONT_OPTIMIZE`. However, if `-O...` and/or 65 `-fno-unroll-loops` are set, these are not overridden. 66 67 - Setting `AFL_HARDEN` automatically adds code hardening options when invoking 68 the downstream compiler. This currently includes `-D_FORTIFY_SOURCE=2` and 69 `-fstack-protector-all`. The setting is useful for catching non-crashing 70 memory bugs at the expense of a very slight (sub-5%) performance loss. 71 72 - Setting `AFL_INST_RATIO` to a percentage between 0 and 100 controls the 73 probability of instrumenting every branch. This is (very rarely) useful when 74 dealing with exceptionally complex programs that saturate the output bitmap. 75 Examples include ffmpeg, perl, and v8. 76 77 (If this ever happens, afl-fuzz will warn you ahead of the time by 78 displaying the "bitmap density" field in fiery red.) 79 80 Setting `AFL_INST_RATIO` to 0 is a valid choice. This will instrument only 81 the transitions between function entry points, but not individual branches. 82 83 Note that this is an outdated variable. A few instances (e.g., afl-gcc) 84 still support these, but state-of-the-art (e.g., LLVM LTO and LLVM PCGUARD) 85 do not need this. 86 87 - `AFL_NO_BUILTIN` causes the compiler to generate code suitable for use with 88 libtokencap.so (but perhaps running a bit slower than without the flag). 89 90 - `AFL_PATH` can be used to point afl-gcc to an alternate location of afl-as. 91 One possible use of this is utils/clang_asm_normalize/, which lets you 92 instrument hand-written assembly when compiling clang code by plugging a 93 normalizer into the chain. (There is no equivalent feature for GCC.) 94 95 - Setting `AFL_QUIET` will prevent afl-as and afl-cc banners from being 96 displayed during compilation, in case you find them distracting. 97 98 - Setting `AFL_USE_...` automatically enables supported sanitizers - provided 99 that your compiler supports it. Available are: 100 - `AFL_USE_ASAN=1` - activates the address sanitizer (memory corruption 101 detection) 102 - `AFL_USE_CFISAN=1` - activates the Control Flow Integrity sanitizer (e.g. 103 type confusion vulnerabilities) 104 - `AFL_USE_LSAN` - activates the leak sanitizer. To perform a leak check 105 within your program at a certain point (such as at the end of an 106 `__AFL_LOOP()`), you can run the macro `__AFL_LEAK_CHECK();` which will 107 cause an abort if any memory is leaked (you can combine this with the 108 `__AFL_LSAN_OFF();` and `__AFL_LSAN_ON();` macros to avoid checking for 109 memory leaks from memory allocated between these two calls. 110 - `AFL_USE_MSAN=1` - activates the memory sanitizer (uninitialized memory) 111 - `AFL_USE_TSAN=1` - activates the thread sanitizer to find thread race 112 conditions 113 - `AFL_USE_UBSAN=1` - activates the undefined behavior sanitizer 114 115 - `TMPDIR` is used by afl-as for temporary files; if this variable is not set, 116 the tool defaults to /tmp. 117 118## 2) Settings for LLVM and LTO: afl-clang-fast / afl-clang-fast++ / afl-clang-lto / afl-clang-lto++ 119 120The native instrumentation helpers (instrumentation and gcc_plugin) accept a 121subset of the settings discussed in section 1, with the exception of: 122 123 - `AFL_AS`, since this toolchain does not directly invoke GNU `as`. 124 125 - `AFL_INST_RATIO`, as we use collision free instrumentation by default. Not 126 all passes support this option though as it is an outdated feature. 127 128 - LLVM modes support `AFL_LLVM_DICT2FILE=/absolute/path/file.txt` which will 129 write all constant string comparisons to this file to be used later with 130 afl-fuzz' `-x` option. 131 132 - `TMPDIR` and `AFL_KEEP_ASSEMBLY`, since no temporary assembly files are 133 created. 134 135Then there are a few specific features that are only available in 136instrumentation mode: 137 138### Select the instrumentation mode 139 140`AFL_LLVM_INSTRUMENT` - this configures the instrumentation mode. 141 142Available options: 143 144 - CLANG - outdated clang instrumentation 145 - CLASSIC - classic AFL (map[cur_loc ^ prev_loc >> 1]++) (default) 146 147 You can also specify CTX and/or NGRAM, separate the options with a comma "," 148 then, e.g.: `AFL_LLVM_INSTRUMENT=CLASSIC,CTX,NGRAM-4` 149 150 Note: It is actually not a good idea to use both CTX and NGRAM. :) 151 - CTX - context sensitive instrumentation 152 - GCC - outdated gcc instrumentation 153 - LTO - LTO instrumentation 154 - NATIVE - clang's original pcguard based instrumentation 155 - NGRAM-x - deeper previous location coverage (from NGRAM-2 up to NGRAM-16) 156 - PCGUARD - our own pcgard based instrumentation (default) 157 158#### CMPLOG 159 160Setting `AFL_LLVM_CMPLOG=1` during compilation will tell afl-clang-fast to 161produce a CmpLog binary. 162 163For more information, see 164[instrumentation/README.cmplog.md](../instrumentation/README.cmplog.md). 165 166#### CTX 167 168Setting `AFL_LLVM_CTX` or `AFL_LLVM_INSTRUMENT=CTX` activates context sensitive 169branch coverage - meaning that each edge is additionally combined with its 170caller. It is highly recommended to increase the `MAP_SIZE_POW2` definition in 171config.h to at least 18 and maybe up to 20 for this as otherwise too many map 172collisions occur. 173 174For more information, see 175[instrumentation/README.llvm.md#6) AFL++ Context Sensitive Branch Coverage](../instrumentation/README.llvm.md#6-afl-context-sensitive-branch-coverage). 176 177#### INSTRUMENT LIST (selectively instrument files and functions) 178 179This feature allows selective instrumentation of the source. 180 181Setting `AFL_LLVM_ALLOWLIST` or `AFL_LLVM_DENYLIST` with a file name and/or 182function will only instrument (or skip) those files that match the names listed 183in the specified file. 184 185For more information, see 186[instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md). 187 188#### LAF-INTEL 189 190This great feature will split compares into series of single byte comparisons to 191allow afl-fuzz to find otherwise rather impossible paths. It is not restricted 192to Intel CPUs. ;-) 193 194 - Setting `AFL_LLVM_LAF_TRANSFORM_COMPARES` will split string compare 195 functions. 196 197 - Setting `AFL_LLVM_LAF_SPLIT_COMPARES` will split all floating point and 64, 198 32 and 16 bit integer CMP instructions. 199 200 - Setting `AFL_LLVM_LAF_SPLIT_FLOATS` will split floating points, needs 201 `AFL_LLVM_LAF_SPLIT_COMPARES` to be set. 202 203 - Setting `AFL_LLVM_LAF_SPLIT_SWITCHES` will split all `switch` constructs. 204 205 - Setting `AFL_LLVM_LAF_ALL` sets all of the above. 206 207For more information, see 208[instrumentation/README.laf-intel.md](../instrumentation/README.laf-intel.md). 209 210#### LTO 211 212This is a different way of instrumentation: first it compiles all code in LTO 213(link time optimization) and then performs an edge inserting instrumentation 214which is 100% collision free (collisions are a big issue in AFL and AFL-like 215instrumentations). This is performed by using afl-clang-lto/afl-clang-lto++ 216instead of afl-clang-fast, but is only built if LLVM 11 or newer is used. 217 218`AFL_LLVM_INSTRUMENT=CFG` will use Control Flow Graph instrumentation. (Not 219recommended for afl-clang-fast, default for afl-clang-lto as there it is a 220different and better kind of instrumentation.) 221 222None of the following options are necessary to be used and are rather for manual 223use (which only ever the author of this LTO implementation will use). These are 224used if several separated instrumentations are performed which are then later 225combined. 226 227 - `AFL_LLVM_DOCUMENT_IDS=file` will document to a file which edge ID was given 228 to which function. This helps to identify functions with variable bytes or 229 which functions were touched by an input. 230 - `AFL_LLVM_LTO_DONTWRITEID` prevents that the highest location ID written 231 into the instrumentation is set in a global variable. 232 - `AFL_LLVM_LTO_STARTID` sets the starting location ID for the 233 instrumentation. This defaults to 1. 234 - `AFL_LLVM_MAP_ADDR` sets the fixed map address to a different address than 235 the default `0x10000`. A value of 0 or empty sets the map address to be 236 dynamic (the original AFL way, which is slower). 237 - `AFL_LLVM_MAP_DYNAMIC` sets the shared memory address to be dynamic. 238 239 For more information, see 240 [instrumentation/README.lto.md](../instrumentation/README.lto.md). 241 242#### NGRAM 243 244Setting `AFL_LLVM_INSTRUMENT=NGRAM-{value}` or `AFL_LLVM_NGRAM_SIZE` activates 245ngram prev_loc coverage. Good values are 2, 4, or 8 (any value between 2 and 16 246is valid). It is highly recommended to increase the `MAP_SIZE_POW2` definition 247in config.h to at least 18 and maybe up to 20 for this as otherwise too many map 248collisions occur. 249 250For more information, see 251[instrumentation/README.llvm.md#7) AFL++ N-Gram Branch Coverage](../instrumentation/README.llvm.md#7-afl-n-gram-branch-coverage). 252 253#### NOT_ZERO 254 255 - Setting `AFL_LLVM_NOT_ZERO=1` during compilation will use counters that skip 256 zero on overflow. This is the default for llvm >= 9, however, for llvm 257 versions below that this will increase an unnecessary slowdown due a 258 performance issue that is only fixed in llvm 9+. This feature increases path 259 discovery by a little bit. 260 261 - Setting `AFL_LLVM_SKIP_NEVERZERO=1` will not implement the skip zero test. 262 If the target performs only a few loops, then this will give a small 263 performance boost. 264 265#### Thread safe instrumentation counters (in all modes) 266 267Setting `AFL_LLVM_THREADSAFE_INST` will inject code that implements thread safe 268counters. The overhead is a little bit higher compared to the older non-thread 269safe case. Note that this disables neverzero (see NOT_ZERO). 270 271## 3) Settings for GCC / GCC_PLUGIN modes 272 273There are a few specific features that are only available in GCC and GCC_PLUGIN 274mode. 275 276 - GCC mode only: Setting `AFL_KEEP_ASSEMBLY` prevents afl-as from deleting 277 instrumented assembly files. Useful for troubleshooting problems or 278 understanding how the tool works. 279 280 To get them in a predictable place, try something like: 281 282 ``` 283 mkdir assembly_here 284 TMPDIR=$PWD/assembly_here AFL_KEEP_ASSEMBLY=1 make clean all 285 ``` 286 287 - GCC_PLUGIN mode only: Setting `AFL_GCC_INSTRUMENT_FILE` or 288 `AFL_GCC_ALLOWLIST` with a filename will only instrument those files that 289 match the names listed in this file (one filename per line). 290 291 Setting `AFL_GCC_DENYLIST` or `AFL_GCC_BLOCKLIST` with a file name and/or 292 function will only skip those files that match the names listed in the 293 specified file. See 294 [instrumentation/README.instrument_list.md](../instrumentation/README.instrument_list.md) 295 for more information. 296 297 Setting `AFL_GCC_OUT_OF_LINE=1` will instruct afl-gcc-fast to instrument the 298 code with calls to an injected subroutine instead of the much more efficient 299 inline instrumentation. 300 301 Setting `AFL_GCC_SKIP_NEVERZERO=1` will not implement the skip zero test. If 302 the target performs only a few loops, then this will give a small 303 performance boost. 304 305## 4) Settings for afl-fuzz 306 307The main fuzzer binary accepts several options that disable a couple of sanity 308checks or alter some of the more exotic semantics of the tool: 309 310 - Setting `AFL_AUTORESUME` will resume a fuzz run (same as providing `-i -`) 311 for an existing out folder, even if a different `-i` was provided. Without 312 this setting, afl-fuzz will refuse execution for a long-fuzzed out dir. 313 314 - Benchmarking only: `AFL_BENCH_JUST_ONE` causes the fuzzer to exit after 315 processing the first queue entry; and `AFL_BENCH_UNTIL_CRASH` causes it to 316 exit soon after the first crash is found. 317 318 - `AFL_CMPLOG_ONLY_NEW` will only perform the expensive cmplog feature for 319 newly found test cases and not for test cases that are loaded on startup 320 (`-i in`). This is an important feature to set when resuming a fuzzing 321 session. 322 323 - Setting `AFL_CRASH_EXITCODE` sets the exit code AFL++ treats as crash. For 324 example, if `AFL_CRASH_EXITCODE='-1'` is set, each input resulting in a `-1` 325 return code (i.e. `exit(-1)` got called), will be treated as if a crash had 326 occurred. This may be beneficial if you look for higher-level faulty 327 conditions in which your target still exits gracefully. 328 329 - Setting `AFL_CUSTOM_MUTATOR_LIBRARY` to a shared library with 330 afl_custom_fuzz() creates additional mutations through this library. If 331 afl-fuzz is compiled with Python (which is autodetected during building 332 afl-fuzz), setting `AFL_PYTHON_MODULE` to a Python module can also provide 333 additional mutations. If `AFL_CUSTOM_MUTATOR_ONLY` is also set, all 334 mutations will solely be performed with the custom mutator. This feature 335 allows to configure custom mutators which can be very helpful, e.g., fuzzing 336 XML or other highly flexible structured input. For details, see 337 [custom_mutators.md](custom_mutators.md). 338 339 - Setting `AFL_CYCLE_SCHEDULES` will switch to a different schedule every time 340 a cycle is finished. 341 342 - Setting `AFL_DEBUG_CHILD` will not suppress the child output. This lets you 343 see all output of the child, making setup issues obvious. For example, in an 344 unicornafl harness, you might see python stacktraces. You may also see other 345 logs that way, indicating why the forkserver won't start. Not pretty but 346 good for debugging purposes. Note that `AFL_DEBUG_CHILD_OUTPUT` is 347 deprecated. 348 349 - Setting `AFL_DISABLE_TRIM` tells afl-fuzz not to trim test cases. This is 350 usually a bad idea! 351 352 - Setting `AFL_KEEP_TIMEOUTS` will keep longer running inputs if they reach 353 new coverage 354 355 - `AFL_EXIT_ON_SEED_ISSUES` will restore the vanilla afl-fuzz behavior which 356 does not allow crashes or timeout seeds in the initial -i corpus. 357 358 - `AFL_EXIT_ON_TIME` causes afl-fuzz to terminate if no new paths were found 359 within a specified period of time (in seconds). May be convenient for some 360 types of automated jobs. 361 362 - `AFL_EXIT_WHEN_DONE` causes afl-fuzz to terminate when all existing paths 363 have been fuzzed and there were no new finds for a while. This would be 364 normally indicated by the cycle counter in the UI turning green. May be 365 convenient for some types of automated jobs. 366 367 - Setting `AFL_EXPAND_HAVOC_NOW` will start in the extended havoc mode that 368 includes costly mutations. afl-fuzz automatically enables this mode when 369 deemed useful otherwise. 370 371 - `AFL_FAST_CAL` keeps the calibration stage about 2.5x faster (albeit less 372 precise), which can help when starting a session against a slow target. 373 `AFL_CAL_FAST` works too. 374 375 - Setting `AFL_FORCE_UI` will force painting the UI on the screen even if no 376 valid terminal was detected (for virtual consoles). 377 378 - Setting `AFL_FORKSRV_INIT_TMOUT` allows you to specify a different timeout 379 to wait for the forkserver to spin up. The default is the `-t` value times 380 `FORK_WAIT_MULT` from `config.h` (usually 10), so for a `-t 100`, the 381 default would wait for `1000` milliseconds. Setting a different time here is 382 useful if the target has a very slow startup time, for example, when doing 383 full-system fuzzing or emulation, but you don't want the actual runs to wait 384 too long for timeouts. 385 386 - Setting `AFL_HANG_TMOUT` allows you to specify a different timeout for 387 deciding if a particular test case is a "hang". The default is 1 second or 388 the value of the `-t` parameter, whichever is larger. Dialing the value down 389 can be useful if you are very concerned about slow inputs, or if you don't 390 want AFL++ to spend too much time classifying that stuff and just rapidly 391 put all timeouts in that bin. 392 393 - If you are Jakub, you may need `AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES`. 394 Others need not apply, unless they also want to disable the 395 `/proc/sys/kernel/core_pattern` check. 396 397 - If afl-fuzz encounters an incorrect fuzzing setup during a fuzzing session 398 (not at startup), it will terminate. If you do not want this, then you can 399 set `AFL_IGNORE_PROBLEMS`. 400 401 - When running in the `-M` or `-S` mode, setting `AFL_IMPORT_FIRST` causes the 402 fuzzer to import test cases from other instances before doing anything else. 403 This makes the "own finds" counter in the UI more accurate. Beyond counter 404 aesthetics, not much else should change. 405 406 - Setting `AFL_INPUT_LEN_MIN` and `AFL_INPUT_LEN_MAX` are an alternative to 407 the afl-fuzz -g/-G command line option to control the minimum/maximum 408 of fuzzing input generated. 409 410 - `AFL_KILL_SIGNAL`: Set the signal ID to be delivered to child processes on 411 timeout. Unless you implement your own targets or instrumentation, you 412 likely don't have to set it. By default, on timeout and on exit, `SIGKILL` 413 (`AFL_KILL_SIGNAL=9`) will be delivered to the child. 414 415 - `AFL_MAP_SIZE` sets the size of the shared map that afl-analyze, afl-fuzz, 416 afl-showmap, and afl-tmin create to gather instrumentation data from the 417 target. This must be equal or larger than the size the target was compiled 418 with. 419 420 - Setting `AFL_MAX_DET_EXTRAS` will change the threshold at what number of 421 elements in the `-x` dictionary and LTO autodict (combined) the 422 probabilistic mode will kick off. In probabilistic mode, not all dictionary 423 entries will be used all of the time for fuzzing mutations to not slow down 424 fuzzing. The default count is `200` elements. So for the 200 + 1st element, 425 there is a 1 in 201 chance, that one of the dictionary entries will not be 426 used directly. 427 428 - Setting `AFL_NO_AFFINITY` disables attempts to bind to a specific CPU core 429 on Linux systems. This slows things down, but lets you run more instances of 430 afl-fuzz than would be prudent (if you really want to). 431 432 - `AFL_NO_ARITH` causes AFL++ to skip most of the deterministic arithmetics. 433 This can be useful to speed up the fuzzing of text-based file formats. 434 435 - Setting `AFL_NO_AUTODICT` will not load an LTO generated auto dictionary 436 that is compiled into the target. 437 438 - Setting `AFL_NO_COLOR` or `AFL_NO_COLOUR` will omit control sequences for 439 coloring console output when configured with USE_COLOR and not 440 ALWAYS_COLORED. 441 442 - The CPU widget shown at the bottom of the screen is fairly simplistic and 443 may complain of high load prematurely, especially on systems with low core 444 counts. To avoid the alarming red color for very high CPU usages, you can 445 set `AFL_NO_CPU_RED`. 446 447 - Setting `AFL_NO_FORKSRV` disables the forkserver optimization, reverting to 448 fork + execve() call for every tested input. This is useful mostly when 449 working with unruly libraries that create threads or do other crazy things 450 when initializing (before the instrumentation has a chance to run). 451 452 Note that this setting inhibits some of the user-friendly diagnostics 453 normally done when starting up the forkserver and causes a pretty 454 significant performance drop. 455 456 - `AFL_NO_SNAPSHOT` will advice afl-fuzz not to use the snapshot feature if 457 the snapshot lkm is loaded. 458 459 - Setting `AFL_NO_UI` inhibits the UI altogether and just periodically prints 460 some basic stats. This behavior is also automatically triggered when the 461 output from afl-fuzz is redirected to a file or to a pipe. 462 463 - In QEMU mode (-Q) and Frida mode (-O), `AFL_PATH` will be searched for 464 afl-qemu-trace and afl-frida-trace.so. 465 466 - If you are using persistent mode (you should, see 467 [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md)), 468 some targets keep inherent state due which a detected crash test case does 469 not crash the target again when the test case is given. To be able to still 470 re-trigger these crashes, you can use the `AFL_PERSISTENT_RECORD` variable 471 with a value of how many previous fuzz cases to keep prio a crash. If set to 472 e.g., 10, then the 9 previous inputs are written to out/default/crashes as 473 RECORD:000000,cnt:000000 to RECORD:000000,cnt:000008 and 474 RECORD:000000,cnt:000009 being the crash case. NOTE: This option needs to be 475 enabled in config.h first! 476 477 - Note that `AFL_POST_LIBRARY` is deprecated, use `AFL_CUSTOM_MUTATOR_LIBRARY` 478 instead. 479 480 - Setting `AFL_PRELOAD` causes AFL++ to set `LD_PRELOAD` for the target binary 481 without disrupting the afl-fuzz process itself. This is useful, among other 482 things, for bootstrapping libdislocator.so. 483 484 - In QEMU mode (-Q), setting `AFL_QEMU_CUSTOM_BIN` will cause afl-fuzz to skip 485 prepending `afl-qemu-trace` to your command line. Use this if you wish to 486 use a custom afl-qemu-trace or if you need to modify the afl-qemu-trace 487 arguments. 488 489 - `AFL_SHUFFLE_QUEUE` randomly reorders the input queue on startup. Requested 490 by some users for unorthodox parallelized fuzzing setups, but not advisable 491 otherwise. 492 493 - When developing custom instrumentation on top of afl-fuzz, you can use 494 `AFL_SKIP_BIN_CHECK` to inhibit the checks for non-instrumented binaries and 495 shell scripts; and `AFL_DUMB_FORKSRV` in conjunction with the `-n` setting 496 to instruct afl-fuzz to still follow the fork server protocol without 497 expecting any instrumentation data in return. Note that this also turns off 498 auto map size detection. 499 500 - Setting `AFL_SKIP_CPUFREQ` skips the check for CPU scaling policy. This is 501 useful if you can't change the defaults (e.g., no root access to the system) 502 and are OK with some performance loss. 503 504 - Setting `AFL_STATSD` enables StatsD metrics collection. By default, AFL++ 505 will send these metrics over UDP to 127.0.0.1:8125. The host and port are 506 configurable with `AFL_STATSD_HOST` and `AFL_STATSD_PORT` respectively. To 507 enable tags (banner and afl_version), you should provide 508 `AFL_STATSD_TAGS_FLAVOR` that matches your StatsD server (see 509 `AFL_STATSD_TAGS_FLAVOR`). 510 511 - Setting `AFL_STATSD_TAGS_FLAVOR` to one of `dogstatsd`, `influxdb`, 512 `librato`, or `signalfx` allows you to add tags to your fuzzing instances. 513 This is especially useful when running multiple instances (`-M/-S` for 514 example). Applied tags are `banner` and `afl_version`. `banner` corresponds 515 to the name of the fuzzer provided through `-M/-S`. `afl_version` 516 corresponds to the currently running AFL++ version (e.g., `++3.0c`). Default 517 (empty/non present) will add no tags to the metrics. For more information, 518 see [rpc_statsd.md](rpc_statsd.md). 519 520 - Setting `AFL_TARGET_ENV` causes AFL++ to set extra environment variables for 521 the target binary. Example: `AFL_TARGET_ENV="VAR1=1 VAR2='a b c'" afl-fuzz 522 ... `. This exists mostly for things like `LD_LIBRARY_PATH` but it would 523 theoretically allow fuzzing of AFL++ itself (with 'target' AFL++ using some 524 AFL_ vars that would disrupt work of 'fuzzer' AFL++). Note that when using 525 QEMU mode, the `AFL_TARGET_ENV` environment variables will apply to QEMU, as 526 well as the target binary. Therefore, in this case, you might want to use 527 QEMU's `QEMU_SET_ENV` environment variable (see QEMU's documentation because 528 the format is different from `AFL_TARGET_ENV`) to apply the environment 529 variables to the target and not QEMU. 530 531 - `AFL_TESTCACHE_SIZE` allows you to override the size of `#define 532 TESTCASE_CACHE` in config.h. Recommended values are 50-250MB - or more if 533 your fuzzing finds a huge amount of paths for large inputs. 534 535 - `AFL_TMPDIR` is used to write the `.cur_input` file to if it exists, and in 536 the normal output directory otherwise. You would use this to point to a 537 ramdisk/tmpfs. This increases the speed by a small value but also reduces 538 the stress on SSDs. 539 540 - Setting `AFL_TRY_AFFINITY` tries to attempt binding to a specific CPU core 541 on Linux systems, but will not terminate if that fails. 542 543 - The following environment variables are only needed if you implemented 544 your own forkserver or persistent mode, or if __AFL_LOOP or __AFL_INIT 545 are in a shared library and not the main binary: 546 - `AFL_DEFER_FORKSRV` enforces a deferred forkserver even if none was 547 detected in the target binary 548 - `AFL_PERSISTENT` enforces persistent mode even if none was detected 549 in the target binary 550 551 - If you need an early forkserver in your target because of early 552 constructors in your target you can set `AFL_EARLY_FORKSERVER`. 553 Note that this is not a compile time option but a runtime option :-) 554 555 - set `AFL_PIZZA_MODE` to 1 to enable the April 1st stats menu, set to 0 556 to disable although it is 1st of April. 557 558## 5) Settings for afl-qemu-trace 559 560The QEMU wrapper used to instrument binary-only code supports several settings: 561 562 - Setting `AFL_COMPCOV_LEVEL` enables the CompareCoverage tracing of all cmp 563 and sub in x86 and x86_64 and memory comparison functions (e.g., strcmp, 564 memcmp, ...) when libcompcov is preloaded using `AFL_PRELOAD`. More info at 565 [qemu_mode/libcompcov/README.md](../qemu_mode/libcompcov/README.md). 566 567 There are two levels at the moment, `AFL_COMPCOV_LEVEL=1` that instruments 568 only comparisons with immediate values / read-only memory and 569 `AFL_COMPCOV_LEVEL=2` that instruments all the comparisons. Level 2 is more 570 accurate but may need a larger shared memory. 571 572 - `AFL_DEBUG` will print the found entry point for the binary to stderr. Use 573 this if you are unsure if the entry point might be wrong - but use it 574 directly, e.g., `afl-qemu-trace ./program`. 575 576 - `AFL_ENTRYPOINT` allows you to specify a specific entry point into the 577 binary (this can be very good for the performance!). The entry point is 578 specified as hex address, e.g., `0x4004110`. Note that the address must be 579 the address of a basic block. 580 581 - Setting `AFL_INST_LIBS` causes the translator to also instrument the code 582 inside any dynamically linked libraries (notably including glibc). 583 584 - It is possible to set `AFL_INST_RATIO` to skip the instrumentation on some 585 of the basic blocks, which can be useful when dealing with very complex 586 binaries. 587 588 - Setting `AFL_QEMU_COMPCOV` enables the CompareCoverage tracing of all cmp 589 and sub in x86 and x86_64. This is an alias of `AFL_COMPCOV_LEVEL=1` when 590 `AFL_COMPCOV_LEVEL` is not specified. 591 592 - With `AFL_QEMU_FORCE_DFL`, you force QEMU to ignore the registered signal 593 handlers of the target. 594 595 - When the target is i386/x86_64, you can specify the address of the function 596 that has to be the body of the persistent loop using 597 `AFL_QEMU_PERSISTENT_ADDR=start addr`. 598 599 - With `AFL_QEMU_PERSISTENT_GPR=1`, QEMU will save the original value of 600 general purpose registers and restore them in each persistent cycle. 601 602 - Another modality to execute the persistent loop is to specify also the 603 `AFL_QEMU_PERSISTENT_RET=end addr` environment variable. With this variable 604 assigned, instead of patching the return address, the specified instruction 605 is transformed to a jump towards `start addr`. 606 607 - With `AFL_QEMU_PERSISTENT_RETADDR_OFFSET`, you can specify the offset from 608 the stack pointer in which QEMU can find the return address when `start 609 addr` is hit. 610 611 - With `AFL_USE_QASAN`, you can enable QEMU AddressSanitizer for dynamically 612 linked binaries. 613 614 - The underlying QEMU binary will recognize any standard "user space 615 emulation" variables (e.g., `QEMU_STACK_SIZE`), but there should be no 616 reason to touch them. 617 618## 7) Settings for afl-frida-trace 619 620The FRIDA wrapper used to instrument binary-only code supports many of the same 621options as `afl-qemu-trace`, but also has a number of additional advanced 622options. These are listed in brief below (see 623[frida_mode/README.md](../frida_mode/README.md) for more details). These 624settings are provided for compatibility with QEMU mode, the preferred way to 625configure FRIDA mode is through its [scripting](../frida_mode/Scripting.md) 626support. 627 628* `AFL_FRIDA_DEBUG_MAPS` - See `AFL_QEMU_DEBUG_MAPS` 629* `AFL_FRIDA_DRIVER_NO_HOOK` - See `AFL_QEMU_DRIVER_NO_HOOK`. When using the 630 QEMU driver to provide a `main` loop for a user provided 631 `LLVMFuzzerTestOneInput`, this option configures the driver to read input from 632 `stdin` rather than using in-memory test cases. 633* `AFL_FRIDA_EXCLUDE_RANGES` - See `AFL_QEMU_EXCLUDE_RANGES` 634* `AFL_FRIDA_INST_COVERAGE_FILE` - File to write DynamoRio format coverage 635 information (e.g., to be loaded within IDA lighthouse). 636* `AFL_FRIDA_INST_DEBUG_FILE` - File to write raw assembly of original blocks 637 and their instrumented counterparts during block compilation. 638* `AFL_FRIDA_INST_JIT` - Enable the instrumentation of Just-In-Time compiled 639 code. Code is considered to be JIT if the executable segment is not backed by 640 a file. 641* `AFL_FRIDA_INST_NO_OPTIMIZE` - Don't use optimized inline assembly coverage 642 instrumentation (the default where available). Required to use 643 `AFL_FRIDA_INST_TRACE`. 644* `AFL_FRIDA_INST_NO_BACKPATCH` - Disable backpatching. At the end of executing 645 each block, control will return to FRIDA to identify the next block to 646 execute. 647* `AFL_FRIDA_INST_NO_PREFETCH` - Disable prefetching. By default, the child will 648 report instrumented blocks back to the parent so that it can also instrument 649 them and they be inherited by the next child on fork, implies 650 `AFL_FRIDA_INST_NO_PREFETCH_BACKPATCH`. 651* `AFL_FRIDA_INST_NO_PREFETCH_BACKPATCH` - Disable prefetching of stalker 652 backpatching information. By default, the child will report applied 653 backpatches to the parent so that they can be applied and then be inherited by 654 the next child on fork. 655* `AFL_FRIDA_INST_RANGES` - See `AFL_QEMU_INST_RANGES` 656* `AFL_FRIDA_INST_SEED` - Sets the initial seed for the hash function used to 657 generate block (and hence edge) IDs. Setting this to a constant value may be 658 useful for debugging purposes, e.g., investigating unstable edges. 659* `AFL_FRIDA_INST_TRACE` - Log to stdout the address of executed blocks, implies 660 `AFL_FRIDA_INST_NO_OPTIMIZE`. 661* `AFL_FRIDA_INST_TRACE_UNIQUE` - As per `AFL_FRIDA_INST_TRACE`, but each edge 662 is logged only once, requires `AFL_FRIDA_INST_NO_OPTIMIZE`. 663* `AFL_FRIDA_INST_UNSTABLE_COVERAGE_FILE` - File to write DynamoRio format 664 coverage information for unstable edges (e.g., to be loaded within IDA 665 lighthouse). 666* `AFL_FRIDA_JS_SCRIPT` - Set the script to be loaded by the FRIDA scripting 667 engine. See [frida_mode/Scripting.md](../frida_mode/Scripting.md) for details. 668* `AFL_FRIDA_OUTPUT_STDOUT` - Redirect the standard output of the target 669 application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) 670* `AFL_FRIDA_OUTPUT_STDERR` - Redirect the standard error of the target 671 application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) 672* `AFL_FRIDA_PERSISTENT_ADDR` - See `AFL_QEMU_PERSISTENT_ADDR` 673* `AFL_FRIDA_PERSISTENT_CNT` - See `AFL_QEMU_PERSISTENT_CNT` 674* `AFL_FRIDA_PERSISTENT_DEBUG` - Insert a Breakpoint into the instrumented code 675 at `AFL_FRIDA_PERSISTENT_HOOK` and `AFL_FRIDA_PERSISTENT_RET` to allow the 676 user to detect issues in the persistent loop using a debugger. 677* `AFL_FRIDA_PERSISTENT_HOOK` - See `AFL_QEMU_PERSISTENT_HOOK` 678* `AFL_FRIDA_PERSISTENT_RET` - See `AFL_QEMU_PERSISTENT_RET` 679* `AFL_FRIDA_SECCOMP_FILE` - Write a log of any syscalls made by the target to 680 the specified file. 681* `AFL_FRIDA_STALKER_ADJACENT_BLOCKS` - Configure the number of adjacent blocks 682 to fetch when generating instrumented code. By fetching blocks in the same 683 order they appear in the original program, rather than the order of execution 684 should help reduce locallity and adjacency. This includes allowing us to 685 vector between adjancent blocks using a NOP slide rather than an immediate 686 branch. 687* `AFL_FRIDA_STALKER_IC_ENTRIES` - Configure the number of inline cache entries 688 stored along-side branch instructions which provide a cache to avoid having to 689 call back into FRIDA to find the next block. Default is 32. 690* `AFL_FRIDA_STATS_FILE` - Write statistics information about the code being 691 instrumented to the given file name. The statistics are written only for the 692 child process when new block is instrumented (when the 693 `AFL_FRIDA_STATS_INTERVAL` has expired). Note that just because a new path is 694 found does not mean a new block needs to be compiled. It could be that the 695 existing blocks instrumented have been executed in a different order. 696* `AFL_FRIDA_STATS_INTERVAL` - The maximum frequency to output statistics 697 information. Stats will be written whenever they are updated if the given 698 interval has elapsed since last time they were written. 699* `AFL_FRIDA_TRACEABLE` - Set the child process to be traceable by any process 700 to aid debugging and overcome the restrictions imposed by YAMA. Supported on 701 Linux only. Permits a non-root user to use `gcore` or similar to collect a 702 core dump of the instrumented target. Note that in order to capture the core 703 dump you must set a sufficient timeout (using `-t`) to avoid `afl-fuzz` 704 killing the process whilst it is being dumped. 705 706## 8) Settings for afl-cmin 707 708The corpus minimization script offers very little customization: 709 710 - `AFL_ALLOW_TMP` permits this and some other scripts to run in /tmp. This is 711 a modest security risk on multi-user systems with rogue users, but should be 712 safe on dedicated fuzzing boxes. 713 714 - `AFL_KEEP_TRACES` makes the tool keep traces and other metadata used for 715 minimization and normally deleted at exit. The files can be found in the 716 `<out_dir>/.traces/` directory. 717 718 - Setting `AFL_PATH` offers a way to specify the location of afl-showmap and 719 afl-qemu-trace (the latter only in `-Q` mode). 720 721 - `AFL_PRINT_FILENAMES` prints each filename to stdout, as it gets processed. 722 This can help when embedding `afl-cmin` or `afl-showmap` in other scripts. 723 724## 9) Settings for afl-tmin 725 726Virtually nothing to play with. Well, in QEMU mode (`-Q`), `AFL_PATH` will be 727searched for afl-qemu-trace. In addition to this, `TMPDIR` may be used if a 728temporary file can't be created in the current working directory. 729 730You can specify `AFL_TMIN_EXACT` if you want afl-tmin to require execution paths 731to match when minimizing crashes. This will make minimization less useful, but 732may prevent the tool from "jumping" from one crashing condition to another in 733very buggy software. You probably want to combine it with the `-e` flag. 734 735## 10) Settings for afl-analyze 736 737You can set `AFL_ANALYZE_HEX` to get file offsets printed as hexadecimal instead 738of decimal. 739 740## 11) Settings for libdislocator 741 742The library honors these environment variables: 743 744 - `AFL_ALIGNED_ALLOC=1` will force the alignment of the allocation size to 745 `max_align_t` to be compliant with the C standard. 746 747 - `AFL_LD_HARD_FAIL` alters the behavior by calling `abort()` on excessive 748 allocations, thus causing what AFL++ would perceive as a crash. Useful for 749 programs that are supposed to maintain a specific memory footprint. 750 751 - `AFL_LD_LIMIT_MB` caps the size of the maximum heap usage permitted by the 752 library, in megabytes. The default value is 1 GB. Once this is exceeded, 753 allocations will return NULL. 754 755 - `AFL_LD_NO_CALLOC_OVER` inhibits `abort()` on `calloc()` overflows. Most of 756 the common allocators check for that internally and return NULL, so it's a 757 security risk only in more exotic setups. 758 759 - `AFL_LD_VERBOSE` causes the library to output some diagnostic messages that 760 may be useful for pinpointing the cause of any observed issues. 761 762## 11) Settings for libtokencap 763 764This library accepts `AFL_TOKEN_FILE` to indicate the location to which the 765discovered tokens should be written. 766 767## 12) Third-party variables set by afl-fuzz & other tools 768 769Several variables are not directly interpreted by afl-fuzz, but are set to 770optimal values if not already present in the environment: 771 772 - By default, `ASAN_OPTIONS` are set to (among others): 773 774 ``` 775 abort_on_error=1 776 detect_leaks=0 777 malloc_context_size=0 778 symbolize=0 779 allocator_may_return_null=1 780 ``` 781 782 If you want to set your own options, be sure to include `abort_on_error=1` - 783 otherwise, the fuzzer will not be able to detect crashes in the tested app. 784 Similarly, include `symbolize=0`, since without it, AFL++ may have 785 difficulty telling crashes and hangs apart. 786 787 - Similarly, the default `LSAN_OPTIONS` are set to: 788 789 ``` 790 exit_code=23 791 fast_unwind_on_malloc=0 792 symbolize=0 793 print_suppressions=0 794 ``` 795 796 Be sure to include the first ones for LSAN and MSAN when customizing 797 anything, since some MSAN and LSAN versions don't call `abort()` on error, 798 and we need a way to detect faults. 799 800 - In the same vein, by default, `MSAN_OPTIONS` are set to: 801 802 ``` 803 exit_code=86 (required for legacy reasons) 804 abort_on_error=1 805 symbolize=0 806 msan_track_origins=0 807 allocator_may_return_null=1 808 ``` 809 810 - By default, `LD_BIND_NOW` is set to speed up fuzzing by forcing the linker 811 to do all the work before the fork server kicks in. You can override this by 812 setting `LD_BIND_LAZY` beforehand, but it is almost certainly pointless. 813