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.3 - corpus distillation, and the placeholder without which cmin sees no instrumentation

CarterPerez-dev1de356b605ca
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/corpus.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/corpus.rs
new file mode 100644
index 00000000..1deb9152
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/corpus.rs
@@ -0,0 +1,237 @@
+// ©AngelaMos | 2026
+// corpus.rs
+
+use std::path::Path;
+use std::process::{Command, Stdio};
+use std::time::Duration;
+
+pub const AFL_CMIN_BIN: &str = "afl-cmin";
+
+const ARG_INPUT: &str = "-i";
+const ARG_OUTPUT: &str = "-o";
+const ARG_TIMEOUT: &str = "-t";
+const ARG_WORKERS: &str = "-T";
+const ARG_EDGES_ONLY: &str = "-e";
+const ARG_SEPARATOR: &str = "--";
+const ARG_INPUT_PLACEHOLDER: &str = "@@";
+const ENV_SKIP_CPUFREQ: &str = "AFL_SKIP_CPUFREQ";
+const ENV_NO_AFFINITY: &str = "AFL_NO_AFFINITY";
+const ENV_ENABLED: &str = "1";
+
+#[derive(Debug, thiserror::Error)]
+pub enum CorpusError {
+ #[error("io error: {0}")]
+ Io(#[from] std::io::Error),
+ #[error("the input corpus at {0} holds no file to minimize")]
+ EmptyInput(String),
+ #[error("{AFL_CMIN_BIN} exited with {status}")]
+ CminFailed { status: String },
+ #[error(
+ "{AFL_CMIN_BIN} reported success but wrote no file, so accepting its output would replace a working corpus of {input} with nothing"
+ )]
+ EmptyOutput { input: usize },
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct Reduction {
+ pub before: usize,
+ pub after: usize,
+}
+
+impl Reduction {
+ #[must_use]
+ pub fn removed(self) -> usize {
+ self.before.saturating_sub(self.after)
+ }
+
+ #[must_use]
+ pub fn is_reduction(self) -> bool {
+ self.after < self.before
+ }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct CminInvocation<'a> {
+ pub target: &'a Path,
+ pub input: &'a Path,
+ pub output: &'a Path,
+ pub workers: usize,
+ pub timeout: Duration,
+}
+
+#[must_use]
+pub fn cmin_command(invocation: CminInvocation<'_>) -> Command {
+ let mut command = Command::new(AFL_CMIN_BIN);
+ command
+ .arg(ARG_INPUT)
+ .arg(invocation.input)
+ .arg(ARG_OUTPUT)
+ .arg(invocation.output)
+ .arg(ARG_TIMEOUT)
+ .arg(invocation.timeout.as_millis().to_string())
+ .arg(ARG_WORKERS)
+ .arg(invocation.workers.max(1).to_string())
+ .arg(ARG_EDGES_ONLY)
+ .env(ENV_SKIP_CPUFREQ, ENV_ENABLED)
+ .env(ENV_NO_AFFINITY, ENV_ENABLED)
+ .arg(ARG_SEPARATOR)
+ .arg(invocation.target)
+ .arg(ARG_INPUT_PLACEHOLDER)
+ .stdout(Stdio::null())
+ .stderr(Stdio::null());
+ command
+}
+
+pub fn count_files(dir: &Path) -> std::io::Result<usize> {
+ if !dir.is_dir() {
+ return Ok(0);
+ }
+ let mut count = 0;
+ for entry in std::fs::read_dir(dir)? {
+ if entry?.file_type()?.is_file() {
+ count += 1;
+ }
+ }
+ Ok(count)
+}
+
+pub fn minimize_corpus(invocation: CminInvocation<'_>) -> Result<Reduction, CorpusError> {
+ let before = count_files(invocation.input)?;
+ if before == 0 {
+ return Err(CorpusError::EmptyInput(
+ invocation.input.display().to_string(),
+ ));
+ }
+
+ let status = cmin_command(invocation).status()?;
+ if !status.success() {
+ return Err(CorpusError::CminFailed {
+ status: status.to_string(),
+ });
+ }
+
+ let after = count_files(invocation.output)?;
+ if after == 0 {
+ return Err(CorpusError::EmptyOutput { input: before });
+ }
+
+ Ok(Reduction { before, after })
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use std::path::PathBuf;
+
+ fn invocation<'a>(input: &'a Path, output: &'a Path, target: &'a Path) -> CminInvocation<'a> {
+ CminInvocation {
+ target,
+ input,
+ output,
+ workers: 4,
+ timeout: Duration::from_secs(1),
+ }
+ }
+
+ fn scratch(name: &str) -> PathBuf {
+ let dir = std::env::temp_dir().join(format!("lisdex-corpus-test-{name}"));
+ let _ = std::fs::remove_dir_all(&dir);
+ std::fs::create_dir_all(&dir).expect("scratch");
+ dir
+ }
+
+ #[test]
+ fn the_command_names_both_directories_and_the_target_after_a_separator() {
+ let command = cmin_command(invocation(
+ Path::new("/seeds"),
+ Path::new("/distilled"),
+ Path::new("/out/harness"),
+ ));
+ let args: Vec<String> = command
+ .get_args()
+ .map(|arg| arg.to_string_lossy().into_owned())
+ .collect();
+ assert_eq!(command.get_program(), AFL_CMIN_BIN);
+ assert!(
+ args.windows(2)
+ .any(|p| p[0] == ARG_INPUT && p[1] == "/seeds")
+ );
+ assert!(
+ args.windows(2)
+ .any(|p| p[0] == ARG_OUTPUT && p[1] == "/distilled")
+ );
+ assert!(args.windows(2).any(|p| p[0] == ARG_WORKERS && p[1] == "4"));
+ let separator = args
+ .iter()
+ .position(|arg| arg == ARG_SEPARATOR)
+ .expect("the target has to sit behind --, or cmin reads it as its own option");
+ assert_eq!(args[separator + 1], "/out/harness");
+ assert_eq!(
+ args[separator + 2],
+ ARG_INPUT_PLACEHOLDER,
+ "afl-fuzz drives these harnesses through persistent mode with no filename, but cmin runs one exec per input through afl-showmap and hands the file over as an argument; without @@ it feeds stdin instead and reports 'no instrumentation output detected'"
+ );
+ }
+
+ #[test]
+ fn a_worker_count_of_zero_is_raised_to_one_rather_than_passed_through() {
+ let mut inv = invocation(
+ Path::new("/seeds"),
+ Path::new("/distilled"),
+ Path::new("/out/harness"),
+ );
+ inv.workers = 0;
+ let command = cmin_command(inv);
+ let args: Vec<String> = command
+ .get_args()
+ .map(|arg| arg.to_string_lossy().into_owned())
+ .collect();
+ assert!(
+ args.windows(2).any(|p| p[0] == ARG_WORKERS && p[1] == "1"),
+ "-T 0 is not a worker count cmin accepts, and a caller deriving it from a failed core probe would otherwise pass one through"
+ );
+ }
+
+ #[test]
+ fn an_empty_input_corpus_is_refused_before_the_tool_is_run() {
+ let input = scratch("empty-in");
+ let output = scratch("empty-out");
+ let target = scratch("empty-target").join("harness");
+ let err = minimize_corpus(invocation(&input, &output, &target))
+ .expect_err("an empty corpus cannot be minimized");
+ assert!(
+ matches!(err, CorpusError::EmptyInput(_)),
+ "running cmin on nothing would either fail obscurely or succeed with nothing, and neither tells the operator their corpus path was wrong"
+ );
+ }
+
+ #[test]
+ fn counting_ignores_directories_and_a_missing_path_counts_zero() {
+ let dir = scratch("counting");
+ std::fs::write(dir.join("a"), b"x").unwrap();
+ std::fs::write(dir.join("b"), b"y").unwrap();
+ std::fs::create_dir(dir.join("sub")).unwrap();
+ assert_eq!(count_files(&dir).unwrap(), 2);
+ assert_eq!(count_files(&dir.join("absent")).unwrap(), 0);
+ }
+
+ #[test]
+ fn a_reduction_reports_what_it_removed_and_knows_when_it_removed_nothing() {
+ let reduced = Reduction {
+ before: 100,
+ after: 12,
+ };
+ assert_eq!(reduced.removed(), 88);
+ assert!(reduced.is_reduction());
+
+ let unchanged = Reduction {
+ before: 12,
+ after: 12,
+ };
+ assert_eq!(unchanged.removed(), 0);
+ assert!(
+ !unchanged.is_reduction(),
+ "a corpus that was already minimal is a valid outcome, not a failure, and must not be reported as one"
+ );
+ }
+}
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/lib.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/lib.rs
index 7dd0a5d9..b4c9a59a 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/lib.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/lib.rs
@@ -1,6 +1,7 @@
// ©AngelaMos | 2026
// lib.rs
+pub mod corpus;
pub mod dictionary;
pub mod minimize;
pub mod plot;
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 a5031ae0..beb606cc 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
@@ -21,6 +21,7 @@ use lisdex_core::crash::Crash;
use lisdex_core::dedup;
use lisdex_core::report::SanitizerReport;
use lisdex_core::store::Store;
+use lisdex_fuzz::corpus;
use lisdex_fuzz::dictionary;
use lisdex_fuzz::minimize::{self, Outcome, TminInvocation};
use lisdex_fuzz::plot;
@@ -114,6 +115,26 @@ enum Command {
Bundle(BundleArgs),
#[command(about = "report the coverage curve a campaign recorded, over time")]
Coverage(CoverageArgs),
+ #[command(about = "distil a corpus to the smallest set that still reaches the same edges")]
+ Corpus(CorpusArgs),
+}
+
+#[derive(clap::Args)]
+struct CorpusArgs {
+ #[arg(
+ long,
+ help = "the instrumented harness the corpus will be fuzzed against"
+ )]
+ target: PathBuf,
+ #[arg(long, help = "directory of inputs to distil")]
+ input: PathBuf,
+ #[arg(long, help = "directory to write the distilled corpus to")]
+ output: PathBuf,
+ #[arg(
+ long,
+ help = "parallel cmin workers (defaults to the machine's available parallelism)"
+ )]
+ workers: Option<usize>,
}
#[derive(clap::Args)]
@@ -501,6 +522,7 @@ fn dispatch() -> Result<(), Box<dyn Error>> {
Command::Advisory(args) => advisories(args),
Command::Bundle(args) => bundles(args),
Command::Coverage(args) => coverage(args),
+ Command::Corpus(args) => distil_corpus(args),
Command::Minimize(args) => minimize_campaign(args),
Command::Llm(args) => llm(args),
}
@@ -1449,6 +1471,27 @@ fn coverage(args: &CoverageArgs) -> Result<(), Box<dyn Error>> {
Ok(())
}
+fn distil_corpus(args: &CorpusArgs) -> Result<(), Box<dyn Error>> {
+ let workers = args
+ .workers
+ .unwrap_or_else(|| std::thread::available_parallelism().map_or(1, std::num::NonZero::get));
+ std::fs::create_dir_all(&args.output)?;
+ let reduction = corpus::minimize_corpus(corpus::CminInvocation {
+ target: &args.target,
+ input: &args.input,
+ output: &args.output,
+ workers,
+ timeout: Duration::from_millis(DEFAULT_REPRODUCE_TIMEOUT_MS),
+ })?;
+ println!("corpus_before {}", reduction.before);
+ println!("corpus_after {}", reduction.after);
+ println!("corpus_removed {}", reduction.removed());
+ if !reduction.is_reduction() {
+ println!("the corpus was already minimal for this target's edges");
+ }
+ Ok(())
+}
+
fn curve_source(findings: &std::path::Path) -> Result<PathBuf, Box<dyn Error>> {
let dirs = runner::instance_dirs(findings)?;
let named = |wanted: &str| {