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 πŸ‘‡

fix(lisdex): B68 - the validation set is 10 libraries, and one empty header hid a whole API

CarterPerez-dev97c470644eb4
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
index eee684b8..5791a3e1 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/headers.rs
@@ -317,19 +317,31 @@ pub fn project_of(source: &Path) -> String {
.unwrap_or_default()
}
-pub fn discover(source: &Path, install: Option<&Path>) -> Result<HeaderSet, HeaderError> {
+// B68. Every candidate header root, most authoritative first, rather than the first one that
+// holds a file. Discovery cannot tell whether a header DECLARES anything without parsing it,
+// and one that declares nothing is not a surface - libtiff ships an `placeholder.h` at its
+// root whose entire contents are "This file is intentionally empty", put there so pre-3.11
+// CMake would accept an `add_library()` call. It has no `include/` directory and its public
+// headers live in `libtiff/`, so the shallow-root rule matched that one empty file and made it
+// the whole header set, and the library read as having no API at all.
+//
+// The caller parses each in turn and stops at the first that yields a declaration, so a tree
+// that works today is unaffected by construction: its first candidate already declares
+// something and no later one is ever reached.
+pub fn candidates(source: &Path, install: Option<&Path>) -> Result<Vec<HeaderSet>, HeaderError> {
if !source.is_dir() {
return Err(HeaderError::NotADirectory(source.to_path_buf()));
}
let project = project_of(source);
+ let mut found = Vec::new();
if let Some(install) = install
&& install.is_dir()
{
let headers = gathered(install, &project)?;
if !headers.is_empty() {
- return Ok(HeaderSet {
+ found.push(HeaderSet {
root: install.to_path_buf(),
origin: HeaderOrigin::Installed,
headers,
@@ -341,7 +353,7 @@ pub fn discover(source: &Path, install: Option<&Path>) -> Result<HeaderSet, Head
if include.is_dir() {
let headers = gathered(&include, &project)?;
if !headers.is_empty() {
- return Ok(HeaderSet {
+ found.push(HeaderSet {
root: include,
origin: HeaderOrigin::IncludeDir,
headers,
@@ -352,7 +364,7 @@ pub fn discover(source: &Path, install: Option<&Path>) -> Result<HeaderSet, Head
if let Some(nested) = nested_include_root(source, &project, 0) {
let headers = gathered(&nested, &project)?;
if !headers.is_empty() {
- return Ok(HeaderSet {
+ found.push(HeaderSet {
root: nested,
origin: HeaderOrigin::IncludeDir,
headers,
@@ -360,25 +372,33 @@ pub fn discover(source: &Path, install: Option<&Path>) -> Result<HeaderSet, Head
}
}
- let mut headers = collect_shallow(source)?;
- headers.sort();
- if !headers.is_empty() {
- return Ok(HeaderSet {
+ let mut shallow = collect_shallow(source)?;
+ shallow.sort();
+ if !shallow.is_empty() {
+ found.push(HeaderSet {
root: source.to_path_buf(),
origin: HeaderOrigin::SourceRoot,
- headers,
+ headers: shallow,
});
}
let headers = gathered(source, &project)?;
- if headers.is_empty() {
+ if !headers.is_empty() {
+ found.push(HeaderSet {
+ root: source.to_path_buf(),
+ origin: HeaderOrigin::Tree,
+ headers,
+ });
+ }
+
+ if found.is_empty() {
return Err(HeaderError::NoHeaders(source.to_path_buf()));
}
- Ok(HeaderSet {
- root: source.to_path_buf(),
- origin: HeaderOrigin::Tree,
- headers,
- })
+ Ok(found)
+}
+
+pub fn discover(source: &Path, install: Option<&Path>) -> Result<HeaderSet, HeaderError> {
+ candidates(source, install).map(|mut found| found.remove(0))
}
#[cfg(test)]
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-surface/src/surface.rs
index 51c4f663..1e2515a9 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
@@ -26,7 +26,8 @@ pub enum SurfaceError {
#[error(
"no header under {root} yielded a declaration; {refused} of {total} were refused. \
first refusal: {first}. if this project generates a config header at build time, \
- run `lisdex build` and pass its install prefix with --install"
+ run `lisdex build` and pass the build directory it reports with --include \
+ (the generated header is written into the build tree, not installed anywhere)"
)]
NothingDeclared {
root: PathBuf,
@@ -37,8 +38,9 @@ pub enum SurfaceError {
#[error(
"{refused} of {total} headers under {root} were refused, so the {declared} declaration(s) \
that did parse are not a usable surface. first refusal: {first}. if this project \
- generates a config header at build time, run `lisdex build` and pass its install \
- prefix with --install"
+ generates a config header at build time, run `lisdex build` and pass the build \
+ directory it reports with --include (the generated header is written into the build \
+ tree, not installed anywhere)"
)]
MostlyRefused {
root: PathBuf,
@@ -50,8 +52,8 @@ pub enum SurfaceError {
#[error(
"{count} file(s) under {root} resolved a header this library owns to a copy outside the \
source tree, so this ranking would describe a different build of the library. first: \
- {first}. build the target and pass its install prefix with --install, or drop the stray \
- copy off the include path"
+ {first}. build the target and pass the build directory it reports with --include, or \
+ drop the stray copy off the include path"
)]
ForeignEnvironment {
root: PathBuf,
@@ -240,26 +242,50 @@ fn read_sources(
}
pub fn analyze(options: &SurfaceOptions) -> Result<Surface, SurfaceError> {
- let set = headers::discover(&options.source, options.install.as_deref())?;
- // Headers the build would generate count as this tree's own for the ownership test, even
- // though no such file exists to parse yet. They are appended AFTER header discovery so
- // nothing tries to read them.
- let mut owned = set.headers.clone();
- owned.extend(headers::generated_headers(&options.source));
+ let roots = headers::candidates(&options.source, options.install.as_deref())?;
let harnesses = harness::discover(&options.source)?;
- let (declared, skipped) = read_headers(&set, options, &owned);
- refuse_foreign(&set.root, &skipped)?;
- if declared.is_empty() {
- return Err(SurfaceError::NothingDeclared {
- root: set.root.clone(),
- refused: skipped.len(),
- total: set.headers.len(),
- first: skipped
- .first()
- .map_or_else(|| "none recorded".to_owned(), |item| item.reason.clone()),
- });
+ // B68. A header root that declares NOTHING is not this library's surface, and discovery
+ // cannot know that without parsing. libtiff's root holds one intentionally-empty
+ // `placeholder.h` - present so pre-3.11 CMake would accept `add_library()` - and no
+ // `include/` directory, so the shallow-root rule chose that single file and the library
+ // read as having no API. Parsing the next candidate finds the real headers under
+ // `libtiff/`. A tree that already works never reaches this loop's second turn, because its
+ // first candidate declares something.
+ //
+ // The foreign-header refusal is NOT retried past: a stray copy of a header the library owns
+ // means the ranking would describe a different build, and that is true of every root in the
+ // tree rather than an accident of which one was chosen.
+ let mut chosen = None;
+ let mut first_failure = None;
+ for set in roots {
+ let mut owned = set.headers.clone();
+ owned.extend(headers::generated_headers(&options.source));
+ let (declared, skipped) = read_headers(&set, options, &owned);
+ refuse_foreign(&set.root, &skipped)?;
+ if !declared.is_empty() {
+ chosen = Some((set, declared, skipped, owned));
+ break;
+ }
+ if first_failure.is_none() {
+ first_failure = Some(SurfaceError::NothingDeclared {
+ root: set.root.clone(),
+ refused: skipped.len(),
+ total: set.headers.len(),
+ first: skipped
+ .first()
+ .map_or_else(|| "none recorded".to_owned(), |item| item.reason.clone()),
+ });
+ }
}
+ let Some((set, declared, skipped, owned)) = chosen else {
+ return Err(first_failure.unwrap_or(SurfaceError::NothingDeclared {
+ root: options.source.clone(),
+ refused: 0,
+ total: 0,
+ first: "none recorded".to_owned(),
+ }));
+ };
if skipped.len() * REFUSAL_DENOMINATOR > set.headers.len() * REFUSAL_NUMERATOR
&& declared.len() < MIN_PLAUSIBLE_SURFACE
{
@@ -496,6 +522,121 @@ void ctx_set_read(struct ctx *c, void *user, read_fn fn) { (void)c; (void)user;
assert!(analyze(&SurfaceOptions::new(&root)).is_err());
}
+ // B68, and this is libtiff exactly. It ships `placeholder.h` at its root - contents
+ // "This file is intentionally empty", present so pre-3.11 CMake would accept an
+ // `add_library()` call - and has no `include/` directory, so the shallow-root rule chose
+ // that one file and the library read as having NO API AT ALL. 0 declarations from a
+ // 200-declaration library.
+ #[test]
+ fn a_root_header_that_declares_nothing_does_not_become_the_whole_surface() {
+ let root = tree(
+ "placeholder",
+ &[
+ ("placeholder.h", "/* intentionally empty */\n"),
+ ("placeholder/lib.h", HEADER),
+ ("placeholder/lib.c", SOURCE),
+ ],
+ );
+ let surface = analyze(&SurfaceOptions::new(&root)).unwrap();
+ assert!(
+ surface.declared >= 4,
+ "the real headers were never reached: {} declared",
+ surface.declared
+ );
+ }
+
+ // The isolating control. A root header that DOES declare something is still the surface,
+ // and the fallback never runs - otherwise "try the next candidate" would quietly become
+ // "scan the whole tree", which is a different and much noisier answer.
+ //
+ // The deeper header sits in `internal/` rather than `vendor/`, and that is the whole
+ // control: `vendor` is in EXCLUDED_DIRS, so a first version of this test put its marker
+ // somewhere the tree walk never looks and the assertion could not fire under any gut.
+ // Both roots also report the SOURCE as `header_root`, so only the CONTENT distinguishes
+ // them.
+ #[test]
+ fn a_root_header_that_declares_something_is_still_the_surface() {
+ let root = tree(
+ "shallowwins",
+ &[
+ ("lib.h", HEADER),
+ ("lib.c", SOURCE),
+ (
+ "internal/other.h",
+ "int deeper_only_symbol(void *p, unsigned long n);\n",
+ ),
+ ],
+ );
+ let surface = analyze(&SurfaceOptions::new(&root)).unwrap();
+ assert_eq!(surface.header_root, root);
+ let seen = surface
+ .ranking
+ .candidates
+ .iter()
+ .map(|item| item.name.as_str())
+ .chain(
+ surface
+ .ranking
+ .excluded
+ .iter()
+ .map(|item| item.name.as_str()),
+ )
+ .any(|name| name == "deeper_only_symbol");
+ assert!(
+ !seen,
+ "the fallback ran when the shallow root already had a surface"
+ );
+ }
+
+ // B68. The advice these two errors carry pointed at `--install` and "its install prefix"
+ // for as long as they existed, and `lisdex build` produces NO install prefix - the ladder
+ // never runs an install step, so `install_dir` is referenced by nothing but its own test.
+ // The remedy named a thing the tool cannot produce. The generated header is written into
+ // the BUILD tree, and `--include` is the flag that reads it.
+ #[test]
+ fn the_config_header_advice_names_a_flag_that_does_something() {
+ let errors = [
+ SurfaceError::NothingDeclared {
+ root: PathBuf::from("/src"),
+ refused: 0,
+ total: 1,
+ first: "none recorded".to_owned(),
+ },
+ SurfaceError::MostlyRefused {
+ root: PathBuf::from("/src"),
+ refused: 7,
+ total: 11,
+ declared: 6,
+ first: "'tiffconf.h' file not found".to_owned(),
+ },
+ ];
+ for error in errors {
+ let text = error.to_string();
+ assert!(text.contains("--include"), "no usable remedy: {text}");
+ assert!(
+ !text.contains("install prefix"),
+ "advice names a prefix `lisdex build` never produces: {text}"
+ );
+ }
+ }
+
+ // A tree where NO candidate declares anything still fails, and fails naming the first root
+ // tried rather than the last - the first is the one the user can act on.
+ #[test]
+ fn a_tree_where_no_candidate_declares_anything_is_still_an_error() {
+ let root = tree(
+ "allempty",
+ &[
+ ("placeholder.h", "/* nothing */\n"),
+ ("sub/also_empty.h", "/* nothing here either */\n"),
+ ],
+ );
+ assert!(matches!(
+ analyze(&SurfaceOptions::new(&root)).unwrap_err(),
+ SurfaceError::NothingDeclared { .. }
+ ));
+ }
+
#[test]
fn fuzz_and_test_directories_are_not_mined_for_complexity() {
let root = fixture("nofuzzsrc", &[]);
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh
index 9216fbba..fac5960e 100755
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/scripts/m3-gate.sh
@@ -177,11 +177,17 @@ banner "1b. targets needing a build-generated config header say so, loudly"
# libtiff needs tiffconf.h and openjpeg needs opj_config.h, both produced by
# their build. Analysing without one must fail with an actionable diagnosis
# rather than silently reporting an empty or partial surface.
+#
+# B68. This asserted the message named `--install`, and `lisdex build` produces NO install
+# prefix - the ladder never runs an install step, so the remedy named a thing the tool cannot
+# make. The generated header is written into the BUILD tree and `--include` is what reads it,
+# so the assertion is now the flag that works AND the absence of the one that never did.
for target in libtiff openjpeg; do
if analyse "$target"; then
bad "$target unexpectedly succeeded with no build; the gate assumption is stale"
- elif grep -q -- "--install" "$OUT/$target.err"; then
- ok "$target refused with an actionable diagnosis naming --install"
+ elif grep -q -- "--include" "$OUT/$target.err" \
+ && ! grep -q -- "install prefix" "$OUT/$target.err"; then
+ ok "$target refused with a diagnosis naming --include, a flag that resolves it"
else
bad "$target failed without telling the user what to do: $(head -1 "$OUT/$target.err")"
fi