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): B5 - Ctrl-C harvests instead of dying, and a killed campaign can be imported back

CarterPerez-dev3abe7e515dcb
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
index 03051003..70653433 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
@@ -456,7 +456,7 @@ dependencies = [
"mio",
"parking_lot",
"rustix",
- "signal-hook",
+ "signal-hook 0.3.18",
"signal-hook-mio",
"winapi",
]
@@ -1271,6 +1271,7 @@ name = "lisdex-fuzz"
version = "0.1.0"
dependencies = [
"lisdex-core",
+ "signal-hook 0.4.4",
"thiserror 2.0.20",
]
@@ -2099,6 +2100,16 @@ dependencies = [
"signal-hook-registry",
]
+[[package]]
+name = "signal-hook"
+version = "0.4.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a0c28ca5908dbdbcd52e6fdaa00358ab88637f8ab33e1f188dd510eb44b53d"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
[[package]]
name = "signal-hook-mio"
version = "0.2.5"
@@ -2107,7 +2118,7 @@ checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
dependencies = [
"libc",
"mio",
- "signal-hook",
+ "signal-hook 0.3.18",
]
[[package]]
@@ -2258,7 +2269,7 @@ dependencies = [
"bitflags 2.13.1",
"parking_lot",
"rustix",
- "signal-hook",
+ "signal-hook 0.3.18",
"windows-sys 0.61.2",
]
@@ -2309,7 +2320,7 @@ dependencies = [
"pest_derive",
"phf",
"sha2",
- "signal-hook",
+ "signal-hook 0.3.18",
"siphasher",
"terminfo",
"termios",
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.toml b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.toml
index 2211e8ca..8b6a2f5c 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.toml
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.toml
@@ -14,6 +14,7 @@ authors = ["Carter Perez <[email protected]>"]
[workspace.dependencies]
thiserror = "2"
+signal-hook = { version = "0.4", default-features = false }
libcasr = { version = "=2.13.1", default-features = false }
clang = { version = "2.0.0", features = ["clang_10_0", "runtime"] }
rusqlite = { version = "0.32", features = ["bundled"] }
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/README.md b/PROJECTS/advanced/zero-day-vulnerability-scanner/README.md
index 09d1d551..d79b0de0 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/README.md
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/README.md
@@ -59,11 +59,14 @@ machine form, the exact crashing bytes, the sanitizer report, and an executable
| `coverage` | Report the coverage curve a campaign recorded |
| `corpus` | Distil a corpus to the smallest set reaching the same edges |
| `crashes` | List the crashes persisted for a campaign |
+| `import` | Persist the crashes of a findings directory a killed campaign left behind |
| `minimize` | Minimize one reproducer per distinct bug |
| `advisory` | Draft a coordinated-disclosure advisory per distinct bug |
| `bundle` | Write a self-contained reproducer bundle per distinct bug |
| `tui` | Terminal dashboard over a live campaign |
| `serve` | Local web console over the same state |
+| `bench` | Compare two builds over repeated trials, with a Mann-Whitney U test |
+| `rank-eval` | Score the cold-start ranking against the entry points real harnesses call |
| `llm` | Report which optional booster tier is configured |
## What it refuses to do
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/Cargo.toml b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/Cargo.toml
index 33e50037..205e528b 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/Cargo.toml
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/Cargo.toml
@@ -14,4 +14,5 @@ workspace = true
[dependencies]
thiserror.workspace = true
+signal-hook.workspace = true
lisdex-core.workspace = true
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/interrupt.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/interrupt.rs
new file mode 100644
index 00000000..10b034e1
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-fuzz/src/interrupt.rs
@@ -0,0 +1,67 @@
+// ©AngelaMos | 2026
+// interrupt.rs
+
+use std::io;
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+
+use signal_hook::consts::{SIGINT, SIGTERM};
+
+// B5, measured: with the default disposition lisdex dies of SIGINT the instant a campaign is
+// interrupted and `harvest` never runs. On a real campaign that lost five crash files already on
+// disk and left the campaign row stranded at `fuzzing`, with no command able to read them back.
+//
+// Registered through signal-hook rather than `libc::signal` so this crate holds no `unsafe`: the
+// workspace denies it outright and there is not one exemption anywhere in the tree, which is a
+// claim worth more than the few lines it would have saved here.
+#[derive(Debug, Clone)]
+pub struct Interrupt {
+ flag: Arc<AtomicBool>,
+}
+
+impl Interrupt {
+ // Arming twice is harmless: signal-hook keeps a list of actions per signal, and both would
+ // set the same flag.
+ pub fn arm() -> Result<Self, io::Error> {
+ let flag = Arc::new(AtomicBool::new(false));
+ for signal in [SIGINT, SIGTERM] {
+ signal_hook::flag::register(signal, Arc::clone(&flag))?;
+ }
+ Ok(Self { flag })
+ }
+
+ #[must_use]
+ pub fn raised(&self) -> bool {
+ self.flag.load(Ordering::SeqCst)
+ }
+
+ // Raising the flag by hand is the only way to test the wait loop's interrupted path without
+ // signalling the test runner itself, which would take the whole suite down with it.
+ #[cfg(test)]
+ pub fn raise_for_test(&self) {
+ self.flag.store(true, Ordering::SeqCst);
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ // The flag has to start clear, or a campaign would decide it had been interrupted before it
+ // ever ran and stop at its first poll.
+ #[test]
+ fn an_armed_interrupt_starts_clear() {
+ let interrupt = Interrupt::arm().expect("registering a handler");
+ assert!(!interrupt.raised());
+ }
+
+ // Clones share one flag, which is what lets the runner hand a copy to its wait loop while
+ // the caller keeps one to report with.
+ #[test]
+ fn a_clone_observes_the_same_flag() {
+ let interrupt = Interrupt::arm().expect("registering a handler");
+ let copy = interrupt.clone();
+ interrupt.flag.store(true, Ordering::SeqCst);
+ assert!(copy.raised(), "a clone must not carry its own flag");
+ }
+}
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 c3631352..1665b63e 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
@@ -4,6 +4,7 @@
pub mod bench;
pub mod corpus;
pub mod dictionary;
+pub mod interrupt;
pub mod minimize;
pub mod plot;
pub mod runner;
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 17e4d52e..40a09b2c 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
@@ -3,7 +3,7 @@
use std::io::Read;
use std::path::{Path, PathBuf};
-use std::process::{Command, Stdio};
+use std::process::{Child, Command, Stdio};
use std::time::{Duration, Instant};
use lisdex_core::campaign::CampaignId;
@@ -15,6 +15,7 @@ use lisdex_core::crash::Crash;
use lisdex_core::report::SanitizerReport;
use crate::dictionary;
+use crate::interrupt;
use crate::plot::{self, CoverageCurve, PLOT_FILE_NAME, PlotError};
use crate::stats::{FuzzerStats, STATS_FILE_NAME, StatsError};
@@ -23,6 +24,9 @@ pub const DEFAULT_INSTANCE: &str = "default";
pub const MAX_REPORT_BYTES: usize = 256 * 1024;
const REPRODUCE_POLL_MS: u64 = 25;
+const SUPERVISE_POLL_MS: u64 = 100;
+// How long a child gets to act on a signal it may never have received before it is killed.
+const INTERRUPT_GRACE_MS: u64 = 5_000;
const UNPARSEABLE_REASON: &str = "no parseable sanitizer report";
const UNSYMBOLIZED_REASON: &str =
"no symbolized frames, so any key would be shared by every crash of this kind in this module";
@@ -133,6 +137,10 @@ pub struct Reproduction {
#[derive(Debug, Clone, PartialEq)]
pub struct RunOutcome {
pub clean_exit: bool,
+ // An interrupted campaign is not a failed one. afl-fuzz stopped because it was asked to, the
+ // crashes it already wrote are on disk, and harvesting them is the whole point of catching
+ // the signal rather than dying of it.
+ pub interrupted: bool,
pub stats: FuzzerStats,
}
@@ -452,7 +460,53 @@ pub fn harvest(
Ok((crashes, problems))
}
-pub fn run(options: &AflOptions) -> Result<RunOutcome, RunnerError> {
+// Waits for every child while watching the interrupt flag, polling rather than blocking in
+// `wait` so the flag is still observed once a signal has been caught.
+//
+// Ctrl-C at a terminal reaches the whole foreground group, so afl-fuzz already has its own copy
+// and stops cleanly on its own; the only thing lisdex must do is survive long enough to harvest.
+// A signal aimed at lisdex alone does NOT reach the children, so after `INTERRUPT_GRACE_MS` of
+// them ignoring it they are killed outright. That loses afl's final `fuzzer_stats` update but
+// never the crash files, which afl writes as it finds them - and recovering exactly those is
+// what this is for.
+fn supervise(
+ mut children: Vec<Child>,
+ interrupt: &interrupt::Interrupt,
+) -> Result<(bool, bool), RunnerError> {
+ let mut clean_exit = true;
+ let mut waited_since_signal = 0u64;
+ let mut killed = false;
+
+ while !children.is_empty() {
+ if interrupt.raised() {
+ if waited_since_signal >= INTERRUPT_GRACE_MS && !killed {
+ for child in &mut children {
+ let _ = child.kill();
+ }
+ killed = true;
+ }
+ waited_since_signal += SUPERVISE_POLL_MS;
+ }
+ let mut running = Vec::with_capacity(children.len());
+ for mut child in children {
+ match child.try_wait()? {
+ Some(status) => clean_exit = clean_exit && status.success(),
+ None => running.push(child),
+ }
+ }
+ children = running;
+ if !children.is_empty() {
+ std::thread::sleep(Duration::from_millis(SUPERVISE_POLL_MS));
+ }
+ }
+
+ Ok((clean_exit, interrupt.raised()))
+}
+
+pub fn run(
+ options: &AflOptions,
+ interrupt: &interrupt::Interrupt,
+) -> Result<RunOutcome, RunnerError> {
// afl-fuzz aborts with "Unable to create" rather than creating the parent itself.
if let Some(parent) = options.findings.parent() {
std::fs::create_dir_all(parent)?;
@@ -463,17 +517,20 @@ pub fn run(options: &AflOptions) -> Result<RunOutcome, RunnerError> {
for (key, value) in &invocation.envs {
command.env(key, value);
}
- let status = command.status()?;
+ // Spawned rather than run through `status`, because the child has to stay addressable while
+ // we wait for it.
+ let (clean_exit, interrupted) = supervise(vec![command.spawn()?], interrupt)?;
let measured = read_stats(&options.findings).map_err(|cause| match cause {
- RunnerError::Io(_) | RunnerError::NoInstance { .. } if !status.success() => {
+ RunnerError::Io(_) | RunnerError::NoInstance { .. } if !clean_exit => {
RunnerError::AflFailed {
- status: status.to_string(),
+ status: "afl-fuzz exited without writing stats".to_owned(),
}
}
other => other,
})?;
Ok(RunOutcome {
- clean_exit: status.success(),
+ clean_exit,
+ interrupted,
stats: measured,
})
}
@@ -482,7 +539,11 @@ 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> {
+pub fn run_parallel(
+ base: &AflOptions,
+ jobs: usize,
+ interrupt: &interrupt::Interrupt,
+) -> Result<RunOutcome, RunnerError> {
if base.resume && !resumable(&base.findings)? {
return Err(RunnerError::NothingToResume {
findings: base.findings.display().to_string(),
@@ -490,7 +551,7 @@ pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, Runner
}
let plan = instance_plan(jobs);
if plan.is_empty() {
- return run(base);
+ return run(base, interrupt);
}
if let Some(parent) = base.findings.parent() {
std::fs::create_dir_all(parent)?;
@@ -516,17 +577,17 @@ pub fn run_parallel(base: &AflOptions, jobs: usize) -> Result<RunOutcome, Runner
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 (clean_exit, interrupted) = supervise(children, interrupt)?;
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 })
+ Ok(RunOutcome {
+ clean_exit,
+ interrupted,
+ stats,
+ })
}
#[cfg(test)]
@@ -574,6 +635,43 @@ mod tests {
assert_eq!(input[1], "/corpus");
}
+ // B5. Every campaign now goes through `supervise`, so a child that simply finishes has to
+ // come back exactly as `status()` used to report it, or the fix for the interrupted case
+ // would have changed every uninterrupted one.
+ #[test]
+ fn an_uninterrupted_child_reports_its_own_exit_and_no_interruption() {
+ let interrupt = interrupt::Interrupt::arm().unwrap();
+ let ok = Command::new("true").spawn().unwrap();
+ assert_eq!(supervise(vec![ok], &interrupt).unwrap(), (true, false));
+
+ let bad = Command::new("false").spawn().unwrap();
+ assert_eq!(
+ supervise(vec![bad], &interrupt).unwrap(),
+ (false, false),
+ "a child that failed on its own must not be reported as interrupted"
+ );
+ }
+
+ // The whole point of B5: a raised flag must end the wait rather than leave lisdex blocked on
+ // a child that never received the signal. `sleep 600` outlives any grace period, so the only
+ // way this returns is the escalation.
+ #[test]
+ fn a_raised_interrupt_ends_the_wait_on_a_child_that_ignores_it() {
+ let interrupt = interrupt::Interrupt::arm().unwrap();
+ interrupt.raise_for_test();
+ let sleeper = Command::new("sleep").arg("600").spawn().unwrap();
+
+ let started = Instant::now();
+ let (clean_exit, interrupted) = supervise(vec![sleeper], &interrupt).unwrap();
+
+ assert!(interrupted, "the outcome must say it was interrupted");
+ assert!(!clean_exit, "a killed child did not exit cleanly");
+ assert!(
+ started.elapsed() < Duration::from_millis(INTERRUPT_GRACE_MS * 4),
+ "the wait outlived the grace period, so lisdex would hang instead of harvesting"
+ );
+ }
+
#[test]
fn resuming_a_findings_directory_that_never_ran_is_refused() {
let empty = scratch("nothing-to-resume");
@@ -582,7 +680,9 @@ mod tests {
let mut options = options();
options.resume = true;
options.findings = empty;
- let err = run_parallel(&options, 1).expect_err("there is nothing to resume from");
+ let interrupt = interrupt::Interrupt::arm().unwrap();
+ let err =
+ run_parallel(&options, 1, &interrupt).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"
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 0966ae0f..96a7afb2 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
@@ -25,6 +25,7 @@ use lisdex_core::store::Store;
use lisdex_fuzz::bench;
use lisdex_fuzz::corpus;
use lisdex_fuzz::dictionary;
+use lisdex_fuzz::interrupt::Interrupt;
use lisdex_fuzz::minimize::{self, Outcome, TminInvocation};
use lisdex_fuzz::plot;
use lisdex_fuzz::runner::{self, AflOptions};
@@ -193,6 +194,10 @@ enum Command {
Verify(VerifyArgs),
#[command(about = "list the crashes persisted for a campaign")]
Crashes(CrashesArgs),
+ #[command(
+ about = "read a findings directory an earlier campaign left on disk and persist its crashes"
+ )]
+ Import(ImportArgs),
#[command(
about = "minimize one reproducer per distinct bug, rejecting any that changes identity"
)]
@@ -524,6 +529,24 @@ struct CrashesArgs {
campaign: i64,
}
+#[derive(clap::Args)]
+struct ImportArgs {
+ #[arg(
+ long,
+ help = "findings directory a previous campaign wrote, whose crashes were never persisted"
+ )]
+ findings: PathBuf,
+ #[arg(
+ long,
+ help = "the instrumented harness that produced them; each input is re-run against it to obtain a report"
+ )]
+ target: PathBuf,
+ #[arg(long, help = "sqlite database to write the recovered campaign into")]
+ db: PathBuf,
+ #[arg(long, help = "campaign label (defaults to the target file name)")]
+ label: Option<String>,
+}
+
#[derive(clap::Args)]
struct MinimizeArgs {
#[arg(long, help = "sqlite database written by a previous campaign")]
@@ -732,6 +755,7 @@ fn dispatch() -> Result<(), Box<dyn Error>> {
Command::Harness(args) => harness(args),
Command::Verify(args) => verify(args),
Command::Crashes(args) => crashes(args),
+ Command::Import(args) => import(args),
Command::Advisory(args) => advisories(args),
Command::Bundle(args) => bundles(args),
Command::Coverage(args) => coverage(args),
@@ -1092,6 +1116,10 @@ fn run_bench(args: &BenchArgs) -> Result<(), Box<dyn Error>> {
.map(|(name, _)| bench::Arm::new(name))
.collect();
+ // A bench is many campaigns back to back, so it is the run most likely to be interrupted.
+ // Arming here keeps the trial that was in flight from being killed mid-write.
+ let interrupt = Interrupt::arm()?;
+
// Interleaved on purpose. Running every trial of one arm and then every trial of the
// other lets any drift in machine state - page cache, thermal, a neighbour's load -
// land entirely on the second arm and be read as an effect of the build. Measured on
@@ -1115,7 +1143,7 @@ fn run_bench(args: &BenchArgs) -> Result<(), Box<dyn Error>> {
instance: None,
resume: false,
};
- let outcome = runner::run(&options)?;
+ let outcome = runner::run(&options, &interrupt)?;
let curve = runner::read_curve(&findings).ok();
arms[index].trials.push(bench::Trial {
edges: outcome.stats.edges_found,
@@ -1819,6 +1847,89 @@ fn campaign_tree(target: &Path) -> TreeProvenance {
tree
}
+// B5's recovery half. A campaign that was killed outright - by a signal lisdex could not catch,
+// an OOM, a lost session - leaves its crash files on disk with nothing able to read them back.
+// This runs the SAME `runner::harvest` and the same insert loop the live campaign runs, so an
+// imported crash is indistinguishable from one harvested in place rather than a second,
+// weaker ingestion path that could disagree with it.
+fn import(args: &ImportArgs) -> Result<(), Box<dyn Error>> {
+ if !args.findings.is_dir() {
+ return Err(format!(
+ "no findings directory at {}; import reads what a campaign already wrote",
+ args.findings.display()
+ )
+ .into());
+ }
+
+ let label = args.label.clone().unwrap_or_else(|| {
+ args.target
+ .file_name()
+ .map_or(UNKNOWN_TARGET.to_owned(), |name| {
+ name.to_string_lossy().into_owned()
+ })
+ });
+
+ if let Some(parent) = args
+ .db
+ .parent()
+ .filter(|parent| !parent.as_os_str().is_empty())
+ {
+ std::fs::create_dir_all(parent)?;
+ }
+ let store = Store::open(&args.db)?;
+ let mut campaign = Campaign::new(label.clone(), campaign_tree(&args.target));
+ let campaign_id = store.insert_campaign(&campaign)?;
+ for status in [CampaignStatus::Building, CampaignStatus::Fuzzing] {
+ campaign.advance(status)?;
+ store.update_campaign_status(campaign_id, status)?;
+ }
+
+ println!("campaign {} target {label}", campaign_id.0);
+ println!("importing from {}", args.findings.display());
+
+ let (harvested, problems) = match runner::harvest(campaign_id, &args.target, &args.findings) {
+ Ok(result) => result,
+ Err(err) => {
+ fail_campaign(&store, &mut campaign, campaign_id);
+ return Err(err.into());
+ }
+ };
+
+ let mut persisted = 0usize;
+ let mut store_problems = Vec::new();
+ for crash in &harvested {
+ match store.insert_crash(crash) {
+ Ok(_) => persisted += 1,
+ Err(err) => store_problems.push(format!("crash not persisted: {err}")),
+ }
+ }
+
+ println!("crashes_persisted {persisted}");
+ print_triaged_crashes(&harvested);
+
+ for problem in problems.iter().chain(store_problems.iter()) {
+ eprintln!("warning: {problem}");
+ }
+
+ if !store_problems.is_empty() {
+ fail_campaign(&store, &mut campaign, campaign_id);
+ return Err(format!("campaign {} marked failed", campaign_id.0).into());
+ }
+
+ // An import that found nothing is not an error - an empty findings directory is a legitimate
+ // answer - but it must not be reported as a recovery either.
+ if harvested.is_empty() {
+ eprintln!(
+ "warning: no crash inputs under {}; nothing was imported",
+ args.findings.display()
+ );
+ }
+
+ campaign.advance(CampaignStatus::Completed)?;
+ store.update_campaign_status(campaign_id, CampaignStatus::Completed)?;
+ Ok(())
+}
+
fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
let label = args.label.clone().unwrap_or_else(|| {
args.target
@@ -1854,7 +1965,11 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
}
println!("running {}", runner::AFL_FUZZ_BIN);
- let outcome = match runner::run_parallel(&options, args.jobs) {
+ // Armed before the first child exists, so no window remains where the default disposition
+ // still applies and an early Ctrl-C kills lisdex with crashes already on disk.
+ let interrupt = Interrupt::arm()?;
+
+ let outcome = match runner::run_parallel(&options, args.jobs, &interrupt) {
Ok(outcome) => outcome,
Err(err) => {
fail_campaign(&store, &mut campaign, campaign_id);
@@ -1886,6 +2001,7 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
println!("afl_version {}", stats.afl_version);
println!("persistent_mode {persistent}");
println!("clean_exit {}", outcome.clean_exit);
+ println!("interrupted {}", outcome.interrupted);
println!("execs_done {}", stats.execs_done);
println!("execs_per_sec {:.2}", stats.execs_per_sec);
println!(
@@ -1911,7 +2027,11 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
);
}
- if !outcome.clean_exit || !store_problems.is_empty() {
+ // An interrupted campaign exits uncleanly BY CONSTRUCTION - afl-fuzz was asked to stop - so
+ // the unclean exit only condemns the campaign when nobody asked for it. Everything above
+ // this point already ran, which is the whole of B5: the crashes are harvested and persisted
+ // before the exit status is judged.
+ if (!outcome.clean_exit && !outcome.interrupted) || !store_problems.is_empty() {
fail_campaign(&store, &mut campaign, campaign_id);
return Err(format!(
"{} exited uncleanly or crashes were lost; campaign {} marked failed",
@@ -1920,6 +2040,12 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
)
.into());
}
+ if outcome.interrupted {
+ eprintln!(
+ "interrupted: {persisted} crash(es) were harvested before stopping, campaign {}",
+ campaign_id.0
+ );
+ }
campaign.advance(CampaignStatus::Completed)?;
store.update_campaign_status(campaign_id, CampaignStatus::Completed)?;
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/learn/00-OVERVIEW.md b/PROJECTS/advanced/zero-day-vulnerability-scanner/learn/00-OVERVIEW.md
index e35c3219..13472e14 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/learn/00-OVERVIEW.md
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/learn/00-OVERVIEW.md
@@ -174,6 +174,14 @@ Your harness defines its own `main`, which links against the driver's weak
`main` and shadows it, so nothing is actually being fuzzed. lisdex warns about
this: look for the line about persistent mode in the campaign output.
+**A campaign was killed and its crashes are not in the database.**
+Ctrl-C is handled: lisdex stops the fuzzers, harvests what they already wrote,
+and exits 0, so the crashes are persisted. A campaign killed outright, by
+`SIGKILL` or a lost session, cannot run that path. The crash files are still on
+disk under the findings directory, and `lisdex import --findings <dir> --target
+<harness> --db <db>` re-runs each one and persists it exactly as a live campaign
+would.
+
**A campaign reports crashes but `lisdex crashes` shows no distinct bugs.**
The crashes were captured unsymbolized, so every one of them would hash to the
same module offset. lisdex refuses to key them rather than invent a bucket. Build
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh
index aa91c0ff..e882fff6 100755
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m6-gate.sh
@@ -46,11 +46,11 @@ require_harness_current "$OUT_ROOT"
mkdir -p "$GATE"
-log "stage 1/8: build lisdex"
+log "stage 1/9: build lisdex"
cargo build -p lisdex
[ -x "$LISDEX_BIN" ] || die "lisdex binary not found at $LISDEX_BIN"
-log "stage 2/8: the campaign layer answers for itself"
+log "stage 2/9: 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.
@@ -60,7 +60,7 @@ else
fail "lisdex-fuzz tests (see $GATE_LOG)"
fi
-log "stage 3/8: a sustained multi-core campaign with a dictionary it chose itself"
+log "stage 3/9: 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" \
@@ -125,7 +125,7 @@ else
fail "$OVER_CAP instance(s) loaded more than $MAX_DICTIONARIES dictionaries"
fi
-log "stage 4/8: the campaign recorded a coverage curve and execs/s"
+log "stage 4/9: 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
@@ -161,7 +161,7 @@ else
fail "the CSV export carried no sample"
fi
-log "stage 5/8: the corpus distils, and resuming continues rather than restarting"
+log "stage 5/9: 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
@@ -199,7 +199,7 @@ else
fi
fi
-log "stage 6/8: the memory sanitizer is a SEPARATE second build, and it finds what address misses"
+log "stage 6/9: the memory sanitizer is a SEPARATE second build, and it finds what address misses"
# MSAN and ASAN cannot coexist in one binary, which is the whole reason the design
# calls for a second build. Two things have to hold: lisdex must actually PRODUCE an
# MSAN artifact when asked, and that artifact must catch a class the ASAN build does
@@ -338,7 +338,7 @@ else
fail "MSAN reported an initialised read ($CLEAN_HIT), so the detection check proves nothing"
fi
-log "stage 7/8: a comparative claim is impossible below the statistical power floor"
+log "stage 7/9: a comparative claim is impossible below the statistical power floor"
# Klees et al. CCS 2018 Finding 1: a single trial can reverse the conclusion. Schloegel
# et al. S&P 2024 add that below ~20 trials Mann-Whitney U at alpha=0.05 cannot reject
# whatever the data. Both halves are checked, because a tool that ALWAYS refuses would
@@ -395,7 +395,7 @@ else
fail "the bench report does not carry quartiles (see $BENCH/powered.txt)"
fi
-log "stage 8/8: the campaign still triages to the canary ground truth"
+log "stage 8/9: 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")"
@@ -406,6 +406,130 @@ else
fail "a multi-core campaign produced no keyed bug, so its crashes were not harvested across instances"
fi
+log "stage 9/9: an interrupted campaign keeps its crashes, and an orphaned one can be imported"
+# B5, measured before it was fixed: SIGINT killed lisdex outright, `harvest` never ran, five
+# crash files already on disk were unreachable and the campaign row stayed at `fuzzing` forever.
+# The signal MUST be sent with its default disposition restored - a shell sets SIGINT to SIG_IGN
+# for background jobs and that is inherited across fork and exec, so a bash-launched campaign
+# cannot receive it and this whole stage would pass without testing anything.
+INT_DIR="$GATE/interrupt"
+rm -rf "$INT_DIR"
+mkdir -p "$INT_DIR"
+python3 - "$LISDEX_BIN" "$TARGET" "$SEEDS" "$INT_DIR" > "$GATE/interrupt.txt" 2>&1 <<'PY'
+import glob, os, signal, sqlite3, subprocess, sys, time
+
+lisdex, target, seeds, work = sys.argv[1:5]
+
+def child_setup():
+ os.setsid()
+ signal.signal(signal.SIGINT, signal.SIG_DFL)
+
+def campaign(tag):
+ log = open(f"{work}/{tag}.log", "w")
+ return subprocess.Popen(
+ [lisdex, "fuzz", "--target", target, "--seeds", seeds,
+ "--findings", f"{work}/{tag}", "--db", f"{work}/{tag}.sqlite"],
+ stdout=log, stderr=log, preexec_fn=child_setup)
+
+def wait_for_crash(tag, proc):
+ for _ in range(180):
+ if glob.glob(f"{work}/{tag}/*/crashes/id:*"):
+ return True
+ if proc.poll() is not None:
+ return False
+ time.sleep(1)
+ return False
+
+def rows(db):
+ if not os.path.exists(db):
+ return 0
+ con = sqlite3.connect(db)
+ try:
+ return con.execute("SELECT COUNT(*) FROM crashes").fetchone()[0]
+ finally:
+ con.close()
+
+proc = campaign("interrupted")
+if not wait_for_crash("interrupted", proc):
+ print("SETUP_FAILED no crash appeared to interrupt over")
+ raise SystemExit(0)
+# The liveness guard: if the signal were ignored the process would keep running and every
+# assertion below would be about a campaign that was never interrupted at all.
+if int(open(f"/proc/{proc.pid}/status").read().split("SigIgn:")[1].split()[0], 16) & 0x2:
+ print("SETUP_FAILED SIGINT is ignored, so this stage cannot interrupt anything")
+ raise SystemExit(0)
+os.killpg(proc.pid, signal.SIGINT)
+code = proc.wait(timeout=120)
+disk = len(glob.glob(f"{work}/interrupted/*/crashes/id:*"))
+print(f"INTERRUPT exit={code} disk={disk} rows={rows(f'{work}/interrupted.sqlite')}")
+
+proc = campaign("orphaned")
+if wait_for_crash("orphaned", proc):
+ os.killpg(proc.pid, signal.SIGKILL)
+ proc.wait()
+ time.sleep(2)
+ os.system("pkill -9 afl-fuzz 2>/dev/null; true")
+ orphan_disk = len(glob.glob(f"{work}/orphaned/*/crashes/id:*"))
+ orphan_rows = rows(f"{work}/orphaned.sqlite")
+ run = subprocess.run([lisdex, "import", "--findings", f"{work}/orphaned",
+ "--target", target, "--db", f"{work}/recovered.sqlite"],
+ capture_output=True, text=True)
+ print(f"ORPHAN disk={orphan_disk} rows={orphan_rows} "
+ f"import_exit={run.returncode} recovered={rows(f'{work}/recovered.sqlite')}")
+else:
+ print("SETUP_FAILED no crash appeared to orphan")
+
+missing = subprocess.run([lisdex, "import", "--findings", f"{work}/never-existed",
+ "--target", target, "--db", f"{work}/never.sqlite"],
+ capture_output=True, text=True)
+print(f"MISSING import_exit={missing.returncode}")
+PY
+cat "$GATE/interrupt.txt"
+
+if grep -q 'SETUP_FAILED' "$GATE/interrupt.txt"; then
+ fail "the interrupt stage never got a campaign into the state it tests: \
+$(grep SETUP_FAILED "$GATE/interrupt.txt" | head -1)"
+else
+ INT_LINE="$(grep '^INTERRUPT ' "$GATE/interrupt.txt")"
+ INT_EXIT="$(echo "$INT_LINE" | grep -oE 'exit=-?[0-9]+' | cut -d= -f2)"
+ INT_DISK="$(echo "$INT_LINE" | grep -oE 'disk=[0-9]+' | cut -d= -f2)"
+ INT_ROWS="$(echo "$INT_LINE" | grep -oE 'rows=[0-9]+' | cut -d= -f2)"
+ # Without the handler this is exit=-2: killed BY SIGINT, before harvest ever ran.
+ if [ "$INT_EXIT" = "0" ]; then
+ pass "an interrupted campaign exits 0 instead of dying of the signal"
+ else
+ fail "an interrupted campaign exited $INT_EXIT; SIGINT still kills lisdex (B5)"
+ fi
+ if [ "$INT_DISK" -gt 0 ] && [ "$INT_ROWS" = "$INT_DISK" ]; then
+ pass "all $INT_DISK crash file(s) on disk were harvested before stopping"
+ else
+ fail "$INT_DISK crash file(s) on disk but $INT_ROWS persisted; Ctrl-C loses crashes (B5)"
+ fi
+
+ ORPHAN_LINE="$(grep '^ORPHAN ' "$GATE/interrupt.txt")"
+ ORPHAN_DISK="$(echo "$ORPHAN_LINE" | grep -oE 'disk=[0-9]+' | cut -d= -f2)"
+ ORPHAN_ROWS="$(echo "$ORPHAN_LINE" | grep -oE ' rows=[0-9]+' | cut -d= -f2)"
+ RECOVERED="$(echo "$ORPHAN_LINE" | grep -oE 'recovered=[0-9]+' | cut -d= -f2)"
+ # Isolates import from the handler: SIGKILL cannot be caught, so no handler can save this
+ # campaign and the only way the rows appear is that import read them back off disk.
+ if [ "$ORPHAN_DISK" -gt 0 ] && [ "$ORPHAN_ROWS" = "0" ]; then
+ pass "a SIGKILLed campaign leaves $ORPHAN_DISK crash file(s) and persists none, so import has real work"
+ else
+ fail "the orphan control is vacuous: disk=$ORPHAN_DISK already-persisted=$ORPHAN_ROWS"
+ fi
+ if [ "$RECOVERED" = "$ORPHAN_DISK" ]; then
+ pass "lisdex import recovered all $RECOVERED of them into a fresh database"
+ else
+ fail "import recovered $RECOVERED of $ORPHAN_DISK orphaned crash file(s)"
+ fi
+fi
+# The refusing direction, or import would "succeed" on a path the user mistyped.
+if grep -q '^MISSING import_exit=1$' "$GATE/interrupt.txt"; then
+ pass "importing a directory that does not exist is refused"
+else
+ fail "import accepted a findings directory that does not exist"
+fi
+
log "RESULT"
if [ "$FAILURES" -eq 0 ]; then
printf '\n[m6] M6 EXIT GATE PASSED\n'
@@ -415,6 +539,7 @@ if [ "$FAILURES" -eq 0 ]; then
printf ' CHECK 4 the corpus distils, and resuming continues the clock rather than restarting it\n'
printf ' CHECK 5 the memory sanitizer builds as a SEPARATE second artifact and reports a class address misses\n'
printf ' CHECK 6 no comparative claim is available below the power floor, and a powered run still yields one\n'
+ printf ' CHECK 7 an interrupted campaign harvests its crashes, and an orphaned one imports back\n'
exit 0
fi
printf '\n[m6] M6 EXIT GATE FAILED: %s check(s)\n' "$FAILURES" >&2