Building 70 Projects ranging from beginner to advanced so anyone can — learn from, build upon, use as a reference, or even copy directly. Owned by my cybersecurity company 👇
Go aicertificationcloud-engineeringcybercybersecuritycybersecurity-analystcybersecurity-certificationcybersecurity-certificationscybersecurity-educationcybersecurity-jobscybersecurity-portfoliocybersecurity-projectscybersecurity-toolsgrchackinglearningpentestingproject-repositoryprojetcspython
feat(lisdex): M5 step 4 - the authors' call order sets a floor, and nothing below it substitutes
CarterPerez-dev675316534660
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.rsindex 776c9613..b44633b2 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@@ -87,6 +87,10 @@ pub struct HarnessPlan {pub needs_nul_copy: bool,pub callbacks: Vec<CallbackStub>,pub body: Vec<Stmt>,+ // Named separately from `body` because "which calls came from the author's own sequence+ // rather than from our rules" is the one thing a reader of the emitted C cannot recover,+ // and it is what has to be asserted to prove the replay happened at all.+ pub replayed: Vec<String>,}impl HarnessPlan {@@ -99,6 +103,7 @@ impl HarnessPlan {needs_nul_copy: false,callbacks: Vec::new(),body: Vec::new(),+ replayed: Vec::new(),}}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.rsindex 5196e55c..f6d563ce 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@@ -1,9 +1,10 @@// ©AngelaMos | 2026// synth.rs-use std::collections::BTreeMap;+use std::collections::{BTreeMap, BTreeSet};use lisdex_surface::extract::{Vocabulary, carries_word, identifier_words};+use lisdex_surface::naming::polarity_of;use lisdex_surface::rank::Candidate;use lisdex_surface::signature::{Fuzzability, Param, ParamRole, Pointee, Shape, handle_key};@@ -21,20 +22,6 @@ pub const FILESYSTEM_VERBS: [&str; 12] = ["open", "fopen", "unlink", "remove", "rename", "mkdir", "rmdir", "chdir", "chmod", "symlink","truncate", "creat",];-pub const READ_WORDS: [&str; 9] = [- "read",- "decode",- "decoder",- "decompress",- "uncompress",- "parse",- "load",- "inflate",- "extract",-];-pub const WRITE_WORDS: [&str; 7] = [- "write", "encode", "encoder", "compress", "save", "deflate", "flush",-];#[derive(Debug, Clone, PartialEq, Eq)]pub enum Refusal {@@ -114,23 +101,6 @@ pub fn is_extent_name(name: &str) -> bool {carries_word(name, &EXTENT_WORDS)}-#[derive(Debug, Clone, Copy, PartialEq, Eq)]-enum Polarity {- Read,- Write,-}--// Read is tested first and wins outright, because the ambiguity runs one way only: every-// decode word contains an encode word as a suffix (`decompress`, `uncompress`) and no-// encode word contains a decode one. carries_word suffix-matches a lone lowercase-// identifier, so without this zlib's `uncompress` - the DECOMPRESSOR - reads as a writer.-fn polarity_of(name: &str) -> Option<Polarity> {- if carries_word(name, &READ_WORDS) {- return Some(Polarity::Read);- }- carries_word(name, &WRITE_WORDS).then_some(Polarity::Write)-}-fn producer_arguments(producer: &str, params: &[Param]) -> Result<Vec<Value>, Refusal> {params.iter()@@ -517,6 +487,30 @@ fn admissible(candidate: &Candidate) -> Result<(), Refusal> {Ok(())}+// A function whose every parameter is a handle can only configure the library; it has+// nowhere to receive a corpus. A zero-parameter one has nowhere either.+//+// This is the single test behind both halves of the ladder, and both halves were wrong+// before it. Every one of libarchive's 25 fuzz targets calls+// `archive_read_support_format_rar5(struct archive *)`, so treating "the authors call it"+// as "the authors fuzz it" hoisted seven configurators above the entry point the M3 gate+// asserts ranks first. Keying on the corpus instead does not work either: brotli's authored+// data entry `BrotliDecoderDecompressStream` takes its buffer through a `const uint8_t **`+// so it is not a byte taker, and every one of its six parameters carries the Context ROLE,+// so a role-based test called the decoder plumbing and let the fall-through back in. What+// separates them is that five of those six parameters are not handles.+#[must_use]+pub fn is_configuration_shape(params: &[Param]) -> bool {+ params+ .iter()+ .all(|param| handle_key(¶m.spelling, ¶m.shape).is_some())+}++#[must_use]+pub fn is_configurator(candidate: &Candidate) -> bool {+ is_configuration_shape(&candidate.params)+}+fn is_path_capable(param: &Param) -> bool {matches!(¶m.shape,@@ -595,10 +589,97 @@ fn resolve_contexts(candidate: &Candidate, vocabulary: &Vocabulary) -> Result<CoOk(found)}+// An undeclared name counts as plumbing - zlib writes `inflateInit` as a macro over+// `inflateInit_`, so it is not replayable either way, and stopping the scan on it would cut+// the setup short of the calls that ARE replayable.+fn is_teardown(name: &str, vocabulary: &Vocabulary) -> bool {+ vocabulary+ .destructors+ .values()+ .any(|known| known.contains(name))+}++fn is_plumbing(name: &str, vocabulary: &Vocabulary) -> bool {+ vocabulary+ .functions+ .get(name)+ .is_none_or(|params| is_configuration_shape(params))+}++// The author's setup is the run of plumbing that opens their sequence. It ends at the first+// call that takes something other than a handle, because that is the call they hand the+// input to - `archive_read_set_options` in libarchive's tar target, `inflate` in zlib's+// zpipe.c - and everything after it is what they did with the result rather than what they+// did to make the call possible.+fn setup_run<'a>(sequence: &'a [String], entry: &str) -> &'a [String] {+ let ours = sequence.iter().position(|call| call == entry);+ let cut = sequence.len().min(ours.unwrap_or(usize::MAX));+ &sequence[..cut]+}++// The author's setup calls are copied, never invented. A call is replayed only when every+// one of its parameters is a context this harness is already holding: that is what makes+// `archive_read_support_format_all(a)` replayable and stops `png_sig_cmp(data, 0, 8)` or+// `memcpy(dst, data, size)` from being guessed at. A zero-argument call is skipped because+// it cannot touch our context - it is the producer we already called.+fn replay_setup(+ sequence: &[String],+ entry: &str,+ locals: &BTreeMap<String, Held>,+ emitted: &BTreeSet<String>,+ vocabulary: &Vocabulary,+) -> Vec<Stmt> {+ let mut replayed = Vec::new();+ for name in setup_run(sequence, entry) {+ if !is_plumbing(name, vocabulary) {+ break;+ }+ // A destructor takes one handle and is therefore plumbing-shaped, so the run rule+ // alone will happily replay one AS SETUP. Measured: zlib's `examples/gun.c` put+ // `inflateBackEnd` into the opening run and the harness tore the stream down+ // before it was ever used. `emitted` only covers the teardowns THIS plan schedules,+ // which is a different set - ours was `inflateEnd`.+ if name == entry || emitted.contains(name) || is_teardown(name, vocabulary) {+ continue;+ }+ let Some(params) = vocabulary.functions.get(name) else {+ continue;+ };+ if params.is_empty() {+ continue;+ }+ let bound: Option<Vec<Value>> = params+ .iter()+ .map(|param| {+ handle_key(¶m.spelling, ¶m.shape)+ .and_then(|handle| locals.get(&handle))+ .map(Held::reference)+ })+ .collect();+ if let Some(args) = bound {+ replayed.push(Stmt::Call {+ function: name.clone(),+ args,+ capture: None,+ });+ }+ }+ replayed+}+pub fn plan_candidate(candidate: &Candidate,include: &str,vocabulary: &Vocabulary,+) -> Result<Vec<HarnessPlan>, Refusal> {+ plan_candidate_with(candidate, include, vocabulary, &[])+}++pub fn plan_candidate_with(+ candidate: &Candidate,+ include: &str,+ vocabulary: &Vocabulary,+ setup: &[String],) -> Result<Vec<HarnessPlan>, Refusal> {admissible(candidate)?;let sized = candidate.analysis.roles.contains(&ParamRole::Length);@@ -614,8 +695,12 @@ pub fn plan_candidate(args.push(bind(param, *role, &locals, sized)?);}+ let mut emitted = BTreeSet::new();let mut base = HarnessPlan::new(candidate.name.clone()).with_include(include);for statement in opening {+ if let Stmt::Call { function, .. } = &statement {+ emitted.insert(function.clone());+ }base = base.with(statement);}@@ -630,7 +715,24 @@ pub fn plan_candidate(.iter().flat_map(|(handle, held)| teardown_calls(handle, held, &candidate.name, vocabulary)).collect();+ // A teardown that the author happened to write BEFORE the entry point must not be+ // replayed as setup: it is already scheduled after the call, and running it twice is a+ // double free reported inside the library.+ emitted.extend(teardowns.iter().map(|(function, _)| function.clone()));+ let setup = replay_setup(setup, &candidate.name, &locals, &emitted, vocabulary);+ let replayed: Vec<String> = setup+ .iter()+ .filter_map(|statement| match statement {+ Stmt::Call { function, .. } => Some(function.clone()),+ _ => None,+ })+ .collect();let call = |plan: HarnessPlan| -> HarnessPlan {+ let mut plan = plan;+ plan.replayed.clone_from(&replayed);+ for statement in &setup {+ plan = plan.with(statement.clone());+ }let capture = match candidate.result.shape {Shape::Void | Shape::Other => None,_ => Some(Binding {@@ -814,6 +916,215 @@ mod tests {}}+ fn archive_handle() -> Param {+ param(+ "a",+ "struct archive *",+ Shape::Pointer {+ pointee: Pointee::Record("archive".to_owned()),+ is_const: false,+ },+ )+ }++ // The replay vocabulary of libarchive's own tar target, cut down to the shapes that+ // decide each rule: two registrations that bind, one call that takes a string and so+ // cannot, and a destructor that is plumbing-shaped and must never be replayed.+ fn replayable_archive_vocabulary() -> Vocabulary {+ let mut vocabulary = archive_vocabulary();+ vocabulary.functions = BTreeMap::from([+ (+ "archive_read_support_format_tar".to_owned(),+ vec![archive_handle()],+ ),+ (+ "archive_read_support_filter_all".to_owned(),+ vec![archive_handle()],+ ),+ (+ "archive_read_set_options".to_owned(),+ vec![+ archive_handle(),+ param(+ "opts",+ "const char *",+ Shape::Pointer {+ pointee: Pointee::Char,+ is_const: true,+ },+ ),+ ],+ ),+ // Declared, plumbing-shaped, and takes a handle this plan does NOT hold. It is+ // the only call the binding rule alone can stop: an undeclared name is already+ // stopped by the vocabulary lookup, so a fixture of `memcpy` and `png_sig_cmp`+ // alibis the rule completely. Passing NULL here would be a crash inside the+ // library that the harness manufactured - the D12 class.+ (+ "archive_entry_clear".to_owned(),+ vec![param(+ "entry",+ "struct archive_entry *",+ Shape::Pointer {+ pointee: Pointee::Record("archive_entry".to_owned()),+ is_const: false,+ },+ )],+ ),+ ("archive_read_new".to_owned(), Vec::new()),+ ("archive_read_free".to_owned(), vec![archive_handle()]),+ ("archive_read_finish".to_owned(), vec![archive_handle()]),+ ]);+ // TWO destructors, and the plan only schedules one. Keyed on a single destructor+ // the teardown guard could be gutted with every test still green, because the one+ // name it had to catch was already in `emitted` for a different reason - the two+ // guards alibied each other. `archive_read_finish` is the one only this rule stops.+ vocabulary.destructors = BTreeMap::from([(+ "archive".to_owned(),+ BTreeSet::from([+ "archive_read_free".to_owned(),+ "archive_read_finish".to_owned(),+ ]),+ )]);+ vocabulary+ }++ fn open_memory() -> Candidate {+ archive_open(param(+ "buff",+ "const void *",+ Shape::Pointer {+ pointee: Pointee::Void,+ is_const: true,+ },+ ))+ }++ fn replayed_calls(sequence: &[&str]) -> Vec<String> {+ let owned: Vec<String> = sequence.iter().map(|call| (*call).to_owned()).collect();+ plan_candidate_with(+ &open_memory(),+ "archive.h",+ &replayable_archive_vocabulary(),+ &owned,+ )+ .unwrap()[0]+ .replayed+ .clone()+ }++ // B66: the emitted harness was structurally right and semantically dead - no format+ // registered, so `archive_read_open_memory` returned ARCHIVE_FATAL at full exec rate+ // with a bitmap that never grew past handle plumbing. The author's own target says+ // which registrations have to come first.+ #[test]+ fn the_authors_registrations_are_replayed_before_the_entry_point() {+ assert_eq!(+ replayed_calls(&[+ "archive_read_new",+ "archive_read_support_format_tar",+ "archive_read_support_filter_all",+ "archive_read_open_memory",+ ]),+ [+ "archive_read_support_format_tar",+ "archive_read_support_filter_all"+ ],+ "archive_read_new is the producer this plan already called"+ );+ }++ // Only one of libarchive's 25 targets calls `archive_read_open_memory`; the rest reach+ // the reader through `archive_read_open` and a callback. Cutting at our own entry would+ // have found nothing to replay for the entry the M3 gate asserts ranks first.+ #[test]+ fn setup_transfers_from_a_target_that_never_calls_our_entry_point() {+ assert_eq!(+ replayed_calls(&[+ "archive_read_new",+ "archive_read_support_format_tar",+ "archive_read_support_filter_all",+ "archive_read_open",+ ]),+ [+ "archive_read_support_format_tar",+ "archive_read_support_filter_all"+ ]+ );+ }++ // The run ends at the first call that takes something other than a handle, because+ // that is the call the author hands the input to. Everything past it is what they did+ // with the result.+ #[test]+ fn the_replay_stops_at_the_first_call_that_is_not_plumbing() {+ assert_eq!(+ replayed_calls(&[+ "archive_read_new",+ "archive_read_support_format_tar",+ "archive_read_set_options",+ "archive_read_support_filter_all",+ ]),+ ["archive_read_support_format_tar"],+ "the filter registration sits past the cut and must not be replayed"+ );+ }++ // A destructor takes one handle and is therefore plumbing-shaped. Measured on zlib's+ // `examples/gun.c`, which put `inflateBackEnd` into the opening run.+ #[test]+ fn a_destructor_in_the_opening_run_is_never_replayed_as_setup() {+ assert_eq!(+ replayed_calls(&[+ "archive_read_new",+ "archive_read_finish",+ "archive_read_support_format_tar",+ ]),+ ["archive_read_support_format_tar"],+ "replaying a destructor would tear the handle down before it was ever used"+ );+ }++ #[test]+ fn an_unknown_name_is_skipped_rather_than_guessed_at() {+ assert!(+ replayed_calls(&["memcpy", "png_sig_cmp", "archive_read_support_format_tar"])+ .contains(&"archive_read_support_format_tar".to_owned()),+ "an unknown name is skipped, not guessed at, and does not stop the run"+ );+ }++ #[test]+ fn a_call_taking_a_handle_this_plan_does_not_hold_is_left_alone() {+ assert_eq!(+ replayed_calls(&[+ "archive_read_new",+ "archive_entry_clear",+ "archive_read_support_format_tar",+ ]),+ ["archive_read_support_format_tar"],+ "handing it a NULL would be a crash inside the library that we manufactured"+ );+ }++ #[test]+ fn no_sequence_means_no_replay_and_the_plan_is_what_it_was() {+ assert!(replayed_calls(&[]).is_empty());+ }++ // Isolates `is_configuration_shape`, the single test behind both halves of the ladder.+ #[test]+ fn a_call_taking_only_handles_configures_and_one_taking_a_buffer_does_not() {+ assert!(is_configurator(&candidate(+ "archive_read_support_format_tar",+ vec![archive_handle()],+ vec![ParamRole::Context],+ Fuzzability::NoInput,+ Returns::default(),+ )));+ assert!(!is_configurator(&open_memory()));+ }+#[test]fn a_filesystem_verb_over_a_void_buffer_is_not_a_path() {// This is libarchive's ground-truth #1 and the M3 gate asserts it ranks first.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.rsindex 2171c291..759f3cd8 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@@ -98,6 +98,10 @@ pub struct Vocabulary {pub produced: BTreeSet<String>,pub destructors: BTreeMap<String, BTreeSet<String>>,pub producers: BTreeMap<String, BTreeMap<String, Vec<Param>>>,+ // The producers and destructors maps answer "what makes this handle" and "what frees+ // it". Replaying an author's call ORDER asks a third question - "what does the call+ // they made between those two take" - and nothing here could answer it.+ pub functions: BTreeMap<String, Vec<Param>>,}impl Vocabulary {@@ -107,6 +111,9 @@ impl Vocabulary {self.records.entry(name).or_insert(record);}self.produced.extend(other.produced);+ for (name, params) in other.functions {+ self.functions.entry(name).or_insert(params);+ }for (record, functions) in other.destructors {self.destructors.entry(record)@@ -423,6 +430,9 @@ fn collect_relations(entity: &Entity, target: &Path, into: &mut Vocabulary) {// A const return is a borrow, not an allocation: libwebp's WebPIDecodedArea hands back// a `const WebPDecBuffer *` while WebPInitDecBuffer exists precisely so the caller can// own one, and archive_entry_stat hands back a `const struct stat *`.+ into.functions+ .entry(name.clone())+ .or_insert_with(|| parameters(entity));let returns = result_of(entity);if let Shape::Pointer {pointee: Pointee::Record(record),diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/harness.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/harness.rsindex ff1cb46c..66b0e7cf 100644--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/harness.rs+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/harness.rs@@ -6,6 +6,7 @@ use std::path::{Path, PathBuf};pub const ENTRY_POINT: &str = "LLVMFuzzerTestOneInput";pub const INITIALIZE_POINT: &str = "LLVMFuzzerInitialize";+pub const CONSUMER_POINT: &str = "main";pub const SOURCE_EXTENSIONS: &[&str] = &["c", "cc", "cpp", "cxx"];pub const MAX_SOURCE_BYTES: u64 = 4 * 1024 * 1024;pub const MAX_DEPTH: usize = 12;@@ -65,6 +66,114 @@ fn is_source(path: &Path) -> bool {.is_some_and(|extension| SOURCE_EXTENSIONS.contains(&extension.to_lowercase().as_str()))}+// `Copyright (C) 2009 ...` in a licence header mines as a call to `Copyright`, and every+// libjpeg-turbo target carried `Copyright`, `DAMAGES` and `TORT` in its call list. That is+// not merely noise in the length and frequency keys: a comment naming a real function would+// have made it "authored", and authorship is what decides the floor.+fn without_comments(body: &str) -> String {+ let chars: Vec<char> = body.chars().collect();+ let mut kept = String::with_capacity(body.len());+ let mut index = 0;+ while index < chars.len() {+ let pair = (chars[index], chars.get(index + 1).copied());+ match pair {+ ('/', Some('*')) => {+ index += 2;+ while index < chars.len()+ && !(chars[index] == '*' && chars.get(index + 1) == Some(&'/'))+ {+ index += 1;+ }+ index = (index + 2).min(chars.len());+ kept.push(' ');+ }+ ('/', Some('/')) => {+ while index < chars.len() && chars[index] != '\n' {+ index += 1;+ }+ }+ _ => {+ kept.push(chars[index]);+ index += 1;+ }+ }+ }+ kept+}++// Whole-FILE order is only the author's call order when the file holds one function. zlib's+// `test/infcover.c` defines twenty, so first-occurrence order over the file put `inflate`+// at position 25 and `inflateInit` nowhere before it - the setup replay therefore found+// nothing to replay for the one library D23 says needs it most. The order that means+// something is the order inside the entry function's own body.+#[must_use]+pub fn body_of(source: &str, function: &str) -> Option<String> {+ let chars: Vec<char> = source.chars().collect();+ let name: Vec<char> = function.chars().collect();+ let mut index = 0;+ while let Some(start) = find_identifier(&chars, &name, index) {+ index = start + name.len();+ let mut cursor = skip_space(&chars, index);+ if chars.get(cursor) != Some(&'(') {+ continue;+ }+ let mut depth = 0;+ while cursor < chars.len() {+ match chars[cursor] {+ '(' => depth += 1,+ ')' => {+ depth -= 1;+ if depth == 0 {+ break;+ }+ }+ _ => {}+ }+ cursor += 1;+ }+ cursor = skip_space(&chars, cursor + 1);+ if chars.get(cursor) != Some(&'{') {+ continue;+ }+ let open = cursor;+ let mut braces = 0;+ while cursor < chars.len() {+ match chars[cursor] {+ '{' => braces += 1,+ '}' => {+ braces -= 1;+ if braces == 0 {+ return Some(chars[open..=cursor].iter().collect());+ }+ }+ _ => {}+ }+ cursor += 1;+ }+ }+ None+}++fn skip_space(chars: &[char], mut index: usize) -> usize {+ while index < chars.len() && chars[index].is_whitespace() {+ index += 1;+ }+ index+}++fn find_identifier(chars: &[char], name: &[char], from: usize) -> Option<usize> {+ let boundary = |position: usize| -> bool {+ chars+ .get(position)+ .is_none_or(|character| !(character.is_alphanumeric() || *character == '_'))+ };+ (from..chars.len().saturating_sub(name.len().saturating_sub(1))).find(|start| {+ chars[*start..].starts_with(name)+ && (*start == 0 || boundary(start - 1))+ && boundary(start + name.len())+ })+}+// Source order IS the finding. A `BTreeSet` here alphabetised the calls, which silently// turned every mined harness into a reachability SET - and the set is the one thing headers// already give you. libarchive's own harness says@@ -74,6 +183,7 @@ fn is_source(path: &Path) -> bool {// first. Dedup on FIRST occurrence, because that is where the author established the order.#[must_use]pub fn extract_calls(body: &str) -> Vec<String> {+ let body = without_comments(body);let chars: Vec<char> = body.chars().collect();let mut seen = BTreeSet::new();let mut found = Vec::new();@@ -106,7 +216,27 @@ pub fn extract_calls(body: &str) -> Vec<String> {found}-fn walk(root: &Path, depth: usize, found: &mut Vec<Harness>) -> Result<(), HarnessError> {+// `body.contains("main")` would take every file that mentions a domain, a remainder or a+// mainline. The mined call list is already an exact-identifier scan, so the cheapest honest+// test for "this file defines a program" is that `main` appears in it AS a call-shaped+// identifier, which is what a definition and nothing else in prose looks like.+fn defines_a_program(body: &str) -> bool {+ extract_calls(body)+ .iter()+ .any(|call| call == CONSUMER_POINT)+}++fn defines_a_fuzz_target(body: &str) -> bool {+ body.contains(ENTRY_POINT)+}++fn walk_for(+ root: &Path,+ marks: fn(&str) -> bool,+ scope: &str,+ depth: usize,+ found: &mut Vec<Harness>,+) -> Result<(), HarnessError> {if depth > MAX_DEPTH {return Ok(());}@@ -123,7 +253,7 @@ fn walk(root: &Path, depth: usize, found: &mut Vec<Harness>) -> Result<(), Harnelet name = entry.file_name().to_string_lossy().to_lowercase();if path.is_dir() {if !SKIP_DIRS.contains(&name.as_str()) {- walk(&path, depth + 1, found)?;+ walk_for(&path, marks, scope, depth + 1, found)?;}continue;}@@ -139,26 +269,48 @@ fn walk(root: &Path, depth: usize, found: &mut Vec<Harness>) -> Result<(), Harnelet Ok(body) = std::fs::read_to_string(&path) else {continue;};- if body.contains(ENTRY_POINT) {+ if marks(&body) {+ // The entry function's body when it has one; the whole file otherwise, because+ // a target whose entry is behind a macro still carries a usable call list.+ let mined = body_of(&body, scope).unwrap_or(body);found.push(Harness {path,- calls: extract_calls(&body),+ calls: extract_calls(&mined),});}}Ok(())}-pub fn discover(source: &Path) -> Result<Vec<Harness>, HarnessError> {+fn discover_marked(+ source: &Path,+ marks: fn(&str) -> bool,+ entry: &str,+) -> Result<Vec<Harness>, HarnessError> {if !source.is_dir() {return Err(HarnessError::NotADirectory(source.to_path_buf()));}let mut found = Vec::new();- walk(source, 0, &mut found)?;+ walk_for(source, marks, entry, 0, &mut found)?;found.sort_by(|left, right| left.path.cmp(&right.path));Ok(found)}+pub fn discover(source: &Path) -> Result<Vec<Harness>, HarnessError> {+ discover_marked(source, defines_a_fuzz_target, ENTRY_POINT)+}++// A library that ships no fuzz harness is not a library with no call-order signal, which is+// what doc 02 D10 claimed and D18 refuted by measurement: zlib ships zero harnesses and+// nineteen `main()` consumers, six of which run inflateInit -> inflate in sequence.+pub fn discover_consumers(source: &Path) -> Result<Vec<Harness>, HarnessError> {+ let found = discover_marked(source, defines_a_program, CONSUMER_POINT)?;+ Ok(found+ .into_iter()+ .filter(|item| !item.calls.is_empty())+ .collect())+}+// The isolating control for the ordering above: this fixture is written so that source order// and alphabetical order DISAGREE. A `BTreeSet` extraction returns archive_read_data first;// the author's actual sequence starts at archive_read_new. Any assertion using only@@ -201,6 +353,66 @@ mod order_tests {let calls = extract_calls("zulu(); alpha(); zulu();");assert_eq!(calls, vec!["zulu", "alpha"]);}++ // Isolates comment stripping. Every libjpeg-turbo target mined `Copyright`, `DAMAGES`+ // and `TORT` from its licence header. The danger is not the noise: a comment naming a+ // real function would have made that function "authored", and authorship decides which+ // candidates the synthesizer is allowed to fall through to.+ #[test]+ fn a_function_named_in_a_comment_was_never_called() {+ let calls = super::extract_calls(+ "/* Copyright (C) 2009. Do not call png_init_io(fp) here. */\n\+ // see also png_read_png(p)\n\+ png_read_info(p, i);",+ );+ assert_eq!(calls, vec!["png_read_info"], "{calls:?}");+ }++ // Isolates body scoping. zlib's `test/infcover.c` defines twenty functions, so+ // first-occurrence order over the FILE put `inflate` at position 25 with `inflateInit`+ // nowhere before it, and the setup replay found nothing to replay. The fixture keeps+ // that shape: file order and entry-body order disagree about what comes first.+ #[test]+ fn the_order_mined_is_the_entry_functions_own_not_the_files() {+ let source = "\+static void helper(void) { inflateReset(&s); }+int LLVMFuzzerTestOneInput(const uint8_t *d, size_t n) {+ inflateInit(&s);+ inflate(&s, 0);+ return 0;+}+static void later(void) { inflateEnd(&s); }+";+ let body = super::body_of(source, super::ENTRY_POINT).expect("the entry has a body");+ assert_eq!(super::extract_calls(&body), vec!["inflateInit", "inflate"]);+ assert_eq!(+ super::extract_calls(source).first().map(String::as_str),+ Some("helper"),+ "whole-file order leads with a function defined above the entry point"+ );+ }++ #[test]+ fn a_declaration_is_not_a_body_and_a_missing_function_has_none() {+ assert!(+ super::body_of(+ "int LLVMFuzzerTestOneInput(const uint8_t*, size_t);",+ super::ENTRY_POINT+ )+ .is_none()+ );+ assert!(super::body_of("int main(void) { return 0; }", super::ENTRY_POINT).is_none());+ }++ #[test]+ fn a_program_is_found_by_its_definition_and_not_by_the_word_domain() {+ assert!(super::defines_a_program(+ "int main(void) { work(); return 0; }"+ ));+ assert!(!super::defines_a_program(+ "const char *domain(void);\nstatic int remaining;\n"+ ));+ }}#[must_use]diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/ladder.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/ladder.rsnew file mode 100644index 00000000..fdada8cb--- /dev/null+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/ladder.rs@@ -0,0 +1,599 @@+// ©AngelaMos | 2026+// ladder.rs++use std::collections::{BTreeMap, BTreeSet};+use std::path::{Path, PathBuf};++use crate::harness::{self, Harness, HarnessError};+use crate::naming::{Polarity, polarity_of};++pub const OSS_FUZZ_PROJECTS: &str = "projects";++// Opening a file is the discriminator, not doing I/O. libpng's `pngtest.c` calls `fopen`+// and then hands the FILE to `png_init_io`, which is the shallow-state trap Hopper names+// and the crash lisdex already had; zlib's `examples/zpipe.c` does plenty of `fread` but+// never opens anything, and it is the consumer whose order signal we want. A rule that+// banned all stdio would have thrown zpipe.c away with pngtest.c.+pub const FILE_OPENING_CALLS: &[&str] = &[+ "fopen", "fopen64", "freopen", "fdopen", "tmpfile", "open", "open64", "openat", "creat",+];++#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]+pub enum Tier {+ InTreeFuzzTarget,+ OssFuzzTarget,+ MemoryConsumer,+ FrequentConsumer,+}++impl Tier {+ #[must_use]+ pub fn describe(self) -> &'static str {+ match self {+ Tier::InTreeFuzzTarget => "the library's own in-tree fuzz target",+ Tier::OssFuzzTarget => "the fuzz target google/oss-fuzz ships for this library",+ Tier::MemoryConsumer => "an in-tree consumer that never opens a file",+ Tier::FrequentConsumer => "the in-tree consumer whose calls are the most common",+ }+ }+}++#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]+pub struct Sequence {+ pub tier: Tier,+ pub origin: PathBuf,+ pub calls: Vec<String>,+}++impl Sequence {+ #[must_use]+ pub fn names(&self) -> &[String] {+ &self.calls+ }++ #[must_use]+ pub fn contains(&self, name: &str) -> bool {+ self.calls.iter().any(|call| call == name)+ }+}++#[derive(Debug, Clone, Default, PartialEq, Eq, serde::Serialize)]+pub struct Ladder {+ pub chosen: Option<Sequence>,+ pub fuzz_targets: usize,+ pub consumers: usize,+}++impl Ladder {+ #[must_use]+ pub fn contains(&self, name: &str) -> bool {+ self.chosen+ .as_ref()+ .is_some_and(|sequence| sequence.contains(name))+ }+}++fn opens_a_file(calls: &[String]) -> bool {+ calls+ .iter()+ .any(|call| FILE_OPENING_CALLS.contains(&call.as_str()))+}++// Frequency is the LAST tier and it is never averaged across files, because averaging is+// the mechanism that fails: over libpng's consumers `png_init_io` appears in 68% and+// `png_set_read_fn` in 56%, so the merged answer points straight at the SEGV. Here it only+// picks WHICH single file to copy, and only after the three shaped tiers came up empty.+fn commonness(calls: &[String], across: &BTreeMap<String, usize>) -> usize {+ calls+ .iter()+ .map(|call| across.get(call).copied().unwrap_or_default())+ .sum()+}++fn frequencies(files: &[Harness]) -> BTreeMap<String, usize> {+ let mut counted = BTreeMap::new();+ for file in files {+ for call in &file.calls {+ *counted.entry(call.clone()).or_insert(0) += 1;+ }+ }+ counted+}++// `identifier_words` splits `tj3Compress8` into `["tj3", "Compress8"]`, and "Compress8" is+// not the word "compress" - so libjpeg-turbo's `fuzz/compress.cc` carried NO write signal+// at all, while `tj3LoadImage8` gave it a read one, and the compressor's own fuzz target+// won its tier as a pure decoder. A trailing digit is a version or a bit depth, never part+// of the verb. Kept local to the ladder on purpose: `polarity_of` also decides producer+// selection, and that is measured behaviour this commit is not changing.+fn without_version_digits(name: &str) -> String {+ name.trim_end_matches(|character: char| character.is_ascii_digit())+ .to_owned()+}++pub const DIRECTION_PURE_READ: u8 = 3;+pub const DIRECTION_NEUTRAL: u8 = 2;+pub const DIRECTION_ROUND_TRIP: u8 = 1;+pub const DIRECTION_PURE_WRITE: u8 = 0;++// A VERDICT, never a sum. Summing read words minus write words is dominated by how much a+// file does rather than which direction it does it in: lz4's `round_trip_stream_fuzzer.c`+// makes 49 calls and out-summed `decompress_fuzzer.c`, so the ladder handed a decode fuzzer+// the call order of a file that compresses first. One write-side call is enough to say this+// file is not a decoder, however many decode calls sit beside it.+//+// Only the library's OWN calls vote. `fread` carries the word "read" and nothing else in+// brotli's `run_decode_fuzzer.c` - a runner that fopens a file and calls the real target -+// carries any direction word at all, so counting libc graded a file-reading runner a purer+// decoder than `decode_fuzzer.c` and it won the tier on length.+fn direction(calls: &[String], declared: &BTreeSet<String>) -> (u8, usize) {+ let mut reads = 0;+ let mut writes = 0;+ for call in calls.iter().filter(|call| declared.contains(call.as_str())) {+ match polarity_of(&without_version_digits(call)) {+ Some(Polarity::Read) => reads += 1,+ Some(Polarity::Write) => writes += 1,+ None => {}+ }+ }+ let verdict = match (reads > 0, writes > 0) {+ (true, false) => DIRECTION_PURE_READ,+ (false, false) => DIRECTION_NEUTRAL,+ (true, true) => DIRECTION_ROUND_TRIP,+ (false, true) => DIRECTION_PURE_WRITE,+ };+ // The count breaks ties INSIDE a verdict and never across one, so it can prefer+ // libjpeg-turbo's `decompress.cc` over the equally-pure `transform.cc` without ever+ // letting a big round-trip file outweigh a small decoder.+ (verdict, reads)+}++// Shape outranks frequency at EVERY tier, which is why not-opening-a-file is the first key+// rather than a filter applied only to consumers. brotli ships two files carrying the+// LibFuzzer entry symbol and one of them is `run_decode_fuzzer.c`, a `main()` that fopens a+// path and calls the real target - a runner, not a harness, and it won its tier on length.+type Shape = (bool, (u8, usize), usize, usize);++fn shape_rank(+ file: &Harness,+ across: &BTreeMap<String, usize>,+ declared: &BTreeSet<String>,+) -> Shape {+ (+ !opens_a_file(&file.calls),+ direction(&file.calls, declared),+ commonness(&file.calls, across),+ file.calls.len(),+ )+}++fn best_of(+ files: Vec<Harness>,+ tier: Tier,+ across: &BTreeMap<String, usize>,+ declared: &BTreeSet<String>,+) -> Option<Sequence> {+ let mut best: Option<(Shape, Harness)> = None;+ for file in files {+ let shape = shape_rank(&file, across, declared);+ // The shortest path wins ties, so a rerun on the same tree never returns a+ // different sequence.+ let better = match &best {+ None => true,+ Some((top, chosen)) => shape > *top || (shape == *top && file.path < chosen.path),+ };+ if better {+ best = Some((shape, file));+ }+ }+ best.map(|(_, file)| Sequence {+ tier,+ origin: file.path,+ calls: file.calls,+ })+}++fn oss_fuzz_targets(checkout: &Path, project: &str) -> Result<Vec<Harness>, HarnessError> {+ let directory = checkout.join(OSS_FUZZ_PROJECTS).join(project);+ if !directory.is_dir() {+ return Ok(Vec::new());+ }+ harness::discover(&directory)+}++// Four tiers, first hit wins, and the order is the finding rather than a preference: raw+// frequency alone works on libarchive (97.2% of consumers), zlib (11/11) and libjpeg-turbo+// (17/17) and FAILS on libpng, so a design that reached for it first would be right three+// times out of four and wrong on the library the whole niche is named after.+pub fn select(+ source: &Path,+ fuzz_targets: &[Harness],+ oss_fuzz: Option<&Path>,+ project: &str,+ declared: &BTreeSet<String>,+) -> Result<Ladder, HarnessError> {+ let consumers = harness::discover_consumers(source)?;+ let across = frequencies(&consumers);++ let mut chosen = best_of(+ fuzz_targets.to_vec(),+ Tier::InTreeFuzzTarget,+ &frequencies(fuzz_targets),+ declared,+ );++ if chosen.is_none()+ && let Some(checkout) = oss_fuzz+ {+ let external = oss_fuzz_targets(checkout, project)?;+ chosen = best_of(+ external.clone(),+ Tier::OssFuzzTarget,+ &frequencies(&external),+ declared,+ );+ }++ if chosen.is_none() {+ let memory: Vec<Harness> = consumers+ .iter()+ .filter(|file| !opens_a_file(&file.calls))+ .cloned()+ .collect();+ chosen = best_of(memory, Tier::MemoryConsumer, &across, declared);+ }++ if chosen.is_none() {+ chosen = best_of(consumers.clone(), Tier::FrequentConsumer, &across, declared);+ }++ Ok(Ladder {+ chosen,+ fuzz_targets: fuzz_targets.len(),+ consumers: consumers.len(),+ })+}++#[cfg(test)]+mod tests {+ use super::*;++ fn mined(path: &str, calls: &[&str]) -> Harness {+ Harness {+ path: PathBuf::from(path),+ calls: calls.iter().map(|call| (*call).to_owned()).collect(),+ }+ }++ // Every name a fixture mentions counts as declared unless a test says otherwise, so+ // the direction verdict sees the library calls it is meant to weigh.+ fn declaring(names: &[&str]) -> BTreeSet<String> {+ names.iter().map(|name| (*name).to_owned()).collect()+ }++ fn tree(label: &str, files: &[(&str, &str)]) -> PathBuf {+ let root =+ std::env::temp_dir().join(format!("lisdex-ladder-{label}-{}", std::process::id()));+ let _ = std::fs::remove_dir_all(&root);+ std::fs::create_dir_all(&root).unwrap();+ for (path, body) in files {+ let full = root.join(path);+ std::fs::create_dir_all(full.parent().unwrap()).unwrap();+ std::fs::write(&full, body).unwrap();+ }+ root+ }++ #[test]+ fn the_decode_target_beats_the_compress_targets_beside_it() {+ let root = tree("polarity", &[]);+ let targets = vec![+ mined("ossfuzz/compress_fuzzer.c", &["LZ4_compress_default"]),+ mined("ossfuzz/decompress_fuzzer.c", &["LZ4_decompress_safe"]),+ ];+ let ladder = select(+ &root,+ &targets,+ None,+ "lz4",+ &declaring(&["LZ4_compress_default", "LZ4_decompress_safe"]),+ )+ .unwrap();+ let chosen = ladder.chosen.unwrap();+ assert_eq!(chosen.tier, Tier::InTreeFuzzTarget);+ assert!(+ chosen.origin.ends_with("decompress_fuzzer.c"),+ "alphabetical order and file order both lead with the compressor: {chosen:?}"+ );+ }++ // The measured failure, not a hypothetical one: lz4's real round_trip_stream_fuzzer.c+ // mines 49 calls, so under a summed read-minus-write score it beat decompress_fuzzer.c+ // outright and the ladder returned the compressor's call order. The fixture keeps that+ // shape - the round trip carries MORE decode calls than the pure decoder and wins every+ // other key in shape_rank - so only the direction verdict can decide it.+ #[test]+ fn a_round_trip_target_loses_to_a_pure_decoder_it_outweighs_on_every_other_key() {+ let root = tree("roundtrip", &[]);+ let targets = vec![+ mined(+ "ossfuzz/a_round_trip_fuzzer.c",+ &[+ "LZ4_decompress_safe",+ "LZ4_decompress_safe_partial",+ "LZ4_decompress_safe_usingDict",+ "LZ4_compress_default",+ ],+ ),+ mined("ossfuzz/z_decompress_fuzzer.c", &["LZ4_decompress_safe"]),+ ];+ let chosen = select(+ &root,+ &targets,+ None,+ "lz4",+ &declaring(&[+ "LZ4_decompress_safe",+ "LZ4_decompress_safe_partial",+ "LZ4_decompress_safe_usingDict",+ "LZ4_compress_default",+ ]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert!(+ chosen.origin.ends_with("z_decompress_fuzzer.c"),+ "one compress call is enough to disqualify a file, however many decode calls \+ sit beside it: {chosen:?}"+ );+ }++ #[test]+ fn a_consumer_that_opens_a_file_loses_to_one_that_does_not() {+ let root = tree(+ "memory",+ &[+ (+ "contrib/pngtest.c",+ "int main(void) { FILE *f = fopen(\"x\", \"rb\"); png_init_io(p, f); \+ png_read_image(p); return 0; }",+ ),+ (+ "contrib/pngmem.c",+ "int main(void) { png_set_read_fn(p, &s, cb); png_read_info(p, i); return 0; }",+ ),+ ],+ );+ let chosen = select(+ &root,+ &[],+ None,+ "libpng",+ &declaring(&[+ "png_init_io",+ "png_read_image",+ "png_set_read_fn",+ "png_read_info",+ ]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert_eq!(chosen.tier, Tier::MemoryConsumer);+ assert!(+ chosen.origin.ends_with("pngmem.c"),+ "the fopen consumer carries more read words and would win on any other key: \+ {chosen:?}"+ );+ assert!(!chosen.contains("png_init_io"), "{chosen:?}");+ }++ #[test]+ fn an_in_tree_fuzz_target_outranks_every_consumer() {+ let root = tree(+ "tiers",+ &[(+ "examples/zpipe.c",+ "int main(void) { inflateInit(&s); inflate(&s, 0); inflateEnd(&s); return 0; }",+ )],+ );+ let targets = vec![mined("fuzz/f.c", &["uncompress"])];+ let ladder = select(+ &root,+ &targets,+ None,+ "zlib",+ &declaring(&["uncompress", "inflate", "inflateInit", "inflateEnd"]),+ )+ .unwrap();+ let chosen = ladder.chosen.as_ref().unwrap();+ assert_eq!(chosen.tier, Tier::InTreeFuzzTarget);+ assert_eq!(ladder.consumers, 1, "the consumer was still counted");+ }++ #[test]+ fn a_tree_with_no_fuzz_target_falls_to_its_consumers() {+ let root = tree(+ "consumer",+ &[(+ "examples/zpipe.c",+ "int main(void) { inflateInit(&s); inflate(&s, 0); inflateEnd(&s); return 0; }",+ )],+ );+ let chosen = select(+ &root,+ &[],+ None,+ "zlib",+ &declaring(&["inflate", "inflateInit", "inflateEnd"]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert_eq!(chosen.tier, Tier::MemoryConsumer);+ assert_eq!(+ chosen.names(),+ ["inflateInit", "inflate", "inflateEnd"],+ "the author initialises before inflating and that order is the whole point"+ );+ }++ #[test]+ fn the_oss_fuzz_checkout_is_only_read_for_the_project_asked_for() {+ let root = tree("ossfuzz", &[]);+ let checkout = tree(+ "ossfuzz-checkout",+ &[+ (+ "projects/zlib/zlib_uncompress_fuzzer.cc",+ "int LLVMFuzzerTestOneInput(const uint8_t *d, size_t n) { uncompress(a, b, d, n); return 0; }",+ ),+ (+ "projects/libpng/libpng_read_fuzzer.cc",+ "int LLVMFuzzerTestOneInput(const uint8_t *d, size_t n) { png_read_info(p, i); return 0; }",+ ),+ ],+ );+ let chosen = select(+ &root,+ &[],+ Some(&checkout),+ "zlib",+ &declaring(&["uncompress", "png_read_info"]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert_eq!(chosen.tier, Tier::OssFuzzTarget);+ assert!(chosen.contains("uncompress"), "{chosen:?}");+ assert!(!chosen.contains("png_read_info"), "{chosen:?}");+ }++ #[test]+ fn a_checkout_without_the_project_is_not_a_hit() {+ let root = tree("nomatch", &[]);+ let checkout = tree(+ "nomatch-checkout",+ &[(+ "projects/libpng/libpng_read_fuzzer.cc",+ "int LLVMFuzzerTestOneInput(const uint8_t *d, size_t n) { png_read_info(p, i); return 0; }",+ )],+ );+ let ladder = select(+ &root,+ &[],+ Some(&checkout),+ "zlib",+ &declaring(&["png_read_info"]),+ )+ .unwrap();+ assert!(ladder.chosen.is_none(), "{ladder:?}");+ }++ // Isolates the file-opening key AT TIER 1, where the memory-consumer filter cannot+ // reach. Gutting the key alone left every other control green: the consumer test is+ // alibied by that filter, and brotli's real runner is already demoted by the+ // declared-only rule. Both targets here are pure readers with the same declared read+ // count, so direction ties and the one that fopens is longer - it wins every later key.+ #[test]+ fn a_fuzz_target_that_opens_a_file_loses_even_when_it_reads_as_much() {+ let root = tree("openkey", &[]);+ let targets = vec![+ mined(+ "fuzz/a_via_file.c",+ &["fopen", "png_read_info", "png_read_end"],+ ),+ mined("fuzz/z_via_memory.c", &["png_read_info", "png_read_end"]),+ ];+ let chosen = select(+ &root,+ &targets,+ None,+ "libpng",+ &declaring(&["png_read_info", "png_read_end"]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert!(+ chosen.origin.ends_with("z_via_memory.c"),+ "a target that opens a file teaches an order we cannot replay: {chosen:?}"+ );+ }++ // Isolates the trailing-digit strip on its own. `identifier_words` splits+ // `tj3Compress8` into ["tj3", "Compress8"], so without the strip the compressor's own+ // fuzz target carries NO write signal, `tj3LoadImage8` gives it a read one, and it+ // grades a pure decoder. The decoder here is deliberately the shorter, less common file+ // so nothing but the direction verdict can save it.+ #[test]+ fn a_version_digit_does_not_hide_the_word_compress() {+ let root = tree("digits", &[]);+ let targets = vec![+ mined(+ "fuzz/a_compress.cc",+ &["tj3Compress8", "tj3LoadImage8", "tj3Init", "tj3Destroy"],+ ),+ mined("fuzz/z_decompress.cc", &["tj3Decompress8"]),+ ];+ let chosen = select(+ &root,+ &targets,+ None,+ "libjpeg-turbo",+ &declaring(&[+ "tj3Compress8",+ "tj3LoadImage8",+ "tj3Init",+ "tj3Destroy",+ "tj3Decompress8",+ ]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert!(+ chosen.origin.ends_with("z_decompress.cc"),+ "tj3Compress8 must read as a write call: {chosen:?}"+ );+ }++ // Isolates the declared-only filter. `fread` carries the word "read", and it is the+ // ONLY direction word in brotli's `run_decode_fuzzer.c` - a runner, not a harness - so+ // counting libc graded it a pure decoder. The runner is longer and would win every+ // later key, and it is given no fopen here so the file-opening rule cannot alibi this.+ #[test]+ fn libc_does_not_vote_on_which_way_a_target_reads() {+ let root = tree("libc", &[]);+ let targets = vec![+ mined(+ "fuzz/a_runner.c",+ &["fread", "malloc", "memcpy", "free", "fclose"],+ ),+ mined("fuzz/z_decode.c", &["BrotliDecoderDecompressStream"]),+ ];+ let chosen = select(+ &root,+ &targets,+ None,+ "brotli",+ &declaring(&["BrotliDecoderDecompressStream"]),+ )+ .unwrap()+ .chosen+ .unwrap();+ assert!(+ chosen.origin.ends_with("z_decode.c"),+ "only the library's own calls may set the direction: {chosen:?}"+ );+ }++ #[test]+ fn a_tree_with_nothing_to_mine_yields_no_sequence_rather_than_an_error() {+ let root = tree("empty", &[("src/lib.c", "int helper(void) { return 0; }")]);+ let ladder = select(&root, &[], None, "lib", &declaring(&["helper"])).unwrap();+ assert!(ladder.chosen.is_none());+ assert_eq!(ladder.consumers, 0);+ }+}diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/lib.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/lib.rsindex b7053ec4..54bb0e10 100644--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/lib.rs+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/lib.rs@@ -5,6 +5,7 @@ pub mod complexity;pub mod extract;pub mod harness;pub mod headers;+pub mod ladder;pub mod naming;pub mod rank;pub mod signature;diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/naming.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/naming.rsindex 85423d51..044f553b 100644--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/naming.rs+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/naming.rs@@ -75,6 +75,40 @@ pub const PRODUCER_TOKENS: &[&str] = &["dest",];+pub const READ_WORDS: [&str; 9] = [+ "read",+ "decode",+ "decoder",+ "decompress",+ "uncompress",+ "parse",+ "load",+ "inflate",+ "extract",+];++pub const WRITE_WORDS: [&str; 7] = [+ "write", "encode", "encoder", "compress", "save", "deflate", "flush",+];++#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum Polarity {+ Read,+ Write,+}++// Read is tested first and wins outright, because the ambiguity runs one way only: every+// decode word contains an encode word as a suffix (`decompress`, `uncompress`) and no+// encode word contains a decode one. carries_word suffix-matches a lone lowercase+// identifier, so without this zlib's `uncompress` - the DECOMPRESSOR - reads as a writer.+#[must_use]+pub fn polarity_of(name: &str) -> Option<Polarity> {+ if crate::extract::carries_word(name, &READ_WORDS) {+ return Some(Polarity::Read);+ }+ crate::extract::carries_word(name, &WRITE_WORDS).then_some(Polarity::Write)+}+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]pub enum Role {Entry,diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/signature.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/signature.rsindex 7cff6565..d054d29f 100644--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/signature.rs+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/signature.rs@@ -76,6 +76,16 @@ pub enum Fuzzability {}impl Fuzzability {+ // The call that RECEIVES the corpus bytes, as opposed to one that merely appears in the+ // author's sequence. libarchive's `archive_read_support_format_rar5(struct archive *)`+ // is in every one of its 25 fuzz targets and takes no input at all; treating "the+ // authors call it" as "the authors fuzz it" hoisted seven such configurators above the+ // entry point the M3 gate asserts ranks first.+ #[must_use]+ pub fn takes_bytes(self) -> bool {+ matches!(self, Fuzzability::DirectBuffer | Fuzzability::CastBuffer)+ }+#[must_use]pub fn score(self) -> f64 {match self {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.rsindex 27272337..51c4f663 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@@ -8,6 +8,7 @@ use crate::complexity::{self, CallGraph, Defined};use crate::extract::{self, Declared, Language, ParseOptions};use crate::harness::{self, Harness};use crate::headers::{self, HeaderError, HeaderSet};+use crate::ladder::{self, Ladder};use crate::rank::{self, Complexity, Function, Ranking, Weights};pub const SOURCE_EXTENSIONS: &[&str] = &["c", "cc", "cpp", "cxx"];@@ -68,6 +69,7 @@ pub struct SurfaceOptions {pub language: Language,pub weights: Weights,pub ignore_harnesses: bool,+ pub oss_fuzz: Option<PathBuf>,}impl SurfaceOptions {@@ -81,6 +83,7 @@ impl SurfaceOptions {language: Language::default(),weights: Weights::default(),ignore_harnesses: true,+ oss_fuzz: None,}}@@ -115,6 +118,7 @@ pub struct Surface {pub headers: Vec<PathBuf>,pub skipped: Vec<SkippedHeader>,pub harnesses: Vec<Harness>,+ pub ladder: Ladder,pub declared: usize,pub defined: usize,pub skipped_sources: Vec<SkippedHeader>,@@ -270,6 +274,16 @@ pub fn analyze(options: &SurfaceOptions) -> Result<Surface, SurfaceError> {});}+ // After the headers on purpose: a mined call list is raw text, so the only way to tell+ // one of the library's own calls from libc is to ask what the library declares.+ let ladder = ladder::select(+ &options.source,+ &harnesses,+ options.oss_fuzz.as_deref(),+ &headers::project_of(&options.source),+ &declared.iter().map(|item| item.name.clone()).collect(),+ )?;+let (defined, skipped_sources) = read_sources(&options.source, options, &set.root, &owned);refuse_foreign(&set.root, &skipped_sources)?;let defined_count = defined.len();@@ -310,6 +324,7 @@ pub fn analyze(options: &SurfaceOptions) -> Result<Surface, SurfaceError> {headers: set.headers.clone(),skipped,harnesses,+ ladder,declared: declared.len(),defined: defined_count,skipped_sources,diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/src/main.rsindex 061016e3..777eb716 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@@ -244,6 +244,11 @@ struct HarnessArgs {defines: Vec<String>,#[arg(long, help = "parse headers as C++ instead of C")]cpp: bool,+ #[arg(+ long = "oss-fuzz",+ help = "checkout of google/oss-fuzz, read for the call order of libraries that ship no fuzz target of their own"+ )]+ oss_fuzz: Option<PathBuf>,#[arg(long, default_value_t = DEFAULT_SURFACE_TOP, help = "how many ranked entry points to try")]top: usize,#[arg(long, help = "directory to write the synthesized harness into")]@@ -253,6 +258,11 @@ struct HarnessArgs {help = "emit the first candidate that plans without running any oracle against it")]no_verify: bool,+ #[arg(+ long = "plan-only",+ help = "report what every ranked candidate plans or is refused for, and write nothing"+ )]+ plan_only: bool,#[command(flatten)]oracle: OracleArgs,}@@ -275,6 +285,11 @@ struct SurfaceArgs {help = "rank the unreached frontier: what to fuzz next given the in-tree harnesses that already exist")]frontier: bool,+ #[arg(+ long = "oss-fuzz",+ help = "checkout of google/oss-fuzz, read for the call order of libraries that ship no fuzz target of their own"+ )]+ oss_fuzz: Option<PathBuf>,#[arg(long, default_value_t = DEFAULT_SURFACE_TOP, help = "how many ranked entry points to print")]top: usize,#[arg(long, help = "emit the full ranking as json")]@@ -335,12 +350,21 @@ fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {options.defines.clone_from(&args.defines);options.language = if args.cpp { Language::Cpp } else { Language::C };options.ignore_harnesses = true;+ options.oss_fuzz.clone_from(&args.oss_fuzz);let analysis = surface::analyze(&options)?;+ report_ladder(&analysis.ladder);let root = std::fs::canonicalize(&analysis.header_root).unwrap_or_else(|_| analysis.header_root.clone());let parse = options.parse_options(&root, &analysis.headers);+ let vocabulary = library_vocabulary(&analysis, &parse);++ if args.plan_only {+ plan_only(&analysis, &root, &vocabulary, args.top);+ return Ok(());+ }+let bench = if args.no_verify {println!("{UNVERIFIED_BANNER}");None@@ -357,16 +381,12 @@ fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {std::fs::create_dir_all(&candidates)?;let mut rejected = Vec::new();let mut accepted = EdgeSet::new();- let vocabulary = library_vocabulary(&analysis, &parse);- for candidate in analysis.ranking.candidates.iter().take(args.top) {- let include = candidate- .header- .strip_prefix(&root)- .unwrap_or(&candidate.header)- .display()- .to_string();- let plans = match synth::plan_candidate(candidate, &include, &vocabulary) {+ let sequence = authored_sequence(&analysis);++ for candidate in ladder_ordered(&analysis).into_iter().take(args.top) {+ let include = include_of(candidate, &root);+ let plans = match synth::plan_candidate_with(candidate, &include, &vocabulary, sequence) {Ok(plans) => plans,Err(refusal) => {rejected.push(format!(" {} - refused: {refusal}", candidate.name));@@ -426,6 +446,103 @@ fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {Err("no harness synthesized".into())}+// The ladder RESCORES nothing. It reorders, and inside each group the surface's own rank+// order is untouched.+//+// Two rules, and the second one is the point. First, a candidate is hoisted only if the+// authors both CALL it and feed it the corpus: every one of libarchive's 25 fuzz targets+// calls `archive_read_support_format_rar5`, and hoisting on mention alone put seven such+// configurators above `archive_read_open_memory`.+//+// Second, those data-entry calls set a FLOOR. Nothing ranked below the authors' own+// entry points may substitute for them. That is the fall-through B46 named, still live:+// with every real lz4 decoder refused for an unrelated reason, the loop kept walking down+// the ranking and emitted `LZ4_loadDictHC` - the COMPRESSOR's dictionary loader - and+// brotli likewise emitted `BrotliDecoderAttachDictionary`. Once the library's authors have+// shown which call takes the bytes, a lower-ranked function that merely accepts a buffer is+// not an answer to the same question. Candidates ABOVE the floor stay eligible, so the+// unfuzzed frontier this whole tool is aimed at is untouched.+fn ladder_ordered(analysis: &surface::Surface) -> Vec<&lisdex_surface::rank::Candidate> {+ let ranked = &analysis.ranking.candidates;+ let authored = |candidate: &lisdex_surface::rank::Candidate| {+ analysis.ladder.contains(&candidate.name) && !synth::is_configurator(candidate)+ };+ let floor = ranked.iter().rposition(&authored);+ let eligible = floor.map_or(ranked.len(), |index| index + 1);+ let (entries, rest): (Vec<_>, Vec<_>) = ranked+ .iter()+ .take(eligible)+ .partition(|candidate| authored(candidate));+ entries.into_iter().chain(rest).collect()+}++fn authored_sequence(analysis: &surface::Surface) -> &[String] {+ analysis+ .ladder+ .chosen+ .as_ref()+ .map_or(&[][..], |sequence| sequence.names())+}++fn report_ladder(ladder: &lisdex_surface::ladder::Ladder) {+ match &ladder.chosen {+ Some(sequence) => println!(+ "call order: {} from {} ({} call(s), {} in-tree fuzz target(s), {} consumer(s))",+ sequence.tier.describe(),+ sequence.origin.display(),+ sequence.calls.len(),+ ladder.fuzz_targets,+ ladder.consumers+ ),+ None => println!(+ "call order: none - this tree ships no fuzz target and no consumer program, so \+ ranking alone decides what to synthesize"+ ),+ }+}++fn include_of(candidate: &lisdex_surface::rank::Candidate, root: &std::path::Path) -> String {+ candidate+ .header+ .strip_prefix(root)+ .unwrap_or(&candidate.header)+ .display()+ .to_string()+}++// The synthesizer returns on the FIRST candidate that plans, so the only way to see why the+// ones above it were refused was to bisect --top by hand. A fix cannot be sized against a+// decision nobody can read.+fn plan_only(+ analysis: &surface::Surface,+ root: &std::path::Path,+ vocabulary: &lisdex_surface::extract::Vocabulary,+ top: usize,+) {+ let sequence = authored_sequence(analysis);+ for (index, candidate) in ladder_ordered(analysis).into_iter().take(top).enumerate() {+ let include = include_of(candidate, root);+ let order = index + 1;+ let authored = if analysis.ladder.contains(&candidate.name) {+ "authored"+ } else {+ " "+ };+ match synth::plan_candidate_with(candidate, &include, vocabulary, sequence) {+ Ok(plans) => println!(+ "{order:>3}. {authored} PLANS {} ({} variant(s)), replaying {:?}",+ candidate.name,+ plans.len(),+ plans.first().map_or(&[][..], |plan| &plan.replayed)+ ),+ Err(refusal) => println!(+ "{order:>3}. {authored} refused {} - {refusal}",+ candidate.name+ ),+ }+ }+}+fn report_rejections(rejected: &[String]) {// Printed on SUCCESS too: a libarchive user handed a date parser needs to see that the// archive readers above it were refused, not just the winner.@@ -531,6 +648,7 @@ fn surface(args: &SurfaceArgs) -> Result<(), Box<dyn Error>> {options.defines.clone_from(&args.defines);options.language = if args.cpp { Language::Cpp } else { Language::C };options.ignore_harnesses = !args.frontier;+ options.oss_fuzz.clone_from(&args.oss_fuzz);let analysis = surface::analyze(&options)?;@@ -552,6 +670,7 @@ fn surface(args: &SurfaceArgs) -> Result<(), Box<dyn Error>> {"canonical"});+ report_ladder(&analysis.ladder);if !analysis.skipped_sources.is_empty() {println!("{} source file(s) did not parse; the call graph behind 55% of the score is \diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.shindex c941c29d..707e08a9 100755--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh@@ -75,6 +75,10 @@ clone libpng https://github.com/pnggroup/libpng.git libpng16clone libtiff https://gitlab.com/libtiff/libtiff.git masterclone openjpeg https://github.com/uclouvain/openjpeg.git masterclone libarchive https://github.com/libarchive/libarchive.git master+# lz4 and brotli are the two libraries whose every real decoder is refused for reasons the+# ladder does not touch, so they are where a fall-through is visible at all.+clone lz4 https://github.com/lz4/lz4.git dev+clone brotli https://github.com/google/brotli.git master# libpng's png.h includes pnglibconf.h, which is NOT in the repository - it is# produced by the build. libpng ships scripts/pnglibconf.h.prebuilt for exactly@@ -283,6 +287,95 @@ $(head -1 "$OUT/b30-intree.txt")"firm -rf "$FOREIGN" "$B30ROOT"+# M5 step 4. Every assertion here is a behaviour that was measured WRONG at 4e23a80a and is+# named with the library it was measured on, so a regression says which library to open.+banner "M5 RANKED SOURCE LADDER"++plan_of() {+ local name="$1"+ "$LISDEX" harness "$SRC/$name" --out "$OUT/ladder-$name" --plan-only --top 30 \+ >"$OUT/ladder-$name.txt" 2>&1+ cat "$OUT/ladder-$name.txt"+}++# The single line the whole B66 entry is about: `archive_read_open_memory` returned+# ARCHIVE_FATAL ("No formats registered") at full exec rate with a bitmap that never grew+# past handle plumbing, because nothing registered a format first.+LADDER_ARCHIVE="$(plan_of libarchive)"+REPLAY="$(echo "$LADDER_ARCHIVE" | grep "PLANS archive_read_open_memory" | head -1)"+if echo "$REPLAY" | grep -q "archive_read_support_format"; then+ ok "libarchive replays the author's format registration before archive_read_open_memory"+else+ bad "libarchive registers no format, so the reader returns ARCHIVE_FATAL (B66): $REPLAY"+fi+if echo "$REPLAY" | grep -q "archive_read_support_filter"; then+ ok "libarchive replays the author's filter registration too"+else+ bad "libarchive replays no filter registration: $REPLAY"+fi+# Isolates the binding rule from the run rule: `archive_read_free` is plumbing-shaped and+# sits inside the opening run of several targets, and `archive_read_set_options` takes a+# string. Neither may be replayed, and replaying the free would tear the handle down first.+if echo "$REPLAY" | grep -qE "archive_read_free|archive_read_set_options"; then+ bad "libarchive replayed a teardown or a string-taking call as setup: $REPLAY"+else+ ok "only handle-taking registrations are replayed, no teardown and no string-taking call"+fi++# The fall-through B46 named, still live at 4e23a80a: with every real decoder refused for an+# unrelated reason, the loop kept walking down the ranking and emitted a configurator.+LADDER_LZ4="$(plan_of lz4)"+if echo "$LADDER_LZ4" | grep "PLANS" | head -1 | grep -q "LZ4_loadDictHC"; then+ bad "lz4 still synthesizes the COMPRESSOR's dictionary loader"+else+ ok "lz4 does not fall through to LZ4_loadDictHC on an LZ4_streamHC_t"+fi+# Isolates the direction verdict on a real tree: lz4 ships 11 targets and only two of them+# are pure decoders. A summed read-minus-write score picked round_trip_stream_fuzzer.c,+# which makes 49 calls and compresses first.+if echo "$LADDER_LZ4" | grep -q "^call order.*decompress.*fuzzer"; then+ ok "lz4's call order comes from a decompress target, not a compress or round-trip one"+else+ bad "lz4 took its call order from the wrong direction: \+$(echo "$LADDER_LZ4" | grep '^call order')"+fi++LADDER_BROTLI="$(plan_of brotli)"+if echo "$LADDER_BROTLI" | grep "PLANS" | head -1 | grep -q "BrotliDecoderAttachDictionary"; then+ bad "brotli still synthesizes a dictionary configurator"+else+ ok "brotli does not fall through to BrotliDecoderAttachDictionary"+fi+# Isolates the file-opening key. brotli ships TWO files carrying the LibFuzzer entry symbol+# and `run_decode_fuzzer.c` is a main() that fopens a path and calls the real one; it is+# longer, so it won the tier on every later key.+if echo "$LADDER_BROTLI" | grep -q "^call order.*c/fuzz/decode_fuzzer.c"; then+ ok "brotli's call order comes from the fuzz target, not from the runner beside it"+else+ bad "brotli took its call order from a runner: \+$(echo "$LADDER_BROTLI" | grep '^call order')"+fi++# The negative control the ladder must REFUSE to help: a tree with nothing to mine has no+# authored floor, so the ranking alone decides and no setup is invented.+BARE="$WORK/ladder-bare"+rm -rf "$BARE"+mkdir -p "$BARE/include" "$BARE/src"+cp "$SRC/libarchive/libarchive/archive.h" "$BARE/include/archive.h" 2>/dev/null+if "$LISDEX" harness "$BARE" --out "$OUT/ladder-bare-out" --plan-only --top 5 \+ >"$OUT/ladder-bare.txt" 2>&1; then+ if grep -q "call order: none" "$OUT/ladder-bare.txt" \+ && ! grep -q "replaying \[\"" "$OUT/ladder-bare.txt"; then+ ok "a tree with no fuzz target and no consumer replays nothing and says so"+ else+ bad "the ladder invented a sequence for a tree with nothing to mine: \+$(head -2 "$OUT/ladder-bare.txt")"+ fi+else+ ok "a tree with no fuzz target and no consumer replays nothing and says so"+fi+rm -rf "$BARE"+banner "RESULT"echo " passed: $PASS"echo " failed: $FAIL"