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 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.rsindex 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, Runnerstd::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, Runnerfor (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.rsindex 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/justfileindex 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.shdiff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.shnew file mode 100755index 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