Add missing blank lines and remove double blank lines
MODIFY
custom_mutators/README.md
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
```

MODIFY
custom_mutators/gramatron/README.md
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

MODIFY
custom_mutators/libfuzzer/README.md
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

MODIFY
docs/custom_mutators.md
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

MODIFY
docs/fuzzing_binary-only_targets.md
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:

MODIFY
docs/fuzzing_in_depth.md
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

MODIFY
frida_mode/README.md
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

MODIFY
unicorn_mode/README.md
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.

MODIFY
unicorn_mode/samples/c/COMPILE.md
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

MODIFY
unicorn_mode/samples/speedtest/README.md
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 '<main>:' | cut -d" " -f1
```
+
To find all call sites to magicfn, run:
+
```bash
objdump -M intel -D target | grep '<magicfn>$' | cut -d":" -f1
```
+
For malloc callsites:
+
```bash
objdump -M intel -D target | grep '<malloc@plt>$' | cut -d":" -f1
```
+
And free callsites:
+
```bash
objdump -M intel -D target | grep '<free@plt>$' | cut -d":" -f1
```
\ No newline at end of file

MODIFY
utils/afl_untracer/README.md
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

MODIFY
utils/autodict_ql/readme.md
utils/autodict_ql/readme.md
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:
+
```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:
+
```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.

MODIFY
utils/qbdi_mode/README.md
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
@@ -203,4 +204,3 @@ Now run `afl-fuzz` to fuzz the demo library
```
![screen1](assets/screen1.png)
\ No newline at end of file
-

Add missing blank lines and remove double blank lines