From fc809ccb335b3ff8f9a3f91d934a75d668ade4b1 Mon Sep 17 00:00:00 2001 From: Dominik Maier Date: Tue, 1 Aug 2023 23:27:51 +0200 Subject: [PATCH] Remove FeedbackState reference from the book (#1391) * Remove FeedbackState reference from the book * Update feedback.md --- docs/src/core_concepts/feedback.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/src/core_concepts/feedback.md b/docs/src/core_concepts/feedback.md index eb9bacd130..70fb3a66d6 100644 --- a/docs/src/core_concepts/feedback.md +++ b/docs/src/core_concepts/feedback.md @@ -10,8 +10,13 @@ The concept of "interestingness" is abstract, but typically it is related to a n As an example, given an Observer that reports all the sizes of memory allocations, a maximization Feedback can be used to maximize these sizes to sport pathological inputs in terms of memory consumption. -In terms of code, the library offers the [`Feedback`](https://docs.rs/libafl/0/libafl/feedbacks/trait.Feedback.html) and the [`FeedbackState`](https://docs.rs/libafl/0/libafl/feedbacks/trait.FeedbackState.html) traits. -The first is used to implement functors that, given the state of the observers from the last execution, tells if the execution was interesting. The second is tied with `Feedback` and is the state of the data that the feedback wants to persist in the fuzzers's state, for instance the cumulative map holding all the edges seen so far in the case of a feedback based on edge coverage. +In terms of code, the library offers the [`Feedback`](https://docs.rs/libafl/0/libafl/feedbacks/trait.Feedback.html) trait. +It is used to implement functors that, given the state of the observers from the last execution, tells if the execution was interesting. +So to speak, it reduces the observations to a boolean result of [`is_interesting`](https://docs.rs/libafl/0/libafl/feedbacks/trait.Feedback.html#tymethod.is_interesting) - or not. +For this, a `Feedback` can store anything it wants to persist in the fuzzers's state. +This might be, for instance, the cumulative map of all edges seen so far, in the case of a feedback based on edge coverage. +This can be achieved by adding `Metadata` in [`init_state`](https://docs.rs/libafl/0/libafl/feedbacks/trait.Feedback.html#method.init_state) and accessing it later in `is_interesting`. +`Feedback` can also add custom metadata to a newly created [`Testcase`](https://docs.rs/libafl/0/libafl/corpus/testcase/struct.Testcase.html) using [`append_metadata`](https://docs.rs/libafl/0.10.1/libafl/feedbacks/trait.Feedback.html#method.append_metadata). Multiple Feedbacks can be combined into a boolean expression, considering for instance an execution as interesting if it triggers new code paths or execute in less time compared to the average execution time using [`feedback_or`](https://docs.rs/libafl/*/libafl/macro.feedback_or.html). @@ -24,3 +29,6 @@ Using `feedback_and_fast` in combination with [`ConstFeedback`](https://docs.rs/ While feedbacks are commonly used to decide if an [`Input`](https://docs.rs/libafl/*/libafl/inputs/trait.Input.html) should be kept for future mutations, they serve a double-purpose, as so-called `Objective Feedbacks`. In this case, the `interestingness` of a feedback indicates if an `Objective` has been hit. Commonly, these objectives would be a crash or a timeout, but they can also be used to detect if specific parts of the program have been reached, for sanitization, or a differential fuzzing success. +Objectives use the same trait as a normal [`Feedback`](https://docs.rs/libafl/0/libafl/feedbacks/trait.Feedback.html) and the implementations can be used interchangeably. + +The only difference is that `interesting` Objectives won't be mutated further, and are counted as `Solutions`, a successful fuzzing campaign.