diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | coresight_mode/README.md | 7 | ||||
| -rw-r--r-- | dictionaries/README.md | 2 | ||||
| -rw-r--r-- | docs/INSTALL.md | 6 | ||||
| -rw-r--r-- | docs/afl-fuzz_approach.md | 4 | ||||
| -rw-r--r-- | docs/custom_mutators.md | 3 | ||||
| -rw-r--r-- | docs/env_variables.md | 4 | ||||
| -rw-r--r-- | docs/fuzzing_in_depth.md | 8 | ||||
| -rw-r--r-- | testcases/README.md | 2 | ||||
| -rw-r--r-- | unicorn_mode/README.md | 10 | ||||
| -rw-r--r-- | utils/argv_fuzzing/README.md | 4 | ||||
| -rw-r--r-- | utils/libdislocator/README.md | 8 | ||||
| -rw-r--r-- | utils/libtokencap/README.md | 2 |
13 files changed, 33 insertions, 29 deletions
diff --git a/README.md b/README.md index dbf49b20..93c0dd10 100644 --- a/README.md +++ b/README.md @@ -99,7 +99,7 @@ Step-by-step quick start: To add a dictionary, add `-x /path/to/dictionary.txt` to afl-fuzz. If the program takes input from a file, you can put `@@` in the program's - command line; AFL will put an auto-generated file name in there for you. + command line; AFL++ will put an auto-generated file name in there for you. 4. Investigate anything shown in red in the fuzzer UI by promptly consulting [docs/afl-fuzz_approach.md#understanding-the-status-screen](docs/afl-fuzz_approach.md#understanding-the-status-screen). diff --git a/coresight_mode/README.md b/coresight_mode/README.md index cd1bccab..1a39d347 100644 --- a/coresight_mode/README.md +++ b/coresight_mode/README.md @@ -3,7 +3,7 @@ CoreSight mode enables binary-only fuzzing on ARM64 Linux using CoreSight (ARM's hardware tracing technology). NOTE: CoreSight mode is in the early development stage. Not applicable for production use. -Currently the following hardware boards are supported: +Currently the following hardware boards are supported: * NVIDIA Jetson TX2 (NVIDIA Parker) * NVIDIA Jetson Nano (NVIDIA Tegra X1) * GIGABYTE R181-T90 (Marvell ThunderX2 CN99XX) @@ -12,7 +12,10 @@ Currently the following hardware boards are supported: Please read the [RICSec/coresight-trace README](https://github.com/RICSecLab/coresight-trace/blob/master/README.md) and check the prerequisites (capstone) before getting started. -CoreSight mode supports the AFL fork server mode to reduce `exec` system call overhead. To support it for binary-only fuzzing, it needs to modify the target ELF binary to re-link to the patched glibc. We employ this design from [PTrix](https://github.com/junxzm1990/afl-pt). +CoreSight mode supports the AFL++ fork server mode to reduce `exec` system call +overhead. To support it for binary-only fuzzing, it needs to modify the target +ELF binary to re-link to the patched glibc. We employ this design from +[PTrix](https://github.com/junxzm1990/afl-pt). Check out all the git submodules in the `cs_mode` directory: diff --git a/dictionaries/README.md b/dictionaries/README.md index 7c587abb..2c0056f6 100644 --- a/dictionaries/README.md +++ b/dictionaries/README.md @@ -1,4 +1,4 @@ -# AFL dictionaries +# AFL++ dictionaries (See [../README.md](../README.md) for the general instruction manual.) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index cfa20dea..ab6e735b 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -20,7 +20,7 @@ The easiest choice is to build and install everything: sudo apt-get update sudo apt-get install -y build-essential python3-dev automake git flex bison libglib2.0-dev libpixman-1-dev python3-setuptools # try to install llvm 11 and install the distro default if that fails -sudo apt-get install -y lld-11 llvm-11 llvm-11-dev clang-11 || sudo apt-get install -y lld llvm llvm-dev clang +sudo apt-get install -y lld-11 llvm-11 llvm-11-dev clang-11 || sudo apt-get install -y lld llvm llvm-dev clang sudo apt-get install -y gcc-$(gcc --version|head -n1|sed 's/.* //'|sed 's/\..*//')-plugin-dev libstdc++-$(gcc --version|head -n1|sed 's/.* //'|sed 's/\..*//')-dev sudo apt-get install -y ninja-build # for qemu_mode git clone https://github.com/AFLplusplus/AFLplusplus @@ -114,8 +114,8 @@ This means two things: - Fuzzing will be probably slower than on Linux. In fact, some folks report considerable performance gains by running the jobs inside a Linux VM on MacOS X. - - Some non-portable, platform-specific code may be incompatible with the - AFL forkserver. If you run into any problems, set `AFL_NO_FORKSRV=1` in the + - Some non-portable, platform-specific code may be incompatible with the AFL++ + forkserver. If you run into any problems, set `AFL_NO_FORKSRV=1` in the environment before starting afl-fuzz. User emulation mode of QEMU does not appear to be supported on MacOS X, so black-box instrumentation mode (`-Q`) will not work. diff --git a/docs/afl-fuzz_approach.md b/docs/afl-fuzz_approach.md index 4e8e5eaa..3e4faaec 100644 --- a/docs/afl-fuzz_approach.md +++ b/docs/afl-fuzz_approach.md @@ -348,7 +348,7 @@ That last bit is actually fairly interesting: it measures the consistency of observed traces. If a program always behaves the same for the same input data, it will earn a score of 100%. When the value is lower but still shown in purple, the fuzzing process is unlikely to be negatively affected. If it goes into red, -you may be in trouble, since AFL will have difficulty discerning between +you may be in trouble, since AFL++ will have difficulty discerning between meaningful and "phantom" effects of tweaking the input file. Now, most targets will just get a 100% score, but when you see lower figures, @@ -506,7 +506,7 @@ directory. This includes: - `edges_found` - how many edges have been found - `var_byte_count` - how many edges are non-deterministic - `afl_banner` - banner text (e.g. the target name) -- `afl_version` - the version of AFL used +- `afl_version` - the version of AFL++ used - `target_mode` - default, persistent, qemu, unicorn, non-instrumented - `command_line` - full command line used for the fuzzing session diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md index 2caba560..3a2ec3b2 100644 --- a/docs/custom_mutators.md +++ b/docs/custom_mutators.md @@ -21,7 +21,8 @@ fuzzing by using libraries that perform mutations according to a given grammar. The custom mutator is passed to `afl-fuzz` via the `AFL_CUSTOM_MUTATOR_LIBRARY` or `AFL_PYTHON_MODULE` environment variable, and must export a fuzz function. -Now AFL also supports multiple custom mutators which can be specified in the same `AFL_CUSTOM_MUTATOR_LIBRARY` environment variable like this. +Now AFL++ also supports multiple custom mutators which can be specified in the +same `AFL_CUSTOM_MUTATOR_LIBRARY` environment variable like this. ```bash export AFL_CUSTOM_MUTATOR_LIBRARY="full/path/to/mutator_first.so;full/path/to/mutator_second.so" ``` diff --git a/docs/env_variables.md b/docs/env_variables.md index 6c90e84c..715a60cb 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -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 @@ -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). diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index 8188a18e..4d2884f6 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -106,9 +106,9 @@ You can select the mode for the afl-cc compiler by: MODE can be one of: LTO (afl-clang-lto*), LLVM (afl-clang-fast*), GCC_PLUGIN (afl-g*-fast) or GCC (afl-gcc/afl-g++) or CLANG(afl-clang/afl-clang++). -Because no AFL specific command-line options are accepted (beside the --afl-MODE -command), the compile-time tools make fairly broad use of environment variables, -which can be listed with `afl-cc -hh` or by reading +Because no AFL++ specific command-line options are accepted (beside the +--afl-MODE command), the compile-time tools make fairly broad use of environment +variables, which can be listed with `afl-cc -hh` or by reading [env_variables.md](env_variables.md). ### b) Selecting instrumentation options @@ -213,7 +213,7 @@ is more effective). If the target has features that make fuzzing more difficult, e.g. checksums, HMAC, etc. then modify the source code so that checks for these values are removed. This can even be done safely for source code used in operational -products by eliminating these checks within these AFL specific blocks: +products by eliminating these checks within these AFL++ specific blocks: ``` #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION diff --git a/testcases/README.md b/testcases/README.md index ef38d3c4..a2f74d68 100644 --- a/testcases/README.md +++ b/testcases/README.md @@ -1,4 +1,4 @@ -# AFL starting test cases +# AFL++ starting test cases (See [../README.md](../README.md) for the general instruction manual.) diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index ed85e687..4c95e8f3 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -8,7 +8,8 @@ The CompareCoverage and NeverZero counters features are by Andrea Fioraldi <andr ## 1) Introduction -The code in ./unicorn_mode allows you to build the (Unicorn Engine)[https://github.com/unicorn-engine/unicorn] with AFL support. +The code in ./unicorn_mode allows you to build the +(Unicorn Engine)[https://github.com/unicorn-engine/unicorn] with AFL++ support. This means, you can run anything that can be emulated in unicorn and obtain instrumentation output for black-box, closed-source binary code snippets. This mechanism can be then used by afl-fuzz to stress-test targets that couldn't be built @@ -46,7 +47,7 @@ To use unicorn-mode effectively you need to prepare the following: * Relevant binary code to be fuzzed * Knowledge of the memory map and good starting state * Folder containing sample inputs to start fuzzing with - + Same ideas as any other AFL inputs + + Same ideas as any other AFL++ inputs + Quality/speed of results will depend greatly on the quality of starting samples + See AFL's guidance on how to create a sample corpus @@ -55,13 +56,12 @@ To use unicorn-mode effectively you need to prepare the following: + Loads binary code into memory + Calls uc.afl_fuzz() / uc.afl_start_forkserver + Loads and verifies data to fuzz from a command-line specified file - + AFL will provide mutated inputs by changing the file passed to + + AFL++ will provide mutated inputs by changing the file passed to the test harness + Presumably the data to be fuzzed is at a fixed buffer address + If input constraints (size, invalid bytes, etc.) are known they should be checked in the place_input handler. If a constraint - fails, just return false from the handler. AFL will treat the input as - 'uninteresting' and move on. + fails, just return false from the handler. AFL++ will treat the input as 'uninteresting' and move on. + Sets up registers and memory state for beginning of test + Emulates the interesting code from beginning to end + If a crash is detected, the test harness must 'crash' by diff --git a/utils/argv_fuzzing/README.md b/utils/argv_fuzzing/README.md index 192d72f7..e9224995 100644 --- a/utils/argv_fuzzing/README.md +++ b/utils/argv_fuzzing/README.md @@ -1,6 +1,6 @@ # argvfuzz -AFL supports fuzzing file inputs or stdin. When source is available, +AFL++ supports fuzzing file inputs or stdin. When source is available, `argv-fuzz-inl.h` can be used to change `main()` to build argv from stdin. `argvfuzz` tries to provide the same functionality for binaries. When loaded @@ -13,4 +13,4 @@ A few conditions need to be fulfilled for this mechanism to work correctly: 2. If the target binary does not use the default libc's `_start` implementation (crt1.o), the hook may not run. 3. The hook will replace argv with pointers to `.data` of `argvfuzz.so`. If the - target binary expects argv to be living on the stack, things may go wrong. + target binary expects argv to be living on the stack, things may go wrong. \ No newline at end of file diff --git a/utils/libdislocator/README.md b/utils/libdislocator/README.md index d0340af0..64a5f14c 100644 --- a/utils/libdislocator/README.md +++ b/utils/libdislocator/README.md @@ -28,7 +28,7 @@ heap-related security bugs in several ways: - Optionally, in platforms supporting it, huge pages can be used by passing USEHUGEPAGE=1 to make. - + - Size alignment to `max_align_t` can be enforced with AFL_ALIGNED_ALLOC=1. In this case, a tail canary is inserted in the padding bytes at the end of the allocated zone. This reduce the ability of libdislocator to detect @@ -49,7 +49,7 @@ The allocator is slow and memory-intensive (even the tiniest allocation uses up for "production" uses; but it can be faster and more hassle-free than ASAN / MSAN when fuzzing small, self-contained binaries. -To use this library, run AFL like so: +To use this library, run AFL++ like so: ``` AFL_PRELOAD=/path/to/libdislocator.so ./afl-fuzz [...other params...] @@ -62,7 +62,7 @@ Similarly to afl-tmin, the library is not "proprietary" and can be used with other fuzzers or testing tools without the need for any code tweaks. It does not require AFL-instrumented binaries to work. -Note that the AFL_PRELOAD approach (which AFL internally maps to LD_PRELOAD or +Note that the AFL_PRELOAD approach (which AFL++ internally maps to LD_PRELOAD or DYLD_INSERT_LIBRARIES, depending on the OS) works only if the target binary is dynamically linked. Otherwise, attempting to use the library will have no -effect. +effect. \ No newline at end of file diff --git a/utils/libtokencap/README.md b/utils/libtokencap/README.md index 91ebebd1..343fcce0 100644 --- a/utils/libtokencap/README.md +++ b/utils/libtokencap/README.md @@ -43,7 +43,7 @@ when using afl-gcc. This setting specifically adds the following flags: The next step is to load this library via LD_PRELOAD. The optimal usage pattern is to allow afl-fuzz to fuzz normally for a while and build up a corpus, and then fire off the target binary, with libtokencap.so loaded, on every file found -by AFL in that earlier run. This demonstrates the basic principle: +by AFL++ in that earlier run. This demonstrates the basic principle: ``` export AFL_TOKEN_FILE=$PWD/temp_output.txt |