Documentation fixes (#1761)
* Documentation fixes * Fix InProcessExecutor url * Update all urls to latest
This commit is contained in:
parent
ea5ea3410c
commit
ce71858100
@ -169,17 +169,17 @@ No matter the instrumentation method, the interface between the fuzzer and the i
|
|||||||
The only difference between using SymCC and SymQEMU should be the binary that represents the target:
|
The only difference between using SymCC and SymQEMU should be the binary that represents the target:
|
||||||
In the case of SymCC it will be the binary that was build with instrumentation and with SymQEMU it will be the emulator binary (eg. `x86_64-linux-user/symqemu-x86_64`), followed by your uninstrumented target binary and its arguments.
|
In the case of SymCC it will be the binary that was build with instrumentation and with SymQEMU it will be the emulator binary (eg. `x86_64-linux-user/symqemu-x86_64`), followed by your uninstrumented target binary and its arguments.
|
||||||
|
|
||||||
You can use the [`CommandExecutor`](https://docs.rs/libafl/0.6.0/libafl/executors/command/struct.CommandExecutor.html) to execute your target ([example](https://github.com/AFLplusplus/LibAFL/blob/main/fuzzers/libfuzzer_stb_image_concolic/fuzzer/src/main.rs#L244)).
|
You can use the [`CommandExecutor`](https://docs.rs/libafl/latest/libafl/executors/command/struct.CommandExecutor.html) to execute your target ([example](https://github.com/AFLplusplus/LibAFL/blob/main/fuzzers/libfuzzer_stb_image_concolic/fuzzer/src/main.rs#L244)).
|
||||||
When configuring the command, make sure you pass the `SYMCC_INPUT_FILE` environment variable (set to the input file path), if your target reads input from a file (instead of standard input).
|
When configuring the command, make sure you pass the `SYMCC_INPUT_FILE` environment variable (set to the input file path), if your target reads input from a file (instead of standard input).
|
||||||
|
|
||||||
#### Serialization and Solving
|
#### Serialization and Solving
|
||||||
|
|
||||||
While it is perfectly possible to build a custom runtime that also performs the solving step of hybrid fuzzing in the context of the target process, the intended use of the LibAFL concolic tracing support is to serialize the (filtered and pre-processed) branch conditions using the [`TracingRuntime`](https://docs.rs/symcc_runtime/0.1/symcc_runtime/tracing/struct.TracingRuntime.html).
|
While it is perfectly possible to build a custom runtime that also performs the solving step of hybrid fuzzing in the context of the target process, the intended use of the LibAFL concolic tracing support is to serialize the (filtered and pre-processed) branch conditions using the [`TracingRuntime`](https://docs.rs/symcc_runtime/0.1/symcc_runtime/tracing/struct.TracingRuntime.html).
|
||||||
This serialized representation can be deserialized in the fuzzer process for solving using a [`ConcolicObserver`](https://docs.rs/libafl/0.6.0/libafl/observers/concolic/struct.ConcolicObserver.html) wrapped in a [`ConcolicTracingStage`](https://docs.rs/libafl/0.6.0/libafl/stages/concolic/struct.ConcolicTracingStage.html), which will attach a [`ConcolicMetadata`](https://docs.rs/libafl/0.6.0/libafl/observers/concolic/struct.ConcolicMetadata.html) to every [`TestCase`](https://docs.rs/libafl/0.6.0/libafl/corpus/testcase/struct.Testcase.html).
|
This serialized representation can be deserialized in the fuzzer process for solving using a [`ConcolicObserver`](https://docs.rs/libafl/latest/libafl/observers/concolic/struct.ConcolicObserver.html) wrapped in a [`ConcolicTracingStage`](https://docs.rs/libafl/latest/libafl/stages/concolic/struct.ConcolicTracingStage.html), which will attach a [`ConcolicMetadata`](https://docs.rs/libafl/latest/libafl/observers/concolic/struct.ConcolicMetadata.html) to every [`TestCase`](https://docs.rs/libafl/latest/libafl/corpus/testcase/struct.Testcase.html).
|
||||||
|
|
||||||
The `ConcolicMetadata` can be used to replay the concolic trace and to solve the conditions using an SMT-Solver.
|
The `ConcolicMetadata` can be used to replay the concolic trace and to solve the conditions using an SMT-Solver.
|
||||||
Most use-cases involving concolic tracing, however, will need to define some policy around which branches they want to solve.
|
Most use-cases involving concolic tracing, however, will need to define some policy around which branches they want to solve.
|
||||||
The [`SimpleConcolicMutationalStage`](https://docs.rs/libafl/0.6.0//libafl/stages/concolic/struct.SimpleConcolicMutationalStage.html) can be used for testing purposes.
|
The [`SimpleConcolicMutationalStage`](https://docs.rs/libafl/latest/libafl/stages/concolic/struct.SimpleConcolicMutationalStage.html) can be used for testing purposes.
|
||||||
It will attempt to solve all branches, like the original simple backend from SymCC, using Z3.
|
It will attempt to solve all branches, like the original simple backend from SymCC, using Z3.
|
||||||
|
|
||||||
### Example
|
### Example
|
||||||
|
@ -57,7 +57,7 @@ To start, we create the closure that we want to fuzz. It takes a buffer as input
|
|||||||
To test the crash manually, you can add a feature in `Cargo.toml` that enables the call that triggers the panic:
|
To test the crash manually, you can add a feature in `Cargo.toml` that enables the call that triggers the panic:
|
||||||
|
|
||||||
```toml
|
```toml
|
||||||
{{#include ../../listings/baby_fuzzer/listing-03/Cargo.toml:22:24}}
|
{{#include ../../listings/baby_fuzzer/listing-03/Cargo.toml:23:25}}
|
||||||
```
|
```
|
||||||
|
|
||||||
And then run the program with that feature activated:
|
And then run the program with that feature activated:
|
||||||
|
@ -6,6 +6,6 @@ A Corpus can store testcases in different ways, for example on disk, or in memor
|
|||||||
|
|
||||||
Usually, a testcase is added to the Corpus when it is considered as interesting, but a Corpus is used also to store testcases that fulfill an objective (like crashing the program under test for instance).
|
Usually, a testcase is added to the Corpus when it is considered as interesting, but a Corpus is used also to store testcases that fulfill an objective (like crashing the program under test for instance).
|
||||||
|
|
||||||
Related to the Corpus is the way in which the next testcase (the fuzzer would ask for) is retrieved from the Corpus. The taxonomy for this handling in LibAFL is CorpusScheduler, the entity representing the policy to pop testcases from the Corpus, in a FIFO fashion for instance.
|
Related to the Corpus is the way in which the next testcase (the fuzzer would ask for) is retrieved from the Corpus. The taxonomy for this handling in LibAFL is Scheduler, the entity representing the policy to pop testcases from the Corpus, in a FIFO fashion for instance.
|
||||||
|
|
||||||
Speaking about the code, [`Corpus`](https://docs.rs/libafl/0/libafl/corpus/trait.Corpus.html) and [`CorpusScheduler`](https://docs.rs/libafl/0/libafl/corpus/trait.CorpusScheduler.html) are traits.
|
Speaking about the code, [`Corpus`](https://docs.rs/libafl/latest/libafl/corpus/trait.Corpus.html) and [`Scheduler`](https://docs.rs/libafl/latest/libafl/schedulers/trait.Scheduler.html) are traits.
|
||||||
|
@ -9,11 +9,11 @@ So the Executor is for instance responsible to inform the program about the inpu
|
|||||||
|
|
||||||
In our model, it can also hold a set of Observers connected with each execution.
|
In our model, it can also hold a set of Observers connected with each execution.
|
||||||
|
|
||||||
In Rust, we bind this concept to the [`Executor`](https://docs.rs/libafl/0/libafl/executors/trait.Executor.html) trait. A structure implementing this trait must implement [`HasObservers`](https://docs.rs/libafl/0/libafl/executors/trait.HasObservers.html) too if wants to hold a set of Observers.
|
In Rust, we bind this concept to the [`Executor`](https://docs.rs/libafl/latest/libafl/executors/trait.Executor.html) trait. A structure implementing this trait must implement [`HasObservers`](https://docs.rs/libafl/latest/libafl/executors/trait.HasObservers.html) too if wants to hold a set of Observers.
|
||||||
|
|
||||||
By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/0/libafl/executors/inprocess/struct.InProcessExecutor.html) in which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/0/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz.
|
By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/latest/libafl/executors/inprocess/type.InProcessExecutor.html) in which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/latest/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz.
|
||||||
|
|
||||||
A common pattern when creating an Executor is wrapping an existing one, for instance [`TimeoutExecutor`](https://docs.rs/libafl/0.6.1/libafl/executors/timeout/struct.TimeoutExecutor.html) wraps an executor and installs a timeout callback before calling the original `run` function of the wrapped executor.
|
A common pattern when creating an Executor is wrapping an existing one, for instance [`TimeoutExecutor`](https://docs.rs/libafl/latest/libafl/executors/timeout/struct.TimeoutExecutor.html) wraps an executor and installs a timeout callback before calling the original `run` function of the wrapped executor.
|
||||||
|
|
||||||
## InProcessExecutor
|
## InProcessExecutor
|
||||||
Let's begin with the base case; `InProcessExecutor`.
|
Let's begin with the base case; `InProcessExecutor`.
|
||||||
@ -24,7 +24,7 @@ When you want to execute the harness as fast as possible, you will most probably
|
|||||||
One thing to note here is, when your harness is likely to have heap corruption bugs, you want to use another allocator so that corrupted heap does not affect the fuzzer itself. (For example, we adopt MiMalloc in some of our fuzzers.). Alternatively you can compile your harness with address sanitizer to make sure you can catch these heap bugs.
|
One thing to note here is, when your harness is likely to have heap corruption bugs, you want to use another allocator so that corrupted heap does not affect the fuzzer itself. (For example, we adopt MiMalloc in some of our fuzzers.). Alternatively you can compile your harness with address sanitizer to make sure you can catch these heap bugs.
|
||||||
|
|
||||||
## ForkserverExecutor
|
## ForkserverExecutor
|
||||||
Next, we'll take a look at the `ForkserverExecutor`. In this case, it is `afl-cc` (from AFLplusplus/AFLplusplus) that compiles the harness code, and therefore, we can't use `EDGES_MAP` anymore. Fortunately we have [_a way_](https://github.com/AFLplusplus/AFLplusplus/blob/2e15661f184c77ac1fbb6f868c894e946cbb7f17/instrumentation/afl-compiler-rt.o.c#L270) to tell the forkserver which map to record the coverage in.
|
Next, we'll take a look at the `ForkserverExecutor`. In this case, it is `afl-cc` (from AFL/AFLplusplus) that compiles the harness code, and therefore, we can't use `EDGES_MAP` anymore. Fortunately we have [_a way_](https://github.com/AFLplusplus/AFLplusplus/blob/2e15661f184c77ac1fbb6f868c894e946cbb7f17/instrumentation/afl-compiler-rt.o.c#L270) to tell the forkserver which map to record the coverage in.
|
||||||
|
|
||||||
As you can see from the forkserver example,
|
As you can see from the forkserver example,
|
||||||
|
|
||||||
|
@ -10,25 +10,25 @@ 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.
|
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) trait.
|
In terms of code, the library offers the [`Feedback`](https://docs.rs/libafl/latest/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.
|
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.
|
So to speak, it reduces the observations to a boolean result of [`is_interesting`](https://docs.rs/libafl/latest/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.
|
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 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`.
|
This can be achieved by adding `Metadata` in [`init_state`](https://docs.rs/libafl/latest/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).
|
`Feedback` can also add custom metadata to a newly created [`Testcase`](https://docs.rs/libafl/latest/libafl/corpus/testcase/struct.Testcase.html) using [`append_metadata`](https://docs.rs/libafl/latest/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).
|
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/latest/libafl/macro.feedback_or.html).
|
||||||
|
|
||||||
On top, logic operators like `feedback_or` and `feedback_and` have a `_fast` variant (e.g. `feedback_or_fast`) where the second feedback will not be evaluated, if the value of the first feedback operand already answers the `interestingness` question so as to save precious performance.
|
On top, logic operators like `feedback_or` and `feedback_and` have a `_fast` variant (e.g. `feedback_or_fast`) where the second feedback will not be evaluated, if the value of the first feedback operand already answers the `interestingness` question so as to save precious performance.
|
||||||
|
|
||||||
Using `feedback_and_fast` in combination with [`ConstFeedback`](https://docs.rs/libafl/*/libafl/feedbacks/enum.ConstFeedback.html#method.new), certain feedbacks can be disabled dynamically.
|
Using `feedback_and_fast` in combination with [`ConstFeedback`](https://docs.rs/libafl/latest/libafl/feedbacks/enum.ConstFeedback.html#method.new), certain feedbacks can be disabled dynamically.
|
||||||
|
|
||||||
## Objectives
|
## Objectives
|
||||||
|
|
||||||
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`.
|
While feedbacks are commonly used to decide if an [`Input`](https://docs.rs/libafl/latest/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.
|
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.
|
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.
|
Objectives use the same trait as a normal [`Feedback`](https://docs.rs/libafl/latest/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.
|
The only difference is that `interesting` Objectives won't be mutated further, and are counted as `Solutions`, a successful fuzzing campaign.
|
||||||
|
@ -6,4 +6,4 @@ Typically, a random generator is used to generate random inputs.
|
|||||||
|
|
||||||
Generators are traditionally less used in Feedback-driven Fuzzing, but there are exceptions, like Nautilus, that uses a Grammar generator to create the initial corpus and a sub-tree Generator as a mutation of its grammar Mutator.
|
Generators are traditionally less used in Feedback-driven Fuzzing, but there are exceptions, like Nautilus, that uses a Grammar generator to create the initial corpus and a sub-tree Generator as a mutation of its grammar Mutator.
|
||||||
|
|
||||||
In the code, [`Generator`](https://docs.rs/libafl/0/libafl/generators/trait.Generator.html) is a trait.
|
In the code, [`Generator`](https://docs.rs/libafl/latest/libafl/generators/trait.Generator.html) is a trait.
|
||||||
|
@ -10,6 +10,6 @@ But it is not always the case. A program can expect inputs that are not linear b
|
|||||||
|
|
||||||
In case of a grammar fuzzer for instance, the Input is generally an Abstract Syntax Tree because it is a data structure that can be easily manipulated while maintaining the validity, but the program expects a byte array as input, so just before the execution, the tree is serialized to a sequence of bytes.
|
In case of a grammar fuzzer for instance, the Input is generally an Abstract Syntax Tree because it is a data structure that can be easily manipulated while maintaining the validity, but the program expects a byte array as input, so just before the execution, the tree is serialized to a sequence of bytes.
|
||||||
|
|
||||||
In the Rust code, an [`Input`](https://docs.rs/libafl/*/libafl/inputs/trait.Input.html) is a trait that can be implemented only by structures that are serializable and have only owned data as fields.
|
In the Rust code, an [`Input`](https://docs.rs/libafl/latest/libafl/inputs/trait.Input.html) is a trait that can be implemented only by structures that are serializable and have only owned data as fields.
|
||||||
|
|
||||||
While most fuzzers use a normal `BytesInput`, more advanced ones use inputs that include special inputs for grammar fuzzing ([GramatronInput](https://docs.rs/libafl/*/libafl/inputs/gramatron/struct.GramatronInput.html) or `NautilusInput` on Rust nightly), as well as the token-level [EncodedInput](https://docs.rs/libafl/*/libafl/inputs/encoded/struct.EncodedInput.html).
|
While most fuzzers use a normal `BytesInput`, more advanced ones use inputs that include special inputs for grammar fuzzing ([GramatronInput](https://docs.rs/libafl/latest/libafl/inputs/gramatron/struct.GramatronInput.html) or `NautilusInput` on Rust nightly), as well as the token-level [EncodedInput](https://docs.rs/libafl/latest/libafl/inputs/encoded/struct.EncodedInput.html).
|
||||||
|
@ -6,4 +6,4 @@ Mutators can be composed, and they are generally linked to a specific Input type
|
|||||||
|
|
||||||
There can be, for instance, a Mutator that applies more than a single type of mutation to the input. Consider a generic Mutator for a byte stream, bit flip is just one of the possible mutations but not the only one, there is also, for instance, the random replacement of a byte of the copy of a chunk.
|
There can be, for instance, a Mutator that applies more than a single type of mutation to the input. Consider a generic Mutator for a byte stream, bit flip is just one of the possible mutations but not the only one, there is also, for instance, the random replacement of a byte of the copy of a chunk.
|
||||||
|
|
||||||
In LibAFL, [`Mutator`](https://docs.rs/libafl/*/libafl/mutators/trait.Mutator.html) is a trait.
|
In LibAFL, [`Mutator`](https://docs.rs/libafl/latest/libafl/mutators/trait.Mutator.html) is a trait.
|
||||||
|
@ -7,7 +7,7 @@ The information contained in the Observer is not preserved across executions, bu
|
|||||||
As an example, the coverage map, filled during the execution to report the executed edges used by fuzzers such as AFL and `HonggFuzz` can be considered an observation. Another `Observer` can collect the time spent executing a run, the program output, or a more advanced observation, like maximum stack depth at runtime.
|
As an example, the coverage map, filled during the execution to report the executed edges used by fuzzers such as AFL and `HonggFuzz` can be considered an observation. Another `Observer` can collect the time spent executing a run, the program output, or a more advanced observation, like maximum stack depth at runtime.
|
||||||
This information is an observation of a dynamic property of the program.
|
This information is an observation of a dynamic property of the program.
|
||||||
|
|
||||||
In terms of code, in the library this entity is described by the [`Observer`](https://docs.rs/libafl/0/libafl/observers/trait.Observer.html) trait.
|
In terms of code, in the library this entity is described by the [`Observer`](https://docs.rs/libafl/latest/libafl/observers/trait.Observer.html) trait.
|
||||||
|
|
||||||
In addition to holding the volatile data connected with the last execution of the target, the structures implementing this trait can define some execution hooks that are executed before and after each fuzz case. In these hooks, the observer can modify the fuzzer's state.
|
In addition to holding the volatile data connected with the last execution of the target, the structures implementing this trait can define some execution hooks that are executed before and after each fuzz case. In these hooks, the observer can modify the fuzzer's state.
|
||||||
|
|
||||||
|
@ -6,4 +6,4 @@ For instance, a Mutational Stage, given an input of the corpus, applies a Mutato
|
|||||||
|
|
||||||
A stage can also be an analysis stage, for instance, the Colorization stage of Redqueen that aims to introduce more entropy in a testcase or the Trimming stage of AFL that aims to reduce the size of a testcase.
|
A stage can also be an analysis stage, for instance, the Colorization stage of Redqueen that aims to introduce more entropy in a testcase or the Trimming stage of AFL that aims to reduce the size of a testcase.
|
||||||
|
|
||||||
There are several stages in the LibAFL codebase implementing the [`Stage`](https://docs.rs/libafl/*/libafl/stages/trait.Stage.html) trait.
|
There are several stages in the LibAFL codebase implementing the [`Stage`](https://docs.rs/libafl/latest/libafl/stages/trait.Stage.html) trait.
|
||||||
|
@ -8,8 +8,8 @@ The LibAFL code reuse mechanism is based on components, rather than sub-classes,
|
|||||||
|
|
||||||
Thinking about similar fuzzers, you can observe that most of the time the data structures that are modified are the ones related to testcases and the fuzzer global state.
|
Thinking about similar fuzzers, you can observe that most of the time the data structures that are modified are the ones related to testcases and the fuzzer global state.
|
||||||
|
|
||||||
Beside the entities previously described, we introduce the [`Testcase`](https://docs.rs/libafl/0.6/libafl/corpus/testcase/struct.Testcase.html) and [`State`](https://docs.rs/libafl/0.6/libafl/state/struct.StdState.html) entities. The Testcase is a container for an Input stored in the Corpus and its metadata (so, in the implementation, the Corpus stores Testcases) and the State contains all the metadata that are evolved while running the fuzzer, Corpus included.
|
Beside the entities previously described, we introduce the [`Testcase`](https://docs.rs/libafl/latest/libafl/corpus/testcase/struct.Testcase.html) and [`State`](https://docs.rs/libafl/latest/libafl/state/struct.StdState.html) entities. The Testcase is a container for an Input stored in the Corpus and its metadata (so, in the implementation, the Corpus stores Testcases) and the State contains all the metadata that are evolved while running the fuzzer, Corpus included.
|
||||||
|
|
||||||
The State, in the implementation, contains only owned objects that are serializable, and it is serializable itself. Some fuzzers may want to serialize their state when pausing or just, when doing in-process fuzzing, serialize on crash and deserialize in the new process to continue to fuzz with all the metadata preserved.
|
The State, in the implementation, contains only owned objects that are serializable, and it is serializable itself. Some fuzzers may want to serialize their state when pausing or just, when doing in-process fuzzing, serialize on crash and deserialize in the new process to continue to fuzz with all the metadata preserved.
|
||||||
|
|
||||||
Additionally, we group the entities that are "actions", like the `CorpusScheduler` and the `Feedbacks`, in a common place, the [`Fuzzer'](https://docs.rs/libafl/*/libafl/fuzzer/struct.StdFuzzer.html).
|
Additionally, we group the entities that are "actions", like the `CorpusScheduler` and the `Feedbacks`, in a common place, the [`Fuzzer'](https://docs.rs/libafl/latest/libafl/fuzzer/struct.StdFuzzer.html).
|
||||||
|
@ -23,11 +23,11 @@ As an alternative to `derive(SerdeAny)` which is a proc-macro in `libafl_derive`
|
|||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Metadata objects are primarly intended to be used inside [`SerdeAnyMap`](https://docs.rs/libafl/0.5.0/libafl/bolts/serdeany/serdeany_registry/struct.SerdeAnyMap.html) and [`NamedSerdeAnyMap`](https://docs.rs/libafl/0.5.0/libafl/bolts/serdeany/serdeany_registry/struct.NamedSerdeAnyMap.html).
|
Metadata objects are primarly intended to be used inside [`SerdeAnyMap`](https://docs.rs/libafl_bolts/latest/libafl_bolts/serdeany/serdeany_registry/struct.SerdeAnyMap.html) and [`NamedSerdeAnyMap`](https://docs.rs/libafl_bolts/latest/libafl_bolts/serdeany/serdeany_registry/struct.NamedSerdeAnyMap.html).
|
||||||
|
|
||||||
With these maps, the user can retrieve instances by type (and name). Internally, the instances are stored as SerdeAny trait objects.
|
With these maps, the user can retrieve instances by type (and name). Internally, the instances are stored as SerdeAny trait objects.
|
||||||
|
|
||||||
Structs that want to have a set of metadata must implement the [`HasMetadata`](https://docs.rs/libafl/0.5.0/libafl/state/trait.HasMetadata.html) trait.
|
Structs that want to have a set of metadata must implement the [`HasMetadata`](https://docs.rs/libafl/latest/libafl/state/trait.HasMetadata.html) trait.
|
||||||
|
|
||||||
By default, Testcase and State implement it and hold a SerdeAnyMap testcase.
|
By default, Testcase and State implement it and hold a SerdeAnyMap testcase.
|
||||||
|
|
||||||
|
@ -31,7 +31,7 @@ You can choose the features by using `features = ["feature1", "feature2", ...]`
|
|||||||
Out of this list, by default, `std`, `derive`, and `rand_trait` are already set.
|
Out of this list, by default, `std`, `derive`, and `rand_trait` are already set.
|
||||||
You can choose to disable them by setting `default-features = false` in your `Cargo.toml`.
|
You can choose to disable them by setting `default-features = false` in your `Cargo.toml`.
|
||||||
|
|
||||||
### [`libafl_bolts`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl)
|
### [`libafl_bolts`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_bolts)
|
||||||
|
|
||||||
The `libafl_bolts` crate is a minimal tool shed filled with useful low-level rust features, not necessarily related to fuzzers.
|
The `libafl_bolts` crate is a minimal tool shed filled with useful low-level rust features, not necessarily related to fuzzers.
|
||||||
In it, you'll find highlights like:
|
In it, you'll find highlights like:
|
||||||
@ -46,20 +46,20 @@ In it, you'll find highlights like:
|
|||||||
|
|
||||||
... and much more.
|
... and much more.
|
||||||
|
|
||||||
### `libafl_sugar`
|
### [`libafl_sugar`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_sugar)
|
||||||
|
|
||||||
The sugar crate abstracts away most of the complexity of LibAFL's API.
|
The sugar crate abstracts away most of the complexity of LibAFL's API.
|
||||||
Instead of high flexibility, it aims to be high-level and easy-to-use.
|
Instead of high flexibility, it aims to be high-level and easy-to-use.
|
||||||
It is not as flexible as stitching your fuzzer together from each individual component, but allows you to build a fuzzer with minimal lines of code.
|
It is not as flexible as stitching your fuzzer together from each individual component, but allows you to build a fuzzer with minimal lines of code.
|
||||||
To see it in action, take a look at the [`libfuzzer_stb_image_sugar` example fuzzer](https://github.com/AFLplusplus/LibAFL/tree/main/fuzzers/libfuzzer_stb_image_sugar).
|
To see it in action, take a look at the [`libfuzzer_stb_image_sugar` example fuzzer](https://github.com/AFLplusplus/LibAFL/tree/main/fuzzers/libfuzzer_stb_image_sugar).
|
||||||
|
|
||||||
### `libafl_derive`
|
### [`libafl_derive`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_derive)
|
||||||
|
|
||||||
This a proc-macro crate paired with the `libafl` crate.
|
This a proc-macro crate paired with the `libafl` crate.
|
||||||
|
|
||||||
At the moment, it just exposes the `derive(SerdeAny)` macro that can be used to define Metadata structs, see the section about [Metadata](../design/metadata.md) for details.
|
At the moment, it just exposes the `derive(SerdeAny)` macro that can be used to define Metadata structs, see the section about [Metadata](../design/metadata.md) for details.
|
||||||
|
|
||||||
### `libafl_targets`
|
### [`libafl_targets`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_targets)
|
||||||
|
|
||||||
This crate exposes code to interact with, and to instrument, targets.
|
This crate exposes code to interact with, and to instrument, targets.
|
||||||
To enable and disable features at compile-time, the features are enabled and disabled using feature flags.
|
To enable and disable features at compile-time, the features are enabled and disabled using feature flags.
|
||||||
@ -71,32 +71,32 @@ Currently, the supported flags are:
|
|||||||
- `libfuzzer` exposes a compatibility layer with libFuzzer style harnesses.
|
- `libfuzzer` exposes a compatibility layer with libFuzzer style harnesses.
|
||||||
- `value_profile` defines the SanitizerCoverage trace-cmp hooks to track the matching bits of each comparison in a map.
|
- `value_profile` defines the SanitizerCoverage trace-cmp hooks to track the matching bits of each comparison in a map.
|
||||||
|
|
||||||
### `libafl_cc`
|
### [`libafl_cc`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_cc)
|
||||||
|
|
||||||
This is a library that provides utils to wrap compilers and create source-level fuzzers.
|
This is a library that provides utils to wrap compilers and create source-level fuzzers.
|
||||||
|
|
||||||
At the moment, only the Clang compiler is supported.
|
At the moment, only the Clang compiler is supported.
|
||||||
To understand it deeper, look through the tutorials and examples.
|
To understand it deeper, look through the tutorials and examples.
|
||||||
|
|
||||||
### `libafl_frida`
|
### [`libafl_frida`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_frida)
|
||||||
|
|
||||||
This library bridges LibAFL with Frida as instrumentation backend.
|
This library bridges LibAFL with Frida as instrumentation backend.
|
||||||
With this crate, you can instrument targets on Linux/macOS/Windows/Android for coverage collection.
|
With this crate, you can instrument targets on Linux/macOS/Windows/Android for coverage collection.
|
||||||
Additionally, it supports CmpLog, and AddressSanitizer instrumentation and runtimes for aarch64.
|
Additionally, it supports CmpLog, and AddressSanitizer instrumentation and runtimes for aarch64.
|
||||||
See further information, as well as usage instructions, [later in the book](../advanced_features/frida.md).
|
See further information, as well as usage instructions, [later in the book](../advanced_features/frida.md).
|
||||||
|
|
||||||
### `libafl_qemu`
|
### [`libafl_qemu`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_qemu)
|
||||||
|
|
||||||
This library bridges LibAFL with QEMU user-mode to fuzz ELF cross-platform binaries.
|
This library bridges LibAFL with QEMU user-mode to fuzz ELF cross-platform binaries.
|
||||||
|
|
||||||
It works on Linux and can collect edge coverage without collisions!
|
It works on Linux and can collect edge coverage without collisions!
|
||||||
It also supports a wide range of hooks and instrumentation options.
|
It also supports a wide range of hooks and instrumentation options.
|
||||||
|
|
||||||
### `libafl_nyx`
|
### [`libafl_nyx`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_nyx)
|
||||||
|
|
||||||
[Nyx](https://nyx-fuzz.com/) is a KVM-based snapshot fuzzer. `libafl_nyx` adds these capabilities to LibAFL. There is a specific section explaining usage of libafl_nyx [later in the book](../advanced_features/nyx.md).
|
[Nyx](https://nyx-fuzz.com/) is a KVM-based snapshot fuzzer. `libafl_nyx` adds these capabilities to LibAFL. There is a specific section explaining usage of libafl_nyx [later in the book](../advanced_features/nyx.md).
|
||||||
|
|
||||||
### `libafl_concolic`
|
### [`libafl_concolic`](https://github.com/AFLplusplus/LibAFL/tree/main/libafl_concolic)
|
||||||
|
|
||||||
Concolic fuzzing is the combination of fuzzing and a symbolic execution engine.
|
Concolic fuzzing is the combination of fuzzing and a symbolic execution engine.
|
||||||
This can reach greater depth than normal fuzzing, and is exposed in this crate.
|
This can reach greater depth than normal fuzzing, and is exposed in this crate.
|
||||||
|
@ -22,9 +22,9 @@ $ git clone https://github.com/AFLplusplus/LibAFL.git
|
|||||||
Alternatively, on a UNIX-like machine, you can download a compressed archive and extract it with:
|
Alternatively, on a UNIX-like machine, you can download a compressed archive and extract it with:
|
||||||
|
|
||||||
```sh
|
```sh
|
||||||
wget https://github.com/AFLplusplus/LibAFL/archive/main.tar.gz
|
$ wget https://github.com/AFLplusplus/LibAFL/archive/main.tar.gz
|
||||||
$ tar xvf LibAFL-main.tar.gz
|
$ tar xvf main.tar.gz
|
||||||
$ rm LibAFL-main.tar.gz
|
$ rm main.tar.gz
|
||||||
$ ls LibAFL-main # this is the extracted folder
|
$ ls LibAFL-main # this is the extracted folder
|
||||||
```
|
```
|
||||||
|
|
||||||
|
@ -78,7 +78,7 @@ They are the default if using LibAFL's `Launcher`.
|
|||||||
If you should want to use `LLMP` in its raw form, without any `LibAFL` abstractions, take a look at the `llmp_test` example in [./libafl/examples](https://github.com/AFLplusplus/LibAFL/blob/main/libafl/examples/llmp_test/main.rs).
|
If you should want to use `LLMP` in its raw form, without any `LibAFL` abstractions, take a look at the `llmp_test` example in [./libafl/examples](https://github.com/AFLplusplus/LibAFL/blob/main/libafl/examples/llmp_test/main.rs).
|
||||||
You can run the example using `cargo run --example llmp_test` with the appropriate modes, as indicated by its help output.
|
You can run the example using `cargo run --example llmp_test` with the appropriate modes, as indicated by its help output.
|
||||||
First, you will have to create a broker using `LlmpBroker::new()`.
|
First, you will have to create a broker using `LlmpBroker::new()`.
|
||||||
Then, create some `LlmpClient``s` in other threads and register them with the main thread using `LlmpBroker::register_client`.
|
Then, create some `LlmpClient`s in other threads and register them with the main thread using `LlmpBroker::register_client`.
|
||||||
Finally, call `LlmpBroker::loop_forever()`.
|
Finally, call `LlmpBroker::loop_forever()`.
|
||||||
|
|
||||||
### B2B: Connecting Fuzzers via TCP
|
### B2B: Connecting Fuzzers via TCP
|
||||||
|
@ -13,7 +13,7 @@ If the port is not yet bound, this instance becomes the broker, binding itself t
|
|||||||
If the port is already bound, the EventManager will try to connect to it.
|
If the port is already bound, the EventManager will try to connect to it.
|
||||||
The instance becomes a client and can now communicate with all other nodes.
|
The instance becomes a client and can now communicate with all other nodes.
|
||||||
|
|
||||||
Launching nodes manually has the benefit that you can have multiple nodes with different configurations, such as clients fuzzing with and without `ASan``.
|
Launching nodes manually has the benefit that you can have multiple nodes with different configurations, such as clients fuzzing with and without `ASan`.
|
||||||
|
|
||||||
While it's called "restarting" manager, it uses `fork` on Unix-like operating systems as optimization and only actually restarts from scratch on Windows.
|
While it's called "restarting" manager, it uses `fork` on Unix-like operating systems as optimization and only actually restarts from scratch on Windows.
|
||||||
|
|
||||||
|
Loading…
x
Reference in New Issue
Block a user