From 21301f2cf83e8c0d582183800a1e571d5f223bf8 Mon Sep 17 00:00:00 2001 From: Andrea Fioraldi Date: Tue, 16 Mar 2021 10:53:32 +0100 Subject: [PATCH] more doc --- libafl/src/bolts/ownedref.rs | 17 +++++++++++++++++ libafl/src/bolts/serdeany.rs | 1 + libafl/src/corpus/minimizer.rs | 12 ++++++++++++ libafl/src/corpus/mod.rs | 3 +++ libafl/src/corpus/queue.rs | 5 +++-- 5 files changed, 36 insertions(+), 2 deletions(-) diff --git a/libafl/src/bolts/ownedref.rs b/libafl/src/bolts/ownedref.rs index 968b7bc4ce..979f3fb00d 100644 --- a/libafl/src/bolts/ownedref.rs +++ b/libafl/src/bolts/ownedref.rs @@ -1,6 +1,11 @@ +//! Wrappers that abstracts references (or pointers) and owned data accesses. +// The serialization is towards owned, allowing to serialize pointers without troubles. + use alloc::{boxed::Box, vec::Vec}; +use core::{clone::Clone, fmt::Debug}; use serde::{Deserialize, Deserializer, Serialize, Serializer}; +/// Wrap a reference and convert to a Box on serialize #[derive(Clone, Debug)] pub enum Ptr<'a, T: 'a + ?Sized> { Ref(&'a T), @@ -40,6 +45,8 @@ impl<'a, T: Sized> AsRef for Ptr<'a, T> { } } +/// Wrap a mutable reference and convert to a Box on serialize +#[derive(Debug)] pub enum PtrMut<'a, T: 'a + ?Sized> { Ref(&'a mut T), Owned(Box), @@ -87,6 +94,8 @@ impl<'a, T: Sized> AsMut for PtrMut<'a, T> { } } +/// Wrap a slice and convert to a Vec on serialize +#[derive(Clone, Debug)] pub enum Slice<'a, T: 'a + Sized> { Ref(&'a [T]), Owned(Vec), @@ -125,6 +134,8 @@ impl<'a, T: Sized> Slice<'a, T> { } } +/// Wrap a mutable slice and convert to a Vec on serialize +#[derive(Debug)] pub enum SliceMut<'a, T: 'a + Sized> { Ref(&'a mut [T]), Owned(Vec), @@ -170,6 +181,7 @@ impl<'a, T: Sized> SliceMut<'a, T> { } } +/// Wrap a C-style pointer and convert to a Box on serialize #[derive(Clone, Debug)] pub enum Cptr { Cptr(*const T), @@ -206,6 +218,8 @@ impl AsRef for Cptr { } } +/// Wrap a C-style mutable pointer and convert to a Box on serialize +#[derive(Clone, Debug)] pub enum CptrMut { Cptr(*mut T), Owned(Box), @@ -250,6 +264,8 @@ impl AsMut for CptrMut { } } +/// Wrap a C-style pointer to an array (with size= and convert to a Vec on serialize +#[derive(Clone, Debug)] pub enum Array { Cptr((*const T, usize)), Owned(Vec), @@ -285,6 +301,7 @@ impl Array { } } +/// Wrap a C-style mutable pointer to an array (with size= and convert to a Vec on serialize #[derive(Clone, Debug)] pub enum ArrayMut { Cptr((*mut T, usize)), diff --git a/libafl/src/bolts/serdeany.rs b/libafl/src/bolts/serdeany.rs index 01a2a2e85f..50e3d6034f 100644 --- a/libafl/src/bolts/serdeany.rs +++ b/libafl/src/bolts/serdeany.rs @@ -1,4 +1,5 @@ //! Poor-rust-man's downcasts for stuff we send over the wire (or shared maps) + use serde::{Deserialize, Deserializer, Serialize, Serializer}; use alloc::boxed::Box; diff --git a/libafl/src/corpus/minimizer.rs b/libafl/src/corpus/minimizer.rs index 0520d98734..475688909b 100644 --- a/libafl/src/corpus/minimizer.rs +++ b/libafl/src/corpus/minimizer.rs @@ -1,3 +1,6 @@ +//! The Minimizer schedulers are a family of corpus schedulers that feed the fuzzer +// with testcases only from a subset of the total corpus. + use crate::{ bolts::serdeany::SerdeAny, corpus::{Corpus, CorpusScheduler, Testcase}, @@ -43,6 +46,7 @@ impl Default for TopRatedsMetadata { } } +/// Compute the favor factor of a testcase. Lower is better. pub trait FavFactor where I: Input, @@ -50,6 +54,8 @@ where fn compute(testcase: &mut Testcase) -> Result; } +/// Multiply the testcase size with the execution time. +/// This favors small and quick testcases. pub struct LenTimeMulFavFactor where I: Input + HasLen, @@ -67,6 +73,9 @@ where } } +/// The Minimizer scheduler employs a genetic algorithm to compute a subset of the +/// corpus that exercise all the requested features (e.g. all the coverage seen so far) +/// prioritizing testcases using FavFactor pub struct MinimizerCorpusScheduler where CS: CorpusScheduler, @@ -230,8 +239,11 @@ where } } +/// A MinimizerCorpusScheduler with LenTimeMulFavFactor to prioritize quick and small testcases pub type LenTimeMinimizerCorpusScheduler = MinimizerCorpusScheduler, I, M, R, S>; +/// A MinimizerCorpusScheduler with LenTimeMulFavFactor to prioritize quick and small testcases +/// that exercise all the entries registered in the MapIndexesMetadata pub type IndexesLenTimeMinimizerCorpusScheduler = MinimizerCorpusScheduler, I, MapIndexesMetadata, R, S>; diff --git a/libafl/src/corpus/mod.rs b/libafl/src/corpus/mod.rs index 3f48ffa0c7..73849fb871 100644 --- a/libafl/src/corpus/mod.rs +++ b/libafl/src/corpus/mod.rs @@ -63,6 +63,8 @@ where fn current_mut(&mut self) -> &mut Option; } +/// The scheduler define how the fuzzer requests a testcase from the corpus. +/// It has hooks to corpus add/replace/remove to allow complex scheduling algorithms to collect data. pub trait CorpusScheduler where I: Input, @@ -96,6 +98,7 @@ where fn next(&self, state: &mut S) -> Result; } +/// Feed the fuzzer simpply with a random testcase on request pub struct RandCorpusScheduler where S: HasCorpus + HasRand, diff --git a/libafl/src/corpus/queue.rs b/libafl/src/corpus/queue.rs index 3edb0f0833..89b10b945f 100644 --- a/libafl/src/corpus/queue.rs +++ b/libafl/src/corpus/queue.rs @@ -1,4 +1,4 @@ -//! The queue corpus implements an afl-like queue mechanism +//! The queue corpus scheduler implements an AFL-like queue mechanism use alloc::borrow::ToOwned; use core::marker::PhantomData; @@ -10,6 +10,7 @@ use crate::{ Error, }; +/// Walk the corpus in a queue-like fashion pub struct QueueCorpusScheduler where S: HasCorpus, @@ -25,7 +26,7 @@ where C: Corpus, I: Input, { - /// Gets the next entry at random + /// Gets the next entry in the queue fn next(&self, state: &mut S) -> Result { if state.corpus().count() == 0 { Err(Error::Empty("No entries in corpus".to_owned()))