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 π
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
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.rsindex 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.rsindex 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());