From a7694e299a331bd8c4826b2402ee68cd6f83d8f9 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Thu, 2 Dec 2021 20:45:48 +0100 Subject: Fix punctuation in connection with "however" --- utils/afl_untracer/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'utils/afl_untracer') diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md index ada0c916..9f41618f 100644 --- a/utils/afl_untracer/README.md +++ b/utils/afl_untracer/README.md @@ -5,9 +5,9 @@ afl-untracer is an example skeleton file which can easily be used to fuzz a closed source library. -It requires less memory and is x3-5 faster than qemu_mode however it is way -more course grained and does not provide interesting features like compcov -or cmplog. +It requires less memory and is x3-5 faster than qemu_mode, however, it is way +more course grained and does not provide interesting features like compcov or +cmplog. Supported is so far Intel (i386/x86_64) and AARCH64. -- cgit 1.4.1 From 6eab6a55af74754cd0229012f1c9543c0c3cb2a7 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Sat, 4 Dec 2021 21:14:50 +0100 Subject: Fix spelling of "FRIDA mode" and "QEMU mode" --- TODO.md | 2 +- docs/INSTALL.md | 4 ++-- docs/features.md | 8 ++++---- docs/fuzzing_binary-only_targets.md | 35 ++++++++++++++++++----------------- docs/important_changes.md | 8 ++++---- instrumentation/README.llvm.md | 2 +- qemu_mode/libqasan/README.md | 2 +- utils/README.md | 2 +- utils/afl_untracer/README.md | 2 +- utils/aflpp_driver/README.md | 4 ++-- utils/qbdi_mode/README.md | 2 +- 11 files changed, 36 insertions(+), 35 deletions(-) (limited to 'utils/afl_untracer') diff --git a/TODO.md b/TODO.md index 04f3abab..e6b095fc 100644 --- a/TODO.md +++ b/TODO.md @@ -16,7 +16,7 @@ ## Further down the road -qemu_mode/frida_mode: +QEMU mode/FRIDA mode: - non colliding instrumentation - rename qemu specific envs to AFL_QEMU (AFL_ENTRYPOINT, AFL_CODE_START/END, AFL_COMPCOV_LEVEL?) diff --git a/docs/INSTALL.md b/docs/INSTALL.md index 08d3283e..9d1309fe 100644 --- a/docs/INSTALL.md +++ b/docs/INSTALL.md @@ -23,7 +23,7 @@ sudo apt-get install -y build-essential python3-dev automake git flex bison libg # 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 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 +sudo apt-get install -y ninja-build # for QEMU mode git clone https://github.com/AFLplusplus/AFLplusplus cd AFLplusplus make distrib @@ -33,7 +33,7 @@ sudo make install It is recommended to install the newest available gcc, clang and llvm-dev possible in your distribution! -Note that "make distrib" also builds instrumentation, qemu_mode, unicorn_mode +Note that "make distrib" also builds instrumentation, QEMU mode, unicorn_mode and more. If you just want plain AFL++, then do "make all". However, compiling and using at least instrumentation is highly recommended for much better results - hence in this case choose: diff --git a/docs/features.md b/docs/features.md index fb688a64..06b1bcbe 100644 --- a/docs/features.md +++ b/docs/features.md @@ -4,7 +4,7 @@ AFL++ supports llvm from 3.8 up to version 12, very fast binary fuzzing with QEMU 5.1 with laf-intel and redqueen, frida mode, unicorn mode, gcc plugin, full *BSD, Mac OS, Solaris and Android support and much, much, much more. -| Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | frida_mode(9) | qemu_mode(10) |unicorn_mode(10) |coresight_mode(11)| +| Feature/Instrumentation | afl-gcc | llvm | gcc_plugin | FRIDA mode(9) | QEMU mode(10) |unicorn_mode(10) |coresight_mode(11)| | -------------------------|:-------:|:---------:|:----------:|:----------------:|:----------------:|:----------------:|:----------------:| | Threadsafe counters | | x(3) | | | | | | | NeverZero | x86[_64]| x(1) | x | x | x | x | | @@ -37,9 +37,9 @@ QEMU 5.1 with laf-intel and redqueen, frida mode, unicorn mode, gcc plugin, full Among others, the following features and patches have been integrated: -* NeverZero patch for afl-gcc, instrumentation, qemu_mode and unicorn_mode which +* NeverZero patch for afl-gcc, instrumentation, QEMU mode and unicorn_mode which prevents a wrapping map value to zero, increases coverage -* Persistent mode, deferred forkserver and in-memory fuzzing for qemu_mode +* Persistent mode, deferred forkserver and in-memory fuzzing for QEMU mode * Unicorn mode which allows fuzzing of binaries from completely different platforms (integration provided by domenukk) * The new CmpLog instrumentation for LLVM and QEMU inspired by @@ -51,7 +51,7 @@ Among others, the following features and patches have been integrated: [https://github.com/puppet-meteor/MOpt-AFL](https://github.com/puppet-meteor/MOpt-AFL) * LLVM mode Ngram coverage by Adrian Herrera [https://github.com/adrianherrera/afl-ngram-pass](https://github.com/adrianherrera/afl-ngram-pass) -* LAF-Intel/CompCov support for instrumentation, qemu_mode and unicorn_mode +* LAF-Intel/CompCov support for instrumentation, QEMU mode and unicorn_mode (with enhanced capabilities) * Radamsa and honggfuzz mutators (as custom mutators). * QBDI mode to fuzz android native libraries via Quarkslab's diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md index b3d9ca02..15155111 100644 --- a/docs/fuzzing_binary-only_targets.md +++ b/docs/fuzzing_binary-only_targets.md @@ -12,18 +12,18 @@ fuzzed with AFL++. ## TL;DR: -Qemu_mode in persistent mode is the fastest - if the stability is high enough. +QEMU mode in persistent mode is the fastest - if the stability is high enough. Otherwise, try RetroWrite, Dyninst, and if these fail, too, then try standard -qemu_mode with AFL_ENTRYPOINT to where you need it. +QEMU mode with `AFL_ENTRYPOINT` to where you need it. -If your target is a library, then use frida_mode. +If your target is a library, then use FRIDA mode. If your target is non-linux, then use unicorn_mode. ## Fuzzing binary-only targets with AFL++ -### Qemu_mode +### QEMU mode -Qemu_mode is the "native" solution to the program. It is available in the +QEMU mode is the "native" solution to the program. It is available in the ./qemu_mode/ directory and, once compiled, it can be accessed by the afl-fuzz -Q command line option. It is the easiest to use alternative and even works for cross-platform binaries. @@ -37,11 +37,12 @@ cd qemu_mode ./build_qemu_support.sh ``` -The following setup to use qemu_mode is recommended: +The following setup to use QEMU mode is recommended: + * run 1 afl-fuzz -Q instance with CMPLOG (`-c 0` + `AFL_COMPCOV_LEVEL=2`) * run 1 afl-fuzz -Q instance with QASAN (`AFL_USE_QASAN=1`) * run 1 afl-fuzz -Q instance with LAF (`AFL_PRELOAD=libcmpcov.so` + - `AFL_COMPCOV_LEVEL=2`), alternatively you can use frida_mode, just switch `-Q` + `AFL_COMPCOV_LEVEL=2`), alternatively you can use FRIDA mode, just switch `-Q` with `-O` and remove the LAF instance Then run as many instances as you have cores left with either -Q mode or - even @@ -49,16 +50,16 @@ better - use a binary rewriter like Dyninst, RetroWrite, ZAFL, etc. If [afl-dyninst](https://github.com/vanhauser-thc/afl-dyninst) works for your binary, then you can use afl-fuzz normally and it will have twice the speed -compared to qemu_mode (but slower than qemu persistent mode). Note that several +compared to QEMU mode (but slower than QEMU persistent mode). Note that several other binary rewriters exist, all with their advantages and caveats. -The speed decrease of qemu_mode is at about 50%. However, various options exist +The speed decrease of QEMU mode is at about 50%. However, various options exist to increase the speed: - using AFL_ENTRYPOINT to move the forkserver entry to a later basic block in the binary (+5-10% speed) - using persistent mode [qemu_mode/README.persistent.md](../qemu_mode/README.persistent.md) this will - result in a 150-300% overall speed increase - so 3-8x the original qemu_mode + result in a 150-300% overall speed increase - so 3-8x the original QEMU mode speed! - using AFL_CODE_START/AFL_CODE_END to only instrument specific parts @@ -71,7 +72,7 @@ conducive to parallelization. Note that there is also honggfuzz: [https://github.com/google/honggfuzz](https://github.com/google/honggfuzz) which -now has a qemu_mode, but its performance is just 1.5% ... +now has a QEMU mode, but its performance is just 1.5% ... If you like to code a customized fuzzer without much work, we highly recommend to check out our sister project libafl which supports QEMU, too: @@ -87,14 +88,14 @@ It is included in AFL++. For more information, see [qemu_mode/README.wine.md](../qemu_mode/README.wine.md). -### Frida_mode +### FRIDA mode -In frida_mode, you can fuzz binary-only targets as easily as with QEMU. -Frida_mode is sometimes faster and sometimes slower than Qemu_mode. It is also +In FRIDA mode, you can fuzz binary-only targets as easily as with QEMU mode. +FRIDA mode is sometimes faster and sometimes slower than QEMU mode. It is also newer, lacks COMPCOV, and has the advantage that it works on MacOS (both intel and M1). -To build frida_mode: +To build FRIDA mode: ```shell cd frida_mode @@ -149,11 +150,11 @@ For further information, check out If the goal is to fuzz a dynamic library, then there are two options available. For both, you need to write a small harness that loads and calls the library. -Then you fuzz this with either frida_mode or qemu_mode and either use +Then you fuzz this with either FRIDA mode or QEMU mode and either use `AFL_INST_LIBS=1` or `AFL_QEMU/FRIDA_INST_RANGES`. Another, less precise and slower option is to fuzz it with utils/afl_untracer/ -and use afl-untracer.c as a template. It is slower than frida_mode. +and use afl-untracer.c as a template. It is slower than FRIDA mode. For more information, see [utils/afl_untracer/README.md](../utils/afl_untracer/README.md). diff --git a/docs/important_changes.md b/docs/important_changes.md index 203c5a66..d5e67f75 100644 --- a/docs/important_changes.md +++ b/docs/important_changes.md @@ -5,8 +5,8 @@ changes. ## From version 3.00 onwards -With AFL++ 3.13-3.20, we introduce frida_mode (-O) to have an alternative for -binary-only fuzzing. It is slower than Qemu mode but works on MacOS, Android, +With AFL++ 3.13-3.20, we introduce FRIDA mode (`-O`) to have an alternative for +binary-only fuzzing. It is slower than QEMU mode but works on MacOS, Android, iOS etc. With AFL++ 3.15, we introduced the following changes from previous behaviors: @@ -31,8 +31,8 @@ behaviors and defaults: All instrumentation source code is now in the `instrumentation/` folder. * The gcc_plugin was replaced with a new version submitted by AdaCore that supports more features. Thank you! - * qemu_mode got upgraded to QEMU 5.1, but to be able to build this a current - ninja build tool version and python3 setuptools are required. qemu_mode also + * QEMU mode got upgraded to QEMU 5.1, but to be able to build this a current + ninja build tool version and python3 setuptools are required. QEMU mode also got new options like snapshotting, instrumenting specific shared libraries, etc. Additionally QEMU 5.1 supports more CPU targets so this is really worth it. diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md index c93cd312..fa025643 100644 --- a/instrumentation/README.llvm.md +++ b/instrumentation/README.llvm.md @@ -218,7 +218,7 @@ by Jinghan Wang, et. al. Note that the original implementation (available [here](https://github.com/bitsecurerlab/afl-sensitive)) is built on top of AFL's -qemu_mode. This is essentially a port that uses LLVM vectorized instructions +QEMU mode. This is essentially a port that uses LLVM vectorized instructions (available from llvm versions 4.0.1 and higher) to achieve the same results when compiling source code. diff --git a/qemu_mode/libqasan/README.md b/qemu_mode/libqasan/README.md index 6a65c12b..41195933 100644 --- a/qemu_mode/libqasan/README.md +++ b/qemu_mode/libqasan/README.md @@ -9,7 +9,7 @@ and this runtime is injected via LD_PRELOAD (so works just for dynamically linked binaries). The usage is super simple, just set the env var `AFL_USE_QASAN=1` when fuzzing -in qemu mode (-Q). afl-fuzz will automatically set AFL_PRELOAD to load this +in QEMU mode (-Q). afl-fuzz will automatically set AFL_PRELOAD to load this library and enable the QASan instrumentation in afl-qemu-trace. For debugging purposes, we still suggest to run the original QASan as the diff --git a/utils/README.md b/utils/README.md index b7eead8e..5f5745b9 100644 --- a/utils/README.md +++ b/utils/README.md @@ -16,7 +16,7 @@ Here's a quick overview of the stuff you can find in this directory: different means, e.g., hw debugger - afl_untracer - fuzz binary-only libraries much faster but with - less coverage than qemu_mode + less coverage than QEMU mode - analysis_scripts - random -o out analysis scripts diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md index 9f41618f..3fff5f83 100644 --- a/utils/afl_untracer/README.md +++ b/utils/afl_untracer/README.md @@ -5,7 +5,7 @@ afl-untracer is an example skeleton file which can easily be used to fuzz a closed source library. -It requires less memory and is x3-5 faster than qemu_mode, however, it is way +It requires less memory and is x3-5 faster than QEMU mode, however, it is way more course grained and does not provide interesting features like compcov or cmplog. diff --git a/utils/aflpp_driver/README.md b/utils/aflpp_driver/README.md index d534cd7f..8b9fe15f 100644 --- a/utils/aflpp_driver/README.md +++ b/utils/aflpp_driver/README.md @@ -22,10 +22,10 @@ or `@@` as command line parameters. ## aflpp_qemu_driver -Note that you can use the driver too for frida_mode (`-O`). +Note that you can use the driver too for FRIDA mode (`-O`). aflpp_qemu_driver is used for libfuzzer `LLVMFuzzerTestOneInput()` targets that -are to be fuzzed in qemu_mode. So compile them with clang/clang++, without +are to be fuzzed in QEMU mode. So compile them with clang/clang++, without -fsantize=fuzzer or afl-clang-fast, and link in libAFLQemuDriver.a: `clang++ -o fuzz fuzzer_harness.cc libAFLQemuDriver.a [plus required linking]`. diff --git a/utils/qbdi_mode/README.md b/utils/qbdi_mode/README.md index c8d46fca..02dd3c74 100755 --- a/utils/qbdi_mode/README.md +++ b/utils/qbdi_mode/README.md @@ -2,7 +2,7 @@ NOTE: this code is outdated and first would need to be adapted to the current AFL++ versions. -Try frida_mode or fpicker [https://github.com/ttdennis/fpicker/](https://github.com/ttdennis/fpicker/) first, maybe they suite your need. +Try FRIDA mode or fpicker [https://github.com/ttdennis/fpicker/](https://github.com/ttdennis/fpicker/) first, maybe they suite your need. ## 1) Introduction -- cgit 1.4.1 From 3506077fd6f250f3c080b58ea3bae117c3b122da Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Sat, 4 Dec 2021 22:28:05 +0100 Subject: Add missing blank lines and remove double blank lines --- custom_mutators/README.md | 1 + custom_mutators/gramatron/README.md | 1 + custom_mutators/libfuzzer/README.md | 4 +++- docs/custom_mutators.md | 8 +++++++- docs/fuzzing_binary-only_targets.md | 3 ++- docs/fuzzing_in_depth.md | 1 - frida_mode/README.md | 1 + unicorn_mode/README.md | 1 - unicorn_mode/samples/c/COMPILE.md | 1 + unicorn_mode/samples/speedtest/README.md | 13 ++++++++++--- utils/afl_untracer/README.md | 8 +++++++- utils/autodict_ql/readme.md | 17 ++++++++++------- utils/qbdi_mode/README.md | 8 ++++---- utils/qemu_persistent_hook/README.md | 2 +- 14 files changed, 48 insertions(+), 21 deletions(-) (limited to 'utils/afl_untracer') diff --git a/custom_mutators/README.md b/custom_mutators/README.md index fa877f34..0289e150 100644 --- a/custom_mutators/README.md +++ b/custom_mutators/README.md @@ -15,6 +15,7 @@ In `./rust`, you will find rust bindings, including a simple example in `./rust/ If you use git to clone AFL++, then the following will incorporate our excellent grammar custom mutator: + ```sh git submodule update --init ``` diff --git a/custom_mutators/gramatron/README.md b/custom_mutators/gramatron/README.md index 2ed014cd..5e10f97b 100644 --- a/custom_mutators/gramatron/README.md +++ b/custom_mutators/gramatron/README.md @@ -34,6 +34,7 @@ afl-fuzz -i in -o out -- ./target E.g., ./preprocess/prep_automaton.sh ~/grammars/ruby/source.json PROGRAM ``` + - If the grammar has no self-embedding rules then you do not need to pass the stack limit parameter. However, if it does have self-embedding rules then you need to pass the stack limit parameter. We recommend starting with `5` and diff --git a/custom_mutators/libfuzzer/README.md b/custom_mutators/libfuzzer/README.md index fb3025f2..cb4773b7 100644 --- a/custom_mutators/libfuzzer/README.md +++ b/custom_mutators/libfuzzer/README.md @@ -11,9 +11,11 @@ Note that this is currently a simple implementation and it is missing two featur * Dictionary support To update the source, all that is needed is that FuzzerDriver.cpp has to receive + ``` #include "libfuzzer.inc" ``` + before the closing namespace bracket. It is also libfuzzer.inc where the configuration of the libfuzzer mutations @@ -21,4 +23,4 @@ are done. > Original repository: https://github.com/llvm/llvm-project > Path: compiler-rt/lib/fuzzer/*.{h|cpp} -> Source commit: df3e903655e2499968fc7af64fb5fa52b2ee79bb +> Source commit: df3e903655e2499968fc7af64fb5fa52b2ee79bb \ No newline at end of file diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md index 0e94ab10..2f632e1f 100644 --- a/docs/custom_mutators.md +++ b/docs/custom_mutators.md @@ -23,6 +23,7 @@ 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. + ```bash export AFL_CUSTOM_MUTATOR_LIBRARY="full/path/to/mutator_first.so;full/path/to/mutator_second.so" ``` @@ -38,6 +39,7 @@ performed with the custom mutator. ## 2) APIs C/C++: + ```c void *afl_custom_init(afl_state_t *afl, unsigned int seed); unsigned int afl_custom_fuzz_count(void *data, const unsigned char *buf, size_t buf_size); @@ -56,6 +58,7 @@ void afl_custom_deinit(void *data); ``` Python: + ```python def init(seed): pass @@ -233,7 +236,6 @@ Optionally, the following environment variables are supported: combined with a custom trimming routine (see below) because trimming can cause the same test breakage like havoc and splice. - - `AFL_PYTHON_ONLY` Deprecated and removed, use `AFL_CUSTOM_MUTATOR_ONLY` instead. @@ -268,9 +270,11 @@ In case your setup is different, set the necessary variables like this: ### Custom Mutator Preparation For C/C++ mutators, the source code must be compiled as a shared object: + ```bash gcc -shared -Wall -O3 example.c -o example.so ``` + Note that if you specify multiple custom mutators, the corresponding functions will be called in the order in which they are specified. e.g. first `post_process` function of `example_first.so` will be called and then that of @@ -279,12 +283,14 @@ will be called in the order in which they are specified. e.g. first ### Run C/C++ + ```bash export AFL_CUSTOM_MUTATOR_LIBRARY="/full/path/to/example_first.so;/full/path/to/example_second.so" afl-fuzz /path/to/program ``` Python + ```bash export PYTHONPATH=`dirname /full/path/to/example.py` export AFL_PYTHON_MODULE=example diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md index 15155111..eaed3a91 100644 --- a/docs/fuzzing_binary-only_targets.md +++ b/docs/fuzzing_binary-only_targets.md @@ -21,6 +21,7 @@ If your target is a library, then use FRIDA mode. If your target is non-linux, then use unicorn_mode. ## Fuzzing binary-only targets with AFL++ + ### QEMU mode QEMU mode is the "native" solution to the program. It is available in the @@ -175,6 +176,7 @@ An alternative solution are binary rewriters. They are faster then the solutions native to AFL++ but don't always work. ### ZAFL + ZAFL is a static rewriting platform supporting x86-64 C/C++, stripped/unstripped, and PIE/non-PIE binaries. Beyond conventional instrumentation, ZAFL's API enables transformation passes (e.g., laf-Intel, @@ -277,7 +279,6 @@ There are many binary-only fuzzing frameworks. Some are great for CTFs but don't work with large binaries, others are very slow but have good path discovery, some are very hard to set-up... - * Jackalope: [https://github.com/googleprojectzero/Jackalope](https://github.com/googleprojectzero/Jackalope) * Manticore: diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index 2e030e7b..4a1ddf45 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -808,7 +808,6 @@ then color-codes the input based on which sections appear to be critical, and which are not; while not bulletproof, it can often offer quick insights into complex file formats. - ## 5. CI fuzzing Some notes on CI fuzzing - this fuzzing is different to normal fuzzing campaigns diff --git a/frida_mode/README.md b/frida_mode/README.md index e88bda8d..08f6b891 100644 --- a/frida_mode/README.md +++ b/frida_mode/README.md @@ -141,6 +141,7 @@ instances run CMPLOG mode and instrumentation of the binary is less frequent (only on CMP, SUB and CALL instructions) performance is not quite so critical. ## Advanced configuration options + * `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 diff --git a/unicorn_mode/README.md b/unicorn_mode/README.md index 4c95e8f3..ee4a7b22 100644 --- a/unicorn_mode/README.md +++ b/unicorn_mode/README.md @@ -83,7 +83,6 @@ 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 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. diff --git a/unicorn_mode/samples/c/COMPILE.md b/unicorn_mode/samples/c/COMPILE.md index 4e3cf568..e5265071 100644 --- a/unicorn_mode/samples/c/COMPILE.md +++ b/unicorn_mode/samples/c/COMPILE.md @@ -6,6 +6,7 @@ This shows a simple harness for unicornafl in C The target can be built using the `make` command. Just make sure you have built unicorn support first: + ```bash cd /path/to/afl/unicorn_mode ./build_unicorn_support.sh diff --git a/unicorn_mode/samples/speedtest/README.md b/unicorn_mode/samples/speedtest/README.md index 496d75cd..bd5ba8d0 100644 --- a/unicorn_mode/samples/speedtest/README.md +++ b/unicorn_mode/samples/speedtest/README.md @@ -35,7 +35,6 @@ cd python TODO: add results here. - ## Compiling speedtest_target.c You shouldn't need to compile simple_target.c since a X86_64 binary version is @@ -46,20 +45,28 @@ The pre-built binary (simple_target_x86_64.bin) was built using -g -O0 in gcc. Then load the binary and execute the main function directly. -## Addresses for the harness: +## Addresses for the harness + To find the address (in hex) of main, run: + ```bash objdump -M intel -D target | grep '
:' | cut -d" " -f1 ``` + To find all call sites to magicfn, run: + ```bash objdump -M intel -D target | grep '$' | cut -d":" -f1 ``` + For malloc callsites: + ```bash objdump -M intel -D target | grep '$' | cut -d":" -f1 ``` + And free callsites: + ```bash objdump -M intel -D target | grep '$' | cut -d":" -f1 -``` +``` \ No newline at end of file diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md index 3fff5f83..cd87998b 100644 --- a/utils/afl_untracer/README.md +++ b/utils/afl_untracer/README.md @@ -28,28 +28,34 @@ To generate the `patches.txt` file for your target library use the The patches.txt file has to be pointed to by `AFL_UNTRACER_FILE`. To easily run the scripts without needing to run the GUI with Ghidra: + ``` /opt/ghidra/support/analyzeHeadless /tmp/ tmp$$ -import libtestinstr.so -postscript ./ghidra_get_patchpoints.java rm -rf /tmp/tmp$$ ``` + The file is created at `~/Desktop/patches.txt` ### Fuzzing Example (after modifying afl-untracer.c to your needs, compiling and creating patches.txt): + ``` LD_LIBRARY_PATH=/path/to/target/library AFL_UNTRACER_FILE=./patches.txt afl-fuzz -i in -o out -- ./afl-untracer ``` + (or even remote via afl-network-proxy). ### Testing and debugging For testing/debugging you can try: + ``` make DEBUG=1 AFL_UNTRACER_FILE=./patches.txt AFL_DEBUG=1 gdb ./afl-untracer ``` + and then you can easily set breakpoints to "breakpoint" and "fuzz". # Background @@ -57,4 +63,4 @@ and then you can easily set breakpoints to "breakpoint" and "fuzz". This idea is based on [UnTracer](https://github.com/FoRTE-Research/UnTracer-AFL) and modified by [Trapfuzz](https://github.com/googleprojectzero/p0tools/tree/master/TrapFuzz). This implementation is slower because the traps are not patched out with each -run, but on the other hand gives much better coverage information. +run, but on the other hand gives much better coverage information. \ No newline at end of file diff --git a/utils/autodict_ql/readme.md b/utils/autodict_ql/readme.md index 491ec85b..789cd152 100644 --- a/utils/autodict_ql/readme.md +++ b/utils/autodict_ql/readme.md @@ -6,12 +6,12 @@ Tokens are useful when you perform fuzzing on different parsers. The AFL++ `-x` switch enables the usage of dictionaries through your fuzzing campaign. If you are not familiar with Dictionaries in fuzzing, take a look [here](https://github.com/AFLplusplus/AFLplusplus/tree/stable/dictionaries) . - ## Why CodeQL ? -We basically developed this plugin on top of the CodeQL engine because it gives the user scripting features, it's easier and it's independent of the LLVM system. This means that a user can write his CodeQL scripts or modify the current scripts to improve or change the token generation algorithms based on different program analysis concepts. +We basically developed this plugin on top of the CodeQL engine because it gives the user scripting features, it's easier and it's independent of the LLVM system. This means that a user can write his CodeQL scripts or modify the current scripts to improve or change the token generation algorithms based on different program analysis concepts. ## CodeQL scripts + Currently, we pushed some scripts as defaults for Token generation. In addition, we provide every CodeQL script as an standalone script because it's easier to modify or test. Currently we provided the following CodeQL scripts : @@ -28,23 +28,26 @@ Currently we provided the following CodeQL scripts : You can write other CodeQL scripts to extract possible effective tokens if you think they can be useful. - ## Usage -Before you proceed to installation make sure that you have the following packages by installing them : +Before you proceed to installation make sure that you have the following packages by installing them: + ```shell sudo apt install build-essential libtool-bin python3-dev python3 automake git vim wget -y ``` + The usage of Autodict-QL is pretty easy. But let's describe it as: 1. First of all, you need to have CodeQL installed on the system. We make this possible with `build-codeql.sh` bash script. This script will install CodeQL completety and will set the required environment variables for your system. -Do the following : +Do the following: + ```shell # chmod +x codeql-build.sh # ./codeql-build.sh # source ~/.bashrc # codeql ``` + Then you should get: ```shell @@ -86,8 +89,8 @@ Commands: - This will create the final `tokens` dir for you and you are done, then pass the tokens path to AFL++'s `-x` flag. 5. Done! - ## More on dictionaries and tokens + Core developer of the AFL++ project Marc Heuse also developed a similar tool named `dict2file` which is a LLVM pass which can automatically extract useful tokens, in addition with LTO instrumentation mode, this dict2file is automatically generates token extraction. `Autodict-QL` plugin gives you scripting capability and you can do whatever you want to extract from the Codebase and it's up to you. In addition it's independent from LLVM system. On the other hand, you can also use Google dictionaries which have been made public in May 2020, but the problem of using Google dictionaries is that they are limited to specific file formats and specifications. For example, for testing binutils and ELF file format or AVI in FFMPEG, there are no pre-built dictionaries, so it is highly recommended to use `Autodict-QL` or `Dict2File` features to automatically generate dictionaries based on the target. @@ -97,4 +100,4 @@ In overall, fuzzing with dictionaries and well-generated tokens will give better There are 2 important points to remember : - If you combine `Autodict-QL` with AFL++ cmplog, you will get much better code coverage and hence better chances to discover new bugs. -- Do not forget to set `AFL_MAX_DET_EXTRAS` at least to the number of generated dictionaries. If you forget to set this environment variable, then AFL++ uses just 200 tokens and use the rest of them only probabilistically. So this will guarantee that your tokens will be used by AFL++. +- Do not forget to set `AFL_MAX_DET_EXTRAS` at least to the number of generated dictionaries. If you forget to set this environment variable, then AFL++ uses just 200 tokens and use the rest of them only probabilistically. So this will guarantee that your tokens will be used by AFL++. \ No newline at end of file diff --git a/utils/qbdi_mode/README.md b/utils/qbdi_mode/README.md index 02dd3c74..08558017 100755 --- a/utils/qbdi_mode/README.md +++ b/utils/qbdi_mode/README.md @@ -9,7 +9,6 @@ Try FRIDA mode or fpicker [https://github.com/ttdennis/fpicker/](https://github. The code in ./qbdi_mode allows you to build a standalone feature that using the QBDI framework to fuzz android native library. - ## 2) Build First download the Android NDK @@ -53,6 +52,7 @@ https://qbdi.quarkslab.com/ ``` For Android x86_64 + ``` https://github.com/QBDI/QBDI/releases/download/v0.7.0/QBDI-0.7.0-android-X86_64.tar.gz ``` @@ -86,7 +86,6 @@ Then run the build.sh this could build the afl-fuzz and also the qbdi template for android x86_64 - ### Example The demo-so.c is an vulnerable library, it has a function for test @@ -160,6 +159,7 @@ QBDI_NOINLINE int fuzz_func() { ``` Just compile it + ``` ./build.sh x86_64 ``` @@ -176,6 +176,7 @@ adb push ../../android-standalone-toolchain-x86_64/sysroot/usr/lib/x86_64-linux- ``` In android adb shell, run the loader to test if it runs + ``` cd /data/local/tmp export LD_LIBRARY_PATH=/data/local/tmp @@ -202,5 +203,4 @@ Now run `afl-fuzz` to fuzz the demo library ./afl-fuzz -i in -o out -- ./loader /data/local/tmp/libdemo.so @@ ``` -![screen1](assets/screen1.png) - +![screen1](assets/screen1.png) \ No newline at end of file diff --git a/utils/qemu_persistent_hook/README.md b/utils/qemu_persistent_hook/README.md index 3f908c22..3bbaef6b 100644 --- a/utils/qemu_persistent_hook/README.md +++ b/utils/qemu_persistent_hook/README.md @@ -16,4 +16,4 @@ mkdir in echo 0000 > in/in ../../afl-fuzz -Q -i in -o out -- ./test -``` +``` \ No newline at end of file -- cgit 1.4.1 From 139db40cfc243d2de4eb1584e41867e5a44a06f9 Mon Sep 17 00:00:00 2001 From: llzmb <46303940+llzmb@users.noreply.github.com> Date: Sun, 5 Dec 2021 19:31:43 +0100 Subject: Fix usage and punctuation in connection with "then" and "than" --- docs/fuzzing_binary-only_targets.md | 2 +- docs/fuzzing_in_depth.md | 32 ++++++++++++++++---------------- instrumentation/README.llvm.md | 2 +- utils/afl_network_proxy/README.md | 2 +- utils/afl_untracer/README.md | 2 +- utils/aflpp_driver/README.md | 26 +++++++++++++------------- 6 files changed, 33 insertions(+), 33 deletions(-) (limited to 'utils/afl_untracer') diff --git a/docs/fuzzing_binary-only_targets.md b/docs/fuzzing_binary-only_targets.md index fd18b5c1..5434a22c 100644 --- a/docs/fuzzing_binary-only_targets.md +++ b/docs/fuzzing_binary-only_targets.md @@ -172,7 +172,7 @@ Fore more information, see ## Binary rewriters -An alternative solution are binary rewriters. They are faster then the solutions +An alternative solution are binary rewriters. They are faster than the solutions native to AFL++ but don't always work. ### ZAFL diff --git a/docs/fuzzing_in_depth.md b/docs/fuzzing_in_depth.md index 29e8f817..aaceb600 100644 --- a/docs/fuzzing_in_depth.md +++ b/docs/fuzzing_in_depth.md @@ -211,7 +211,7 @@ is more effective). ### d) Modifying the target 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 +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: @@ -244,16 +244,16 @@ Then build the target. (Usually with `make`) **NOTES** -1. sometimes configure and build systems are fickle and do not like stderr +1. Sometimes configure and build systems are fickle and do not like stderr output (and think this means a test failure) - which is something AFL++ likes to do to show statistics. It is recommended to disable AFL++ instrumentation reporting via `export AFL_QUIET=1`. -2. sometimes configure and build systems error on warnings - these should be +2. Sometimes configure and build systems error on warnings - these should be disabled (e.g., `--disable-werror` for some configure scripts). -3. in case the configure/build system complains about AFL++'s compiler and - aborts then set `export AFL_NOOPT=1` which will then just behave like the +3. In case the configure/build system complains about AFL++'s compiler and + aborts, then set `export AFL_NOOPT=1` which will then just behave like the real compiler. This option has to be unset again before building the target! #### configure @@ -304,8 +304,8 @@ that you want to fuzz, plus a few specific AFL++ functions around it. See [instrumentation/README.persistent_mode.md](../instrumentation/README.persistent_mode.md) for details. -Basically if you do not fuzz a target in persistent mode then you are just doing -it for a hobby and not professionally :-). +Basically if you do not fuzz a target in persistent mode, then you are just +doing it for a hobby and not professionally :-). ### g) libfuzzer fuzzer harnesses with LLVMFuzzerTestOneInput() @@ -418,9 +418,9 @@ Note that both scripts improve your fuzzing performance but also decrease your system protection against attacks! So set strong firewall rules and only expose SSH as a network service if you use these (which is highly recommended). -If you have an input corpus from step 2 then specify this directory with the -`-i` option. Otherwise create a new directory and create a file with any content -as test data in there. +If you have an input corpus from step 2, then specify this directory with the +`-i` option. Otherwise, create a new directory and create a file with any +content as test data in there. If you do not want anything special, the defaults are already usually best, hence all you need is to specify the seed input directory with the result of @@ -498,8 +498,8 @@ and not waste CPU time. ### c) Using multiple cores -If you want to seriously fuzz then use as many cores/threads as possible to fuzz -your target. +If you want to seriously fuzz, then use as many cores/threads as possible to +fuzz your target. On the same machine - due to the design of how AFL++ works - there is a maximum number of CPU cores/threads that are useful, use more and the overall @@ -658,7 +658,7 @@ An "easy" helper script for this is [https://github.com/vanhauser-thc/afl-cov](https://github.com/vanhauser-thc/afl-cov), just follow the README of that separate project. -If you see that an important area or a feature has not been covered so far then +If you see that an important area or a feature has not been covered so far, then try to find an input that is able to reach that and start a new secondary in that fuzzing campaign with that seed as input, let it run for a few minutes, then terminate it. The main node will pick it up and make it available to the @@ -668,13 +668,13 @@ AFL_TRY_AFFINITY=1` if you have no free core. Note that in nearly all cases you can never reach full coverage. A lot of functionality is usually dependent on exclusive options that would need individual fuzzing campaigns each with one of these options set. E.g., if you -fuzz a library to convert image formats and your target is the png to tiff API +fuzz a library to convert image formats and your target is the png to tiff API, then you will not touch any of the other library APIs and features. ### h) How long to fuzz a target? -This is a difficult question. Basically if no new path is found for a long time -(e.g., for a day or a week) then you can expect that your fuzzing won't be +This is a difficult question. Basically, if no new path is found for a long time +(e.g., for a day or a week), then you can expect that your fuzzing won't be fruitful anymore. However, often this just means that you should switch out secondaries for others, e.g., custom mutator modules, sync to very different fuzzers, etc. diff --git a/instrumentation/README.llvm.md b/instrumentation/README.llvm.md index ca9ce933..d220e52c 100644 --- a/instrumentation/README.llvm.md +++ b/instrumentation/README.llvm.md @@ -269,7 +269,7 @@ can set: AFL_LLVM_SKIP_NEVERZERO=1 ``` -If the target does not have extensive loops or functions that are called a lot +If the target does not have extensive loops or functions that are called a lot, then this can give a small performance boost. Please note that the default counter implementations are not thread safe! diff --git a/utils/afl_network_proxy/README.md b/utils/afl_network_proxy/README.md index c478319a..c34463e2 100644 --- a/utils/afl_network_proxy/README.md +++ b/utils/afl_network_proxy/README.md @@ -1,6 +1,6 @@ # afl-network-proxy -If you want to run afl-fuzz over the network than this is what you need :) +If you want to run afl-fuzz over the network, then this is what you need. :) Note that the impact on fuzzing speed will be huge, expect a loss of 90%. ## When to use this diff --git a/utils/afl_untracer/README.md b/utils/afl_untracer/README.md index cd87998b..da0e0c77 100644 --- a/utils/afl_untracer/README.md +++ b/utils/afl_untracer/README.md @@ -15,7 +15,7 @@ Supported is so far Intel (i386/x86_64) and AARCH64. ### Modify afl-untracer.c -Read and modify afl-untracer.c then `make`. +Read and modify afl-untracer.c, then `make`. To adapt afl-untracer.c to your needs, read the header of the file and then search and edit the `STEP 1`, `STEP 2` and `STEP 3` locations. diff --git a/utils/aflpp_driver/README.md b/utils/aflpp_driver/README.md index 8b9fe15f..c547aaea 100644 --- a/utils/aflpp_driver/README.md +++ b/utils/aflpp_driver/README.md @@ -5,20 +5,20 @@ aflpp_driver is used to compile directly libfuzzer `LLVMFuzzerTestOneInput()` targets. -Just do `afl-clang-fast++ -o fuzz fuzzer_harness.cc libAFLDriver.a [plus required linking]`. +Just do `afl-clang-fast++ -o fuzz fuzzer_harness.cc libAFLDriver.a [plus +required linking]`. -You can also sneakily do this little trick: -If this is the clang compile command to build for libfuzzer: - `clang++ -o fuzz -fsanitize=fuzzer fuzzer_harness.cc -lfoo` -then just switch `clang++` with `afl-clang-fast++` and our compiler will +You can also sneakily do this little trick: If this is the clang compile command +to build for libfuzzer: `clang++ -o fuzz -fsanitize=fuzzer fuzzer_harness.cc +-lfoo`, then just switch `clang++` with `afl-clang-fast++` and our compiler will magically insert libAFLDriver.a :) -To use shared-memory test cases, you need nothing to do. -To use stdin test cases, give `-` as the only command line parameter. -To use file input test cases, give `@@` as the only command line parameter. +To use shared-memory test cases, you need nothing to do. To use stdin test +cases, give `-` as the only command line parameter. To use file input test +cases, give `@@` as the only command line parameter. -IMPORTANT: if you use `afl-cmin` or `afl-cmin.bash` then either pass `-` -or `@@` as command line parameters. +IMPORTANT: if you use `afl-cmin` or `afl-cmin.bash`, then either pass `-` or +`@@` as command line parameters. ## aflpp_qemu_driver @@ -38,6 +38,6 @@ AFL_QEMU_PERSISTENT_HOOK=/path/to/aflpp_qemu_driver_hook.so afl-fuzz -Q ... -- . ``` if you use afl-cmin or `afl-showmap -C` with the aflpp_qemu_driver you need to -set the set same AFL_QEMU_... (or AFL_FRIDA_...) environment variables. -If you want to use afl-showmap (without -C) or afl-cmin.bash then you may not -set these environment variables and rather set `AFL_QEMU_DRIVER_NO_HOOK=1`. \ No newline at end of file +set the set same AFL_QEMU_... (or AFL_FRIDA_...) environment variables. If you +want to use afl-showmap (without -C) or afl-cmin.bash, then you may not set +these environment variables and rather set `AFL_QEMU_DRIVER_NO_HOOK=1`. \ No newline at end of file -- cgit 1.4.1