diff options
Diffstat (limited to 'docs/env_variables.md')
| -rw-r--r-- | docs/env_variables.md | 147 |
1 files changed, 75 insertions, 72 deletions
diff --git a/docs/env_variables.md b/docs/env_variables.md index c1c70ec5..c45f4ab9 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -59,9 +59,9 @@ fairly broad use of environment variables instead: otherwise. - By default, the wrapper appends `-O3` to optimize builds. Very rarely, this - will cause problems in programs built with -Werror, simply because `-O3` - enables more thorough code analysis and can spew out additional warnings. To - disable optimizations, set `AFL_DONT_OPTIMIZE`. However, if `-O...` and/or + will cause problems in programs built with -Werror, because `-O3` enables + more thorough code analysis and can spew out additional warnings. To disable + optimizations, set `AFL_DONT_OPTIMIZE`. However, if `-O...` and/or `-fno-unroll-loops` are set, these are not overridden. - Setting `AFL_HARDEN` automatically adds code hardening options when invoking @@ -80,9 +80,9 @@ fairly broad use of environment variables instead: Setting `AFL_INST_RATIO` to 0 is a valid choice. This will instrument only the transitions between function entry points, but not individual branches. - Note that this is an outdated variable. A few instances (e.g. afl-gcc) still - support these, but state-of-the-art (e.g. LLVM LTO and LLVM PCGUARD) do not - need this. + Note that this is an outdated variable. A few instances (e.g., afl-gcc) + still support these, but state-of-the-art (e.g., LLVM LTO and LLVM PCGUARD) + do not need this. - `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). @@ -109,7 +109,7 @@ fairly broad use of environment variables instead: - `AFL_USE_MSAN=1` - activates the memory sanitizer (uninitialized memory) - `AFL_USE_TSAN=1` - activates the thread sanitizer to find thread race conditions - - `AFL_USE_UBSAN=1` - activates the undefined behaviour sanitizer + - `AFL_USE_UBSAN=1` - activates the undefined behavior sanitizer - `TMPDIR` is used by afl-as for temporary files; if this variable is not set, the tool defaults to /tmp. @@ -307,7 +307,7 @@ checks or alter some of the more exotic semantics of the tool: (`-i in`). This is an important feature to set when resuming a fuzzing session. - - Setting `AFL_CRASH_EXITCODE` sets the exit code AFL treats as crash. For + - Setting `AFL_CRASH_EXITCODE` sets the exit code AFL++ treats as crash. For example, if `AFL_CRASH_EXITCODE='-1'` is set, each input resulting in a `-1` return code (i.e. `exit(-1)` got called), will be treated as if a crash had occurred. This may be beneficial if you look for higher-level faulty @@ -319,8 +319,8 @@ checks or alter some of the more exotic semantics of the tool: afl-fuzz), setting `AFL_PYTHON_MODULE` to a Python module can also provide additional mutations. If `AFL_CUSTOM_MUTATOR_ONLY` is also set, all mutations will solely be performed with the custom mutator. This feature - allows to configure custom mutators which can be very helpful, e.g. fuzzing - XML or other highly flexible structured input. Please see + allows to configure custom mutators which can be very helpful, e.g., fuzzing + XML or other highly flexible structured input. For details, see [custom_mutators.md](custom_mutators.md). - Setting `AFL_CYCLE_SCHEDULES` will switch to a different schedule every time @@ -336,7 +336,7 @@ checks or alter some of the more exotic semantics of the tool: - Setting `AFL_DISABLE_TRIM` tells afl-fuzz not to trim test cases. This is usually a bad idea! - - `AFL_EXIT_ON_SEED_ISSUES` will restore the vanilla afl-fuzz behaviour which + - `AFL_EXIT_ON_SEED_ISSUES` will restore the vanilla afl-fuzz behavior which does not allow crashes or timeout seeds in the initial -i corpus. - `AFL_EXIT_ON_TIME` causes afl-fuzz to terminate if no new paths were found @@ -449,7 +449,7 @@ checks or alter some of the more exotic semantics of the tool: not crash the target again when the test case is given. To be able to still re-trigger these crashes, you can use the `AFL_PERSISTENT_RECORD` variable with a value of how many previous fuzz cases to keep prio a crash. If set to - e.g. 10, then the 9 previous inputs are written to out/default/crashes as + e.g., 10, then the 9 previous inputs are written to out/default/crashes as RECORD:000000,cnt:000000 to RECORD:000000,cnt:000008 and RECORD:000000,cnt:000009 being the crash case. NOTE: This option needs to be enabled in config.h first! @@ -493,7 +493,7 @@ checks or alter some of the more exotic semantics of the tool: This is especially useful when running multiple instances (`-M/-S` for example). Applied tags are `banner` and `afl_version`. `banner` corresponds to the name of the fuzzer provided through `-M/-S`. `afl_version` - corresponds to the currently running AFL version (e.g. `++3.0c`). Default + corresponds to the currently running AFL++ version (e.g., `++3.0c`). Default (empty/non present) will add no tags to the metrics. For more information, see [rpc_statsd.md](rpc_statsd.md). @@ -535,11 +535,11 @@ The QEMU wrapper used to instrument binary-only code supports several settings: - `AFL_DEBUG` will print the found entry point for the binary to stderr. Use this if you are unsure if the entry point might be wrong - but use it - directly, e.g. `afl-qemu-trace ./program`. + directly, e.g., `afl-qemu-trace ./program`. - `AFL_ENTRYPOINT` allows you to specify a specific entry point into the binary (this can be very good for the performance!). The entry point is - specified as hex address, e.g. `0x4004110`. Note that the address must be + specified as hex address, e.g., `0x4004110`. Note that the address must be the address of a basic block. - Setting `AFL_INST_LIBS` causes the translator to also instrument the code @@ -553,26 +553,26 @@ The QEMU wrapper used to instrument binary-only code supports several settings: and sub in x86 and x86_64. This is an alias of `AFL_COMPCOV_LEVEL=1` when `AFL_COMPCOV_LEVEL` is not specified. - - With `AFL_QEMU_FORCE_DFL` you force QEMU to ignore the registered signal + - With `AFL_QEMU_FORCE_DFL`, you force QEMU to ignore the registered signal handlers of the target. - When the target is i386/x86_64, you can specify the address of the function that has to be the body of the persistent loop using `AFL_QEMU_PERSISTENT_ADDR=start addr`. - - With `AFL_QEMU_PERSISTENT_GPR=1` QEMU will save the original value of + - With `AFL_QEMU_PERSISTENT_GPR=1`, QEMU will save the original value of general purpose registers and restore them in each persistent cycle. - Another modality to execute the persistent loop is to specify also the - `AFL_QEMU_PERSISTENT_RET=end addr` env variable. With this variable + `AFL_QEMU_PERSISTENT_RET=end addr` environment variable. With this variable assigned, instead of patching the return address, the specified instruction is transformed to a jump towards `start addr`. - - With `AFL_QEMU_PERSISTENT_RETADDR_OFFSET` you can specify the offset from + - With `AFL_QEMU_PERSISTENT_RETADDR_OFFSET`, you can specify the offset from the stack pointer in which QEMU can find the return address when `start addr` is hit. - - With `AFL_USE_QASAN` you can enable QEMU AddressSanitizer for dynamically + - With `AFL_USE_QASAN`, you can enable QEMU AddressSanitizer for dynamically linked binaries. - The underlying QEMU binary will recognize any standard "user space @@ -583,86 +583,89 @@ The QEMU wrapper used to instrument binary-only code supports several settings: The FRIDA wrapper used to instrument binary-only code supports many of the same options as `afl-qemu-trace`, but also has a number of additional advanced -options. These are listed in brief below (see [here](../frida_mode/README.md) -for more details). These settings are provided for compatibiltiy with QEMU mode, -the preferred way to configure FRIDA mode is through its -[scripting](../frida_mode/Scripting.md) support. +options. These are listed in brief below (see +[frida_mode/README.md](../frida_mode/README.md) for more details). These +settings are provided for compatibility with QEMU mode, the preferred way to +configure FRIDA mode is through its [scripting](../frida_mode/Scripting.md) +support. * `AFL_FRIDA_DEBUG_MAPS` - See `AFL_QEMU_DEBUG_MAPS` * `AFL_FRIDA_DRIVER_NO_HOOK` - See `AFL_QEMU_DRIVER_NO_HOOK`. When using the -QEMU driver to provide a `main` loop for a user provided -`LLVMFuzzerTestOneInput`, this option configures the driver to read input from -`stdin` rather than using in-memory test cases. + QEMU driver to provide a `main` loop for a user provided + `LLVMFuzzerTestOneInput`, this option configures the driver to read input from + `stdin` rather than using in-memory test cases. * `AFL_FRIDA_EXCLUDE_RANGES` - See `AFL_QEMU_EXCLUDE_RANGES` * `AFL_FRIDA_INST_COVERAGE_FILE` - File to write DynamoRio format coverage -information (e.g. to be loaded within IDA lighthouse). + information (e.g., to be loaded within IDA lighthouse). * `AFL_FRIDA_INST_DEBUG_FILE` - File to write raw assembly of original blocks -and their instrumented counterparts during block compilation. + and their instrumented counterparts during block compilation. * `AFL_FRIDA_INST_JIT` - Enable the instrumentation of Just-In-Time compiled -code. Code is considered to be JIT if the executable segment is not backed by a -file. + code. Code is considered to be JIT if the executable segment is not backed by + a file. * `AFL_FRIDA_INST_NO_OPTIMIZE` - Don't use optimized inline assembly coverage -instrumentation (the default where available). Required to use -`AFL_FRIDA_INST_TRACE`. + instrumentation (the default where available). Required to use + `AFL_FRIDA_INST_TRACE`. * `AFL_FRIDA_INST_NO_BACKPATCH` - Disable backpatching. At the end of executing -each block, control will return to FRIDA to identify the next block to execute. -* `AFL_FRIDA_INST_NO_PREFETCH` - Disable prefetching. By default the child will -report instrumented blocks back to the parent so that it can also instrument -them and they be inherited by the next child on fork, implies -`AFL_FRIDA_INST_NO_PREFETCH_BACKPATCH`. + each block, control will return to FRIDA to identify the next block to + execute. +* `AFL_FRIDA_INST_NO_PREFETCH` - Disable prefetching. By default, the child will + report instrumented blocks back to the parent so that it can also instrument + them and they be inherited by the next child on fork, implies + `AFL_FRIDA_INST_NO_PREFETCH_BACKPATCH`. * `AFL_FRIDA_INST_NO_PREFETCH_BACKPATCH` - Disable prefetching of stalker -backpatching information. By default the child will report applied backpatches -to the parent so that they can be applied and then be inherited by the next -child on fork. + backpatching information. By default, the child will report applied + backpatches to the parent so that they can be applied and then be inherited by + the next child on fork. * `AFL_FRIDA_INST_RANGES` - See `AFL_QEMU_INST_RANGES` * `AFL_FRIDA_INST_SEED` - Sets the initial seed for the hash function used to -generate block (and hence edge) IDs. Setting this to a constant value may be -useful for debugging purposes, e.g. investigating unstable edges. -* `AFL_FRIDA_INST_TRACE` - Log to stdout the address of executed blocks, -implies `AFL_FRIDA_INST_NO_OPTIMIZE`. + generate block (and hence edge) IDs. Setting this to a constant value may be + useful for debugging purposes, e.g., investigating unstable edges. +* `AFL_FRIDA_INST_TRACE` - Log to stdout the address of executed blocks, implies + `AFL_FRIDA_INST_NO_OPTIMIZE`. * `AFL_FRIDA_INST_TRACE_UNIQUE` - As per `AFL_FRIDA_INST_TRACE`, but each edge -is logged only once, requires `AFL_FRIDA_INST_NO_OPTIMIZE`. + is logged only once, requires `AFL_FRIDA_INST_NO_OPTIMIZE`. * `AFL_FRIDA_INST_UNSTABLE_COVERAGE_FILE` - File to write DynamoRio format -coverage information for unstable edges (e.g. to be loaded within IDA -lighthouse). + coverage information for unstable edges (e.g., to be loaded within IDA + lighthouse). * `AFL_FRIDA_JS_SCRIPT` - Set the script to be loaded by the FRIDA scripting -engine. See [here](Scripting.md) for details. + engine. See [frida_mode/Scripting.md](../frida_mode/Scripting.md) for details. * `AFL_FRIDA_OUTPUT_STDOUT` - Redirect the standard output of the target -application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) + application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) * `AFL_FRIDA_OUTPUT_STDERR` - Redirect the standard error of the target -application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) + application to the named file (supersedes the setting of `AFL_DEBUG_CHILD`) * `AFL_FRIDA_PERSISTENT_ADDR` - See `AFL_QEMU_PERSISTENT_ADDR` * `AFL_FRIDA_PERSISTENT_CNT` - See `AFL_QEMU_PERSISTENT_CNT` * `AFL_FRIDA_PERSISTENT_DEBUG` - Insert a Breakpoint into the instrumented code -at `AFL_FRIDA_PERSISTENT_HOOK` and `AFL_FRIDA_PERSISTENT_RET` to allow the user -to detect issues in the persistent loop using a debugger. + at `AFL_FRIDA_PERSISTENT_HOOK` and `AFL_FRIDA_PERSISTENT_RET` to allow the + user to detect issues in the persistent loop using a debugger. * `AFL_FRIDA_PERSISTENT_HOOK` - See `AFL_QEMU_PERSISTENT_HOOK` * `AFL_FRIDA_PERSISTENT_RET` - See `AFL_QEMU_PERSISTENT_RET` * `AFL_FRIDA_SECCOMP_FILE` - Write a log of any syscalls made by the target to -the specified file. + the specified file. * `AFL_FRIDA_STALKER_ADJACENT_BLOCKS` - Configure the number of adjacent blocks - to fetch when generating instrumented code. By fetching blocks in the same - order they appear in the original program, rather than the order of execution - should help reduce locallity and adjacency. This includes allowing us to vector - between adjancent blocks using a NOP slide rather than an immediate branch. + to fetch when generating instrumented code. By fetching blocks in the same + order they appear in the original program, rather than the order of execution + should help reduce locallity and adjacency. This includes allowing us to + vector between adjancent blocks using a NOP slide rather than an immediate + branch. * `AFL_FRIDA_STALKER_IC_ENTRIES` - Configure the number of inline cache entries -stored along-side branch instructions which provide a cache to avoid having to -call back into FRIDA to find the next block. Default is 32. + stored along-side branch instructions which provide a cache to avoid having to + call back into FRIDA to find the next block. Default is 32. * `AFL_FRIDA_STATS_FILE` - Write statistics information about the code being -instrumented to the given file name. The statistics are written only for the -child process when new block is instrumented (when the -`AFL_FRIDA_STATS_INTERVAL` has expired). Note that simply because a new path is -found does not mean a new block needs to be compiled. It could simply be that -the existing blocks instrumented have been executed in a different order. + instrumented to the given file name. The statistics are written only for the + child process when new block is instrumented (when the + `AFL_FRIDA_STATS_INTERVAL` has expired). Note that just because a new path is + found does not mean a new block needs to be compiled. It could be that the + existing blocks instrumented have been executed in a different order. * `AFL_FRIDA_STATS_INTERVAL` - The maximum frequency to output statistics -information. Stats will be written whenever they are updated if the given -interval has elapsed since last time they were written. + information. Stats will be written whenever they are updated if the given + interval has elapsed since last time they were written. * `AFL_FRIDA_TRACEABLE` - Set the child process to be traceable by any process -to aid debugging and overcome the restrictions imposed by YAMA. Supported on -Linux only. Permits a non-root user to use `gcore` or similar to collect a core -dump of the instrumented target. Note that in order to capture the core dump you -must set a sufficient timeout (using `-t`) to avoid `afl-fuzz` killing the -process whilst it is being dumped. + to aid debugging and overcome the restrictions imposed by YAMA. Supported on + Linux only. Permits a non-root user to use `gcore` or similar to collect a + core dump of the instrumented target. Note that in order to capture the core + dump you must set a sufficient timeout (using `-t`) to avoid `afl-fuzz` + killing the process whilst it is being dumped. ## 8) Settings for afl-cmin |