Skip to content

Building 70 Projects ranging from beginner to advanced so anyone can β€” learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company πŸ‘‡

feat(lisdex): M6.2 - parallel campaigns, and the coverage curve that silently vanished when they ran

CarterPerez-dev14afd724e6ba
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/runner.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/runner.rs
index 0b2acd1e..f3269cb3 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/runner.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/runner.rs
@@ -35,7 +35,12 @@ const ARG_CMPLOG: &str = "-c";
const ARG_DURATION: &str = "-V";
const ARG_SKIP_DETERMINISTIC: &str = "-d";
const ARG_DICTIONARY: &str = "-x";
+const ARG_MAIN: &str = "-M";
+const ARG_SECONDARY: &str = "-S";
+const ARG_SCHEDULE: &str = "-p";
const ARG_SEPARATOR: &str = "--";
+const ENV_FINAL_SYNC: &str = "AFL_FINAL_SYNC";
+
const ENV_SKIP_CPUFREQ: &str = "AFL_SKIP_CPUFREQ";
const ENV_NO_AFFINITY: &str = "AFL_NO_AFFINITY";
const ENV_NO_UI: &str = "AFL_NO_UI";
@@ -43,6 +48,45 @@ const ENV_MISSING_CRASHES: &str = "AFL_I_DONT_CARE_ABOUT_MISSING_CRASHES";
const ENV_BENCH_UNTIL_CRASH: &str = "AFL_BENCH_UNTIL_CRASH";
const ENV_ENABLED: &str = "1";
+pub const MAIN_INSTANCE: &str = "main";
+pub const SECONDARY_PREFIX: &str = "secondary";
+pub const SECONDARY_SCHEDULES: [&str; 6] = ["fast", "coe", "lin", "quad", "exploit", "rare"];
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Instance {
+ Main(String),
+ Secondary { name: String, schedule: String },
+}
+
+impl Instance {
+ #[must_use]
+ pub fn name(&self) -> &str {
+ match self {
+ Self::Main(name) | Self::Secondary { name, .. } => name,
+ }
+ }
+
+ #[must_use]
+ pub fn is_main(&self) -> bool {
+ matches!(self, Self::Main(_))
+ }
+}
+
+#[must_use]
+pub fn instance_plan(jobs: usize) -> Vec<Instance> {
+ if jobs <= 1 {
+ return Vec::new();
+ }
+ let mut plan = vec![Instance::Main(MAIN_INSTANCE.to_owned())];
+ for index in 0..jobs - 1 {
+ plan.push(Instance::Secondary {
+ name: format!("{SECONDARY_PREFIX}{}", index + 1),
+ schedule: SECONDARY_SCHEDULES[index % SECONDARY_SCHEDULES.len()].to_owned(),
+ });
+ }
+ plan
+}
+
#[derive(Debug, thiserror::Error)]
pub enum RunnerError {
#[error("io error: {0}")]
@@ -78,6 +122,7 @@ pub struct AflOptions {
pub bench_until_crash: bool,
pub skip_deterministic: bool,
pub dictionaries: Vec<PathBuf>,
+ pub instance: Option<Instance>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -118,6 +163,20 @@ impl AflOptions {
args.push(dictionary.display().to_string());
}
+ match &self.instance {
+ Some(Instance::Main(name)) => {
+ args.push(ARG_MAIN.to_owned());
+ args.push(name.clone());
+ }
+ Some(Instance::Secondary { name, schedule }) => {
+ args.push(ARG_SECONDARY.to_owned());
+ args.push(name.clone());
+ args.push(ARG_SCHEDULE.to_owned());
+ args.push(schedule.clone());
+ }
+ None => {}
+ }
+
args.push(ARG_SEPARATOR.to_owned());
args.push(self.target.display().to_string());
@@ -130,6 +189,9 @@ impl AflOptions {
if self.bench_until_crash {
envs.push((ENV_BENCH_UNTIL_CRASH.to_owned(), ENV_ENABLED.to_owned()));
}
+ if self.instance.as_ref().is_some_and(Instance::is_main) {
+ envs.push((ENV_FINAL_SYNC.to_owned(), ENV_ENABLED.to_owned()));
+ }
AflInvocation {
program: AFL_FUZZ_BIN.to_owned(),
@@ -199,6 +261,30 @@ pub fn read_stats_text(findings: &Path) -> Result<String, RunnerError> {
Ok(std::fs::read_to_string(path)?)
}
+pub fn read_all_stats(findings: &Path) -> Result<Vec<FuzzerStats>, RunnerError> {
+ let mut all = Vec::new();
+ for dir in instance_dirs(findings)? {
+ let text = std::fs::read_to_string(dir.join(STATS_FILE_NAME))?;
+ all.push(FuzzerStats::parse(&text)?);
+ }
+ Ok(all)
+}
+
+#[must_use]
+pub fn combine_stats(instances: &[FuzzerStats]) -> Option<FuzzerStats> {
+ let first = instances.first()?;
+ let mut combined = first.clone();
+ for stats in instances.iter().skip(1) {
+ combined.execs_done += stats.execs_done;
+ combined.execs_per_sec += stats.execs_per_sec;
+ combined.saved_crashes += stats.saved_crashes;
+ combined.edges_found = combined.edges_found.max(stats.edges_found);
+ combined.bitmap_coverage_pct = combined.bitmap_coverage_pct.max(stats.bitmap_coverage_pct);
+ combined.total_edges = combined.total_edges.max(stats.total_edges);
+ }
+ Some(combined)
+}
+
pub fn reproduce(
target: &Path,
input: &Path,
@@ -325,6 +411,42 @@ pub fn run(options: &AflOptions) -> Result<RunOutcome, RunnerError> {
})
}
+pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, RunnerError> {
+ let plan = instance_plan(jobs);
+ if plan.is_empty() {
+ return run(base);
+ }
+ if let Some(parent) = base.findings.parent() {
+ std::fs::create_dir_all(parent)?;
+ }
+
+ let mut children = Vec::new();
+ for instance in plan {
+ let mut options = base.clone();
+ options.instance = Some(instance);
+ let invocation = options.invocation();
+ let mut command = Command::new(&invocation.program);
+ command.args(&invocation.args);
+ for (key, value) in &invocation.envs {
+ command.env(key, value);
+ }
+ command.stdout(Stdio::null()).stderr(Stdio::null());
+ children.push(command.spawn()?);
+ }
+
+ let mut clean_exit = true;
+ for mut child in children {
+ let status = child.wait()?;
+ clean_exit = clean_exit && status.success();
+ }
+
+ let instances = read_all_stats(&base.findings)?;
+ let stats = combine_stats(&instances).ok_or(RunnerError::AflFailed {
+ status: "no instance wrote fuzzer_stats".to_owned(),
+ })?;
+ Ok(RunOutcome { clean_exit, stats })
+}
+
#[cfg(test)]
mod tests {
use super::*;
@@ -339,9 +461,133 @@ mod tests {
bench_until_crash: true,
skip_deterministic: true,
dictionaries: Vec::new(),
+ instance: None,
+ }
+ }
+
+ #[test]
+ fn a_single_job_campaign_names_no_instance_at_all() {
+ assert!(
+ instance_plan(1).is_empty(),
+ "-M on a lone fuzzer costs trimming and buys nothing, so one job stays the plain single-instance invocation it already was"
+ );
+ assert!(instance_plan(0).is_empty());
+ let args = options().invocation().args;
+ assert!(!args.contains(&ARG_MAIN.to_owned()) && !args.contains(&ARG_SECONDARY.to_owned()));
+ }
+
+ #[test]
+ fn a_parallel_plan_has_exactly_one_main_and_unique_names() {
+ let plan = instance_plan(5);
+ assert_eq!(plan.len(), 5);
+ assert_eq!(
+ plan.iter().filter(|instance| instance.is_main()).count(),
+ 1,
+ "afl-fuzz syncs through a single main; a second one would leave two queues claiming to be authoritative"
+ );
+ let mut names: Vec<&str> = plan.iter().map(Instance::name).collect();
+ names.sort_unstable();
+ let unique = names.len();
+ names.dedup();
+ assert_eq!(
+ names.len(),
+ unique,
+ "every -M/-S name has to be unique or the instances collide in one output directory"
+ );
+ }
+
+ #[test]
+ fn the_main_instance_carries_the_final_sync_afl_documents() {
+ let mut options = options();
+ options.instance = Some(Instance::Main(MAIN_INSTANCE.to_owned()));
+ let invocation = options.invocation();
+ assert!(invocation.args.windows(2).any(|pair| pair[0] == ARG_MAIN));
+ assert!(
+ invocation.envs.iter().any(|(key, _)| key == ENV_FINAL_SYNC),
+ "without a final sync the main's queue can miss what the secondaries found just before the deadline"
+ );
+ }
+
+ #[test]
+ fn a_secondary_carries_a_power_schedule_and_no_final_sync() {
+ let mut options = options();
+ options.instance = Some(Instance::Secondary {
+ name: "secondary1".to_owned(),
+ schedule: "fast".to_owned(),
+ });
+ let invocation = options.invocation();
+ let args = invocation.args;
+ assert!(args.windows(2).any(|pair| pair[0] == ARG_SECONDARY));
+ assert!(
+ args.windows(2)
+ .any(|pair| pair[0] == ARG_SCHEDULE && pair[1] == "fast"),
+ "-p is the power schedule and -P is the mutation strategy; they are different flags that share value names"
+ );
+ assert!(!invocation.envs.iter().any(|(key, _)| key == ENV_FINAL_SYNC));
+ }
+
+ #[test]
+ fn secondaries_vary_their_schedules_rather_than_all_running_the_default() {
+ let plan = instance_plan(4);
+ let schedules: Vec<&str> = plan
+ .iter()
+ .filter_map(|instance| match instance {
+ Instance::Secondary { schedule, .. } => Some(schedule.as_str()),
+ Instance::Main(_) => None,
+ })
+ .collect();
+ assert_eq!(schedules.len(), 3);
+ let mut unique = schedules.clone();
+ unique.sort_unstable();
+ unique.dedup();
+ assert_eq!(
+ unique.len(),
+ schedules.len(),
+ "AFL++ recommends running each secondary on a different power schedule; identical secondaries would explore the same way and waste the cores"
+ );
+ for schedule in schedules {
+ assert!(
+ SECONDARY_SCHEDULES.contains(&schedule),
+ "{schedule} is not one of the schedules afl-fuzz accepts, and an unknown -p value stops the campaign at startup"
+ );
}
}
+ #[test]
+ fn combined_stats_add_the_work_and_never_add_the_coverage() {
+ let mut first = FuzzerStats {
+ execs_done: 100,
+ execs_per_sec: 10.0,
+ saved_crashes: 2,
+ bitmap_coverage_pct: 5.0,
+ edges_found: 500,
+ total_edges: 1000,
+ afl_version: "5.02c".to_owned(),
+ };
+ let second = FuzzerStats {
+ execs_done: 50,
+ execs_per_sec: 4.0,
+ saved_crashes: 3,
+ bitmap_coverage_pct: 6.0,
+ edges_found: 600,
+ ..first.clone()
+ };
+ first.afl_version = "5.02c".to_owned();
+ let combined = combine_stats(&[first, second]).expect("two instances combine");
+ assert_eq!(combined.execs_done, 150);
+ assert_eq!(combined.saved_crashes, 5);
+ assert_eq!(
+ combined.edges_found, 600,
+ "instances share one coverage map and sync, so adding their edge counts would report coverage the campaign never had; the best instance is an honest lower bound on the union"
+ );
+ assert_eq!(combined.total_edges, 1000);
+ }
+
+ #[test]
+ fn combining_nothing_yields_nothing_rather_than_a_zeroed_campaign() {
+ assert_eq!(combine_stats(&[]), None);
+ }
+
#[test]
fn each_dictionary_becomes_its_own_flag() {
let mut options = options();
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rs
index cd5b776e..a5031ae0 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rs
@@ -284,6 +284,12 @@ struct FuzzArgs {
help = "directory of format dictionaries to select from (defaults to the ones AFL++ ships)"
)]
dict_dir: Option<PathBuf>,
+ #[arg(
+ long,
+ default_value_t = 1,
+ help = "parallel afl-fuzz instances sharing one findings directory: one main and the rest secondaries"
+ )]
+ jobs: usize,
}
#[derive(clap::Args)]
@@ -1232,12 +1238,16 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
bench_until_crash: args.until_crash,
skip_deterministic: args.skip_deterministic,
dictionaries,
+ instance: None,
};
println!("campaign {} target {label}", campaign_id.0);
+ for instance in runner::instance_plan(args.jobs) {
+ println!("instance {}", instance.name());
+ }
println!("running {}", runner::AFL_FUZZ_BIN);
- let outcome = match runner::run(&options) {
+ let outcome = match runner::run_parallel(&options, args.jobs) {
Ok(outcome) => outcome,
Err(err) => {
fail_campaign(&store, &mut campaign, campaign_id);
@@ -1439,10 +1449,21 @@ fn coverage(args: &CoverageArgs) -> Result<(), Box<dyn Error>> {
Ok(())
}
+fn curve_source(findings: &std::path::Path) -> Result<PathBuf, Box<dyn Error>> {
+ let dirs = runner::instance_dirs(findings)?;
+ let named = |wanted: &str| {
+ dirs.iter()
+ .find(|dir| dir.file_name().is_some_and(|name| name == wanted))
+ .cloned()
+ };
+ named(runner::MAIN_INSTANCE)
+ .or_else(|| named(runner::DEFAULT_INSTANCE))
+ .or_else(|| dirs.first().cloned())
+ .ok_or_else(|| format!("no fuzzer instance under {}", findings.display()).into())
+}
+
fn coverage_curve(findings: &std::path::Path) -> Result<plot::CoverageCurve, Box<dyn Error>> {
- let path = findings
- .join(runner::DEFAULT_INSTANCE)
- .join(plot::PLOT_FILE_NAME);
+ let path = curve_source(findings)?.join(plot::PLOT_FILE_NAME);
let text =
std::fs::read_to_string(&path).map_err(|err| format!("{}: {err}", path.display()))?;
Ok(plot::parse(&text)?)
@@ -1460,6 +1481,11 @@ fn print_coverage_curve(findings: &std::path::Path) {
eprintln!("warning: the coverage curve is empty; the campaign wrote no sample");
return;
};
+ if let Ok(source) = curve_source(findings)
+ && let Some(name) = source.file_name()
+ {
+ println!("curve_instance {}", name.to_string_lossy());
+ }
println!("curve_samples {}", curve.samples().len());
println!("curve_seconds {}", curve.duration_secs());
println!("curve_peak_edges {}", curve.peak_edges());