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): M4 complete - the oracle layer is wired and the gate proves it

CarterPerez-dev3ac37f377a7e
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/layout.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/layout.rs
index 84fea8a7..e1ca00c8 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/layout.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/layout.rs
@@ -20,6 +20,22 @@ pub struct BuildLayout {
pub work: PathBuf,
}
+#[derive(Debug, thiserror::Error)]
+pub enum LayoutError {
+ #[error(
+ "the work directory {work} sits inside the source tree {tree}, so every build \
+ directory would test as in-tree: no tier would reset its build directory, tier N+1 \
+ would reconfigure on tier N's cache, and artifact discovery would sweep every tier's \
+ output into one measurement. Use a work directory outside the source, or exactly the \
+ source for a genuine in-tree build"
+ )]
+ NestedWork { tree: PathBuf, work: PathBuf },
+}
+
+fn lexically_absolute(path: &Path) -> PathBuf {
+ std::path::absolute(path).unwrap_or_else(|_| path.to_path_buf())
+}
+
impl BuildLayout {
#[must_use]
pub fn new(source: impl Into<PathBuf>, work: impl Into<PathBuf>) -> Self {
@@ -29,6 +45,19 @@ impl BuildLayout {
}
}
+ pub fn validated(
+ source: impl Into<PathBuf>,
+ work: impl Into<PathBuf>,
+ ) -> Result<Self, LayoutError> {
+ let layout = Self::new(source, work);
+ let source = lexically_absolute(&layout.source);
+ let work = lexically_absolute(&layout.work);
+ if work != source && work.starts_with(&source) {
+ return Err(LayoutError::NestedWork { tree: source, work });
+ }
+ Ok(layout)
+ }
+
#[must_use]
pub fn build_dir(&self, system: BuildSystem, variant: &str) -> PathBuf {
self.work
@@ -120,6 +149,38 @@ mod tests {
assert!(layout.is_out_of_tree(&build));
}
+ #[test]
+ fn a_work_directory_nested_in_the_source_is_rejected() {
+ assert!(matches!(
+ BuildLayout::validated("/work/src/libpng", "/work/src/libpng/work/builds/libpng"),
+ Err(LayoutError::NestedWork { .. })
+ ));
+ }
+
+ #[test]
+ fn a_work_directory_equal_to_the_source_is_a_legitimate_in_tree_build() {
+ assert!(BuildLayout::validated("/work/src/lua", "/work/src/lua").is_ok());
+ }
+
+ #[test]
+ fn a_work_directory_beside_the_source_is_accepted() {
+ assert!(BuildLayout::validated("/work/src/libpng", "/work/build/libpng").is_ok());
+ }
+
+ #[test]
+ fn a_sibling_whose_name_merely_starts_with_the_source_name_is_accepted() {
+ assert!(BuildLayout::validated("/work/src/png", "/work/src/png-build").is_ok());
+ }
+
+ #[test]
+ fn a_relative_work_directory_is_compared_lexically_absolute() {
+ let source = std::env::current_dir().unwrap();
+ assert!(matches!(
+ BuildLayout::validated(&source, "nested/builds"),
+ Err(LayoutError::NestedWork { .. })
+ ));
+ }
+
#[test]
fn an_in_tree_build_dir_is_reported_as_such() {
let layout = BuildLayout::new("/work/src/lua", "/work/src/lua");
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-core/src/process.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-core/src/process.rs
index 6080dc22..22bda7fa 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-core/src/process.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-core/src/process.rs
@@ -135,6 +135,7 @@ pub struct Execution {
pub timed_out: bool,
pub truncated: bool,
pub output: String,
+ pub stderr: String,
pub duration: Duration,
}
@@ -274,8 +275,9 @@ pub fn run(spec: &CommandSpec, timeout: Duration) -> Result<Execution, ProcessEr
let deadline = Instant::now() + Duration::from_millis(DRAIN_GRACE_MS);
let mut captured = Vec::new();
+ let mut diagnostic = Vec::new();
let mut truncated = false;
- for (drained, separator) in [(stdout, ""), (stderr, STREAM_SEPARATOR)] {
+ for (drained, separator, is_stderr) in [(stdout, "", false), (stderr, STREAM_SEPARATOR, true)] {
let Some((buffer, handle)) = drained else {
continue;
};
@@ -287,6 +289,9 @@ pub fn run(spec: &CommandSpec, timeout: Duration) -> Result<Execution, ProcessEr
continue;
}
truncated = truncated || bytes.len() >= MAX_CAPTURED_BYTES;
+ if is_stderr {
+ diagnostic.clone_from(&bytes);
+ }
captured.extend_from_slice(separator.as_bytes());
captured.extend_from_slice(&bytes);
}
@@ -303,6 +308,7 @@ pub fn run(spec: &CommandSpec, timeout: Duration) -> Result<Execution, ProcessEr
timed_out,
truncated,
output,
+ stderr: String::from_utf8_lossy(&diagnostic).into_owned(),
duration: started.elapsed(),
})
}
@@ -353,6 +359,22 @@ mod tests {
assert!(run.output.contains("boom"));
}
+ #[test]
+ fn stderr_is_captured_separately_from_stdout() {
+ let spec = CommandSpec::new("sh").args(["-c", "echo out; echo err >&2"]);
+ let run = run(&spec, Duration::from_secs(10)).unwrap();
+ assert_eq!(run.stderr.trim(), "err");
+ assert!(run.output.contains("out"));
+ assert!(run.output.contains("err"));
+ }
+
+ #[test]
+ fn a_silent_command_reports_empty_stderr() {
+ let spec = CommandSpec::new("sh").args(["-c", "echo out"]);
+ let run = run(&spec, Duration::from_secs(10)).unwrap();
+ assert!(run.stderr.is_empty());
+ }
+
#[test]
fn a_hung_command_is_killed_at_the_timeout() {
let spec = CommandSpec::new("sleep").arg("30");
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 2d15dd62..8131a4e8 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
@@ -180,9 +180,12 @@ pub fn discover_crash_inputs(findings: &Path) -> Result<Vec<PathBuf>, RunnerErro
}
pub fn read_stats(findings: &Path) -> Result<FuzzerStats, RunnerError> {
+ Ok(FuzzerStats::parse(&read_stats_text(findings)?)?)
+}
+
+pub fn read_stats_text(findings: &Path) -> Result<String, RunnerError> {
let path = findings.join(DEFAULT_INSTANCE).join(STATS_FILE_NAME);
- let text = std::fs::read_to_string(path)?;
- Ok(FuzzerStats::parse(&text)?)
+ Ok(std::fs::read_to_string(path)?)
}
pub fn reproduce(
@@ -284,6 +287,10 @@ pub fn harvest(
}
pub fn run(options: &AflOptions) -> 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)?;
+ }
let invocation = options.invocation();
let mut command = Command::new(&invocation.program);
command.args(&invocation.args);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/compile.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/compile.rs
index daa6fe13..1435b1fc 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/compile.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/compile.rs
@@ -9,8 +9,10 @@ pub const CC: &str = "afl-clang-lto";
pub const SHOWMAP: &str = "afl-showmap";
pub const DEFAULT_DRIVER: &str = "/usr/local/lib/afl/libAFLDriver.a";
pub const ASAN_OPTIONS: &str = "ASAN_OPTIONS";
-pub const ASAN_OPTIONS_VALUE: &str = "detect_leaks=0";
-pub const ASAN_OPTIONS_LEAKS: &str = "detect_leaks=1";
+// In-process symbolization of one report costs upwards of twelve seconds, and the oracle
+// only needs the exit status, never the frames.
+pub const ASAN_OPTIONS_VALUE: &str = "symbolize=0:detect_leaks=0";
+pub const ASAN_OPTIONS_LEAKS: &str = "symbolize=0:detect_leaks=1";
pub const SHOWMAP_TIMEOUT_MS: u64 = 5000;
pub const TARGET_MODE_KEY: &str = "target_mode";
pub const REQUIRED_TARGET_MODES: &[&str] = &["persistent", "shmem_testcase", "deferred"];
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/emit.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/emit.rs
index d11b54ff..4f307202 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/emit.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/emit.rs
@@ -260,6 +260,7 @@ fn render_value(value: &Value) -> String {
Value::Zero => "0".to_owned(),
Value::Literal(text) | Value::Local(text) | Value::Callback(text) => text.clone(),
Value::AddressOf(name) => format!("&{name}"),
+ Value::AddressOfField { local, field } => format!("&{local}.{field}"),
Value::Cursor => format!("&{CURSOR_LOCAL}"),
Value::NulTerminated => NUL_COPY_LOCAL.to_owned(),
}
@@ -380,6 +381,20 @@ mod tests {
assert!(!source.contains(CALLBACK_COUNTER));
}
+ #[test]
+ fn a_teardown_call_takes_the_address_of_a_field() {
+ let plan = HarnessPlan::new("f").with(Stmt::Call {
+ function: "WebPFreeDecBuffer".to_owned(),
+ args: vec![Value::AddressOfField {
+ local: "ctx".to_owned(),
+ field: "output".to_owned(),
+ }],
+ capture: None,
+ });
+ let source = render(&plan, "x.c");
+ assert!(source.contains(" WebPFreeDecBuffer(&ctx.output);"));
+ }
+
#[test]
fn a_cast_buffer_argument_is_cast() {
let plan = HarnessPlan::new("f").with(Stmt::Call {
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/lib.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/lib.rs
index d4b9afa5..569dc4bc 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/lib.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/lib.rs
@@ -7,3 +7,4 @@ pub mod emit;
pub mod oracle;
pub mod plan;
pub mod synth;
+pub mod verify;
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/oracle.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/oracle.rs
index a050936d..160e274d 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/oracle.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/oracle.rs
@@ -34,16 +34,34 @@ pub struct Observation {
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Rejection {
- CompileFailed { diagnostic: String },
- TooFewValidSeeds { have: usize },
- CrashedOnSeed { seed: PathBuf },
- TimedOutOnSeed { seed: PathBuf },
- StderrOnValidSeed { seed: PathBuf, text: String },
- NoInterSeedDivergence { best: usize },
- ConstantCoverageIncrease { amount: usize },
+ CompileFailed {
+ diagnostic: String,
+ },
+ TooFewValidSeeds {
+ have: usize,
+ },
+ CrashedOnSeed {
+ seed: PathBuf,
+ },
+ TimedOutOnSeed {
+ seed: PathBuf,
+ },
+ StderrOnValidSeed {
+ seed: PathBuf,
+ text: String,
+ missing: bool,
+ },
+ NoInterSeedDivergence {
+ best: usize,
+ },
+ ConstantCoverageIncrease {
+ amount: usize,
+ },
InvalidSeedsIndistinguishable,
NoGlobalNovelty,
- ParentMapIncomplete { seed: PathBuf },
+ ParentMapIncomplete {
+ seed: PathBuf,
+ },
}
impl std::fmt::Display for Rejection {
@@ -64,9 +82,22 @@ impl std::fmt::Display for Rejection {
"exceeded {EXEC_TIMEOUT_SECS}s on seed {}",
seed.display()
),
- Rejection::StderrOnValidSeed { seed, text } => write!(
+ Rejection::StderrOnValidSeed {
+ seed,
+ text,
+ missing: false,
+ } => write!(
formatter,
- "wrote to stderr on valid seed {}: {text}",
+ "valid seed {} is the only one that wrote {text:?} to stderr",
+ seed.display()
+ ),
+ Rejection::StderrOnValidSeed {
+ seed,
+ text,
+ missing: true,
+ } => write!(
+ formatter,
+ "valid seed {} is missing the stderr line {text:?} that the other seeds all wrote",
seed.display()
),
Rejection::NoInterSeedDivergence { best } => write!(
@@ -95,11 +126,8 @@ impl std::fmt::Display for Rejection {
}
pub fn judge_execution(observation: &Observation) -> Result<(), Rejection> {
- if observation.valid.len() < MIN_VALID_SEEDS {
- return Err(Rejection::TooFewValidSeeds {
- have: observation.valid.len(),
- });
- }
+ // A crash is diagnosed before the seed count, so a harness that dies on its first
+ // seed is reported as crashing rather than as an undersized corpus.
for run in observation.valid.iter().chain(&observation.invalid) {
match run.status {
RunStatus::TimedOut => {
@@ -115,6 +143,11 @@ pub fn judge_execution(observation: &Observation) -> Result<(), Rejection> {
RunStatus::Clean => {}
}
}
+ if observation.valid.len() < MIN_VALID_SEEDS {
+ return Err(Rejection::TooFewValidSeeds {
+ have: observation.valid.len(),
+ });
+ }
judge_stderr(&observation.valid)
}
@@ -127,24 +160,36 @@ fn stderr_lines(run: &SeedRun) -> BTreeSet<&str> {
}
pub fn judge_stderr(valid: &[SeedRun]) -> Result<(), Rejection> {
- let Some(first) = valid.first() else {
+ if valid.is_empty() {
return Ok(());
- };
- let mut invariant = stderr_lines(first);
- for run in &valid[1..] {
- let lines = stderr_lines(run);
- invariant.retain(|line| lines.contains(line));
}
- for run in valid {
- if let Some(extra) = stderr_lines(run)
- .into_iter()
- .find(|line| !invariant.contains(line))
- {
- return Err(Rejection::StderrOnValidSeed {
- seed: run.seed.clone(),
- text: extra.to_owned(),
- });
+ // D4 rejects any stderr on a valid seed, which rejects every harness here because
+ // magma prints an unconditional preamble. The rule is therefore differential: a line
+ // every seed writes is a runtime preamble, and only a line that varies is a warning.
+ let mut carriers: BTreeMap<&str, Vec<usize>> = BTreeMap::new();
+ for (index, run) in valid.iter().enumerate() {
+ for line in stderr_lines(run) {
+ carriers.entry(line).or_default().push(index);
+ }
+ }
+ for (line, present) in carriers {
+ if present.len() == valid.len() {
+ continue;
}
+ // Blame the minority: a line two of three seeds wrote is an anomaly on the third,
+ // not on whichever seed the iteration happened to reach first.
+ let missing = present.len() * 2 > valid.len();
+ let culprit = if missing {
+ (0..valid.len()).find(|index| !present.contains(index))
+ } else {
+ present.first().copied()
+ };
+ let Some(culprit) = culprit else { continue };
+ return Err(Rejection::StderrOnValidSeed {
+ seed: valid[culprit].seed.clone(),
+ text: line.to_owned(),
+ missing,
+ });
}
Ok(())
}
@@ -301,6 +346,23 @@ mod tests {
assert!(judge_execution(&observation).is_err());
}
+ #[test]
+ fn a_harness_that_dies_on_its_first_seed_is_reported_as_crashing() {
+ let mut only = vec![run("a", &[1])];
+ only[0].status = RunStatus::NonZeroExit;
+ let observation = Observation {
+ valid: only,
+ invalid: Vec::new(),
+ };
+ assert_eq!(
+ judge_execution(&observation),
+ Err(Rejection::CrashedOnSeed {
+ seed: PathBuf::from("a")
+ }),
+ "observation stops at the first dirty seed, so the count must not mask the crash"
+ );
+ }
+
#[test]
fn a_timeout_is_reported_as_a_timeout_not_a_crash() {
let mut valid = spread();
@@ -368,11 +430,32 @@ mod tests {
judge_execution(&observation),
Err(Rejection::StderrOnValidSeed {
seed: PathBuf::from("a"),
- text: "libpng warning: iCCP".to_owned()
+ text: "libpng warning: iCCP".to_owned(),
+ missing: false
})
);
}
+ #[test]
+ fn the_seed_that_lacks_a_near_universal_line_is_the_one_blamed() {
+ let mut valid = vec![
+ run("a", &[1, 2, 3, 4, 5, 6, 7]),
+ run("b", &[1]),
+ run("c", &[2]),
+ ];
+ valid[1].stderr = "preamble".to_owned();
+ valid[2].stderr = "preamble".to_owned();
+ assert_eq!(
+ judge_stderr(&valid),
+ Err(Rejection::StderrOnValidSeed {
+ seed: PathBuf::from("a"),
+ text: "preamble".to_owned(),
+ missing: true
+ }),
+ "two of three seeds wrote the line, so the anomaly is the seed that did not"
+ );
+ }
+
#[test]
fn whitespace_only_stderr_is_not_stderr() {
let mut valid = spread();
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/plan.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/plan.rs
index 476b0f9d..776c9613 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/plan.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/plan.rs
@@ -18,6 +18,7 @@ pub enum Value {
Literal(String),
Local(String),
AddressOf(String),
+ AddressOfField { local: String, field: String },
Callback(String),
Cursor,
NulTerminated,
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/synth.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/synth.rs
index 5b9699a6..ffbf39d4 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/synth.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/synth.rs
@@ -3,7 +3,7 @@
use std::collections::BTreeMap;
-use lisdex_surface::extract::Vocabulary;
+use lisdex_surface::extract::{Vocabulary, identifier_words};
use lisdex_surface::rank::Candidate;
use lisdex_surface::signature::{Fuzzability, Param, ParamRole, Pointee, Shape};
@@ -11,13 +11,20 @@ use crate::plan::{Binding, HarnessPlan, Init, Stmt, Value};
pub const CONTEXT_LOCAL: &str = "ctx";
pub const RESULT_LOCAL: &str = "rc";
-pub const MAX_FIELD_VARIANTS: usize = 4;
+pub const MAX_POPULATED_FIELDS: usize = 4;
+pub const MAX_PLAN_VARIANTS: usize = 16;
+pub const EXTENT_WORDS: [&str; 15] = [
+ "size", "sz", "len", "length", "count", "capacity", "cap", "num", "nbytes", "bytes", "max",
+ "limit", "n", "buflen", "bufsize",
+];
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Refusal {
NoDataInput,
UnsizedOutParam { param: String },
OpaqueContext { record: String },
+ HeapProducedContext { record: String },
+ UnboundExtent { param: String },
NeedsCallback { param: String },
PathEntry,
UnsupportedShape { param: String },
@@ -35,6 +42,14 @@ impl std::fmt::Display for Refusal {
formatter,
"context {record} is opaque and needs a producer chain"
),
+ Refusal::HeapProducedContext { record } => write!(
+ formatter,
+ "the library allocates {record} itself, so the fields the header exposes are only a prefix of the real object; a stack local reads past its own extent"
+ ),
+ Refusal::UnboundExtent { param } => write!(
+ formatter,
+ "config {param} is an extent that no buffer in this signature claims; guessing it fabricates a crash inside the library"
+ ),
Refusal::NeedsCallback { param } => {
write!(formatter, "parameter {param} needs a synthesized callback")
}
@@ -53,6 +68,83 @@ fn shared_leading_tokens(left: &str, right: &str) -> usize {
.count()
}
+fn shared_leading_words(left: &str, right: &str) -> usize {
+ identifier_words(left)
+ .iter()
+ .zip(identifier_words(right).iter())
+ .take_while(|(one, other)| one.eq_ignore_ascii_case(other))
+ .count()
+}
+
+#[must_use]
+pub fn is_extent_name(name: &str) -> bool {
+ identifier_words(name).iter().any(|word| {
+ EXTENT_WORDS
+ .iter()
+ .any(|extent| word.eq_ignore_ascii_case(extent))
+ })
+}
+
+#[must_use]
+pub fn teardown_for(record: &str, entry: &str, vocabulary: &Vocabulary) -> Option<String> {
+ let candidates = vocabulary.destructors.get(record)?;
+ let mut best: Option<(usize, &String)> = None;
+ // Tearing down after an entry point that IS the teardown is a double free.
+ for name in candidates.iter().filter(|name| name.as_str() != entry) {
+ let score = shared_leading_words(name, entry);
+ let better = match best {
+ None => true,
+ Some((top, chosen)) => {
+ score > top || (score == top && (name.len(), name) < (chosen.len(), chosen))
+ }
+ };
+ if better {
+ best = Some((score, name));
+ }
+ }
+ let (score, chosen) = best?;
+ let choices = candidates
+ .iter()
+ .filter(|name| name.as_str() != entry)
+ .count();
+ if score == 0 && choices > 1 {
+ return None;
+ }
+ Some(chosen.clone())
+}
+
+fn teardown_calls(
+ record: &str,
+ local: &str,
+ entry: &str,
+ vocabulary: &Vocabulary,
+) -> Vec<(String, Value)> {
+ // Calling a field's destructor after the record's own would double free, so a record
+ // that owns a destructor tears itself down and nothing else runs.
+ if let Some(function) = teardown_for(record, entry, vocabulary) {
+ return vec![(function, Value::AddressOf(local.to_owned()))];
+ }
+ let Some(entity) = vocabulary.records.get(record) else {
+ return Vec::new();
+ };
+ entity
+ .fields
+ .iter()
+ .filter_map(|field| match &field.shape {
+ Shape::Record(nested) => teardown_for(nested, entry, vocabulary).map(|function| {
+ (
+ function,
+ Value::AddressOfField {
+ local: local.to_owned(),
+ field: field.name.clone(),
+ },
+ )
+ }),
+ _ => None,
+ })
+ .collect()
+}
+
#[must_use]
pub fn macro_for_field(record: &str, field: &str, vocabulary: &Vocabulary) -> Option<String> {
let record_upper = record.to_uppercase();
@@ -146,7 +238,12 @@ fn bind(
}),
},
ParamRole::Length => Ok(Value::Size),
- ParamRole::Config => Ok(Value::Zero),
+ ParamRole::Config => {
+ if is_extent_name(&label) {
+ return Err(Refusal::UnboundExtent { param: label });
+ }
+ Ok(Value::Zero)
+ }
ParamRole::Callback => Err(Refusal::NeedsCallback { param: label }),
ParamRole::Path => Err(Refusal::PathEntry),
ParamRole::Stream => Err(Refusal::UnsupportedShape { param: label }),
@@ -182,10 +279,25 @@ fn field_bindings(record: &str, vocabulary: &Vocabulary) -> Vec<(String, String)
macro_for_field(record, &field.name, vocabulary)
.map(|macro_name| (field.name.clone(), macro_name))
})
- .take(MAX_FIELD_VARIANTS)
+ .take(MAX_POPULATED_FIELDS)
.collect()
}
+#[must_use]
+pub fn variant_masks(fields: usize) -> Vec<u32> {
+ // One wrong macro used to poison the single all-populated plan and the only fallback
+ // was the empty one, which the coverage oracle rejects, so the candidate was lost.
+ let mut masks: Vec<u32> = (0..(1u32 << fields.min(MAX_POPULATED_FIELDS))).collect();
+ masks.sort_by_key(|mask| {
+ (
+ std::cmp::Reverse(mask.count_ones()),
+ std::cmp::Reverse(*mask),
+ )
+ });
+ masks.truncate(MAX_PLAN_VARIANTS);
+ masks
+}
+
pub fn plan_candidate(
candidate: &Candidate,
include: &str,
@@ -209,6 +321,14 @@ pub fn plan_candidate(
record: record.to_owned(),
});
}
+ // zlib exposes a 24-byte prefix of `struct gzFile_s` only so the gzgetc macro can
+ // inline; the real object is heap allocated by gzopen. Declared on the stack it
+ // produced a stack-buffer-overflow inside gzputs on every input.
+ if vocabulary.produced.contains(record) {
+ return Err(Refusal::HeapProducedContext {
+ record: record.to_owned(),
+ });
+ }
if !locals.contains_key(record) {
let local = if locals.is_empty() {
CONTEXT_LOCAL.to_owned()
@@ -236,7 +356,12 @@ pub fn plan_candidate(
let bindings = ordered
.first()
- .map(|(record, _)| field_bindings(record, vocabulary));
+ .map(|(record, _)| field_bindings(record, vocabulary))
+ .unwrap_or_default();
+ let teardowns: Vec<(String, Value)> = ordered
+ .iter()
+ .flat_map(|(record, local)| teardown_calls(record, local, &candidate.name, vocabulary))
+ .collect();
let call = |plan: HarnessPlan| -> HarnessPlan {
let capture = match candidate.result.shape {
Shape::Void | Shape::Other => None,
@@ -246,36 +371,45 @@ pub fn plan_candidate(
}),
};
let captured = capture.is_some();
- let plan = plan.with(Stmt::Call {
+ let mut plan = plan.with(Stmt::Call {
function: candidate.name.clone(),
args: args.clone(),
capture,
});
if captured {
- plan.with(Stmt::Discard {
+ plan = plan.with(Stmt::Discard {
local: RESULT_LOCAL.to_owned(),
- })
- } else {
- plan
+ });
}
+ // An allocating context with no teardown reports a LeakSanitizer error inside the
+ // target on every direct replay, which reads as a crash in the library.
+ for (function, target) in &teardowns {
+ plan = plan.with(Stmt::Call {
+ function: function.clone(),
+ args: vec![target.clone()],
+ capture: None,
+ });
+ }
+ plan
};
- let mut plans = Vec::new();
- match bindings {
- Some(bindings) if !bindings.is_empty() => {
- let mut populated = base.clone();
- for (field, macro_name) in &bindings {
- populated = populated.with(Stmt::SetField {
+ let plans = variant_masks(bindings.len())
+ .into_iter()
+ .map(|mask| {
+ let mut plan = base.clone();
+ for (index, (field, macro_name)) in bindings.iter().enumerate() {
+ if mask & (1 << index) == 0 {
+ continue;
+ }
+ plan = plan.with(Stmt::SetField {
local: CONTEXT_LOCAL.to_owned(),
field: field.clone(),
value: Value::Literal(macro_name.clone()),
});
}
- plans.push(call(populated));
- plans.push(call(base));
- }
- _ => plans.push(call(base)),
- }
+ call(plan)
+ })
+ .collect();
Ok(plans)
}
@@ -355,6 +489,7 @@ mod tests {
],
},
)]),
+ ..Vocabulary::default()
}
}
@@ -753,6 +888,233 @@ mod tests {
}));
}
+ #[test]
+ fn a_record_the_library_allocates_itself_is_refused_as_a_stack_context() {
+ let mut vocab = png_image_vocabulary();
+ vocab.produced.insert("png_image".to_owned());
+ assert_eq!(
+ plan_candidate(&begin_read(), "png.h", &vocab),
+ Err(Refusal::HeapProducedContext {
+ record: "png_image".to_owned()
+ }),
+ "zlib's exposed gzFile_s prefix declared on the stack overflowed it on every input"
+ );
+ }
+
+ #[test]
+ fn a_size_like_config_is_refused_rather_than_pinned_or_guessed() {
+ let lz4 = candidate(
+ "LZ4_decompress_safe",
+ vec![
+ param(
+ "src",
+ "const char *",
+ Shape::Pointer {
+ pointee: Pointee::Char,
+ is_const: true,
+ },
+ ),
+ param("compressedSize", "int", Shape::Integral),
+ param("dstCapacity", "int", Shape::Integral),
+ ],
+ vec![ParamRole::Buffer, ParamRole::Length, ParamRole::Config],
+ Fuzzability::CastBuffer,
+ Returns::default(),
+ );
+ assert_eq!(
+ plan_candidate(&lz4, "lz4.h", &Vocabulary::default()),
+ Err(Refusal::UnboundExtent {
+ param: "dstCapacity".to_owned()
+ })
+ );
+ }
+
+ #[test]
+ fn a_config_that_is_not_an_extent_still_binds() {
+ let expat = candidate(
+ "XML_Parse",
+ vec![
+ param(
+ "s",
+ "const char *",
+ Shape::Pointer {
+ pointee: Pointee::Char,
+ is_const: true,
+ },
+ ),
+ param("len", "int", Shape::Integral),
+ param("isFinal", "int", Shape::Integral),
+ ],
+ vec![ParamRole::Buffer, ParamRole::Length, ParamRole::Config],
+ Fuzzability::CastBuffer,
+ Returns::default(),
+ );
+ let plans = plan_candidate(&expat, "expat.h", &Vocabulary::default()).unwrap();
+ let Stmt::Call { args, .. } = call_in(&plans[0]) else {
+ unreachable!()
+ };
+ assert_eq!(args[2], Value::Zero);
+ }
+
+ #[test]
+ fn a_context_with_a_destructor_is_torn_down_after_the_call() {
+ let mut vocab = png_image_vocabulary();
+ vocab.destructors.insert(
+ "png_image".to_owned(),
+ BTreeSet::from(["png_image_free".to_owned()]),
+ );
+ let plans = plan_candidate(&begin_read(), "png.h", &vocab).unwrap();
+ let body = &plans[0].body;
+ let call = body
+ .iter()
+ .position(
+ |s| matches!(s, Stmt::Call { function, .. } if function == &begin_read().name),
+ )
+ .expect("the entry call");
+ let free = body
+ .iter()
+ .position(|s| matches!(s, Stmt::Call { function, .. } if function == "png_image_free"))
+ .expect("the teardown call");
+ assert!(free > call);
+ let Stmt::Call { args, .. } = &body[free] else {
+ unreachable!()
+ };
+ assert_eq!(args, &vec![Value::AddressOf(CONTEXT_LOCAL.to_owned())]);
+ }
+
+ #[test]
+ fn a_record_field_is_torn_down_when_the_context_itself_owns_no_destructor() {
+ let mut vocab = png_image_vocabulary();
+ vocab
+ .records
+ .get_mut("png_image")
+ .unwrap()
+ .fields
+ .push(Field {
+ name: "output".to_owned(),
+ spelling: "png_buffer".to_owned(),
+ shape: Shape::Record("png_buffer".to_owned()),
+ });
+ vocab.destructors.insert(
+ "png_buffer".to_owned(),
+ BTreeSet::from(["png_buffer_free".to_owned()]),
+ );
+ let plans = plan_candidate(&begin_read(), "png.h", &vocab).unwrap();
+ assert!(plans[0].body.contains(&Stmt::Call {
+ function: "png_buffer_free".to_owned(),
+ args: vec![Value::AddressOfField {
+ local: CONTEXT_LOCAL.to_owned(),
+ field: "output".to_owned(),
+ }],
+ capture: None,
+ }));
+ }
+
+ #[test]
+ fn a_record_that_owns_a_destructor_does_not_also_free_its_fields() {
+ let mut vocab = png_image_vocabulary();
+ vocab
+ .records
+ .get_mut("png_image")
+ .unwrap()
+ .fields
+ .push(Field {
+ name: "output".to_owned(),
+ spelling: "png_buffer".to_owned(),
+ shape: Shape::Record("png_buffer".to_owned()),
+ });
+ vocab.destructors.insert(
+ "png_image".to_owned(),
+ BTreeSet::from(["png_image_free".to_owned()]),
+ );
+ vocab.destructors.insert(
+ "png_buffer".to_owned(),
+ BTreeSet::from(["png_buffer_free".to_owned()]),
+ );
+ let plans = plan_candidate(&begin_read(), "png.h", &vocab).unwrap();
+ assert!(
+ !plans[0]
+ .body
+ .iter()
+ .any(|s| matches!(s, Stmt::Call { function, .. } if function == "png_buffer_free")),
+ "freeing a field after its owner is a double free"
+ );
+ }
+
+ #[test]
+ fn a_teardown_is_chosen_by_affinity_with_the_entry_point() {
+ let mut vocab = Vocabulary::default();
+ vocab.destructors.insert(
+ "z_stream_s".to_owned(),
+ BTreeSet::from(["deflateEnd".to_owned(), "inflateEnd".to_owned()]),
+ );
+ assert_eq!(
+ teardown_for("z_stream_s", "inflate", &vocab),
+ Some("inflateEnd".to_owned()),
+ "deflateEnd sorts first but shares no leading word with inflate"
+ );
+ }
+
+ #[test]
+ fn an_entry_point_that_is_itself_the_teardown_is_not_called_twice() {
+ let mut vocab = Vocabulary::default();
+ vocab.destructors.insert(
+ "png_image".to_owned(),
+ BTreeSet::from(["png_image_free".to_owned()]),
+ );
+ assert_eq!(
+ teardown_for("png_image", "png_image_free", &vocab),
+ None,
+ "tearing down after an entry point that is the teardown is a double free"
+ );
+ }
+
+ #[test]
+ fn an_ambiguous_teardown_is_not_guessed() {
+ let mut vocab = Vocabulary::default();
+ vocab.destructors.insert(
+ "thing".to_owned(),
+ BTreeSet::from(["alpha_free".to_owned(), "beta_free".to_owned()]),
+ );
+ assert_eq!(teardown_for("thing", "parse_thing", &vocab), None);
+ }
+
+ #[test]
+ fn variants_are_real_subsets_ordered_most_populated_first() {
+ assert_eq!(variant_masks(0), vec![0]);
+ assert_eq!(variant_masks(1), vec![1, 0]);
+ assert_eq!(variant_masks(2), vec![3, 2, 1, 0]);
+ assert_eq!(variant_masks(4).len(), MAX_PLAN_VARIANTS);
+ }
+
+ #[test]
+ fn one_wrong_macro_no_longer_costs_the_whole_candidate() {
+ let mut vocab = png_image_vocabulary();
+ vocab.macros.insert("PNG_IMAGE_FORMAT".to_owned());
+ vocab
+ .records
+ .get_mut("png_image")
+ .unwrap()
+ .fields
+ .push(Field {
+ name: "format".to_owned(),
+ spelling: "png_uint_32".to_owned(),
+ shape: Shape::Integral,
+ });
+ let plans = plan_candidate(&begin_read(), "png.h", &vocab).unwrap();
+ assert_eq!(plans.len(), 4);
+ let populated = |plan: &HarnessPlan| {
+ plan.body
+ .iter()
+ .filter(|s| matches!(s, Stmt::SetField { .. }))
+ .count()
+ };
+ assert_eq!(populated(&plans[0]), 2);
+ assert_eq!(populated(&plans[1]), 1);
+ assert_eq!(populated(&plans[2]), 1);
+ assert_eq!(populated(&plans[3]), 0);
+ }
+
#[test]
fn an_opaque_context_is_refused_rather_than_guessed() {
let mut opaque = begin_read();
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/verify.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/verify.rs
new file mode 100644
index 00000000..57ec730e
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/verify.rs
@@ -0,0 +1,375 @@
+// ©AngelaMos | 2026
+// verify.rs
+
+use std::collections::BTreeMap;
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use lisdex_core::process::{self, ProcessError};
+
+use crate::compile::{self, BuildSpec, DEFAULT_DRIVER, LeakCheck};
+use crate::coverage::{self, EdgeSet};
+use crate::oracle::{
+ self, EXEC_TIMEOUT_SECS, MIN_VALID_SEEDS, Observation, Rejection, RunStatus, SeedRun,
+};
+
+pub const COMPILE_TIMEOUT_SECS: u64 = 300;
+pub const DIAGNOSTIC_LINES: usize = 12;
+pub const MAX_SEEDS_PER_ORACLE: usize = 12;
+pub const MAPS_DIR: &str = "maps";
+pub const BINARIES_DIR: &str = "bin";
+
+#[derive(Debug, thiserror::Error)]
+pub enum VerifyError {
+ #[error(
+ "{path} holds {found} readable seed(s); the coverage oracle needs at least {MIN_VALID_SEEDS}"
+ )]
+ TooFewSeeds { path: PathBuf, found: usize },
+ #[error("io error at {path}: {source}")]
+ Io {
+ path: PathBuf,
+ source: std::io::Error,
+ },
+ #[error(
+ "{SHOWMAP} produced no coverage map for {seed} even though the harness ran clean on it"
+ )]
+ NoCoverageMap { seed: PathBuf },
+ #[error(transparent)]
+ Process(#[from] ProcessError),
+}
+
+const SHOWMAP: &str = compile::SHOWMAP;
+
+fn io(path: &Path) -> impl FnOnce(std::io::Error) -> VerifyError + '_ {
+ move |source| VerifyError::Io {
+ path: path.to_path_buf(),
+ source,
+ }
+}
+
+#[must_use]
+pub fn sample(mut files: Vec<PathBuf>, limit: usize) -> Vec<PathBuf> {
+ files.sort();
+ if files.len() <= limit || limit == 0 {
+ return files;
+ }
+ // Taking the first N of a sorted corpus takes N near-identical neighbours; an even
+ // stride keeps the spread the inter-seed divergence oracle depends on.
+ (0..limit)
+ .map(|index| files[index * files.len() / limit].clone())
+ .collect()
+}
+
+fn read_dir(path: &Path) -> Result<Vec<PathBuf>, VerifyError> {
+ let mut files = Vec::new();
+ for entry in std::fs::read_dir(path).map_err(io(path))? {
+ let entry = entry.map_err(io(path))?;
+ if entry.path().is_file() {
+ files.push(entry.path());
+ }
+ }
+ Ok(files)
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct Corpus {
+ pub valid: Vec<PathBuf>,
+ pub invalid: Vec<PathBuf>,
+}
+
+impl Corpus {
+ pub fn read(valid: &Path, invalid: Option<&Path>) -> Result<Self, VerifyError> {
+ let found = sample(read_dir(valid)?, MAX_SEEDS_PER_ORACLE);
+ if found.len() < MIN_VALID_SEEDS {
+ return Err(VerifyError::TooFewSeeds {
+ path: valid.to_path_buf(),
+ found: found.len(),
+ });
+ }
+ let rejected = match invalid {
+ Some(dir) => sample(read_dir(dir)?, MAX_SEEDS_PER_ORACLE),
+ None => Vec::new(),
+ };
+ Ok(Self {
+ valid: found,
+ invalid: rejected,
+ })
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct Toolchain {
+ pub includes: Vec<PathBuf>,
+ pub defines: Vec<String>,
+ pub cflags: Vec<String>,
+ pub archives: Vec<PathBuf>,
+ pub link_args: Vec<String>,
+ pub driver: PathBuf,
+}
+
+impl Default for Toolchain {
+ fn default() -> Self {
+ Self {
+ includes: Vec::new(),
+ defines: Vec::new(),
+ cflags: Vec::new(),
+ archives: Vec::new(),
+ link_args: Vec::new(),
+ driver: PathBuf::from(DEFAULT_DRIVER),
+ }
+ }
+}
+
+impl Toolchain {
+ #[must_use]
+ pub fn spec(&self, source: &Path, output: &Path) -> BuildSpec {
+ let mut spec = BuildSpec::new(source, output);
+ spec.includes.clone_from(&self.includes);
+ spec.defines.clone_from(&self.defines);
+ spec.cflags.clone_from(&self.cflags);
+ spec.archives.clone_from(&self.archives);
+ spec.link_args.clone_from(&self.link_args);
+ spec.driver.clone_from(&self.driver);
+ spec
+ }
+}
+
+#[derive(Debug, Clone)]
+pub struct Verdict {
+ pub label: String,
+ pub source: PathBuf,
+ pub binary: PathBuf,
+ pub outcome: Result<EdgeSet, Rejection>,
+ pub observation: Option<Observation>,
+}
+
+#[derive(Debug, Clone)]
+pub struct Bench {
+ pub work: PathBuf,
+ pub corpus: Corpus,
+ pub toolchain: Toolchain,
+}
+
+impl Bench {
+ #[must_use]
+ pub fn new(work: impl Into<PathBuf>, corpus: Corpus, toolchain: Toolchain) -> Self {
+ Self {
+ work: work.into(),
+ corpus,
+ toolchain,
+ }
+ }
+
+ fn build(&self, source: &Path, binary: &Path) -> Result<Option<Rejection>, VerifyError> {
+ if let Some(parent) = binary.parent() {
+ std::fs::create_dir_all(parent).map_err(io(parent))?;
+ }
+ let _ = std::fs::remove_file(binary);
+ let spec = self.toolchain.spec(source, binary);
+ let run = process::run(
+ &compile::build_command(&spec),
+ Duration::from_secs(COMPILE_TIMEOUT_SECS),
+ )?;
+ if run.success && binary.is_file() {
+ return Ok(None);
+ }
+ Ok(Some(Rejection::CompileFailed {
+ diagnostic: run.tail(DIAGNOSTIC_LINES),
+ }))
+ }
+
+ fn exercise(
+ binary: &Path,
+ seed: &Path,
+ map: &Path,
+ leaks: LeakCheck,
+ ) -> Result<SeedRun, VerifyError> {
+ // afl-showmap returns 0 on a genuine SEGV, so the exit status has to come from a
+ // direct run. That run is also the only path where LeakSanitizer fires, because
+ // afl-fuzz injects detect_leaks=0 into every child.
+ let direct = process::run(
+ &compile::exercise_command(binary, seed, leaks),
+ Duration::from_secs(EXEC_TIMEOUT_SECS),
+ )?;
+ let status = if direct.timed_out {
+ RunStatus::TimedOut
+ } else if direct.success {
+ RunStatus::Clean
+ } else {
+ RunStatus::NonZeroExit
+ };
+
+ let _ = std::fs::remove_file(map);
+ process::run(
+ &compile::showmap_command(binary, seed, map),
+ Duration::from_secs(EXEC_TIMEOUT_SECS * 2),
+ )?;
+ let coverage = match std::fs::read_to_string(map) {
+ Ok(text) => coverage::parse_showmap(&text),
+ Err(_) if status != RunStatus::Clean => EdgeSet::new(),
+ Err(_) => {
+ return Err(VerifyError::NoCoverageMap {
+ seed: seed.to_path_buf(),
+ });
+ }
+ };
+
+ Ok(SeedRun {
+ seed: seed.to_path_buf(),
+ map: coverage,
+ status,
+ stderr: direct.stderr,
+ })
+ }
+
+ fn observe(&self, label: &str, binary: &Path) -> Result<Observation, VerifyError> {
+ let maps = self.work.join(MAPS_DIR).join(label);
+ std::fs::create_dir_all(&maps).map_err(io(&maps))?;
+ let mut observation = Observation::default();
+ for (index, seed) in self.corpus.valid.iter().enumerate() {
+ let map = maps.join(format!("valid-{index}.map"));
+ let run = Self::exercise(binary, seed, &map, LeakCheck::Enforce)?;
+ // The execution oracle runs before any coverage oracle, so once one seed is
+ // dirty the verdict is settled and the remaining runs are wasted work.
+ let dirty = run.status != RunStatus::Clean;
+ observation.valid.push(run);
+ if dirty {
+ return Ok(observation);
+ }
+ }
+ // A leak on a malformed input can be the library's own error path, which is a
+ // finding rather than a reason to throw the harness away.
+ for (index, seed) in self.corpus.invalid.iter().enumerate() {
+ let map = maps.join(format!("invalid-{index}.map"));
+ observation
+ .invalid
+ .push(Self::exercise(binary, seed, &map, LeakCheck::Ignore)?);
+ }
+ Ok(observation)
+ }
+
+ pub fn verify(
+ &self,
+ source: &Path,
+ label: &str,
+ parent: Option<&BTreeMap<PathBuf, EdgeSet>>,
+ accepted: &EdgeSet,
+ ) -> Result<Verdict, VerifyError> {
+ let binary = self.work.join(BINARIES_DIR).join(label);
+ if let Some(rejection) = self.build(source, &binary)? {
+ return Ok(Verdict {
+ label: label.to_owned(),
+ source: source.to_path_buf(),
+ binary,
+ outcome: Err(rejection),
+ observation: None,
+ });
+ }
+ let observation = self.observe(label, &binary)?;
+ let outcome = oracle::judge(&observation, parent, accepted);
+ Ok(Verdict {
+ label: label.to_owned(),
+ source: source.to_path_buf(),
+ binary,
+ outcome,
+ observation: Some(observation),
+ })
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn scratch(label: &str) -> PathBuf {
+ let dir =
+ std::env::temp_dir().join(format!("lisdex-verify-{label}-{}", std::process::id()));
+ let _ = std::fs::remove_dir_all(&dir);
+ std::fs::create_dir_all(&dir).unwrap();
+ dir
+ }
+
+ fn seeded(label: &str, count: usize) -> PathBuf {
+ let dir = scratch(label);
+ for index in 0..count {
+ let byte = u8::try_from(index & 0xFF).unwrap_or_default();
+ std::fs::write(dir.join(format!("seed-{index:03}")), [byte]).unwrap();
+ }
+ dir
+ }
+
+ #[test]
+ fn a_corpus_smaller_than_the_oracle_floor_is_an_error_not_a_pass() {
+ let dir = seeded("tiny", 1);
+ assert!(matches!(
+ Corpus::read(&dir, None),
+ Err(VerifyError::TooFewSeeds { found: 1, .. })
+ ));
+ }
+
+ #[test]
+ fn a_corpus_is_read_deterministically() {
+ let dir = seeded("determinism", 5);
+ let once = Corpus::read(&dir, None).unwrap();
+ let twice = Corpus::read(&dir, None).unwrap();
+ assert_eq!(once.valid, twice.valid);
+ }
+
+ #[test]
+ fn a_large_corpus_is_capped_but_stays_spread() {
+ let files: Vec<PathBuf> = (0..100).map(|i| PathBuf::from(format!("{i:03}"))).collect();
+ let taken = sample(files, 10);
+ assert_eq!(taken.len(), 10);
+ assert_eq!(taken[0], PathBuf::from("000"));
+ assert_eq!(taken[9], PathBuf::from("090"));
+ }
+
+ #[test]
+ fn a_corpus_at_or_below_the_cap_is_taken_whole() {
+ let files: Vec<PathBuf> = (0..4).map(|i| PathBuf::from(format!("{i}"))).collect();
+ assert_eq!(sample(files.clone(), 12), files);
+ }
+
+ #[test]
+ fn an_invalid_corpus_is_optional() {
+ let dir = seeded("optional", 3);
+ let corpus = Corpus::read(&dir, None).unwrap();
+ assert!(corpus.invalid.is_empty());
+ }
+
+ #[test]
+ fn the_toolchain_reaches_the_build_spec() {
+ let mut toolchain = Toolchain::default();
+ toolchain.archives.push(PathBuf::from("/out/libpng16.a"));
+ toolchain.link_args.push("-lz".to_owned());
+ toolchain.includes.push(PathBuf::from("/src"));
+ let spec = toolchain.spec(Path::new("/w/h.c"), Path::new("/w/h.bin"));
+ let line = compile::build_command(&spec).command_line();
+ assert!(line.contains("libpng16.a"));
+ assert!(line.contains("-lz"));
+ assert!(line.contains("-I/src"));
+ }
+
+ #[test]
+ fn a_source_that_does_not_compile_is_a_rejection_not_an_error() {
+ let work = scratch("nocompile");
+ let seeds = seeded("nocompile-seeds", 3);
+ let source = work.join("broken.c");
+ std::fs::write(&source, "this is not c\n").unwrap();
+ let bench = Bench::new(
+ &work,
+ Corpus::read(&seeds, None).unwrap(),
+ Toolchain {
+ driver: PathBuf::from("/nonexistent/libAFLDriver.a"),
+ ..Toolchain::default()
+ },
+ );
+ let Ok(verdict) = bench.verify(&source, "broken", None, &EdgeSet::new()) else {
+ return;
+ };
+ assert!(matches!(
+ verdict.outcome,
+ Err(Rejection::CompileFailed { .. })
+ ));
+ }
+}
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/extract.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/extract.rs
index 3e9a146c..9fdd64f3 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/extract.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/extract.rs
@@ -11,9 +11,24 @@ use clang::{Clang, Entity, EntityKind, Index, Type, TypeKind};
use crate::signature::{Param, Pointee, Returns, Shape};
static PARSE_LOCK: Mutex<()> = Mutex::new(());
+thread_local! {
+ static PARSING: std::cell::Cell<bool> = const { std::cell::Cell::new(false) };
+}
+
+struct ReentryGuard;
+
+impl Drop for ReentryGuard {
+ fn drop(&mut self) {
+ PARSING.set(false);
+ }
+}
pub const C_ARGS: [&str; 3] = ["-x", "c", "-std=c11"];
pub const CPP_ARGS: [&str; 3] = ["-x", "c++", "-std=c++17"];
+pub const TEARDOWN_VERBS: [&str; 12] = [
+ "free", "destroy", "release", "delete", "close", "cleanup", "end", "fini", "finish", "dispose",
+ "uninit", "deinit",
+];
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum Language {
@@ -77,6 +92,8 @@ pub struct Record {
pub struct Vocabulary {
pub macros: BTreeSet<String>,
pub records: BTreeMap<String, Record>,
+ pub produced: BTreeSet<String>,
+ pub destructors: BTreeMap<String, BTreeSet<String>>,
}
impl Vocabulary {
@@ -85,6 +102,13 @@ impl Vocabulary {
for (name, record) in other.records {
self.records.entry(name).or_insert(record);
}
+ self.produced.extend(other.produced);
+ for (record, functions) in other.destructors {
+ self.destructors
+ .entry(record)
+ .or_default()
+ .extend(functions);
+ }
}
}
@@ -118,12 +142,21 @@ pub enum ExtractError {
count: usize,
first: String,
},
+ #[error(
+ "a libclang parse was started from inside another one; PARSE_LOCK is not reentrant and would deadlock forever"
+ )]
+ Reentrant,
}
pub fn with_index<T, F>(action: F) -> Result<T, ExtractError>
where
F: FnOnce(&Index) -> Result<T, ExtractError>,
{
+ // The lock is not reentrant, so a nested parse used to hang with no output at all.
+ if PARSING.replace(true) {
+ return Err(ExtractError::Reentrant);
+ }
+ let _reentry = ReentryGuard;
let _guard = PARSE_LOCK.lock().unwrap_or_else(PoisonError::into_inner);
let clang = Clang::new().map_err(ExtractError::Libclang)?;
let index = Index::new(&clang, false, false);
@@ -295,9 +328,75 @@ fn record_fields(entity: &Entity) -> Vec<Field> {
.collect()
}
-fn collect_vocabulary(entity: &Entity, into: &mut Vocabulary) {
+#[must_use]
+pub fn identifier_words(name: &str) -> Vec<String> {
+ let mut words = Vec::new();
+ for part in name.split(['_', '-']) {
+ let chars: Vec<char> = part.chars().collect();
+ let mut start = 0;
+ for index in 1..chars.len() {
+ let upper = chars[index].is_uppercase();
+ let after_lower = chars[index - 1].is_lowercase() || chars[index - 1].is_ascii_digit();
+ let before_lower = chars.get(index + 1).is_some_and(|next| next.is_lowercase());
+ if upper && (after_lower || (chars[index - 1].is_uppercase() && before_lower)) {
+ words.push(chars[start..index].iter().collect());
+ start = index;
+ }
+ }
+ if start < chars.len() {
+ words.push(chars[start..].iter().collect());
+ }
+ }
+ words
+}
+
+fn is_teardown_name(name: &str) -> bool {
+ identifier_words(name).iter().any(|word| {
+ TEARDOWN_VERBS
+ .iter()
+ .any(|verb| word.eq_ignore_ascii_case(verb))
+ })
+}
+
+fn sole_record_parameter(entity: &Entity) -> Option<String> {
+ let arguments = entity.get_arguments()?;
+ let [only] = arguments.as_slice() else {
+ return None;
+ };
+ match shape_of(&only.get_type()?) {
+ Shape::Pointer {
+ pointee: Pointee::Record(name),
+ ..
+ } => Some(name),
+ _ => None,
+ }
+}
+
+fn collect_relations(entity: &Entity, target: &Path, into: &mut Vocabulary) {
+ let Some(name) = entity.get_name() else {
+ return;
+ };
+ if declared_in(entity, target).is_none() {
+ return;
+ }
+ if let Shape::Pointer {
+ pointee: Pointee::Record(record),
+ ..
+ } = result_of(entity).shape
+ {
+ into.produced.insert(record);
+ }
+ if is_teardown_name(&name)
+ && let Some(record) = sole_record_parameter(entity)
+ {
+ into.destructors.entry(record).or_default().insert(name);
+ }
+}
+
+fn collect_vocabulary(entity: &Entity, target: &Path, into: &mut Vocabulary) {
for child in entity.get_children() {
match child.get_kind() {
+ EntityKind::FunctionDecl => collect_relations(&child, target, into),
EntityKind::MacroDefinition => {
if child.is_builtin_macro() || child.is_function_like_macro() {
continue;
@@ -327,7 +426,7 @@ fn collect_vocabulary(entity: &Entity, into: &mut Vocabulary) {
}
}
EntityKind::LinkageSpec | EntityKind::Namespace | EntityKind::UnexposedDecl => {
- collect_vocabulary(&child, into);
+ collect_vocabulary(&child, target, into);
}
_ => {}
}
@@ -372,7 +471,7 @@ pub fn parse_vocabulary(path: &Path, options: &ParseOptions) -> Result<Vocabular
}
let mut vocabulary = Vocabulary::default();
- collect_vocabulary(&unit.get_entity(), &mut vocabulary);
+ collect_vocabulary(&unit.get_entity(), &target, &mut vocabulary);
Ok(vocabulary)
})
}
@@ -459,6 +558,100 @@ typedef struct png_image {
int png_image_begin_read_from_memory(png_image *image, const void *m, unsigned long s);
";
+ const ZLIB_GZ_API: &str = r"
+struct gzFile_s { unsigned have; unsigned char *next; long pos; };
+typedef struct gzFile_s *gzFile;
+gzFile gzopen(const char *path, const char *mode);
+int gzclose(gzFile file);
+int gzputs(gzFile file, const char *s);
+";
+
+ const WEBP_API: &str = r"
+typedef struct WebPDecBuffer { int colorspace; unsigned char *rgba; } WebPDecBuffer;
+typedef struct WebPDecoderConfig { int bypass; WebPDecBuffer output; } WebPDecoderConfig;
+int WebPDecode(const unsigned char *data, unsigned long size, WebPDecoderConfig *config);
+void WebPFreeDecBuffer(WebPDecBuffer *buffer);
+";
+
+ #[test]
+ fn a_nested_parse_errors_instead_of_deadlocking_forever() {
+ let inner = header("reentrant_inner", SIMPLIFIED_API);
+ let outcome: Result<(), ExtractError> = with_index(|_| {
+ parse_header(&inner, &ParseOptions::default())?;
+ Ok(())
+ });
+ assert!(matches!(outcome, Err(ExtractError::Reentrant)));
+ }
+
+ #[test]
+ fn the_reentrancy_flag_is_cleared_so_the_next_parse_still_works() {
+ let path = header("reentrant_after", SIMPLIFIED_API);
+ let _ = with_index(|_| {
+ parse_header(&path, &ParseOptions::default())?;
+ Ok(())
+ });
+ assert!(parse_header(&path, &ParseOptions::default()).is_ok());
+ }
+
+ #[test]
+ fn a_record_the_library_allocates_for_you_is_recorded_as_produced() {
+ let vocab = vocabulary("produced", ZLIB_GZ_API);
+ assert!(
+ vocab.produced.contains("gzFile_s"),
+ "gzopen returns struct gzFile_s *, so the exposed prefix is not a usable stack local"
+ );
+ }
+
+ #[test]
+ fn a_caller_allocated_context_is_not_recorded_as_produced() {
+ let vocab = vocabulary("not_produced", SIMPLIFIED_API);
+ assert!(!vocab.produced.contains("png_image"));
+ }
+
+ #[test]
+ fn a_single_pointer_teardown_is_paired_with_its_record() {
+ let vocab = vocabulary("teardown_camel", WEBP_API);
+ assert_eq!(
+ vocab.destructors.get("WebPDecBuffer"),
+ Some(&BTreeSet::from(["WebPFreeDecBuffer".to_owned()])),
+ "an unpaired constructor fabricates a LeakSanitizer report inside the target"
+ );
+ }
+
+ #[test]
+ fn a_teardown_is_found_through_a_run_of_capitals() {
+ assert_eq!(
+ identifier_words("WebPFreeDecBuffer"),
+ vec!["Web", "P", "Free", "Dec", "Buffer"]
+ );
+ }
+
+ #[test]
+ fn a_verb_only_matches_a_whole_word_never_a_substring() {
+ assert!(!is_teardown_name("archive_entry_append"));
+ assert!(!is_teardown_name("png_extend_row"));
+ assert!(is_teardown_name("inflateEnd"));
+ assert!(is_teardown_name("archive_read_free"));
+ }
+
+ #[test]
+ fn a_multi_parameter_teardown_is_not_paired() {
+ let vocab = vocabulary(
+ "teardown_multi",
+ "struct s { int a; };\nvoid s_destroy(struct s *p, int mode);\n",
+ );
+ assert!(vocab.destructors.is_empty());
+ }
+
+ #[test]
+ fn every_teardown_candidate_for_one_record_is_kept_for_the_planner_to_choose() {
+ let vocab = vocabulary(
+ "teardown_many",
+ "struct z_stream_s { int x; };\ntypedef struct z_stream_s z_stream;\nint deflateEnd(z_stream *s);\nint inflateEnd(z_stream *s);\n",
+ );
+ assert_eq!(vocab.destructors["z_stream_s"].len(), 2);
+ }
+
#[test]
fn a_macro_is_collected_by_name() {
let vocab = vocabulary("macros", SIMPLIFIED_API);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
index 70bdde9d..ffc454a2 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
@@ -68,6 +68,7 @@ pub struct HeaderSet {
pub const PRIVATE_MARKERS: &[&str] = &["priv", "internal", "impl", "iop"];
pub const PRIVATE_SUFFIXES: &[&str] = &["_p", "-p", "_int"];
+pub const LICENSE_STEMS: &[&str] = &["license", "licence", "copying", "copyright", "notice"];
#[must_use]
pub fn is_private_header(path: &Path) -> bool {
@@ -95,6 +96,24 @@ pub fn is_excluded(name: &str) -> bool {
EXCLUDED_DIRS.contains(&name.to_lowercase().as_str())
}
+#[must_use]
+pub fn is_vendored_tree(dir: &Path) -> bool {
+ // A name list never ends: libjpeg-turbo vendors a whole PNG decoder at src/spng and
+ // ranked eight spng_* functions in its own top 20. The structural signal is that the
+ // subdirectory carries its own licence while the project's licence sits at the root.
+ let Ok(entries) = std::fs::read_dir(dir) else {
+ return false;
+ };
+ entries.flatten().any(|entry| {
+ entry.file_type().is_ok_and(|kind| kind.is_file())
+ && entry
+ .path()
+ .file_stem()
+ .and_then(|stem| stem.to_str())
+ .is_some_and(|stem| LICENSE_STEMS.contains(&stem.to_lowercase().as_str()))
+ })
+}
+
fn collect(root: &Path, depth: usize, found: &mut Vec<PathBuf>) -> Result<(), HeaderError> {
if depth > MAX_DEPTH {
return Ok(());
@@ -111,7 +130,7 @@ fn collect(root: &Path, depth: usize, found: &mut Vec<PathBuf>) -> Result<(), He
let path = entry.path();
let name = entry.file_name().to_string_lossy().into_owned();
if path.is_dir() {
- if !is_excluded(&name) {
+ if !is_excluded(&name) && !is_vendored_tree(&path) {
collect(&path, depth + 1, found)?;
}
} else if is_header(&path) && !is_private_header(&path) {
@@ -236,6 +255,42 @@ mod tests {
assert_eq!(names(&set), vec!["png.h"]);
}
+ #[test]
+ fn a_subdirectory_carrying_its_own_licence_is_a_vendored_tree() {
+ let root = fixture(
+ "vendored",
+ &[
+ "LICENSE.md",
+ "include/turbojpeg.h",
+ "include/spng/LICENSE",
+ "include/spng/spng.h",
+ ],
+ );
+ let set = discover(&root, None).unwrap();
+ assert_eq!(
+ names(&set),
+ vec!["turbojpeg.h"],
+ "libjpeg-turbo ranked eight spng_* functions from a vendored PNG decoder"
+ );
+ }
+
+ #[test]
+ fn the_projects_own_licence_at_the_root_excludes_nothing() {
+ let root = fixture("root_licence", &["COPYING", "include/archive.h"]);
+ let set = discover(&root, None).unwrap();
+ assert_eq!(names(&set), vec!["archive.h"]);
+ }
+
+ #[test]
+ fn a_licence_like_name_that_is_not_a_licence_does_not_exclude_a_tree() {
+ let root = fixture(
+ "licence_prefix",
+ &["include/lib/libpng-LICENSE.txt", "include/lib/png.h"],
+ );
+ let set = discover(&root, None).unwrap();
+ assert_eq!(names(&set), vec!["png.h"]);
+ }
+
#[test]
fn an_include_directory_is_used_when_nothing_was_installed() {
let root = fixture("includedir", &["include/tiff.h", "libtiff/tif_dir.c"]);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs
index a5d0aa6a..397586d0 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs
@@ -123,7 +123,7 @@ fn walk_sources(root: &Path, depth: usize, found: &mut Vec<PathBuf>) {
let path = entry.path();
let name = entry.file_name().to_string_lossy().to_lowercase();
if path.is_dir() {
- if !headers::is_excluded(&name) {
+ if !headers::is_excluded(&name) && !headers::is_vendored_tree(&path) {
walk_sources(&path, depth + 1, found);
}
} else if is_source(&path) {
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 8e4608a9..6eabee99 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
@@ -15,8 +15,10 @@ use lisdex_core::campaign::{Campaign, CampaignId, CampaignStatus};
use lisdex_core::report::SanitizerReport;
use lisdex_core::store::Store;
use lisdex_fuzz::runner::{self, AflOptions};
+use lisdex_harness::coverage::EdgeSet;
use lisdex_harness::emit;
use lisdex_harness::synth;
+use lisdex_harness::verify::{Bench, Corpus, Toolchain, Verdict};
use lisdex_ingest::acquire::{self, Source};
use lisdex_ingest::detect;
use lisdex_surface::extract::{self, Language};
@@ -31,6 +33,16 @@ const SOURCES_DIR: &str = "sources";
const BUILDS_DIR: &str = "builds";
const DEFAULT_SURFACE_TOP: usize = 20;
const MAX_SKIPPED_SHOWN: usize = 10;
+const CANDIDATES_DIR: &str = "candidates";
+const ORACLE_WORK_DIR: &str = "oracle";
+const NO_SEEDS: &str = "--seeds is required: the harness oracles run the candidate against a \
+ valid corpus, and without one lisdex cannot tell a working harness from \
+ one that reads nothing. Pass --no-verify to emit an unchecked harness \
+ anyway";
+const NO_ARCHIVE: &str = "--archive is required: the harness has to link against the \
+ instrumented library that `lisdex build` produced";
+const UNVERIFIED_BANNER: &str = "UNVERIFIED: no oracle was run against this harness. It may not \
+ compile, may crash on valid input, or may read none of it.";
#[derive(Parser)]
#[command(
@@ -53,6 +65,8 @@ enum Command {
Surface(SurfaceArgs),
#[command(about = "synthesize a fuzz harness for a ranked entry point, with no LLM")]
Harness(HarnessArgs),
+ #[command(about = "run the four harness oracles against one harness source file")]
+ Verify(VerifyArgs),
#[command(about = "list the crashes persisted for a campaign")]
Crashes(CrashesArgs),
}
@@ -119,6 +133,105 @@ struct CrashesArgs {
campaign: i64,
}
+#[derive(clap::Args)]
+struct OracleArgs {
+ #[arg(
+ long,
+ help = "directory of valid inputs the oracles run the harness against"
+ )]
+ seeds: Option<PathBuf>,
+ #[arg(
+ long = "invalid-seeds",
+ help = "directory of malformed inputs for the valid-versus-invalid differential"
+ )]
+ invalid_seeds: Option<PathBuf>,
+ #[arg(
+ long = "archive",
+ help = "instrumented library archive to link against, repeatable"
+ )]
+ archives: Vec<PathBuf>,
+ #[arg(
+ long = "link-arg",
+ allow_hyphen_values = true,
+ help = "extra linker argument, repeatable"
+ )]
+ link_args: Vec<String>,
+ #[arg(
+ long = "cflag",
+ allow_hyphen_values = true,
+ help = "extra compiler flag, repeatable"
+ )]
+ cflags: Vec<String>,
+ #[arg(long, help = "libAFLDriver.a to link the harness against")]
+ driver: Option<PathBuf>,
+ #[arg(long, help = "scratch directory for oracle binaries and coverage maps")]
+ work: Option<PathBuf>,
+}
+
+impl OracleArgs {
+ fn toolchain(&self, includes: Vec<PathBuf>, defines: Vec<String>) -> Toolchain {
+ let mut toolchain = Toolchain {
+ includes,
+ defines,
+ cflags: self.cflags.clone(),
+ archives: self.archives.clone(),
+ link_args: self.link_args.clone(),
+ ..Toolchain::default()
+ };
+ if let Some(driver) = &self.driver {
+ toolchain.driver.clone_from(driver);
+ }
+ toolchain
+ }
+
+ fn bench(
+ &self,
+ includes: Vec<PathBuf>,
+ defines: Vec<String>,
+ fallback: &std::path::Path,
+ ) -> Result<Bench, Box<dyn Error>> {
+ let Some(seeds) = &self.seeds else {
+ return Err(NO_SEEDS.into());
+ };
+ if self.archives.is_empty() {
+ return Err(NO_ARCHIVE.into());
+ }
+ let toolchain = self.toolchain(includes, defines);
+ // A missing archive or driver surfaces as an undefined-symbol wall from the linker
+ // and every candidate is then rejected as CompileFailed for the wrong reason.
+ for archive in &toolchain.archives {
+ if !archive.is_file() {
+ return Err(format!("--archive {} is not a file", archive.display()).into());
+ }
+ }
+ if !toolchain.driver.is_file() {
+ return Err(format!(
+ "the AFL driver {} is not a file; pass --driver with the path to libAFLDriver.a",
+ toolchain.driver.display()
+ )
+ .into());
+ }
+ let corpus = Corpus::read(seeds, self.invalid_seeds.as_deref())?;
+ let work = self
+ .work
+ .clone()
+ .unwrap_or_else(|| fallback.join(ORACLE_WORK_DIR));
+ Ok(Bench::new(work, corpus, toolchain))
+ }
+}
+
+#[derive(clap::Args)]
+struct VerifyArgs {
+ #[arg(help = "harness source file to judge")]
+ source: PathBuf,
+ #[arg(long = "include", help = "extra include directory, repeatable")]
+ includes: Vec<PathBuf>,
+ #[arg(long = "define", help = "extra preprocessor define, repeatable")]
+ defines: Vec<String>,
+ #[command(flatten)]
+ oracle: OracleArgs,
+}
+
#[derive(clap::Args)]
struct HarnessArgs {
#[arg(help = "source tree of the target library")]
@@ -135,6 +248,13 @@ struct HarnessArgs {
top: usize,
#[arg(long, help = "directory to write the synthesized harness into")]
out: PathBuf,
+ #[arg(
+ long = "no-verify",
+ help = "emit the first candidate that plans without running any oracle against it"
+ )]
+ no_verify: bool,
+ #[command(flatten)]
+ oracle: OracleArgs,
}
#[derive(clap::Args)]
@@ -179,6 +299,7 @@ fn dispatch() -> Result<(), Box<dyn Error>> {
Command::Fuzz(args) => fuzz(args),
Command::Surface(args) => surface(args),
Command::Harness(args) => harness(args),
+ Command::Verify(args) => verify(args),
Command::Crashes(args) => crashes(args),
}
}
@@ -192,51 +313,149 @@ fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {
options.ignore_harnesses = true;
let analysis = surface::analyze(&options)?;
- let mut refusals = Vec::new();
-
let root = std::fs::canonicalize(&analysis.header_root)
.unwrap_or_else(|_| analysis.header_root.clone());
+ let parse = options.parse_options(&root);
+
+ let bench = if args.no_verify {
+ println!("{UNVERIFIED_BANNER}");
+ None
+ } else {
+ Some(
+ args.oracle
+ .bench(parse.includes.clone(), parse.defines.clone(), &args.out)?,
+ )
+ };
+
+ let candidates = args.out.join(CANDIDATES_DIR);
+ std::fs::create_dir_all(&candidates)?;
+ let mut rejected = Vec::new();
+ let mut accepted = EdgeSet::new();
+
for candidate in analysis.ranking.candidates.iter().take(args.top) {
- let vocabulary =
- extract::parse_vocabulary(&candidate.header, &options.parse_options(&root))?;
+ let vocabulary = extract::parse_vocabulary(&candidate.header, &parse)?;
let include = candidate
.header
.strip_prefix(&root)
.unwrap_or(&candidate.header)
.display()
.to_string();
- match synth::plan_candidate(candidate, &include, &vocabulary) {
- Ok(plans) => {
- let filename = format!("{}.c", candidate.name);
- let source = emit::render(&plans[0], &filename);
- let path = args.out.join(&filename);
- std::fs::create_dir_all(&args.out)?;
- std::fs::write(&path, &source)?;
- println!(
- "synthesized {} for {} ({} variant(s)) -> {}",
- filename,
- candidate.name,
- plans.len(),
- path.display()
- );
- for (index, plan) in plans.iter().enumerate().skip(1) {
- let alt = format!("{}.v{index}.c", candidate.name);
- std::fs::write(args.out.join(&alt), emit::render(plan, &alt))?;
- println!(" variant {index} -> {alt}");
+ let plans = match synth::plan_candidate(candidate, &include, &vocabulary) {
+ Ok(plans) => plans,
+ Err(refusal) => {
+ rejected.push(format!(" {} - refused: {refusal}", candidate.name));
+ continue;
+ }
+ };
+
+ // Every variant is written before any is judged: the rejected ones are the
+ // evidence trail, and the gate uses them as ready-made negative controls.
+ let mut emitted = Vec::with_capacity(plans.len());
+ for (index, plan) in plans.iter().enumerate() {
+ let label = format!("{}.v{index}", candidate.name);
+ let filename = format!("{label}.c");
+ let source = candidates.join(&filename);
+ std::fs::write(&source, emit::render(plan, &filename))?;
+ emitted.push((label, source));
+ }
+
+ for ((label, source), plan) in emitted.iter().zip(&plans) {
+ let Some(bench) = &bench else {
+ return promote(plan, candidate.name.as_str(), &args.out, plans.len(), None);
+ };
+
+ // No parent: D4's linearity oracle measures a candidate against the shorter
+ // call sequence it EXTENDS, and variants run most-populated first, so no
+ // later variant extends an earlier one. Feeding it a sibling would reject the
+ // fallback for a constant gain of zero, which is true and meaningless.
+ let verdict = bench.verify(source, label, None, &accepted)?;
+ match &verdict.outcome {
+ Ok(reached) => {
+ accepted.absorb(reached);
+ return promote(
+ plan,
+ candidate.name.as_str(),
+ &args.out,
+ plans.len(),
+ Some(&verdict),
+ );
}
- return Ok(());
+ Err(rejection) => rejected.push(format!(" {label} - {rejection}")),
}
- Err(refusal) => refusals.push(format!(" {} - {refusal}", candidate.name)),
}
}
- println!("no candidate in the top {} could be planned:", args.top);
- for line in refusals {
+ println!("no candidate in the top {} survived the oracles:", args.top);
+ for line in rejected {
println!("{line}");
}
Err("no harness synthesized".into())
}
+fn promote(
+ plan: &lisdex_harness::plan::HarnessPlan,
+ name: &str,
+ out: &std::path::Path,
+ variants: usize,
+ verdict: Option<&Verdict>,
+) -> Result<(), Box<dyn Error>> {
+ // Rendered again rather than copied so the file header names the file it is in.
+ let filename = format!("{name}.c");
+ let path = out.join(&filename);
+ std::fs::write(&path, emit::render(plan, &filename))?;
+ println!(
+ "synthesized {filename} for {name} ({variants} variant(s) planned) -> {}",
+ path.display()
+ );
+ match verdict {
+ Some(verdict) => {
+ let reached = verdict.outcome.as_ref().map_or(0, EdgeSet::len);
+ let observation = verdict.observation.as_ref();
+ println!(
+ "accepted by all four oracles: {} edges over {} valid and {} invalid seed(s), binary {}",
+ reached,
+ observation.map_or(0, |o| o.valid.len()),
+ observation.map_or(0, |o| o.invalid.len()),
+ verdict.binary.display()
+ );
+ }
+ None => println!("{UNVERIFIED_BANNER}"),
+ }
+ Ok(())
+}
+
+fn verify(args: &VerifyArgs) -> Result<(), Box<dyn Error>> {
+ let parent = args
+ .source
+ .parent()
+ .map_or_else(|| PathBuf::from("."), std::path::Path::to_path_buf);
+ let bench = args
+ .oracle
+ .bench(args.includes.clone(), args.defines.clone(), &parent)?;
+ let label = args.source.file_stem().map_or_else(
+ || UNKNOWN_TARGET.to_owned(),
+ |stem| stem.to_string_lossy().into_owned(),
+ );
+
+ let verdict = bench.verify(&args.source, &label, None, &EdgeSet::new())?;
+ match &verdict.outcome {
+ Ok(reached) => {
+ println!(
+ "ACCEPTED {} - {} edges over {} valid and {} invalid seed(s)",
+ args.source.display(),
+ reached.len(),
+ bench.corpus.valid.len(),
+ bench.corpus.invalid.len()
+ );
+ Ok(())
+ }
+ Err(rejection) => {
+ println!("REJECTED {} - {rejection}", args.source.display());
+ Err("the harness did not survive the oracles".into())
+ }
+ }
+}
+
fn surface(args: &SurfaceArgs) -> Result<(), Box<dyn Error>> {
let mut options = SurfaceOptions::new(&args.source);
options.install.clone_from(&args.install);
@@ -358,7 +577,7 @@ fn build(args: &BuildArgs) -> Result<(), Box<dyn Error>> {
.with_cmplog(args.cmplog)
.with_extra_cflags(args.cflags.clone());
- let layout = BuildLayout::new(&detected.root, args.work.join(BUILDS_DIR).join(&label));
+ let layout = BuildLayout::validated(&detected.root, args.work.join(BUILDS_DIR).join(&label))?;
let requirements = Requirements::library()
.with_cmplog(args.cmplog)
.with_magma_canaries(args.require_canaries);
@@ -464,8 +683,11 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
}
}
+ let persistent = check_persistent_mode(&options.findings, &args.target);
+
let stats = &outcome.stats;
println!("afl_version {}", stats.afl_version);
+ println!("persistent_mode {persistent}");
println!("clean_exit {}", outcome.clean_exit);
println!("execs_done {}", stats.execs_done);
println!("execs_per_sec {:.2}", stats.execs_per_sec);
@@ -519,6 +741,21 @@ fn fuzz(args: &FuzzArgs) -> Result<(), Box<dyn Error>> {
Ok(())
}
+fn check_persistent_mode(findings: &std::path::Path, target: &std::path::Path) -> bool {
+ // A harness that also defines main links silently against the driver's weak main and
+ // then fuzzes nothing at 1,597 execs/sec instead of 241,807.
+ let persistent = runner::read_stats_text(findings)
+ .is_ok_and(|text| lisdex_harness::compile::drives_persistent_mode(&text));
+ if !persistent {
+ eprintln!(
+ "warning: {} is not running in persistent shmem_testcase deferred mode; the harness \
+ may define its own main, which shadows the driver and fuzzes nothing",
+ target.display()
+ );
+ }
+ persistent
+}
+
fn fail_campaign(store: &Store, campaign: &mut Campaign, campaign_id: CampaignId) {
if campaign.advance(CampaignStatus::Failed).is_err() {
return;
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh
index 9bced85c..90d9ee33 100755
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh
@@ -11,13 +11,14 @@ OUT_ROOT="$WORK/out/libpng"
GATE="$WORK/m4"
SYNTH="$GATE/synth"
CORPUS="$GATE/corpus"
+INVALID="$GATE/invalid"
+CONTROLS="$GATE/controls"
FINDINGS="$GATE/findings"
DB="$GATE/lisdex.sqlite"
DRIVER="${LISDEX_AFL_DRIVER:-/usr/local/lib/afl/libAFLDriver.a}"
LISDEX_BIN="${CARGO_TARGET_DIR:-/cargo-target}/debug/lisdex"
GATE_DURATION="${LISDEX_M4_DURATION:-600}"
TOP="${LISDEX_M4_TOP:-12}"
-MIN_DIVERGENCE=5
CANARY_PREFIX="PNG"
CFLAGS_CANARY="-include $MAGMA/src/canary.h -DMAGMA_ENABLE_CANARIES -DMAGMA_FATAL_CANARIES -g -O0"
@@ -37,18 +38,64 @@ fi
[ -f "$OUT_ROOT/afl/libpng16.a" ] || die "magma libpng not built; run: just magma-libpng"
[ -f "$DRIVER" ] || die "libAFLDriver.a missing at $DRIVER"
-log "stage 1/7: build lisdex"
+log "stage 1/10: build lisdex"
cargo build -p lisdex
[ -x "$LISDEX_BIN" ] || die "lisdex binary not found at $LISDEX_BIN"
-log "stage 2/7: synthesize a harness with NO LLM"
+log "stage 2/10: assemble the two corpora the oracles need"
mkdir -p "$GATE"
+rm -rf "$CORPUS" "$INVALID" "$CONTROLS"
+mkdir -p "$CORPUS" "$INVALID" "$CONTROLS"
+cp "$REPO"/contrib/pngsuite/*.png "$CORPUS/"
+SEEDS="$(find "$CORPUS" -name '*.png' | wc -l)"
+[ "$SEEDS" -ge 2 ] || die "only $SEEDS valid seed(s); the coverage oracle needs at least 2"
+FIRST_PNG="$(find "$CORPUS" -name '*.png' | sort | head -1)"
+head -c 40 "$FIRST_PNG" > "$INVALID/truncated.png"
+printf 'not a png at all, not even close\n' > "$INVALID/text.png"
+head -c 200 /dev/urandom > "$INVALID/random.png"
+pass "$SEEDS valid seeds and 3 invalid seeds staged"
+
+# Every oracle assertion below runs through the shipped judge(), never a shell
+# reimplementation of it. Gutting oracle::judge must turn this gate red.
+oracle_flags() {
+ printf '%s\0' \
+ --seeds "$CORPUS" \
+ --invalid-seeds "$INVALID" \
+ --archive "$OUT_ROOT/afl/libpng16.a" \
+ --driver "$DRIVER" \
+ --link-arg "-L$OUT_ROOT/afl" \
+ --link-arg "-l:magma.o" \
+ --link-arg "-lrt" \
+ --link-arg "-lz" \
+ --link-arg "-g" \
+ --cflag "-include" \
+ --cflag "$MAGMA/src/canary.h" \
+ --cflag "-DMAGMA_ENABLE_CANARIES" \
+ --cflag "-DMAGMA_FATAL_CANARIES" \
+ --cflag "-g" \
+ --cflag "-O0"
+}
+
+lisdex_verify() {
+ SRC="$1"; SCRATCH="$2"
+ rm -rf "$SCRATCH"
+ mapfile -d '' FLAGS < <(oracle_flags)
+ "$LISDEX_BIN" verify "$SRC" --include "$REPO" --work "$SCRATCH" "${FLAGS[@]}"
+}
+
+log "stage 3/10: lisdex synthesizes AND self-verifies a harness with NO LLM"
rm -rf "$SYNTH"
-"$LISDEX_BIN" harness "$REPO" --out "$SYNTH" --top "$TOP" | tee "$GATE/synth.log"
-ENTRY="$(find "$SYNTH" -maxdepth 1 -name '*.c' ! -name '*.v[0-9].c' | head -1)"
+mapfile -d '' HARNESS_FLAGS < <(oracle_flags)
+"$LISDEX_BIN" harness "$REPO" --out "$SYNTH" --top "$TOP" "${HARNESS_FLAGS[@]}" \
+ | tee "$GATE/synth.log"
+ENTRY="$(find "$SYNTH" -maxdepth 1 -name '*.c' | head -1)"
[ -n "$ENTRY" ] || die "no harness was synthesized"
ENTRY_NAME="$(basename "$ENTRY" .c)"
-pass "synthesized a harness for $ENTRY_NAME"
+if grep -q 'accepted by all four oracles' "$GATE/synth.log"; then
+ pass "lisdex accepted $ENTRY_NAME through its own oracle layer"
+else
+ fail "lisdex emitted a harness without reporting an oracle verdict"
+fi
if grep -q 'LLVMFuzzerTestOneInput' "$ENTRY"; then
pass "harness defines LLVMFuzzerTestOneInput"
@@ -72,7 +119,7 @@ build_harness() {
)
}
-log "stage 3/7: ORACLE 1 - it compiles"
+log "stage 4/10: independent cross-check - it compiles and every valid seed runs clean"
if build_harness "$ENTRY" "$GATE/harness" afl 2>"$GATE/compile.log"; then
pass "synthesized harness compiles and links"
else
@@ -82,43 +129,30 @@ fi
build_harness "$ENTRY" "$GATE/harness_cmplog" cmplog cmplog >/dev/null 2>&1 \
|| die "cmplog variant does not compile"
-log "stage 4/7: ORACLE 2 - it runs clean on every valid seed"
-rm -rf "$CORPUS"; mkdir -p "$CORPUS"
-cp "$REPO"/contrib/pngsuite/*.png "$CORPUS/"
-SEEDS="$(find "$CORPUS" -name '*.png' | wc -l)"
CLEAN=0; CRASHED=0
for SEED in "$CORPUS"/*.png; do
- if ASAN_OPTIONS=detect_leaks=0 "$GATE/harness" "$SEED" >/dev/null 2>&1; then
+ if ASAN_OPTIONS=detect_leaks=1 "$GATE/harness" "$SEED" >/dev/null 2>&1; then
CLEAN=$((CLEAN + 1))
else
CRASHED=$((CRASHED + 1))
fi
done
if [ "$CRASHED" -eq 0 ]; then
- pass "$CLEAN/$SEEDS valid seeds run clean"
+ pass "$CLEAN/$SEEDS valid seeds run clean with leak detection ON"
else
- fail "$CRASHED/$SEEDS valid seeds crash - the oracle would be unsound"
+ fail "$CRASHED/$SEEDS valid seeds crash or leak - the oracle would be unsound"
fi
-divergence() {
- BIN="$1"
- A="$(find "$CORPUS" -name '*.png' | sort | head -1)"
- B="$(find "$CORPUS" -name '*.png' | sort | tail -1)"
- ASAN_OPTIONS=detect_leaks=0 afl-showmap -o "$GATE/ma" -t 5000 -- "$BIN" "$A" >/dev/null 2>&1 || true
- ASAN_OPTIONS=detect_leaks=0 afl-showmap -o "$GATE/mb" -t 5000 -- "$BIN" "$B" >/dev/null 2>&1 || true
- cat "$GATE/ma" "$GATE/mb" | cut -d: -f1 | sort | uniq -u | wc -l
-}
-
-log "stage 5/7: ORACLE 3 - inter-seed coverage divergence"
-LIVE_DIV="$(divergence "$GATE/harness")"
-if [ "$LIVE_DIV" -gt "$MIN_DIVERGENCE" ]; then
- pass "accepted harness diverges by $LIVE_DIV edges across seeds (floor $MIN_DIVERGENCE)"
+log "stage 5/10: the shipped judge ACCEPTS the harness it chose"
+if lisdex_verify "$ENTRY" "$GATE/verify-accepted" > "$GATE/verify-accepted.log" 2>&1; then
+ pass "$(grep -m1 ACCEPTED "$GATE/verify-accepted.log" || echo 'accepted')"
else
- fail "accepted harness diverges by only $LIVE_DIV edges - it is not reading its input"
+ tail -5 "$GATE/verify-accepted.log" >&2
+ fail "the shipped judge rejects the harness lisdex itself accepted"
fi
-log "stage 5b/7: NEGATIVE CONTROL - a stub harness must be REJECTED"
-cat > "$GATE/stub.c" <<'STUB'
+log "stage 6/10: NEGATIVE CONTROL - a stub that ignores its input must be REJECTED"
+cat > "$CONTROLS/stub.c" <<'STUB'
// ©AngelaMos | 2026
// stub.c
@@ -134,33 +168,108 @@ int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
return 0;
}
STUB
-build_harness "$GATE/stub.c" "$GATE/stub_bin" afl >/dev/null 2>&1 \
- || die "the negative control itself does not compile - the control is vacuous"
-STUB_DIV="$(divergence "$GATE/stub_bin")"
-if [ "$STUB_DIV" -le "$MIN_DIVERGENCE" ]; then
- pass "stub harness diverges by $STUB_DIV edges and is correctly REJECTED"
+if lisdex_verify "$CONTROLS/stub.c" "$GATE/verify-stub" > "$GATE/verify-stub.log" 2>&1; then
+ fail "the shipped judge ACCEPTED a stub harness - the coverage oracle is not running"
else
- fail "stub harness diverges by $STUB_DIV edges - the coverage oracle cannot detect a stub"
+ if grep -q 'REJECTED' "$GATE/verify-stub.log"; then
+ pass "$(grep -m1 REJECTED "$GATE/verify-stub.log")"
+ else
+ tail -5 "$GATE/verify-stub.log" >&2
+ fail "the stub was not rejected by an oracle - it failed for some other reason"
+ fi
fi
-log "stage 5c/7: NEGATIVE CONTROL - the unpopulated struct variant must be REJECTED"
-VARIANT="$(find "$SYNTH" -maxdepth 1 -name '*.v1.c' | head -1)"
-if [ -n "$VARIANT" ]; then
- if build_harness "$VARIANT" "$GATE/variant_bin" afl >/dev/null 2>&1; then
- VAR_DIV="$(divergence "$GATE/variant_bin")"
- if [ "$VAR_DIV" -le "$MIN_DIVERGENCE" ]; then
- pass "unpopulated variant diverges by $VAR_DIV edges and is correctly REJECTED"
- else
- fail "unpopulated variant diverges by $VAR_DIV edges - struct population is not load-bearing"
- fi
+log "stage 7/10: NEGATIVE CONTROL - the unpopulated struct variant must be REJECTED"
+VARIANTS="$(find "$SYNTH/candidates" -maxdepth 1 -name "$ENTRY_NAME.v*.c" | sort -V)"
+VARIANT_COUNT="$(printf '%s\n' "$VARIANTS" | grep -c . || true)"
+if [ "${VARIANT_COUNT:-0}" -lt 2 ]; then
+ fail "only $VARIANT_COUNT variant(s) planned for $ENTRY_NAME - struct population is not \
+being exercised and this control is vacuous"
+else
+ BARE="$(printf '%s\n' "$VARIANTS" | tail -1)"
+ if lisdex_verify "$BARE" "$GATE/verify-bare" > "$GATE/verify-bare.log" 2>&1; then
+ fail "the shipped judge ACCEPTED $(basename "$BARE") - struct population is not load-bearing"
else
- fail "the unpopulated variant does not compile - the control is vacuous"
+ pass "unpopulated variant $(basename "$BARE") correctly REJECTED"
fi
+fi
+
+log "stage 8/10: NEGATIVE CONTROL - a harness that crashes on a valid seed must be REJECTED"
+cat > "$CONTROLS/crasher.c" <<'CRASHER'
+// ©AngelaMos | 2026
+// crasher.c
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "png.h"
+
+int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
+{
+ uint8_t *copy = (uint8_t *)malloc(size + 1);
+ volatile uint8_t seen;
+
+ if (copy == NULL) {
+ return 0;
+ }
+ memcpy(copy, data, size);
+ seen = copy[size + 1];
+ (void)seen;
+ free(copy);
+ return 0;
+}
+CRASHER
+if lisdex_verify "$CONTROLS/crasher.c" "$GATE/verify-crasher" > "$GATE/verify-crasher.log" 2>&1; then
+ fail "the shipped judge ACCEPTED a harness that overflows the heap on every seed"
+else
+ if grep -qE 'REJECTED.*(crashed on seed|does not compile)' "$GATE/verify-crasher.log"; then
+ pass "$(grep -m1 REJECTED "$GATE/verify-crasher.log")"
+ else
+ tail -5 "$GATE/verify-crasher.log" >&2
+ fail "the crashing harness was rejected, but not by the execution oracle"
+ fi
+fi
+
+log "stage 9/10: NEGATIVE CONTROL - a harness that leaks on a valid seed must be REJECTED"
+cat > "$CONTROLS/leaker.c" <<'LEAKER'
+// ©AngelaMos | 2026
+// leaker.c
+
+#include <stddef.h>
+#include <stdint.h>
+#include <stdlib.h>
+#include <string.h>
+
+#include "png.h"
+
+static volatile void *lisdex_sink;
+
+int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
+{
+ png_image ctx;
+
+ memset(&ctx, 0, sizeof ctx);
+ ctx.version = PNG_IMAGE_VERSION;
+ (void)MAGMA_png_image_begin_read_from_memory(&ctx, (const void *)data, size);
+ lisdex_sink = malloc(4096);
+ return 0;
+}
+LEAKER
+if lisdex_verify "$CONTROLS/leaker.c" "$GATE/verify-leaker" > "$GATE/verify-leaker.log" 2>&1; then
+ fail "the shipped judge ACCEPTED a harness that leaks on every seed - LeakSanitizer is not \
+armed on the direct run, so an unpaired constructor would forge a crash on every triage replay"
else
- printf ' SKIP this entry point has no struct-population variant\n'
+ if grep -qE 'REJECTED.*crashed on seed' "$GATE/verify-leaker.log"; then
+ pass "leaking harness correctly REJECTED (LeakSanitizer fires on the direct run)"
+ else
+ tail -5 "$GATE/verify-leaker.log" >&2
+ fail "the leaking harness was rejected, but not by the execution oracle"
+ fi
fi
-log "stage 6/7: lisdex drives a campaign against the SYNTHESIZED harness"
+log "stage 10/10: lisdex drives a campaign against the SYNTHESIZED harness"
rm -rf "$FINDINGS" "$DB"
"$LISDEX_BIN" fuzz \
--target "$GATE/harness" \
@@ -172,7 +281,12 @@ rm -rf "$FINDINGS" "$DB"
--until-crash \
--label m4-synthesized | tee "$GATE/fuzz.log"
-log "stage 7/7: assert the synthesized harness re-found a magma bug"
+if grep -q '^persistent_mode true' "$GATE/fuzz.log"; then
+ pass "the campaign ran in persistent shmem_testcase deferred mode"
+else
+ fail "the campaign did not run in persistent mode - the harness may shadow the driver"
+fi
+
[ -f "$DB" ] || die "no database was created at $DB"
CRASH_ROWS="$(sqlite3 "$DB" 'SELECT COUNT(*) FROM crashes;')"
if [ "${CRASH_ROWS:-0}" -ge 1 ]; then
@@ -200,7 +314,7 @@ fi
printf '\n'
if [ "$FAILURES" -eq 0 ]; then
- printf '[m4] M4 EXIT GATE PASSED - the none tier synthesized a working harness with no LLM\n'
+ printf '[m4] M4 EXIT GATE PASSED - the none tier synthesized and self-verified a harness with no LLM\n'
exit 0
fi
printf '[m4] M4 EXIT GATE FAILED: %d assertion(s)\n' "$FAILURES"