diff --git a/docs/custom_mutator.md b/docs/custom_mutator.md index 142396dd..19009f92 100644 --- a/docs/custom_mutator.md +++ b/docs/custom_mutator.md @@ -33,4 +33,4 @@ is not needed. ## 2) Example -A simple example is provided in ../custom_mutators/ +A simple example is provided in ../examples/custom_mutators/ diff --git a/docs/python_mutators.txt b/docs/python_mutators.md similarity index 91% rename from docs/python_mutators.txt rename to docs/python_mutators.md index 7fd54547..a7e2c7de 100644 --- a/docs/python_mutators.txt +++ b/docs/python_mutators.md @@ -1,6 +1,4 @@ -================================================== -Adding custom mutators to AFL using Python modules -================================================== +# Adding custom mutators to AFL using Python modules This file describes how you can utilize the external Python API to write your own custom mutation routines. @@ -14,11 +12,10 @@ Adding custom mutators to AFL using Python modules python2 or python3 syntax in your scripts! After a major version upgrade (e.g. 3.7 -> 3.8), a recompilation of afl-fuzz may be needed. - For an example and a template see ../python_mutators/ + For an example and a template see ../examples/python_mutators/ -1) Description and purpose --------------------------- +## 1) Description and purpose While AFLFuzz comes with a good selection of generic deterministic and non-deterministic mutation operations, it sometimes might make sense to extend @@ -40,8 +37,7 @@ See the following information to get a better pictures: https://bugs.chromium.org/p/chromium/issues/detail?id=930663 -2) How the Python module looks like ------------------------------------ +## 2) How the Python module looks like You can find a simple example in pymodules/example.py including documentation explaining each function. In the same directory, you can find another simple @@ -55,8 +51,7 @@ There is also optional support for a trimming API, see the section below for further information about this feature. -3) How to compile AFLFuzz with Python support ---------------------------------------------- +## 3) How to compile AFLFuzz with Python support You must install the python 3 or 2 development package of your Linux distribution before this will work. On Debian/Ubuntu/Kali this can be done @@ -75,8 +70,7 @@ In case your setup is different set the necessary variables like this: PYTHON_INCLUDE=/path/to/python/include LDFLAGS=-L/path/to/python/lib make -4) How to run AFLFuzz with your custom module ---------------------------------------------- +## 4) How to run AFLFuzz with your custom module You must pass the module name inside the env variable AFL_PYTHON_MODULE. @@ -99,8 +93,7 @@ AFL_DEBUG - When combined with AFL_NO_UI, this causes the C trimming code of your custom Python trimmer. Use this to see if it works :) -5) Order and statistics ------------------------ +## 5) Order and statistics The Python stage is set to be the first non-deterministic stage (right before the havoc stage). In the statistics however, it shows up as the third number @@ -108,8 +101,7 @@ under "havoc". That's because I'm lazy and I didn't want to mess with the UI too much ;) -6) Trimming support -------------------- +## 6) Trimming support The generic trimming routines implemented in AFLFuzz can easily destroy the structure of complex formats, possibly leading to a point where you have a lot diff --git a/experimental/README.experiments b/examples/README.md similarity index 93% rename from experimental/README.experiments rename to examples/README.md index 06f22ee1..512b03f7 100644 --- a/experimental/README.experiments +++ b/examples/README.md @@ -1,5 +1,11 @@ +# AFL++ Examples + Here's a quick overview of the stuff you can find in this directory: + - custom_mutstors - An example custom mutator + + - python_mutators - Python mutators examples + - argv_fuzzing - a simple wrapper to allow cmdline to be fuzzed (e.g., to test setuid programs). diff --git a/experimental/argv_fuzzing/Makefile b/examples/argv_fuzzing/Makefile similarity index 100% rename from experimental/argv_fuzzing/Makefile rename to examples/argv_fuzzing/Makefile diff --git a/experimental/argv_fuzzing/README.md b/examples/argv_fuzzing/README.md similarity index 100% rename from experimental/argv_fuzzing/README.md rename to examples/argv_fuzzing/README.md diff --git a/experimental/argv_fuzzing/argv-fuzz-inl.h b/examples/argv_fuzzing/argv-fuzz-inl.h similarity index 100% rename from experimental/argv_fuzzing/argv-fuzz-inl.h rename to examples/argv_fuzzing/argv-fuzz-inl.h diff --git a/experimental/argv_fuzzing/argvfuzz.c b/examples/argv_fuzzing/argvfuzz.c similarity index 100% rename from experimental/argv_fuzzing/argvfuzz.c rename to examples/argv_fuzzing/argvfuzz.c diff --git a/experimental/asan_cgroups/limit_memory.sh b/examples/asan_cgroups/limit_memory.sh similarity index 100% rename from experimental/asan_cgroups/limit_memory.sh rename to examples/asan_cgroups/limit_memory.sh diff --git a/experimental/bash_shellshock/shellshock-fuzz.diff b/examples/bash_shellshock/shellshock-fuzz.diff similarity index 100% rename from experimental/bash_shellshock/shellshock-fuzz.diff rename to examples/bash_shellshock/shellshock-fuzz.diff diff --git a/experimental/canvas_harness/canvas_harness.html b/examples/canvas_harness/canvas_harness.html similarity index 100% rename from experimental/canvas_harness/canvas_harness.html rename to examples/canvas_harness/canvas_harness.html diff --git a/experimental/clang_asm_normalize/as b/examples/clang_asm_normalize/as similarity index 100% rename from experimental/clang_asm_normalize/as rename to examples/clang_asm_normalize/as diff --git a/experimental/crash_triage/triage_crashes.sh b/examples/crash_triage/triage_crashes.sh similarity index 100% rename from experimental/crash_triage/triage_crashes.sh rename to examples/crash_triage/triage_crashes.sh diff --git a/custom_mutators/README b/examples/custom_mutators/README similarity index 100% rename from custom_mutators/README rename to examples/custom_mutators/README diff --git a/custom_mutators/simple_mutator.c b/examples/custom_mutators/simple_mutator.c similarity index 100% rename from custom_mutators/simple_mutator.c rename to examples/custom_mutators/simple_mutator.c diff --git a/experimental/distributed_fuzzing/sync_script.sh b/examples/distributed_fuzzing/sync_script.sh similarity index 100% rename from experimental/distributed_fuzzing/sync_script.sh rename to examples/distributed_fuzzing/sync_script.sh diff --git a/experimental/libpng_no_checksum/libpng-nocrc.patch b/examples/libpng_no_checksum/libpng-nocrc.patch similarity index 100% rename from experimental/libpng_no_checksum/libpng-nocrc.patch rename to examples/libpng_no_checksum/libpng-nocrc.patch diff --git a/experimental/persistent_demo/persistent_demo.c b/examples/persistent_demo/persistent_demo.c similarity index 100% rename from experimental/persistent_demo/persistent_demo.c rename to examples/persistent_demo/persistent_demo.c diff --git a/experimental/post_library/post_library.so.c b/examples/post_library/post_library.so.c similarity index 100% rename from experimental/post_library/post_library.so.c rename to examples/post_library/post_library.so.c diff --git a/experimental/post_library/post_library_png.so.c b/examples/post_library/post_library_png.so.c similarity index 100% rename from experimental/post_library/post_library_png.so.c rename to examples/post_library/post_library_png.so.c diff --git a/python_mutators/README b/examples/python_mutators/README similarity index 100% rename from python_mutators/README rename to examples/python_mutators/README diff --git a/python_mutators/XmlMutatorMin.py b/examples/python_mutators/XmlMutatorMin.py similarity index 100% rename from python_mutators/XmlMutatorMin.py rename to examples/python_mutators/XmlMutatorMin.py diff --git a/python_mutators/common.py b/examples/python_mutators/common.py similarity index 100% rename from python_mutators/common.py rename to examples/python_mutators/common.py diff --git a/python_mutators/example.py b/examples/python_mutators/example.py similarity index 100% rename from python_mutators/example.py rename to examples/python_mutators/example.py diff --git a/python_mutators/simple-chunk-replace.py b/examples/python_mutators/simple-chunk-replace.py similarity index 100% rename from python_mutators/simple-chunk-replace.py rename to examples/python_mutators/simple-chunk-replace.py diff --git a/python_mutators/wrapper_afl_min.py b/examples/python_mutators/wrapper_afl_min.py similarity index 100% rename from python_mutators/wrapper_afl_min.py rename to examples/python_mutators/wrapper_afl_min.py diff --git a/experimental/socket_fuzzing/Makefile b/examples/socket_fuzzing/Makefile similarity index 100% rename from experimental/socket_fuzzing/Makefile rename to examples/socket_fuzzing/Makefile diff --git a/experimental/socket_fuzzing/README.md b/examples/socket_fuzzing/README.md similarity index 100% rename from experimental/socket_fuzzing/README.md rename to examples/socket_fuzzing/README.md diff --git a/experimental/socket_fuzzing/socketfuzz.c b/examples/socket_fuzzing/socketfuzz.c similarity index 100% rename from experimental/socket_fuzzing/socketfuzz.c rename to examples/socket_fuzzing/socketfuzz.c