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 - synthesized harness re-finds a magma bug with no LLM

CarterPerez-dev38f8ec0541b2
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
index f7a969c6..b9b75ea5 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
@@ -296,6 +296,7 @@ dependencies = [
"lisdex-build",
"lisdex-core",
"lisdex-fuzz",
+ "lisdex-harness",
"lisdex-ingest",
"lisdex-surface",
"serde_json",
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 771ffda7..d4b9afa5 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
@@ -6,3 +6,4 @@ pub mod coverage;
pub mod emit;
pub mod oracle;
pub mod plan;
+pub mod synth;
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
new file mode 100644
index 00000000..9d3c2225
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-harness/src/synth.rs
@@ -0,0 +1,521 @@
+// ©AngelaMos | 2026
+// synth.rs
+
+use lisdex_surface::extract::Vocabulary;
+use lisdex_surface::rank::Candidate;
+use lisdex_surface::signature::{Fuzzability, Param, ParamRole, Pointee, Shape};
+
+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;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum Refusal {
+ NoDataInput,
+ UnsizedOutParam { param: String },
+ OpaqueContext { record: String },
+ NeedsCallback { param: String },
+ PathEntry,
+ UnsupportedShape { param: String },
+}
+
+impl std::fmt::Display for Refusal {
+ fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+ match self {
+ Refusal::NoDataInput => write!(formatter, "consumes no fuzzable input"),
+ Refusal::UnsizedOutParam { param } => write!(
+ formatter,
+ "out-param {param} needs a caller-supplied extent that headers cannot give; guessing it fabricates a crash inside the library"
+ ),
+ Refusal::OpaqueContext { record } => write!(
+ formatter,
+ "context {record} is opaque and needs a producer chain"
+ ),
+ Refusal::NeedsCallback { param } => {
+ write!(formatter, "parameter {param} needs a synthesized callback")
+ }
+ Refusal::PathEntry => write!(formatter, "takes a filesystem path"),
+ Refusal::UnsupportedShape { param } => {
+ write!(formatter, "parameter {param} has no binding rule")
+ }
+ }
+ }
+}
+
+#[must_use]
+pub fn macro_for_field(record: &str, field: &str, vocabulary: &Vocabulary) -> Option<String> {
+ let direct = format!("{}_{}", record.to_uppercase(), field.to_uppercase());
+ if vocabulary.macros.contains(&direct) {
+ return Some(direct);
+ }
+ let suffix = format!("_{}", field.to_uppercase());
+ let record_upper = record.to_uppercase();
+ vocabulary
+ .macros
+ .iter()
+ .filter(|name| name.ends_with(&suffix))
+ .find(|name| {
+ let head = &name[..name.len() - suffix.len()];
+ record_upper.starts_with(head) || head.starts_with(&record_upper)
+ })
+ .cloned()
+}
+
+fn is_double_pointer(param: &Param) -> bool {
+ matches!(
+ &param.shape,
+ Shape::Pointer {
+ pointee: Pointee::Pointer,
+ ..
+ }
+ )
+}
+
+fn cast_for(param: &Param) -> Option<String> {
+ match &param.shape {
+ Shape::Pointer { pointee, .. } if pointee.is_exact_byte() => None,
+ Shape::Pointer { .. } => Some(param.spelling.clone()),
+ _ => None,
+ }
+}
+
+fn context_record(param: &Param) -> Option<&str> {
+ match &param.shape {
+ Shape::Pointer {
+ pointee: Pointee::Record(name),
+ ..
+ } => Some(name.as_str()),
+ _ => None,
+ }
+}
+
+fn bind(param: &Param, role: ParamRole, context: Option<&str>) -> Result<Value, Refusal> {
+ let label = param.name.clone().unwrap_or_else(|| param.spelling.clone());
+ match role {
+ ParamRole::Buffer => Ok(Value::Data {
+ cast: cast_for(param),
+ }),
+ ParamRole::Length => Ok(Value::Size),
+ ParamRole::Config => Ok(Value::Zero),
+ ParamRole::Callback => Err(Refusal::NeedsCallback { param: label }),
+ ParamRole::Path => Err(Refusal::PathEntry),
+ ParamRole::Stream => Err(Refusal::UnsupportedShape { param: label }),
+ ParamRole::Output | ParamRole::Context => {
+ if is_double_pointer(param) {
+ return Err(Refusal::UnsizedOutParam { param: label });
+ }
+ match context {
+ Some(local) => Ok(Value::AddressOf(local.to_owned())),
+ None => Err(Refusal::UnsupportedShape { param: label }),
+ }
+ }
+ }
+}
+
+fn field_bindings(record: &str, vocabulary: &Vocabulary) -> Vec<(String, String)> {
+ let Some(fields) = vocabulary.records.get(record) else {
+ return Vec::new();
+ };
+ fields
+ .iter()
+ .filter(|field| field.shape == Shape::Integral)
+ .filter_map(|field| {
+ macro_for_field(record, &field.name, vocabulary)
+ .map(|macro_name| (field.name.clone(), macro_name))
+ })
+ .take(MAX_FIELD_VARIANTS)
+ .collect()
+}
+
+pub fn plan_candidate(
+ candidate: &Candidate,
+ include: &str,
+ vocabulary: &Vocabulary,
+) -> Result<Vec<HarnessPlan>, Refusal> {
+ if candidate.fuzzability == Fuzzability::NoInput {
+ return Err(Refusal::NoDataInput);
+ }
+
+ let context = candidate
+ .params
+ .iter()
+ .zip(&candidate.analysis.roles)
+ .find(|(param, role)| {
+ matches!(role, ParamRole::Context | ParamRole::Output) && !is_double_pointer(param)
+ })
+ .and_then(|(param, _)| context_record(param));
+
+ if let Some(record) = context
+ && !vocabulary.records.contains_key(record)
+ {
+ return Err(Refusal::OpaqueContext {
+ record: record.to_owned(),
+ });
+ }
+
+ let mut args = Vec::with_capacity(candidate.params.len());
+ for (param, role) in candidate.params.iter().zip(&candidate.analysis.roles) {
+ args.push(bind(param, *role, context.map(|_| CONTEXT_LOCAL))?);
+ }
+
+ let mut base = HarnessPlan::new(candidate.name.clone()).with_include(include);
+ if let Some(record) = context {
+ base = base.with(Stmt::Declare {
+ ty: record.to_owned(),
+ name: CONTEXT_LOCAL.to_owned(),
+ init: Init::ZeroBytes,
+ });
+ }
+
+ let bindings = context.map(|record| field_bindings(record, vocabulary));
+ let call = |plan: HarnessPlan| -> HarnessPlan {
+ let capture = match candidate.result.shape {
+ Shape::Void | Shape::Other => None,
+ _ => Some(Binding {
+ ty: candidate.result.spelling.clone(),
+ name: RESULT_LOCAL.to_owned(),
+ }),
+ };
+ plan.with(Stmt::Call {
+ function: candidate.name.clone(),
+ args: args.clone(),
+ capture,
+ })
+ };
+
+ 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 {
+ 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)),
+ }
+ Ok(plans)
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+ use lisdex_surface::extract::Field;
+ use lisdex_surface::rank::Complexity;
+ use lisdex_surface::signature::{Analysis, Returns};
+ use std::collections::{BTreeMap, BTreeSet};
+ use std::path::PathBuf;
+
+ fn param(name: &str, spelling: &str, shape: Shape) -> Param {
+ Param {
+ name: Some(name.to_owned()),
+ spelling: spelling.to_owned(),
+ shape,
+ }
+ }
+
+ fn candidate(
+ name: &str,
+ params: Vec<Param>,
+ roles: Vec<ParamRole>,
+ fuzzability: Fuzzability,
+ result: Returns,
+ ) -> Candidate {
+ Candidate {
+ name: name.to_owned(),
+ params,
+ result,
+ header: PathBuf::from("png.h"),
+ line: 1,
+ fuzzability,
+ analysis: Analysis {
+ fuzzability,
+ roles,
+ context_args: 1,
+ },
+ complexity: Complexity::default(),
+ exported: true,
+ reachable_from_harness: false,
+ score: 1.0,
+ reasons: Vec::new(),
+ }
+ }
+
+ fn png_image_vocabulary() -> Vocabulary {
+ Vocabulary {
+ macros: BTreeSet::from(["PNG_IMAGE_VERSION".to_owned(), "PNG_FORMAT_RGBA".to_owned()]),
+ records: BTreeMap::from([(
+ "png_image".to_owned(),
+ vec![
+ Field {
+ name: "opaque".to_owned(),
+ spelling: "png_controlp".to_owned(),
+ shape: Shape::Pointer {
+ pointee: Pointee::Record("png_control".to_owned()),
+ is_const: false,
+ },
+ },
+ Field {
+ name: "version".to_owned(),
+ spelling: "png_uint_32".to_owned(),
+ shape: Shape::Integral,
+ },
+ ],
+ )]),
+ }
+ }
+
+ fn begin_read() -> Candidate {
+ candidate(
+ "png_image_begin_read_from_memory",
+ vec![
+ param(
+ "image",
+ "png_imagep",
+ Shape::Pointer {
+ pointee: Pointee::Record("png_image".to_owned()),
+ is_const: false,
+ },
+ ),
+ param(
+ "memory",
+ "png_const_voidp",
+ Shape::Pointer {
+ pointee: Pointee::Void,
+ is_const: true,
+ },
+ ),
+ param("size", "size_t", Shape::Integral),
+ ],
+ vec![ParamRole::Context, ParamRole::Buffer, ParamRole::Length],
+ Fuzzability::CastBuffer,
+ Returns {
+ spelling: "int".to_owned(),
+ shape: Shape::Integral,
+ },
+ )
+ }
+
+ #[test]
+ fn the_version_field_binds_to_its_macro_by_name_affinity() {
+ assert_eq!(
+ macro_for_field("png_image", "version", &png_image_vocabulary()),
+ Some("PNG_IMAGE_VERSION".to_owned())
+ );
+ }
+
+ #[test]
+ fn a_field_with_no_matching_macro_binds_to_nothing() {
+ assert_eq!(
+ macro_for_field("png_image", "height", &png_image_vocabulary()),
+ None
+ );
+ }
+
+ #[test]
+ fn macro_affinity_is_case_insensitive_on_the_record_name() {
+ let mut vocab = png_image_vocabulary();
+ vocab.macros.insert("Z_STREAM_VERSION".to_owned());
+ assert_eq!(
+ macro_for_field("z_stream", "version", &vocab),
+ Some("Z_STREAM_VERSION".to_owned())
+ );
+ }
+
+ #[test]
+ fn the_struct_entry_produces_a_populated_variant_first() {
+ let plans = plan_candidate(&begin_read(), "png.h", &png_image_vocabulary()).unwrap();
+ assert_eq!(plans.len(), 2);
+ assert!(plans[0].body.contains(&Stmt::SetField {
+ local: CONTEXT_LOCAL.to_owned(),
+ field: "version".to_owned(),
+ value: Value::Literal("PNG_IMAGE_VERSION".to_owned()),
+ }));
+ }
+
+ #[test]
+ fn the_unpopulated_variant_is_kept_so_the_oracle_can_choose() {
+ let plans = plan_candidate(&begin_read(), "png.h", &png_image_vocabulary()).unwrap();
+ assert!(
+ !plans[1]
+ .body
+ .iter()
+ .any(|s| matches!(s, Stmt::SetField { .. }))
+ );
+ }
+
+ #[test]
+ fn the_context_is_a_zeroed_stack_local_passed_by_address() {
+ let plans = plan_candidate(&begin_read(), "png.h", &png_image_vocabulary()).unwrap();
+ assert_eq!(
+ plans[0].body[0],
+ Stmt::Declare {
+ ty: "png_image".to_owned(),
+ name: CONTEXT_LOCAL.to_owned(),
+ init: Init::ZeroBytes,
+ }
+ );
+ let Some(Stmt::Call { args, .. }) = plans[0].body.last() else {
+ panic!("expected a trailing call");
+ };
+ assert_eq!(args[0], Value::AddressOf(CONTEXT_LOCAL.to_owned()));
+ }
+
+ #[test]
+ fn the_buffer_is_cast_and_the_length_is_the_size() {
+ let plans = plan_candidate(&begin_read(), "png.h", &png_image_vocabulary()).unwrap();
+ let Some(Stmt::Call { args, .. }) = plans[0].body.last() else {
+ panic!("expected a trailing call");
+ };
+ assert_eq!(
+ args[1],
+ Value::Data {
+ cast: Some("png_const_voidp".to_owned())
+ }
+ );
+ assert_eq!(args[2], Value::Size);
+ }
+
+ #[test]
+ fn a_non_void_result_is_captured() {
+ let plans = plan_candidate(&begin_read(), "png.h", &png_image_vocabulary()).unwrap();
+ let Some(Stmt::Call { capture, .. }) = plans[0].body.last() else {
+ panic!("expected a trailing call");
+ };
+ assert_eq!(
+ capture.as_ref().map(|binding| binding.ty.as_str()),
+ Some("int")
+ );
+ }
+
+ #[test]
+ fn an_opaque_context_is_refused_rather_than_guessed() {
+ let mut opaque = begin_read();
+ opaque.params[0].shape = Shape::Pointer {
+ pointee: Pointee::Record("png_struct_def".to_owned()),
+ is_const: false,
+ };
+ assert_eq!(
+ plan_candidate(&opaque, "png.h", &png_image_vocabulary()),
+ Err(Refusal::OpaqueContext {
+ record: "png_struct_def".to_owned()
+ })
+ );
+ }
+
+ #[test]
+ fn an_unsized_double_pointer_out_param_is_refused() {
+ let read_image = candidate(
+ "png_read_image",
+ vec![
+ param(
+ "png_ptr",
+ "png_structrp",
+ Shape::Pointer {
+ pointee: Pointee::Record("png_image".to_owned()),
+ is_const: false,
+ },
+ ),
+ param(
+ "row_pointers",
+ "png_bytepp",
+ Shape::Pointer {
+ pointee: Pointee::Pointer,
+ is_const: false,
+ },
+ ),
+ ],
+ vec![ParamRole::Context, ParamRole::Output],
+ Fuzzability::CastBuffer,
+ Returns::default(),
+ );
+ assert_eq!(
+ plan_candidate(&read_image, "png.h", &png_image_vocabulary()),
+ Err(Refusal::UnsizedOutParam {
+ param: "row_pointers".to_owned()
+ })
+ );
+ }
+
+ #[test]
+ fn a_callback_parameter_is_refused_until_callback_synthesis_lands() {
+ let set_read_fn = candidate(
+ "png_set_read_fn",
+ vec![
+ param(
+ "png_ptr",
+ "png_structrp",
+ Shape::Pointer {
+ pointee: Pointee::Record("png_image".to_owned()),
+ is_const: false,
+ },
+ ),
+ param(
+ "read_fn",
+ "png_rw_ptr",
+ Shape::Pointer {
+ pointee: Pointee::Function,
+ is_const: false,
+ },
+ ),
+ ],
+ vec![ParamRole::Context, ParamRole::Callback],
+ Fuzzability::CustomStream,
+ Returns::default(),
+ );
+ assert!(matches!(
+ plan_candidate(&set_read_fn, "png.h", &png_image_vocabulary()),
+ Err(Refusal::NeedsCallback { .. })
+ ));
+ }
+
+ #[test]
+ fn an_entry_with_no_data_input_is_refused() {
+ let mut dead = begin_read();
+ dead.fuzzability = Fuzzability::NoInput;
+ assert_eq!(
+ plan_candidate(&dead, "png.h", &png_image_vocabulary()),
+ Err(Refusal::NoDataInput)
+ );
+ }
+
+ #[test]
+ fn a_plain_buffer_entry_needs_no_context_local() {
+ let decode = candidate(
+ "decode",
+ vec![
+ param(
+ "data",
+ "const uint8_t *",
+ Shape::Pointer {
+ pointee: Pointee::UnsignedChar,
+ is_const: true,
+ },
+ ),
+ param("len", "size_t", Shape::Integral),
+ ],
+ vec![ParamRole::Buffer, ParamRole::Length],
+ Fuzzability::DirectBuffer,
+ Returns::default(),
+ );
+ let plans = plan_candidate(&decode, "x.h", &Vocabulary::default()).unwrap();
+ assert_eq!(plans.len(), 1);
+ assert!(
+ !plans[0]
+ .body
+ .iter()
+ .any(|s| matches!(s, Stmt::Declare { .. }))
+ );
+ let Some(Stmt::Call { args, .. }) = plans[0].body.last() else {
+ panic!("expected a trailing call");
+ };
+ assert_eq!(args[0], Value::Data { cast: None });
+ }
+}
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 3a7a0d6b..6cecfefd 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
@@ -1,7 +1,7 @@
// ©AngelaMos | 2026
// extract.rs
-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
use std::path::{Path, PathBuf};
use std::sync::{Mutex, PoisonError};
@@ -60,6 +60,28 @@ impl ParseOptions {
}
}
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
+pub struct Field {
+ pub name: String,
+ pub spelling: String,
+ pub shape: Shape,
+}
+
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct Vocabulary {
+ pub macros: BTreeSet<String>,
+ pub records: BTreeMap<String, Vec<Field>>,
+}
+
+impl Vocabulary {
+ pub fn absorb(&mut self, other: Vocabulary) {
+ self.macros.extend(other.macros);
+ for (name, fields) in other.records {
+ self.records.entry(name).or_insert(fields);
+ }
+ }
+}
+
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize)]
pub struct Declared {
pub name: String,
@@ -247,6 +269,82 @@ fn collect(entity: &Entity, target: &Path, found: &mut Vec<Declared>, seen: &mut
}
}
+fn record_fields(entity: &Entity) -> Vec<Field> {
+ entity
+ .get_children()
+ .iter()
+ .filter(|child| child.get_kind() == EntityKind::FieldDecl)
+ .filter_map(|child| {
+ let name = child.get_name()?;
+ let ty = child.get_type();
+ Some(Field {
+ name,
+ spelling: ty
+ .as_ref()
+ .map(clang::Type::get_display_name)
+ .unwrap_or_default(),
+ shape: ty.as_ref().map_or(Shape::Other, shape_of),
+ })
+ })
+ .collect()
+}
+
+fn collect_vocabulary(entity: &Entity, into: &mut Vocabulary) {
+ for child in entity.get_children() {
+ match child.get_kind() {
+ EntityKind::MacroDefinition => {
+ if child.is_builtin_macro() {
+ continue;
+ }
+ if let Some(name) = child.get_name() {
+ into.macros.insert(name);
+ }
+ }
+ EntityKind::StructDecl | EntityKind::UnionDecl => {
+ let fields = record_fields(&child);
+ if !fields.is_empty()
+ && let Some(ty) = child.get_type()
+ {
+ into.records
+ .entry(record_name(&ty.get_canonical_type()))
+ .or_insert(fields);
+ }
+ }
+ EntityKind::LinkageSpec | EntityKind::Namespace | EntityKind::UnexposedDecl => {
+ collect_vocabulary(&child, into);
+ }
+ _ => {}
+ }
+ }
+}
+
+pub fn parse_vocabulary(path: &Path, options: &ParseOptions) -> Result<Vocabulary, ExtractError> {
+ if !path.is_file() {
+ return Err(ExtractError::NotAFile(path.to_path_buf()));
+ }
+ let target = std::fs::canonicalize(path).map_err(|source| ExtractError::Io {
+ path: path.to_path_buf(),
+ source,
+ })?;
+
+ with_index(|index| {
+ let unit = index
+ .parser(&target)
+ .arguments(&options.argv())
+ .skip_function_bodies(true)
+ .detailed_preprocessing_record(true)
+ .parse()
+ .map_err(|source| ExtractError::Parse {
+ path: target.clone(),
+ reason: source.to_string(),
+ })?;
+
+ let mut vocabulary = Vocabulary::default();
+ collect_vocabulary(&unit.get_entity(), &mut vocabulary);
+ Ok(vocabulary)
+ })
+}
+
pub fn parse_header(path: &Path, options: &ParseOptions) -> Result<Vec<Declared>, ExtractError> {
if !path.is_file() {
return Err(ExtractError::NotAFile(path.to_path_buf()));
@@ -311,6 +409,96 @@ mod tests {
parse_header(&path, &ParseOptions::default()).unwrap()
}
+ fn vocabulary(label: &str, body: &str) -> Vocabulary {
+ let path = header(label, body);
+ parse_vocabulary(&path, &ParseOptions::default()).unwrap()
+ }
+
+ const SIMPLIFIED_API: &str = r"
+#define PNG_IMAGE_VERSION 1
+#define PNG_FORMAT_RGBA 3
+typedef struct png_image {
+ void *opaque;
+ unsigned int version;
+ unsigned int width;
+ unsigned int height;
+ unsigned int format;
+} png_image;
+int png_image_begin_read_from_memory(png_image *image, const void *m, unsigned long s);
+";
+
+ #[test]
+ fn a_macro_is_collected_by_name() {
+ let vocab = vocabulary("macros", SIMPLIFIED_API);
+ assert!(vocab.macros.contains("PNG_IMAGE_VERSION"));
+ assert!(vocab.macros.contains("PNG_FORMAT_RGBA"));
+ }
+
+ #[test]
+ fn builtin_macros_are_not_collected() {
+ let vocab = vocabulary("builtins", SIMPLIFIED_API);
+ assert!(!vocab.macros.contains("__FILE__"));
+ assert!(!vocab.macros.contains("__LINE__"));
+ }
+
+ #[test]
+ fn a_record_is_keyed_the_same_way_a_pointee_is() {
+ let vocab = vocabulary("records", SIMPLIFIED_API);
+ let declared = parse("records_fn", SIMPLIFIED_API);
+ let param = &named(&declared, "png_image_begin_read_from_memory").params[0];
+ let Shape::Pointer {
+ pointee: Pointee::Record(record),
+ ..
+ } = &param.shape
+ else {
+ panic!("expected a pointer to a record");
+ };
+ assert!(
+ vocab.records.contains_key(record),
+ "vocabulary keys {:?} do not contain the pointee key {record}",
+ vocab.records.keys().collect::<Vec<_>>()
+ );
+ }
+
+ #[test]
+ fn record_fields_carry_names_and_shapes() {
+ let vocab = vocabulary("fields", SIMPLIFIED_API);
+ let fields = vocab.records.values().next().expect("one record");
+ let version = fields
+ .iter()
+ .find(|field| field.name == "version")
+ .expect("version field");
+ assert_eq!(version.shape, Shape::Integral);
+ }
+
+ #[test]
+ fn a_record_with_no_fields_is_not_recorded() {
+ let vocab = vocabulary(
+ "opaque",
+ "struct png_struct_def; void f(struct png_struct_def *p);",
+ );
+ assert!(vocab.records.is_empty());
+ }
+
+ #[test]
+ fn absorbing_keeps_the_first_definition_of_a_record() {
+ let mut left = Vocabulary::default();
+ left.records.insert(
+ "r".to_owned(),
+ vec![Field {
+ name: "a".to_owned(),
+ spelling: "int".to_owned(),
+ shape: Shape::Integral,
+ }],
+ );
+ let mut right = Vocabulary::default();
+ right.records.insert("r".to_owned(), Vec::new());
+ right.macros.insert("M".to_owned());
+ left.absorb(right);
+ assert_eq!(left.records["r"].len(), 1);
+ assert!(left.macros.contains("M"));
+ }
+
fn named<'a>(found: &'a [Declared], name: &str) -> &'a Declared {
found
.iter()
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml
index 27c23167..57c6c539 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml
@@ -23,4 +23,5 @@ lisdex-fuzz.workspace = true
lisdex-ingest.workspace = true
lisdex-build.workspace = true
lisdex-surface.workspace = true
+lisdex-harness.workspace = true
serde_json.workspace = true
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 c8dfc267..446073fe 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,9 +15,11 @@ 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::emit;
+use lisdex_harness::synth;
use lisdex_ingest::acquire::{self, Source};
use lisdex_ingest::detect;
-use lisdex_surface::extract::Language;
+use lisdex_surface::extract::{self, Language};
use lisdex_surface::surface::{self, SurfaceOptions};
const UNKNOWN_TARGET: &str = "unknown";
@@ -49,6 +51,8 @@ enum Command {
Fuzz(FuzzArgs),
#[command(about = "rank the parser entry points of a source tree")]
Surface(SurfaceArgs),
+ #[command(about = "synthesize a fuzz harness for a ranked entry point, with no LLM")]
+ Harness(HarnessArgs),
#[command(about = "list the crashes persisted for a campaign")]
Crashes(CrashesArgs),
}
@@ -115,6 +119,24 @@ struct CrashesArgs {
campaign: i64,
}
+#[derive(clap::Args)]
+struct HarnessArgs {
+ #[arg(help = "source tree of the target library")]
+ source: PathBuf,
+ #[arg(long, help = "install prefix from a previous build, if one exists")]
+ install: Option<PathBuf>,
+ #[arg(long = "include", help = "extra include directory, repeatable")]
+ includes: Vec<PathBuf>,
+ #[arg(long = "define", help = "extra preprocessor define, repeatable")]
+ defines: Vec<String>,
+ #[arg(long, help = "parse headers as C++ instead of C")]
+ cpp: bool,
+ #[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")]
+ out: PathBuf,
+}
+
#[derive(clap::Args)]
#[allow(clippy::struct_excessive_bools)]
struct SurfaceArgs {
@@ -156,10 +178,62 @@ fn dispatch() -> Result<(), Box<dyn Error>> {
Command::Build(args) => build(args),
Command::Fuzz(args) => fuzz(args),
Command::Surface(args) => surface(args),
+ Command::Harness(args) => harness(args),
Command::Crashes(args) => crashes(args),
}
}
+fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {
+ let mut options = SurfaceOptions::new(&args.source);
+ options.install.clone_from(&args.install);
+ options.includes.clone_from(&args.includes);
+ options.defines.clone_from(&args.defines);
+ options.language = if args.cpp { Language::Cpp } else { Language::C };
+ options.ignore_harnesses = true;
+
+ let analysis = surface::analyze(&options)?;
+ let mut refusals = Vec::new();
+
+ for candidate in analysis.ranking.candidates.iter().take(args.top) {
+ let root = candidate.header.parent().unwrap_or(&args.source);
+ let vocabulary =
+ extract::parse_vocabulary(&candidate.header, &options.parse_options(root))?;
+ let include = candidate.header.file_name().map_or_else(
+ || candidate.header.display().to_string(),
+ |name| name.to_string_lossy().into_owned(),
+ );
+ 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}");
+ }
+ return Ok(());
+ }
+ Err(refusal) => refusals.push(format!(" {} - {refusal}", candidate.name)),
+ }
+ }
+
+ println!("no candidate in the top {} could be planned:", args.top);
+ for line in refusals {
+ println!("{line}");
+ }
+ Err("no harness synthesized".into())
+}
+
fn surface(args: &SurfaceArgs) -> Result<(), Box<dyn Error>> {
let mut options = SurfaceOptions::new(&args.source);
options.install.clone_from(&args.install);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile b/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
index 29077eb7..6d3d2682 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/justfile
@@ -69,3 +69,9 @@ m3-gate:
m3-gate-reset:
docker compose -f dev.compose.yml exec toolchain bash scripts/m3-gate.sh reset
+
+m4-gate:
+ docker compose -f dev.compose.yml exec toolchain bash scripts/m4-gate.sh
+
+m4-gate-reset:
+ docker compose -f dev.compose.yml exec toolchain bash scripts/m4-gate.sh reset
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh
new file mode 100755
index 00000000..9bced85c
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m4-gate.sh
@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# ©AngelaMos | 2026
+# m4-gate.sh
+
+set -euo pipefail
+
+WORK="${MAGMA_WORK:-/opt/magma-work}"
+MAGMA="${MAGMA_ROOT:-/opt/magma}/magma"
+REPO="$WORK/libpng/repo"
+OUT_ROOT="$WORK/out/libpng"
+GATE="$WORK/m4"
+SYNTH="$GATE/synth"
+CORPUS="$GATE/corpus"
+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"
+
+FAILURES=0
+
+log() { printf '\n[m4] %s\n' "$1"; }
+die() { printf '\n[m4] FAIL: %s\n' "$1" >&2; exit 1; }
+pass() { printf ' PASS %s\n' "$1"; }
+fail() { printf ' FAIL %s\n' "$1"; FAILURES=$((FAILURES + 1)); }
+
+if [ "${1:-}" = "reset" ]; then
+ log "resetting $GATE"
+ rm -rf "$GATE"
+fi
+
+[ -d "$REPO" ] || die "magma libpng not fetched; run: just magma-libpng"
+[ -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"
+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"
+mkdir -p "$GATE"
+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)"
+[ -n "$ENTRY" ] || die "no harness was synthesized"
+ENTRY_NAME="$(basename "$ENTRY" .c)"
+pass "synthesized a harness for $ENTRY_NAME"
+
+if grep -q 'LLVMFuzzerTestOneInput' "$ENTRY"; then
+ pass "harness defines LLVMFuzzerTestOneInput"
+else
+ fail "harness does not define LLVMFuzzerTestOneInput"
+fi
+
+if grep -qE '^\s*int\s+main\s*\(' "$ENTRY"; then
+ fail "harness defines its own main - it would silently shadow the AFL driver"
+else
+ pass "harness defines no main (the driver's weak main is not shadowed)"
+fi
+
+build_harness() {
+ SRC="$1"; BIN="$2"; LIB="$3"; EXTRA="${4:-}"
+ (
+ cd "$REPO"
+ env AFL_USE_ASAN=1 AFL_USE_UBSAN=1 AFL_QUIET=1 ${EXTRA:+AFL_LLVM_CMPLOG=1} \
+ afl-clang-lto $CFLAGS_CANARY -I. "$SRC" -o "$BIN" \
+ "$OUT_ROOT/$LIB/libpng16.a" -L"$OUT_ROOT/$LIB" -l:magma.o -lrt "$DRIVER" -lz -g
+ )
+}
+
+log "stage 3/7: ORACLE 1 - it compiles"
+if build_harness "$ENTRY" "$GATE/harness" afl 2>"$GATE/compile.log"; then
+ pass "synthesized harness compiles and links"
+else
+ tail -5 "$GATE/compile.log" >&2
+ die "synthesized harness does not compile"
+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
+ CLEAN=$((CLEAN + 1))
+ else
+ CRASHED=$((CRASHED + 1))
+ fi
+done
+if [ "$CRASHED" -eq 0 ]; then
+ pass "$CLEAN/$SEEDS valid seeds run clean"
+else
+ fail "$CRASHED/$SEEDS valid seeds crash - 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)"
+else
+ fail "accepted harness diverges by only $LIVE_DIV edges - it is not reading its input"
+fi
+
+log "stage 5b/7: NEGATIVE CONTROL - a stub harness must be REJECTED"
+cat > "$GATE/stub.c" <<'STUB'
+// ©AngelaMos | 2026
+// stub.c
+
+#include <stddef.h>
+#include <stdint.h>
+
+#include "png.h"
+
+int LLVMFuzzerTestOneInput(const uint8_t *data, size_t size)
+{
+ (void)data;
+ (void)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"
+else
+ fail "stub harness diverges by $STUB_DIV edges - the coverage oracle cannot detect a stub"
+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
+ else
+ fail "the unpopulated variant does not compile - the control is vacuous"
+ fi
+else
+ printf ' SKIP this entry point has no struct-population variant\n'
+fi
+
+log "stage 6/7: lisdex drives a campaign against the SYNTHESIZED harness"
+rm -rf "$FINDINGS" "$DB"
+"$LISDEX_BIN" fuzz \
+ --target "$GATE/harness" \
+ --cmplog "$GATE/harness_cmplog" \
+ --seeds "$CORPUS" \
+ --findings "$FINDINGS" \
+ --db "$DB" \
+ --duration "$GATE_DURATION" \
+ --until-crash \
+ --label m4-synthesized | tee "$GATE/fuzz.log"
+
+log "stage 7/7: assert the synthesized harness re-found a magma bug"
+[ -f "$DB" ] || die "no database was created at $DB"
+CRASH_ROWS="$(sqlite3 "$DB" 'SELECT COUNT(*) FROM crashes;')"
+if [ "${CRASH_ROWS:-0}" -ge 1 ]; then
+ pass "crashes persisted: $CRASH_ROWS"
+else
+ fail "the synthesized harness found no crash in ${GATE_DURATION}s"
+fi
+
+REPORT="$(sqlite3 "$DB" 'SELECT sanitizer_report FROM crashes WHERE id = (SELECT MIN(id) FROM crashes);')"
+CANARY_LOC="$(printf '%s\n' "$REPORT" | grep -A1 'in magma_log' | tail -1 \
+ | grep -oE '/[^ ]+\.c:[0-9]+' | head -1 || true)"
+if [ -n "$CANARY_LOC" ]; then
+ CANARY_FILE="${CANARY_LOC%:*}"
+ CANARY_LINE="${CANARY_LOC##*:}"
+ BUG_ID="$(awk -v n="$CANARY_LINE" 'NR == n' "$CANARY_FILE" 2>/dev/null \
+ | grep -oE "MAGMA_LOG\(\"${CANARY_PREFIX}[0-9]+\"" | grep -oE "${CANARY_PREFIX}[0-9]+" | head -1 || true)"
+ if [ -n "$BUG_ID" ]; then
+ pass "SYNTHESIZED harness re-found magma bug $BUG_ID at $CANARY_LOC"
+ else
+ fail "canary at $CANARY_LOC did not resolve to a $CANARY_PREFIX bug id"
+ fi
+else
+ fail "crash is not an attributable magma canary trigger"
+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'
+ exit 0
+fi
+printf '[m4] M4 EXIT GATE FAILED: %d assertion(s)\n' "$FAILURES"
+exit 1