From 526ae7526245b997ecae2cfd90cf45a819f16238 Mon Sep 17 00:00:00 2001 From: Dominik Maier Date: Wed, 9 Dec 2020 16:34:33 +0100 Subject: [PATCH] added some comments --- afl/src/corpus/mod.rs | 3 +++ afl/src/engines/mod.rs | 4 ++++ afl/src/events/shmem_translated.rs | 12 ++++++------ afl/src/executors/inmemory.rs | 8 ++++++-- afl/src/executors/mod.rs | 2 ++ afl/src/feedbacks/mod.rs | 15 ++++++++++----- afl/src/generators/mod.rs | 14 ++++++++++---- afl/src/lib.rs | 4 ++++ afl/src/mutators/mod.rs | 6 ++++++ afl/src/mutators/mutations.rs | 3 +++ afl/src/observers/mod.rs | 3 +++ afl/src/stages/mod.rs | 2 ++ afl/src/stages/mutational.rs | 3 +++ 13 files changed, 62 insertions(+), 17 deletions(-) diff --git a/afl/src/corpus/mod.rs b/afl/src/corpus/mod.rs index a2885d6579..f0ff8f247d 100644 --- a/afl/src/corpus/mod.rs +++ b/afl/src/corpus/mod.rs @@ -14,6 +14,7 @@ use crate::inputs::Input; use crate::utils::Rand; use crate::AflError; +/// A way to obtain the containing testcase entries pub trait HasTestcaseVec where I: Input, @@ -111,6 +112,7 @@ where fn current_testcase(&self) -> (&RefCell>, usize); } +/// A corpus handling all important fuzzing in memory. pub struct InMemoryCorpus where I: Input, @@ -171,6 +173,7 @@ where } } +/// A corpus able to store testcases to dis, and load them from disk, when they are being used. #[cfg(feature = "std")] pub struct OnDiskCorpus where diff --git a/afl/src/engines/mod.rs b/afl/src/engines/mod.rs index 387f7456d5..ff3c0466cd 100644 --- a/afl/src/engines/mod.rs +++ b/afl/src/engines/mod.rs @@ -21,13 +21,17 @@ pub trait StateMetadata: Debug { fn name(&self) -> &'static str; } +/// The state a fuzz run. pub struct State where I: Input, R: Rand, { + /// How many times the executor ran the harness/target executions: usize, + /// At what time the fuzzing started start_time: u64, + /// Metadata stored for this state by one of the components metadatas: HashMap<&'static str, Box>, // additional_corpuses: HashMap<&'static str, Box>, feedbacks: Vec>>, diff --git a/afl/src/events/shmem_translated.rs b/afl/src/events/shmem_translated.rs index dbe195dcdd..1506c805d9 100644 --- a/afl/src/events/shmem_translated.rs +++ b/afl/src/events/shmem_translated.rs @@ -23,7 +23,7 @@ extern "C" { } #[derive(Copy, Clone)] #[repr(C)] -pub struct ipc_perm { +struct ipc_perm { pub __key: c_int, pub uid: c_uint, pub gid: c_uint, @@ -39,7 +39,7 @@ pub struct ipc_perm { #[derive(Copy, Clone)] #[repr(C)] -pub struct shmid_ds { +struct shmid_ds { pub shm_perm: ipc_perm, pub shm_segsz: c_ulong, pub shm_atime: c_long, @@ -135,7 +135,7 @@ impl AflShmem { } /// Deinitialize this shmem instance -pub unsafe fn afl_shmem_deinit(shm: *mut AflShmem) { +unsafe fn afl_shmem_deinit(shm: *mut AflShmem) { if shm.is_null() || (*shm).map.is_null() { /* Serialized map id */ // Not set or not initialized; @@ -148,7 +148,7 @@ pub unsafe fn afl_shmem_deinit(shm: *mut AflShmem) { /// Functions to create Shared memory region, for observation channels and /// opening inputs and stuff. -pub unsafe fn afl_shmem_init(shm: *mut AflShmem, map_size: usize) -> *mut c_uchar { +unsafe fn afl_shmem_init(shm: *mut AflShmem, map_size: usize) -> *mut c_uchar { (*shm).map_size = map_size; (*shm).map = 0 as *mut c_uchar; (*shm).shm_id = shmget( @@ -180,7 +180,7 @@ pub unsafe fn afl_shmem_init(shm: *mut AflShmem, map_size: usize) -> *mut c_ucha } /// Uses a shmap id string to open a shared map -pub unsafe fn afl_shmem_by_str( +unsafe fn afl_shmem_by_str( shm: *mut AflShmem, shm_str: &CStr, map_size: usize, @@ -211,7 +211,7 @@ pub unsafe fn afl_shmem_by_str( } /// Write sharedmap as env var and the size as name#_SIZE -pub unsafe fn afl_shmem_to_env_var(shmem: &AflShmem, env_name: &CStr) -> c_uint { +unsafe fn afl_shmem_to_env_var(shmem: &AflShmem, env_name: &CStr) -> c_uint { let env_len = env_name.to_bytes().len(); if env_len == 0 || env_len > 200 || (*shmem).shm_str[0 as c_int as usize] == 0 { return AFL_RET_NULL_PTR; diff --git a/afl/src/executors/inmemory.rs b/afl/src/executors/inmemory.rs index e2fd5ceb63..de68ad85a7 100644 --- a/afl/src/executors/inmemory.rs +++ b/afl/src/executors/inmemory.rs @@ -6,8 +6,14 @@ use crate::inputs::Input; use crate::observers::observer_serde::NamedSerdeAnyMap; use crate::AflError; +/// The (unsafe) pointer to the current inmem executor, for the current run. +/// This is neede for certain non-rust side effects, as well as unix signal handling. +static mut CURRENT_INMEMORY_EXECUTOR_PTR: *const c_void = ptr::null(); + +/// The inmem executor harness type HarnessFunction = fn(&dyn Executor, &[u8]) -> ExitKind; +/// The inmem executor simply calls a target function, then returns afterwards. pub struct InMemoryExecutor where I: Input, @@ -16,8 +22,6 @@ where observers: NamedSerdeAnyMap, } -static mut CURRENT_INMEMORY_EXECUTOR_PTR: *const c_void = ptr::null(); - impl Executor for InMemoryExecutor where I: Input, diff --git a/afl/src/executors/mod.rs b/afl/src/executors/mod.rs index 7a5ae847fc..a1b39f0feb 100644 --- a/afl/src/executors/mod.rs +++ b/afl/src/executors/mod.rs @@ -7,6 +7,7 @@ use crate::observers::observer_serde::NamedSerdeAnyMap; use crate::observers::Observer; use crate::AflError; +/// How an execution finished. pub enum ExitKind { Ok, Crash, @@ -14,6 +15,7 @@ pub enum ExitKind { Timeout, } +/// An executor takes the given inputs, and runs the harness/target. pub trait Executor where I: Input, diff --git a/afl/src/feedbacks/mod.rs b/afl/src/feedbacks/mod.rs index acaf44d453..9117333c1f 100644 --- a/afl/src/feedbacks/mod.rs +++ b/afl/src/feedbacks/mod.rs @@ -8,6 +8,15 @@ use crate::observers::observer_serde::NamedSerdeAnyMap; use crate::observers::MapObserver; use crate::AflError; +pub type MaxMapFeedback = MapFeedback, O>; +pub type MinMapFeedback = MapFeedback, O>; + +//pub type MaxMapTrackerFeedback = MapFeedback, O>; +//pub type MinMapTrackerFeedback = MapFeedback, O>; + +/// Feedbacks evaluate the observers. +/// Basically, they reduce the information provided by an observer to a value, +/// indicating the "interestingness" of the last run. pub trait Feedback where I: Input, @@ -25,6 +34,7 @@ where Ok(()) } + /// The name of this feedback fn name(&self) -> &'static str; } @@ -291,8 +301,3 @@ where } */ -pub type MaxMapFeedback = MapFeedback, O>; -pub type MinMapFeedback = MapFeedback, O>; - -//pub type MaxMapTrackerFeedback = MapFeedback, O>; -//pub type MinMapTrackerFeedback = MapFeedback, O>; diff --git a/afl/src/generators/mod.rs b/afl/src/generators/mod.rs index b3b6f5e112..64f1f3d2ac 100644 --- a/afl/src/generators/mod.rs +++ b/afl/src/generators/mod.rs @@ -7,6 +7,10 @@ use crate::inputs::Input; use crate::utils::Rand; use crate::AflError; +/// The maximum size of dummy bytes generated by _dummy generator methods +const DUMMY_BYTES_MAX: usize = 64; + +/// Generators can generate ranges of bytes. pub trait Generator where I: Input, @@ -19,8 +23,7 @@ where fn generate_dummy(&self) -> I; } -const DUMMY_BYTES_SIZE: usize = 64; - +/// Generates random bytes pub struct RandBytesGenerator where R: Rand, @@ -42,8 +45,9 @@ where Ok(BytesInput::new(random_bytes)) } + /// Generates up to DUMMY_BYTES_MAX non-random dummy bytes (0) fn generate_dummy(&self) -> BytesInput { - let size = min(self.max_size, DUMMY_BYTES_SIZE); + let size = min(self.max_size, DUMMY_BYTES_MAX); BytesInput::new(vec![0; size]) } } @@ -60,6 +64,7 @@ where } } +/// Generates random printable characters pub struct RandPrintablesGenerator { max_size: usize, phantom: PhantomData, @@ -81,8 +86,9 @@ where Ok(BytesInput::new(random_bytes)) } + /// Generates up to DUMMY_BYTES_MAX non-random dummy bytes (0) fn generate_dummy(&self) -> BytesInput { - let size = min(self.max_size, DUMMY_BYTES_SIZE); + let size = min(self.max_size, DUMMY_BYTES_MAX); BytesInput::new(vec!['0' as u8; size]) } } diff --git a/afl/src/lib.rs b/afl/src/lib.rs index c19f048093..ded495487e 100644 --- a/afl/src/lib.rs +++ b/afl/src/lib.rs @@ -1,3 +1,7 @@ +/*! +Welcome to libAFL +*/ + #![cfg_attr(not(feature = "std"), no_std)] #[macro_use] diff --git a/afl/src/mutators/mod.rs b/afl/src/mutators/mod.rs index 2b32fc740a..c8f7562e3b 100644 --- a/afl/src/mutators/mod.rs +++ b/afl/src/mutators/mod.rs @@ -8,6 +8,8 @@ use crate::inputs::Input; use crate::utils::Rand; use crate::AflError; +/// A mutator takes input, and mutates it. +/// Simple as that. pub trait Mutator where C: Corpus, @@ -34,9 +36,13 @@ where } } +/// The maximum size of a testcase pub const DEFAULT_MAX_SIZE: usize = 1048576; +/// Interact with the maximum size pub trait HasMaxSize { + /// The maximum size of the contents returned fn max_size(&self) -> usize; + /// Sets the maximum size of the contents returned fn set_max_size(&mut self, max_size: usize); } diff --git a/afl/src/mutators/mutations.rs b/afl/src/mutators/mutations.rs index 64c3aa5bce..1e4fe95fa1 100644 --- a/afl/src/mutators/mutations.rs +++ b/afl/src/mutators/mutations.rs @@ -4,6 +4,9 @@ use crate::mutators::*; use crate::utils::Rand; use crate::AflError; +/// The result of a mutation. +/// If the mutation got skipped, the target +/// will not be executed with the returned input. pub enum MutationResult { Mutated, Skipped, diff --git a/afl/src/observers/mod.rs b/afl/src/observers/mod.rs index 1aaa3b2b3b..518505b7b5 100644 --- a/afl/src/observers/mod.rs +++ b/afl/src/observers/mod.rs @@ -60,6 +60,9 @@ where } } +/// The Map Observer retrieves the state of a map, +/// that will get updated by the target. +/// A well-known example is the AFL-Style coverage map. #[derive(Serialize, Deserialize)] pub struct StdMapObserver where diff --git a/afl/src/stages/mod.rs b/afl/src/stages/mod.rs index 066adb28dd..202d539056 100644 --- a/afl/src/stages/mod.rs +++ b/afl/src/stages/mod.rs @@ -9,6 +9,8 @@ use crate::inputs::Input; use crate::utils::Rand; use crate::AflError; +/// A stage is one step in the fuzzing process. +/// Multiple stages will be scheduled one by one for each input. pub trait Stage where EM: EventManager, diff --git a/afl/src/stages/mutational.rs b/afl/src/stages/mutational.rs index 44922f8e04..4db004a742 100644 --- a/afl/src/stages/mutational.rs +++ b/afl/src/stages/mutational.rs @@ -14,6 +14,9 @@ use crate::serde_anymap::{Ptr, PtrMut}; // TODO multi mutators stage +/// A Mutational stage is the stage in a fuzzing run that mutates inputs. +/// Mutational stages will usually have a range of mutations that are +/// being applied to the input one by one. pub trait MutationalStage: Stage where M: Mutator,