Merge branch 'custom_describe' into dev

2 files changed, 17 insertions, 4 deletions

diff --git a/docs/Changelog.md b/docs/Changelog.md
index 02728f10..5201eb8b 100644
--- a/docs/Changelog.md
+++ b/docs/Changelog.md
@@ -22,18 +22,18 @@ sending a mail to <afl-users+subscribe@googlegroups.com>.
       a schedule performance score, which is much better that the previous
       walk the whole queue approach. Select the old mode with -Z (auto enabled
       with -M)
-    - rpc.statsd support by Edznux, thanks a lot!
+    - rpc.statsd support, for stats and charts, by Edznux, thanks a lot!
     - Marcel Boehme submitted a patch that improves all AFFast schedules :)
     - not specifying -M or -S will now auto-set "-S default"
     - reading testcases from -i now descends into subdirectories
-    - allow up to 4 times the -x command line option
-    - loaded extras now have a duplicate protection
+    - allow the -x command line option up to 4 times
+    - loaded extras now have a duplication protection
     - If test cases are too large we do a partial read on the maximum
       supported size
     - longer seeds with the same trace information will now be ignored
       for fuzzing but still be used for splicing
     - crashing seeds are now not prohibiting a run anymore but are
-      skipped. They are used for splicing though.
+      skipped - they are used for splicing, though
     - update MOpt for expanded havoc modes
     - setting the env var AFL_NO_AUTODICT will not load an LTO autodictionary
     - added NO_SPLICING compile option and makefile define
@@ -42,6 +42,8 @@ sending a mail to <afl-users+subscribe@googlegroups.com>.
     - print special compile time options used in help output
     - when using -c cmplog, one of the childs was not killed, fixed
     - somewhere we broke -n dumb fuzzing, fixed
+    - added afl_custom_describe to the custom mutator API to allow for easy
+      mutation reproduction on crashing inputs
   - instrumentation
     - We received an enhanced gcc_plugin module from AdaCore, thank you
       very much!!
diff --git a/docs/custom_mutators.md b/docs/custom_mutators.md
index 6e16ba0f..6d3c9f38 100644
--- a/docs/custom_mutators.md
+++ b/docs/custom_mutators.md
@@ -34,6 +34,7 @@ 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);
 size_t afl_custom_fuzz(void *data, unsigned char *buf, size_t buf_size, unsigned char **out_buf, unsigned char *add_buf, size_t add_buf_size, size_t max_size);
+const char *afl_custom_describe(void *data, size_t max_description_len);
 size_t afl_custom_post_process(void *data, unsigned char *buf, size_t buf_size, unsigned char **out_buf);
 int afl_custom_init_trim(void *data, unsigned char *buf, size_t buf_size);
 size_t afl_custom_trim(void *data, unsigned char **out_buf);
@@ -57,6 +58,9 @@ def fuzz_count(buf, add_buf, max_size):
 def fuzz(buf, add_buf, max_size):
     return mutated_out
 
+def describe(max_description_length):
+    return "description_of_current_mutation"
+
 def post_process(buf):
     return out_buf
 
@@ -112,6 +116,13 @@ def introspection():
     You would only skip this if `post_process` is used to fix checksums etc.
     so you are using it e.g. as a post processing library.
 
+- `describe` (optional):
+
+    When this function is called, is shall describe the current testcase,
+    generated by the last mutation. This will be called, for example,
+    to give the written testcase a name after a crash ocurred.
+    Using it can help to reproduce crashing mutations.
+
 - `havoc_mutation` and `havoc_mutation_probability` (optional):
 
     `havoc_mutation` performs a single custom mutation on a given input. This