Add two new hooks for the custom mutator

- `afl_custom_queue_get` and `afl_custom_queue_new_entry`
- Update the corresponding document and examples

examples/custom_mutators/example.c

@@ -57,7 +57,7 @@ size_t afl_custom_fuzz(uint8_t **buf, size_t buf_size,
   // Mutate the payload of the packet
   for (int i = 3; i < mutated_size; i++) {
 
-    mutated_out[i] = (buf[i] + rand() % 10) & 0xff;
+    mutated_out[i] = (mutated_out[i] + rand() % 10) & 0xff;
 
   }
 
@@ -93,10 +93,10 @@ size_t afl_custom_pre_save(uint8_t *buf, size_t buf_size, uint8_t **out_buf) {
 
 }
 
-uint8_t *trim_buf;
-size_t trim_buf_size;
-int trimmming_steps;
-int cur_step;
+static uint8_t *trim_buf;
+static size_t trim_buf_size;
+static int trimmming_steps;
+static int cur_step;
 
 /**
  * This method is called at the start of each trimming operation and receives
@@ -186,9 +186,11 @@ int afl_custom_post_trim(int success) {
  *
  * (Optional)
  *
- * @param[in] buf Pointer to the input data to be mutated
+ * @param[inout] buf Pointer to the input data to be mutated and the mutated
+ *     output
  * @param[in] buf_size Size of input data
- * @param[in] max_size Maximum size of the mutated output. The mutation must not produce data larger than max_size.
+ * @param[in] max_size Maximum size of the mutated output. The mutation must
+ *     not produce data larger than max_size.
  * @return Size of the mutated output.
  */
 size_t afl_custom_havoc_mutation(uint8_t** buf, size_t buf_size, size_t max_size) {
@@ -221,3 +223,35 @@ uint8_t afl_custom_havoc_mutation_probability(void) {
   return 5; // 5 %
 
 }
+
+/**
+ * Determine whether the fuzzer should fuzz the queue entry or not.
+ *
+ * (Optional)
+ *
+ * @param filename File name of the test case in the queue entry
+ * @return Return True(1) if the fuzzer will fuzz the queue entry, and
+ *     False(0) otherwise.
+ */
+uint8_t afl_custom_queue_get(const uint8_t* filename) {
+
+  return 1;
+
+}
+
+/**
+ * Allow for additional analysis (e.g. calling a different tool that does a 
+ * different kind of coverage and saves this for the custom mutator).
+ *
+ * (Optional)
+ *
+ * @param filename_new_queue File name of the new queue entry
+ * @param filename_orig_queue File name of the original queue entry
+ */
+void afl_custom_queue_new_entry(const uint8_t* filename_new_queue,
+                                const uint8_t* filename_orig_queue) {
+
+  /* Additional analysis on the original or new test case */
+
+}
+

examples/custom_mutators/example.py

@@ -120,3 +120,55 @@ def fuzz(buf, add_buf, max_size):
 #     '''
 #     return buf
 #
+# def havoc_mutation(buf, max_size):
+#     '''
+#     Perform a single custom mutation on a given input.
+#
+#     @type buf: bytearray
+#     @param buf: The buffer that should be mutated.
+#
+#     @type max_size: int
+#     @param max_size: Maximum size of the mutated output. The mutation must not
+#         produce data larger than max_size.
+#
+#     @rtype: bytearray
+#     @return: A new bytearray containing the mutated data
+#     '''
+#     return mutated_buf
+#
+# def havoc_mutation_probability():
+#     '''
+#     Called for each `havoc_mutation`. Return the probability (in percentage)
+#     that `havoc_mutation` is called in havoc. Be default it is 6%.
+#
+#     @rtype: int
+#     @return: The probability (0-100)
+#     '''
+#     return prob
+#
+# def queue_get(filename):
+#     '''
+#     Called at the beginning of each fuzz iteration to determine whether the
+#     test case should be fuzzed
+#
+#     @type filename: str
+#     @param filename: File name of the test case in the current queue entry
+#
+#     @rtype: bool
+#     @return: Return True if the custom mutator decides to fuzz the test case,
+#         and False otherwise
+#     '''
+#     return True
+#
+# def queue_new_entry(filename_new_queue, filename_orig_queue):
+#     '''
+#     Called after adding a new test case to the queue
+#
+#     @type filename_new_queue: str 
+#     @param filename_new_queue: File name of the new queue entry
+#
+#     @type filename_orig_queue: str
+#     @param filename_orig_queue: File name of the original queue entry
+#     '''
+#     pass
+