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 exit gate - 20 checks, and the fuzzer's own log is the witness

CarterPerez-dev0d142f0cf919
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 f3269cb3..c4d0a2d8 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
@@ -39,6 +39,7 @@ const ARG_MAIN: &str = "-M";
const ARG_SECONDARY: &str = "-S";
const ARG_SCHEDULE: &str = "-p";
const ARG_SEPARATOR: &str = "--";
+const RESUME_IN_PLACE: &str = "-";
const ENV_FINAL_SYNC: &str = "AFL_FINAL_SYNC";
const ENV_SKIP_CPUFREQ: &str = "AFL_SKIP_CPUFREQ";
@@ -48,6 +49,7 @@ 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 INSTANCE_LOG_SUFFIX: &str = ".log";
pub const MAIN_INSTANCE: &str = "main";
pub const SECONDARY_PREFIX: &str = "secondary";
pub const SECONDARY_SCHEDULES: [&str; 6] = ["fast", "coe", "lin", "quad", "exploit", "rare"];
@@ -97,6 +99,10 @@ pub enum RunnerError {
"{AFL_FUZZ_BIN} failed before writing stats ({status}); check the {AFL_FUZZ_BIN} output above"
)]
AflFailed { status: String },
+ #[error(
+ "asked to resume but {findings} holds no previous instance; drop --resume to start a new campaign there"
+ )]
+ NothingToResume { findings: String },
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -123,6 +129,7 @@ pub struct AflOptions {
pub skip_deterministic: bool,
pub dictionaries: Vec<PathBuf>,
pub instance: Option<Instance>,
+ pub resume: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -137,7 +144,11 @@ impl AflOptions {
pub fn invocation(&self) -> AflInvocation {
let mut args = vec![
ARG_INPUT.to_owned(),
- self.seeds.display().to_string(),
+ if self.resume {
+ RESUME_IN_PLACE.to_owned()
+ } else {
+ self.seeds.display().to_string()
+ },
ARG_OUTPUT.to_owned(),
self.findings.display().to_string(),
ARG_MEMORY.to_owned(),
@@ -411,7 +422,16 @@ pub fn run(options: &AflOptions) -> Result<RunOutcome, RunnerError> {
})
}
+pub fn resumable(findings: &Path) -> Result<bool, RunnerError> {
+ Ok(!instance_dirs(findings)?.is_empty())
+}
+
pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, RunnerError> {
+ if base.resume && !resumable(&base.findings)? {
+ return Err(RunnerError::NothingToResume {
+ findings: base.findings.display().to_string(),
+ });
+ }
let plan = instance_plan(jobs);
if plan.is_empty() {
return run(base);
@@ -420,8 +440,12 @@ pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, Runner
std::fs::create_dir_all(parent)?;
}
+ std::fs::create_dir_all(&base.findings)?;
let mut children = Vec::new();
for instance in plan {
+ let log_path = base
+ .findings
+ .join(format!("{}{INSTANCE_LOG_SUFFIX}", instance.name()));
let mut options = base.clone();
options.instance = Some(instance);
let invocation = options.invocation();
@@ -430,7 +454,9 @@ pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, Runner
for (key, value) in &invocation.envs {
command.env(key, value);
}
- command.stdout(Stdio::null()).stderr(Stdio::null());
+ let log = std::fs::File::create(&log_path)?;
+ let errors = log.try_clone()?;
+ command.stdout(Stdio::from(log)).stderr(Stdio::from(errors));
children.push(command.spawn()?);
}
@@ -462,9 +488,51 @@ mod tests {
skip_deterministic: true,
dictionaries: Vec::new(),
instance: None,
+ resume: false,
}
}
+ #[test]
+ fn a_resuming_campaign_reads_its_own_output_instead_of_the_seed_corpus() {
+ let mut options = options();
+ options.resume = true;
+ let args = options.invocation().args;
+ let input = args
+ .windows(2)
+ .find(|pair| pair[0] == ARG_INPUT)
+ .expect("an input is always given");
+ assert_eq!(
+ input[1], RESUME_IN_PLACE,
+ "afl-fuzz resumes only when the input directory is literally '-'; handing it the seeds again would restart from the seeds and discard the queue"
+ );
+ assert!(!args.contains(&"/corpus".to_owned()));
+ }
+
+ #[test]
+ fn a_fresh_campaign_still_reads_the_seed_corpus() {
+ let args = options().invocation().args;
+ let input = args
+ .windows(2)
+ .find(|pair| pair[0] == ARG_INPUT)
+ .expect("an input is always given");
+ assert_eq!(input[1], "/corpus");
+ }
+
+ #[test]
+ fn resuming_a_findings_directory_that_never_ran_is_refused() {
+ let empty = scratch("nothing-to-resume");
+ std::fs::create_dir_all(&empty).unwrap();
+ assert!(!resumable(&empty).unwrap());
+ let mut options = options();
+ options.resume = true;
+ options.findings = empty;
+ let err = run_parallel(&options, 1).expect_err("there is nothing to resume from");
+ assert!(
+ matches!(err, RunnerError::NothingToResume { .. }),
+ "afl-fuzz would instead start a fresh campaign from an input directory named '-', which does not exist, and fail with a path error that says nothing about resuming"
+ );
+ }
+
#[test]
fn a_single_job_campaign_names_no_instance_at_all() {
assert!(
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 beb606cc..e2d1b30b 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
@@ -311,6 +311,11 @@ struct FuzzArgs {
help = "parallel afl-fuzz instances sharing one findings directory: one main and the rest secondaries"
)]
jobs: usize,
+ #[arg(
+ long,
+ help = "continue a previous campaign in this findings directory instead of starting from the seeds"
+ )]
+ resume: bool,
}
#[derive(clap::Args)]
@@ -1261,6 +1266,7 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
skip_deterministic: args.skip_deterministic,
dictionaries,
instance: None,
+ resume: args.resume,
};
println!("campaign {} target {label}", campaign_id.0);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile b/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
index 46b35397..5d031b9b 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
@@ -76,6 +76,12 @@ m4-gate:
m4-gate-reset:
docker compose -f dev.compose.yml exec toolchain bash scripts/m4-gate.sh reset
+m6-gate:
+ docker compose -f dev.compose.yml exec toolchain bash scripts/m6-gate.sh
+
+m6-gate-reset:
+ docker compose -f dev.compose.yml exec toolchain bash scripts/m6-gate.sh reset
+
m7-gate:
docker compose -f dev.compose.yml exec toolchain bash scripts/m7-gate.sh
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh
new file mode 100755
index 00000000..a589ed06
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh
@@ -0,0 +1,219 @@
+#!/usr/bin/env bash
+# ©AngelaMos | 2026
+# m6-gate.sh
+
+set -euo pipefail
+
+WORK="${MAGMA_WORK:-/opt/magma-work}"
+OUT_ROOT="$WORK/out/libpng"
+SEEDS="$WORK/libpng/corpus/libpng_read_fuzzer"
+GATE="$WORK/m6"
+FINDINGS="$GATE/findings"
+DB="$GATE/lisdex.sqlite"
+DISTILLED="$GATE/distilled"
+GATE_LOG="$GATE/stage.log"
+CAMPAIGN_LOG="$GATE/campaign.log"
+RESUME_LOG="$GATE/resume.log"
+LISDEX_BIN="${CARGO_TARGET_DIR:-/cargo-target}/debug/lisdex"
+TARGET="$OUT_ROOT/afl/lisdex_libpng_read"
+CMPLOG="$OUT_ROOT/cmplog/lisdex_libpng_read"
+GATE_DURATION="${LISDEX_M6_DURATION:-180}"
+GATE_JOBS="${LISDEX_M6_JOBS:-4}"
+DICT_DIR="/AFLplusplus/dictionaries"
+
+MAX_DICTIONARIES=4
+
+FAILURES=0
+
+log() { printf '\n[m6] %s\n' "$1"; }
+die() { printf '\n[m6] FAIL: %s\n' "$1" >&2; exit 1; }
+pass() { printf ' PASS %s\n' "$1"; }
+fail() { printf ' FAIL %s\n' "$1"; FAILURES=$((FAILURES + 1)); }
+
+if [ "${1:-}" = "reset" ]; then
+ log "resetting $GATE"
+ rm -rf "$GATE"
+fi
+
+[ -x "$TARGET" ] || die "magma libpng not built; run: just magma-libpng"
+[ -x "$CMPLOG" ] || die "cmplog target missing at $CMPLOG"
+[ -d "$SEEDS" ] || die "seed corpus missing at $SEEDS"
+[ -d "$DICT_DIR" ] || die "AFL++ dictionaries missing at $DICT_DIR"
+
+mkdir -p "$GATE"
+
+log "stage 1/6: build lisdex"
+cargo build -p lisdex
+[ -x "$LISDEX_BIN" ] || die "lisdex binary not found at $LISDEX_BIN"
+
+log "stage 2/6: the campaign layer answers for itself"
+# The end-to-end campaign below cannot isolate the dictionary selector from the
+# instance planner from the curve parser: they all feed one run. Each owns tests
+# no other mechanism can satisfy.
+if cargo test -p lisdex-fuzz > "$GATE_LOG" 2>&1; then
+ pass "lisdex-fuzz unit and integration tests"
+else
+ fail "lisdex-fuzz tests (see $GATE_LOG)"
+fi
+
+log "stage 3/6: a sustained multi-core campaign with a dictionary it chose itself"
+rm -rf "$FINDINGS" "$DB"
+"$LISDEX_BIN" fuzz --target "$TARGET" --cmplog "$CMPLOG" --seeds "$SEEDS" \
+ --findings "$FINDINGS" --db "$DB" --duration "$GATE_DURATION" \
+ --jobs "$GATE_JOBS" > "$CAMPAIGN_LOG" 2>&1 \
+ || die "campaign failed (see $CAMPAIGN_LOG)"
+
+INSTANCES="$(find "$FINDINGS" -mindepth 1 -maxdepth 1 -type d | wc -l)"
+if [ "$INSTANCES" -eq "$GATE_JOBS" ]; then
+ pass "$INSTANCES instances ran under one findings directory"
+else
+ fail "expected $GATE_JOBS instances, found $INSTANCES"
+fi
+
+if [ -d "$FINDINGS/main" ]; then
+ pass "exactly one main instance, which is what the secondaries sync through"
+else
+ fail "no main instance directory; -M was never passed"
+fi
+
+SECONDARIES="$(find "$FINDINGS" -mindepth 1 -maxdepth 1 -type d -name 'secondary*' | wc -l)"
+if [ "$SECONDARIES" -eq "$((GATE_JOBS - 1))" ]; then
+ pass "$SECONDARIES secondaries alongside it"
+else
+ fail "expected $((GATE_JOBS - 1)) secondaries, found $SECONDARIES"
+fi
+
+if grep -q 'dictionary png' "$CAMPAIGN_LOG"; then
+ pass "the seed corpus was recognised as PNG with no flag given"
+else
+ fail "the dictionary was not selected from the corpus (see $CAMPAIGN_LOG)"
+fi
+
+# Each instance's own afl-fuzz output is the independent witness here: lisdex
+# printing that it chose png.dict proves only what lisdex believes.
+INSTANCE_LOGS="$(find "$FINDINGS" -maxdepth 1 -name '*.log' | sort)"
+INSTANCE_LOG_COUNT="$(printf '%s\n' "$INSTANCE_LOGS" | grep -c . || true)"
+if [ "$INSTANCE_LOG_COUNT" -eq "$GATE_JOBS" ]; then
+ pass "every instance kept its own afl-fuzz output rather than discarding it"
+else
+ fail "expected $GATE_JOBS instance logs, found $INSTANCE_LOG_COUNT"
+fi
+
+CONFIRMED=0
+OVER_CAP=0
+for instance_log in $INSTANCE_LOGS; do
+ if grep -q "Loading extra dictionary from '$DICT_DIR/png.dict'" "$instance_log"; then
+ CONFIRMED=$((CONFIRMED + 1))
+ fi
+ loaded="$(grep -c "Loading extra dictionary" "$instance_log" || true)"
+ if [ "$loaded" -gt "$MAX_DICTIONARIES" ]; then
+ OVER_CAP=$((OVER_CAP + 1))
+ fi
+done
+if [ "$CONFIRMED" -eq "$GATE_JOBS" ]; then
+ pass "all $CONFIRMED instances report loading that exact file, independently of what lisdex printed"
+else
+ fail "only $CONFIRMED of $GATE_JOBS instances loaded the dictionary lisdex selected"
+fi
+if [ "$OVER_CAP" -eq 0 ]; then
+ pass "no instance loaded more than the $MAX_DICTIONARIES dictionaries afl-fuzz accepts"
+else
+ fail "$OVER_CAP instance(s) loaded more than $MAX_DICTIONARIES dictionaries"
+fi
+
+log "stage 4/6: the campaign recorded a coverage curve and execs/s"
+CURVE="$("$LISDEX_BIN" coverage --findings "$FINDINGS" 2>&1)"
+printf '%s\n' "$CURVE" > "$GATE/curve.txt"
+if printf '%s' "$CURVE" | grep -q 'curve_instance main'; then
+ pass "the curve is read from the main instance and says so"
+else
+ fail "the curve did not come from the main instance (see $GATE/curve.txt)"
+fi
+
+CURVE_SECONDS="$(printf '%s' "$CURVE" | awk '/curve_seconds/ {print $2}')"
+if [ -n "$CURVE_SECONDS" ] && [ "$CURVE_SECONDS" -gt 0 ]; then
+ pass "the curve spans ${CURVE_SECONDS}s of campaign time"
+else
+ fail "the curve recorded no elapsed time"
+fi
+
+PEAK="$(printf '%s' "$CURVE" | awk '/curve_peak_edges/ {print $2}')"
+if [ -n "$PEAK" ] && [ "$PEAK" -gt 0 ]; then
+ pass "peak coverage $PEAK edges"
+else
+ fail "the curve recorded no coverage"
+fi
+
+if grep -qE '^execs_per_sec +[0-9]' "$CAMPAIGN_LOG"; then
+ pass "execs/s recorded"
+else
+ fail "no execs/s recorded"
+fi
+
+SAMPLES="$("$LISDEX_BIN" coverage --findings "$FINDINGS" --samples | wc -l)"
+if [ "$SAMPLES" -gt 1 ]; then
+ pass "the curve exports $((SAMPLES - 1)) samples as CSV for plotting"
+else
+ fail "the CSV export carried no sample"
+fi
+
+log "stage 5/6: the corpus distils, and resuming continues rather than restarting"
+rm -rf "$DISTILLED"
+if "$LISDEX_BIN" corpus --target "$TARGET" --input "$FINDINGS/main/queue" \
+ --output "$DISTILLED" > "$GATE/corpus.txt" 2>&1; then
+ BEFORE="$(awk '/corpus_before/ {print $2}' "$GATE/corpus.txt")"
+ AFTER="$(awk '/corpus_after/ {print $2}' "$GATE/corpus.txt")"
+ if [ -n "$AFTER" ] && [ "$AFTER" -gt 0 ] && [ "$AFTER" -le "$BEFORE" ]; then
+ pass "queue of $BEFORE distilled to $AFTER inputs, and the result is not empty"
+ else
+ fail "distillation produced $AFTER inputs from $BEFORE"
+ fi
+else
+ fail "corpus distillation failed (see $GATE/corpus.txt)"
+fi
+
+if "$LISDEX_BIN" fuzz --target "$TARGET" --seeds "$SEEDS" --findings "$FINDINGS" \
+ --db "$DB" --duration 30 --jobs "$GATE_JOBS" --resume > "$RESUME_LOG" 2>&1; then
+ RESUMED_SECONDS="$("$LISDEX_BIN" coverage --findings "$FINDINGS" | awk '/curve_seconds/ {print $2}')"
+ if [ "$RESUMED_SECONDS" -gt "$CURVE_SECONDS" ]; then
+ pass "resuming carried the campaign clock from ${CURVE_SECONDS}s to ${RESUMED_SECONDS}s instead of restarting it"
+ else
+ fail "after resuming the curve still spans ${RESUMED_SECONDS}s, so the campaign started over"
+ fi
+else
+ fail "resume failed (see $RESUME_LOG)"
+fi
+
+if "$LISDEX_BIN" fuzz --target "$TARGET" --seeds "$SEEDS" --findings "$GATE/never-ran" \
+ --db "$GATE/never.sqlite" --duration 10 --resume > "$GATE/noresume.txt" 2>&1; then
+ fail "resuming a directory that never ran was accepted"
+else
+ if grep -q 'holds no previous instance' "$GATE/noresume.txt"; then
+ pass "resuming a directory that never ran is refused, and the message says why"
+ else
+ fail "resume of an empty directory failed for the wrong reason (see $GATE/noresume.txt)"
+ fi
+fi
+
+log "stage 6/6: the campaign still triages to the canary ground truth"
+# `lisdex crashes` prints one row per crash; the campaign itself prints the
+# grouping, which is the number that says harvesting crossed every instance.
+BUGS="$(awk '/^distinct_bugs/ {print $2}' "$CAMPAIGN_LOG")"
+KEYED="$("$LISDEX_BIN" crashes --db "$DB" --campaign 1 2>/dev/null | grep -c 'stack_hash' || true)"
+if [ -n "$BUGS" ] && [ "$BUGS" -gt 0 ]; then
+ pass "$BUGS distinct bug(s) keyed from $KEYED crashes across $GATE_JOBS instances"
+else
+ fail "a multi-core campaign produced no keyed bug, so its crashes were not harvested across instances"
+fi
+
+log "RESULT"
+if [ "$FAILURES" -eq 0 ]; then
+ printf '\n[m6] M6 EXIT GATE PASSED\n'
+ printf ' CHECK 1 a sustained multi-core campaign runs one main and N secondaries\n'
+ printf ' CHECK 2 the format dictionary is chosen from the corpus, and afl-fuzz confirms loading it\n'
+ printf ' CHECK 3 coverage curve and execs/s are recorded, and exportable\n'
+ printf ' CHECK 4 the corpus distils, and resuming continues the clock rather than restarting it\n'
+ exit 0
+fi
+printf '\n[m6] M6 EXIT GATE FAILED: %s check(s)\n' "$FAILURES" >&2
+exit 1