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