diff options
| -rw-r--r-- | README.md | 5 | ||||
| -rw-r--r-- | docs/custom_mutator.md | 51 | ||||
| -rw-r--r-- | examples/custom_mutators/README.md (renamed from examples/custom_mutators/README) | 2 |
3 files changed, 37 insertions, 21 deletions
diff --git a/README.md b/README.md index 7396706c..05511077 100644 --- a/README.md +++ b/README.md @@ -326,6 +326,11 @@ Here are some good writeups to show how to effectibly use AFL++: * [https://bananamafia.dev/post/gb-fuzz/](https://bananamafia.dev/post/gb-fuzz/) * [https://securitylab.github.com/research/fuzzing-challenges-solutions-1](https://securitylab.github.com/research/fuzzing-challenges-solutions-1) +If you are interested in fuzzing structured data (where you define what the +structure is), these two links have you covered: + * [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator) + * [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator) + If you find other good ones, please send them to us :-) ## 6) Power schedules diff --git a/docs/custom_mutator.md b/docs/custom_mutator.md index 19009f92..dff32c1d 100644 --- a/docs/custom_mutator.md +++ b/docs/custom_mutator.md @@ -7,30 +7,39 @@ Implemented by Khaled Yakdan from Code Intelligence <yakdan@code-intelligence.de ## 1) Description Custom mutator libraries can be passed to afl-fuzz to perform custom mutations -on test cases beyond those available in AFL - for example, to enable structure-aware -fuzzing by using libraries that perform mutations according to a given grammar. - -The custom mutator library is passed to afl-fuzz via the AFL_CUSTOM_MUTATOR_LIBRARY -environment variable. The library must export the afl_custom_mutator() function and -must be compiled as a shared object. For example: - $CC -shared -Wall -O3 <lib-name>.c -o <lib-name>.so - -Note: unless AFL_CUSTOM_MUTATOR_ONLY is set, its state mutator like any others, -so it will be used for some test cases, and other mutators for others. +on test cases beyond those available in AFL - for example, to enable +structure-aware fuzzing by using libraries that perform mutations according to +a given grammar. + +The custom mutator library is passed to afl-fuzz via the +AFL_CUSTOM_MUTATOR_LIBRARY environment variable. The library must export +the afl_custom_mutator() function and must be compiled as a shared object. +For example: +``` +$CC -shared -Wall -O3 <lib-name>.c -o <lib-name>.so +``` +Note: unless AFL_CUSTOM_MUTATOR_ONLY is set, it is a state mutator like any +other, so it will be used for some test cases, and other mutators for others. Only if AFL_CUSTOM_MUTATOR_ONLY is set the afl_custom_mutator() function will -be called every time it needs to mutate test case! - -For some cases, the format of the mutated data returned from -the custom mutator is not suitable to directly execute the target with this input. -For example, when using libprotobuf-mutator, the data returned is in a protobuf -format which corresponds to a given grammar. In order to execute the target, -the protobuf data must be converted to the plain-text format expected by the target. -In such scenarios, the user can define the afl_pre_save_handler() function. This function -is then transforms the data into the format expected by the API before executing the target. -afl_pre_save_handler is optional and does not have to be implemented if its functionality -is not needed. +be called every time it needs to mutate a test case. + +For some cases, the format of the mutated data returned from the custom +mutator is not suitable to directly execute the target with this input. +For example, when using libprotobuf-mutator, the data returned is in a +protobuf format which corresponds to a given grammar. +In order to execute the target, the protobuf data must be converted to the +plain-text format expected by the target. +In such scenarios, the user can define the afl_pre_save_handler() function. +This function is then transforms the data into the format expected by the +API before executing the target. +afl_pre_save_handler is optional and does not have to be implemented if its +functionality is not needed. ## 2) Example A simple example is provided in ../examples/custom_mutators/ + +There is also a libprotobuf example available at [https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator](https://github.com/bruce30262/libprotobuf-mutator_fuzzing_learning/tree/master/4_libprotobuf_aflpp_custom_mutator) +Another implementation can be found at [https://github.com/thebabush/afl-libprotobuf-mutator](https://github.com/thebabush/afl-libprotobuf-mutator) + diff --git a/examples/custom_mutators/README b/examples/custom_mutators/README.md index f2ae0e4f..6da288ab 100644 --- a/examples/custom_mutators/README +++ b/examples/custom_mutators/README.md @@ -1,2 +1,4 @@ +# A simple example for AFL_CUSTOM_MUTATOR_LIBRARY + This is a simple example for the AFL_CUSTOM_MUTATOR_LIBRARY feature. For more information see [docs/custom_mutator.md](../docs/custom_mutator.md) |