diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs/custom_mutators.md | 9 | ||||
| -rw-r--r-- | docs/env_variables.md | 2 | ||||
| -rw-r--r-- | docs/fuzzing_in_depth.md | 4 | ||||
| -rw-r--r-- | frida_mode/README.md | 4 | ||||
| -rw-r--r-- | instrumentation/README.laf-intel.md | 6 | ||||
| -rw-r--r-- | instrumentation/README.llvm.md | 8 | ||||
| -rw-r--r-- | unicorn_mode/README.md | 38 | ||||
| -rw-r--r-- | utils/optimin/README.md | 8 |
9 files changed, 41 insertions, 40 deletions
diff --git a/README.md b/README.md index e74c91e5..dbf49b20 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ terms of the Apache-2.0 License. See the [LICENSE](LICENSE) for details. Here is some information to get you started: -* For releases, please see the +* For releases, see the [Releases tab](https://github.com/AFLplusplus/AFLplusplus/releases) and [branches](#branches). Also take a look at the list of [important changes in AFL++](docs/important_changes.md). diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md index b1dfd309..2caba560 100644 --- a/docs/custom_mutators.md +++ b/docs/custom_mutators.md @@ -5,7 +5,7 @@ For now, we support C/C++ library and Python module, collectivelly named as the custom mutator. There is also experimental support for Rust in `custom_mutators/rust`. -Please refer to that directory for documentation. +For documentation, refer to that directory. Run ```cargo doc -p custom_mutator --open``` in that directory to view the documentation in your web browser. @@ -25,7 +25,8 @@ Now AFL also supports multiple custom mutators which can be specified in the sam ```bash export AFL_CUSTOM_MUTATOR_LIBRARY="full/path/to/mutator_first.so;full/path/to/mutator_second.so" ``` -Please see [APIs](#2-apis) and [Usage](#3-usage) for detail. + +For details, see [APIs](#2-apis) and [Usage](#3-usage). The custom mutation stage is set to be the first non-deterministic stage (right before the havoc stage). @@ -288,8 +289,8 @@ afl-fuzz /path/to/program ## 4) Example -Please see [example.c](../custom_mutators/examples/example.c) and -[example.py](../custom_mutators/examples/example.py) +See [example.c](../custom_mutators/examples/example.c) and +[example.py](../custom_mutators/examples/example.py). ## 5) Other Resources diff --git a/docs/env_variables.md b/docs/env_variables.md index 6f6110ae..bb7ea70b 100644 --- a/docs/env_variables.md +++ b/docs/env_variables.md @@ -320,7 +320,7 @@ checks or alter some of the more exotic semantics of the tool: 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 + 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 diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index 7aabe090..c94590a4 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -1,7 +1,7 @@ # Fuzzing with AFL++ The following describes how to fuzz with a target if source code is available. -If you have a binary-only target, please go to +If you have a binary-only target, go to [fuzzing_binary-only_targets.md](fuzzing_binary-only_targets.md). Fuzzing source code is a three-step process: @@ -431,7 +431,7 @@ Run it like `screen -dmS afl-main -- afl-fuzz -M main-$HOSTNAME -i ...` and it will start away in a screen session. To enter this session, type `screen -r afl-main`. You see - it makes sense to name the screen session same as the afl-fuzz -M/-S naming :-) -For more information on screen or tmux please check their documentation. +For more information on screen or tmux, check their documentation. If you need to stop and re-start the fuzzing, use the same command line options (or even change them by selecting a different power schedule or another mutation diff --git a/frida_mode/README.md b/frida_mode/README.md index c2b98473..58519699 100644 --- a/frida_mode/README.md +++ b/frida_mode/README.md @@ -367,8 +367,8 @@ using `AFL_FRIDA_INST_RANGES` or similar. ## Debugging -Please refer to [DEBUGGING.md](DEBUGGING.md) for assistance should you encounter -problems with FRIDA mode. +Should you encounter problems with FRIDA mode, refer to +[DEBUGGING.md](DEBUGGING.md) for assistance. ## To do diff --git a/instrumentation/README.laf-intel.md b/instrumentation/README.laf-intel.md index 3cde10c3..06e653ea 100644 --- a/instrumentation/README.laf-intel.md +++ b/instrumentation/README.laf-intel.md @@ -42,9 +42,9 @@ comparisons. A new experimental feature is splitting floating point comparisons into a series of sign, exponent and mantissa comparisons followed by splitting each of them into 8 bit comparisons when necessary. It is activated with the -`AFL_LLVM_LAF_SPLIT_FLOATS` setting. Please note that full IEEE 754 -functionality is not preserved, that is values of nan and infinity will probably -behave differently. +`AFL_LLVM_LAF_SPLIT_FLOATS` setting. Note that full IEEE 754 functionality is +not preserved, that is values of nan and infinity will probably behave +differently. Note that setting this automatically activates `AFL_LLVM_LAF_SPLIT_COMPARES`. diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md index 35f38261..8133cbe4 100644 --- a/instrumentation/README.llvm.md +++ b/instrumentation/README.llvm.md @@ -119,8 +119,8 @@ If you need just to instrument specific parts of the code, you can the instrument file list which C/C++ files to actually instrument. See [README.instrument_list.md](README.instrument_list.md) -For splitting memcmp, strncmp, etc. please see -[README.laf-intel.md](README.laf-intel.md) +For splitting memcmp, strncmp, etc., see +[README.laf-intel.md](README.laf-intel.md). Then there are different ways of instrumenting the target: @@ -157,8 +157,8 @@ nozero counter default for performance reasons. ## 4) deferred initialization, persistent mode, shared memory fuzzing -This is the most powerful and effective fuzzing you can do. Please see -[README.persistent_mode.md](README.persistent_mode.md) for a full explanation. +This is the most powerful and effective fuzzing you can do. For a full +explanation, see [README.persistent_mode.md](README.persistent_mode.md). ## 5) Bonus feature: 'dict2file' pass diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index d2b7d16f..ed85e687 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -10,8 +10,8 @@ The CompareCoverage and NeverZero counters features are by Andrea Fioraldi <andr 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 +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 with afl-cc or used in QEMU mode. There is a significant performance penalty compared to native AFL, @@ -25,7 +25,7 @@ For some pointers for more advanced emulation, take a look at [BaseSAFE](https:/ ### Building AFL++'s Unicorn Mode First, make AFL++ as usual. -Once that completes successfully you need to build and add in the Unicorn Mode +Once that completes successfully you need to build and add in the Unicorn Mode features: ``` @@ -33,10 +33,10 @@ cd unicorn_mode ./build_unicorn_support.sh ``` -NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested -and is stable-ish, based on the unicorn engine `next` branch. +NOTE: This script checks out a Unicorn Engine fork as submodule that has been tested +and is stable-ish, based on the unicorn engine `next` branch. -Building Unicorn will take a little bit (~5-10 minutes). Once it completes +Building Unicorn will take a little bit (~5-10 minutes). Once it completes it automatically compiles a sample application and verifies that it works. ### Fuzzing with Unicorn Mode @@ -47,24 +47,24 @@ To use unicorn-mode effectively you need to prepare the following: * Knowledge of the memory map and good starting state * Folder containing sample inputs to start fuzzing with + Same ideas as any other AFL inputs - + Quality/speed of results will depend greatly on the quality of starting + + Quality/speed of results will depend greatly on the quality of starting samples + See AFL's guidance on how to create a sample corpus * Unicornafl-based test harness in Rust, C, or Python, which: + Adds memory map regions - + Loads binary code into memory + + 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 + + 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. + 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 + + If a crash is detected, the test harness must 'crash' by throwing a signal (SIGSEGV, SIGKILL, SIGABORT, etc.), or indicate a crash in the crash validation callback. Once you have all those things ready to go you just need to run afl-fuzz in @@ -77,14 +77,14 @@ afl-fuzz -U -m none -i /path/to/inputs -o /path/to/results -- ./test_harness @@ The normal afl-fuzz command line format applies to everything here. Refer to AFL's main documentation for more info about how to use afl-fuzz effectively. -For a much clearer vision of what all of this looks like, please refer to the -sample provided in the 'unicorn_mode/samples' directory. There is also a blog -post that uses slightly older concepts, but describes the general ideas, at: +For a much clearer vision of what all of this looks like, refer to the sample +provided in the 'unicorn_mode/samples' directory. There is also a blog post that +uses slightly older concepts, but describes the general ideas, at: [https://medium.com/@njvoss299/afl-unicorn-fuzzing-arbitrary-binary-code-563ca28936bf](https://medium.com/@njvoss299/afl-unicorn-fuzzing-arbitrary-binary-code-563ca28936bf) -The ['helper_scripts'](./helper_scripts) directory also contains several helper scripts that allow you +The ['helper_scripts'](./helper_scripts) directory also contains several helper scripts that allow you to dump context from a running process, load it, and hook heap allocations. For details on how to use this check out the follow-up blog post to the one linked above. @@ -105,8 +105,8 @@ Comparison instructions are currently instrumented only for the x86, x86_64 and ## 4) Gotchas, feedback, bugs -Running the build script builds Unicornafl and its python bindings and installs -them on your system. +Running the build script builds Unicornafl and its python bindings and installs +them on your system. This installation will leave any existing Unicorn installations untouched. If you want to use unicornafl instead of unicorn in a script, replace all `unicorn` imports with `unicornafl` inputs, everything else should "just work". diff --git a/utils/optimin/README.md b/utils/optimin/README.md index c6f2af06..507cb305 100644 --- a/utils/optimin/README.md +++ b/utils/optimin/README.md @@ -73,9 +73,9 @@ and `WEIGHT_N` is an integer weight. ## Further Details and Citation -For more details, please see the paper [Seed Selection for Successful -Fuzzing](https://dl.acm.org/doi/10.1145/3460319.3464795). If you use OptiMin in -your research, please cite this paper. +For more details, see the paper +[Seed Selection for Successful Fuzzing](https://dl.acm.org/doi/10.1145/3460319.3464795). +If you use OptiMin in your research, please cite this paper. Bibtex: @@ -91,4 +91,4 @@ Bibtex: location = {Virtual, Denmark}, publisher = {Association for Computing Machinery}, } -``` +``` \ No newline at end of file |