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): B27 - rank against the symbols a library really defines, and refuse a library that is not the same build

CarterPerez-dev4341d1763ad9
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/verify.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/verify.rs
index a7753fcf..5bb5939e 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/verify.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-build/src/verify.rs
@@ -1,6 +1,7 @@
// ©AngelaMos | 2026
// verify.rs
+use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use std::time::Duration;
@@ -20,6 +21,9 @@ const PATTERN_MAGMA: &str = "magma_log";
const MEMBER_HEADER_SUFFIX: char = ':';
const ARG_NO_SORT: &str = "--no-sort";
+const ARG_DEFINED_ONLY: &str = "--defined-only";
+const TEXT_SYMBOL_TYPES: [&str; 2] = ["T", "W"];
+const SYMBOL_FIELDS: usize = 2;
#[derive(Debug, thiserror::Error)]
pub enum VerifyError {
@@ -221,6 +225,54 @@ pub fn scan_listing(
Ok(scan_symbols(output))
}
+#[must_use]
+pub fn defined_spec(path: &Path) -> CommandSpec {
+ CommandSpec::new(LLVM_NM)
+ .arg(ARG_NO_SORT)
+ .arg(ARG_DEFINED_ONLY)
+ .path_arg(path)
+}
+
+#[must_use]
+pub fn scan_defined_functions(text: &str) -> BTreeSet<String> {
+ let mut found = BTreeSet::new();
+ for line in text.lines() {
+ let trimmed = line.trim_end();
+ if trimmed.ends_with(MEMBER_HEADER_SUFFIX) {
+ continue;
+ }
+ let fields: Vec<&str> = trimmed.split_whitespace().collect();
+ if fields.len() < SYMBOL_FIELDS {
+ continue;
+ }
+ let kind = fields[fields.len() - SYMBOL_FIELDS];
+ let name = fields[fields.len() - 1];
+ if TEXT_SYMBOL_TYPES.contains(&kind) {
+ found.insert(name.to_owned());
+ }
+ }
+ found
+}
+
+pub fn defined_functions(path: &Path) -> Result<BTreeSet<String>, VerifyError> {
+ let execution = process::run(&defined_spec(path), Duration::from_secs(NM_TIMEOUT_SECS))?;
+ if !execution.success {
+ return Err(VerifyError::Unreadable {
+ nm: LLVM_NM.to_owned(),
+ path: path.to_path_buf(),
+ output: execution.tail(10),
+ });
+ }
+ if execution.truncated {
+ return Err(VerifyError::Truncated {
+ nm: LLVM_NM.to_owned(),
+ path: path.to_path_buf(),
+ captured: process::MAX_CAPTURED_BYTES,
+ });
+ }
+ Ok(scan_defined_functions(&execution.output))
+}
+
pub fn inspect(path: &Path) -> Result<SymbolCounts, VerifyError> {
let execution = process::run(&nm_spec(path), Duration::from_secs(NM_TIMEOUT_SECS))?;
scan_listing(
@@ -273,6 +325,17 @@ libpng16.a[pngread.o]:
U __afl_area_ptr
";
+ const NM_DEFINED: &str = "\
+adler32.c.o:
+---------------- T adler32_z
+ U __ubsan_handle_type_mismatch_v1_abort
+---------------- T adler32
+---------------- t asan.module_ctor
+---------------- d __unnamed_1
+0000000000000000 W inflateResetKeep
+0000000000000000 D z_errmsg
+";
+
const NM_RUNTIME_INTERNALS: &str = "\
00000000001c6370 t _Z19ubsan_GetStackTracePN11__sanitizer18BufferedStackTraceEmmmPvb
0000000000ea0870 b _ZL13ubsan_init_mu
@@ -350,6 +413,36 @@ asan_shim.o:
assert_eq!(counts.afl, 1);
}
+ #[test]
+ fn only_globally_defined_text_symbols_count_as_library_functions() {
+ let defined = scan_defined_functions(NM_DEFINED);
+ assert!(defined.contains("adler32"));
+ assert!(defined.contains("adler32_z"));
+ assert!(
+ defined.contains("inflateResetKeep"),
+ "a weak text symbol is still a definition the linker resolves"
+ );
+ assert!(
+ !defined.contains("asan.module_ctor"),
+ "a lowercase t is file-local: static helpers are not the library's surface"
+ );
+ assert!(
+ !defined.contains("__ubsan_handle_type_mismatch_v1_abort"),
+ "an undefined symbol is imported, not defined here"
+ );
+ assert!(
+ !defined.contains("z_errmsg"),
+ "D is data, not a callable entry point"
+ );
+ assert!(!defined.contains("__unnamed_1"));
+ }
+
+ #[test]
+ fn an_archive_member_header_is_never_read_as_a_defined_function() {
+ let defined = scan_defined_functions(NM_ARCHIVE);
+ assert_eq!(defined, ["png_get_io_ptr".to_owned()].into_iter().collect());
+ }
+
#[test]
fn empty_output_is_empty_counts() {
assert!(scan_symbols("").is_empty());
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 b79a54e9..23ea4bb5 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
@@ -60,6 +60,15 @@ pub enum SurfaceError {
count: usize,
first: String,
},
+ #[error(
+ "not one of the {declared} function(s) these headers declare appears among the {symbols} \
+ text symbol(s) the given library defines, so the two do not describe the same build and \
+ every entry point would be reported as internal. the usual causes are a library from a \
+ different project, a build that renames symbols (a Magma target prefixes every one with \
+ MAGMA_), and a C++ library whose symbols are mangled. pass the matching library or drop \
+ --library to rank on the headers alone"
+ )]
+ LibraryMismatch { declared: usize, symbols: usize },
}
#[derive(Debug, Clone)]
@@ -72,6 +81,7 @@ pub struct SurfaceOptions {
pub weights: Weights,
pub ignore_harnesses: bool,
pub oss_fuzz: Option<PathBuf>,
+ pub library_symbols: Option<BTreeSet<String>>,
}
impl SurfaceOptions {
@@ -86,6 +96,7 @@ impl SurfaceOptions {
weights: Weights::default(),
ignore_harnesses: true,
oss_fuzz: None,
+ library_symbols: None,
}
}
@@ -161,10 +172,32 @@ pub fn library_sources(root: &Path) -> Vec<PathBuf> {
found
}
-// A foreign include is a statement about the ENVIRONMENT, not about one header, so it can
-// never be one line in a skip list. Measured: a single foreign header in libwebp dropped the
-// surface 429 -> 183 declarations, replaced the top entry point with an encoder function, and
-// still exited 0 under the old per-header handling.
+fn refuse_library_mismatch(
+ declared: &[Declared],
+ library: Option<&BTreeSet<String>>,
+) -> Result<(), SurfaceError> {
+ let Some(symbols) = library else {
+ return Ok(());
+ };
+ if symbols.is_empty()
+ || declared.is_empty()
+ || declared.iter().any(|item| symbols.contains(&item.name))
+ {
+ return Ok(());
+ }
+ Err(SurfaceError::LibraryMismatch {
+ declared: declared.len(),
+ symbols: symbols.len(),
+ })
+}
+
+fn exported_by(name: &str, graph: &CallGraph, library: Option<&BTreeSet<String>>) -> bool {
+ library.map_or_else(
+ || graph.get(name).is_none_or(|node| node.exported),
+ |symbols| symbols.contains(name),
+ )
+}
+
fn skipped_by(header: &Path, error: &extract::ExtractError) -> SkippedHeader {
SkippedHeader {
header: header.to_path_buf(),
@@ -175,6 +208,10 @@ fn skipped_by(header: &Path, error: &extract::ExtractError) -> SkippedHeader {
}
}
+// A foreign include is a statement about the ENVIRONMENT, not about one header, so it can
+// never be one line in a skip list. Measured: a single foreign header in libwebp dropped the
+// surface 429 -> 183 declarations, replaced the top entry point with an encoder function, and
+// still exited 0 under the old per-header handling.
fn refuse_foreign(root: &Path, skipped: &[SkippedHeader]) -> Result<(), SurfaceError> {
let foreign: Vec<&SkippedHeader> = skipped.iter().filter(|item| item.foreign).collect();
match foreign.first() {
@@ -323,6 +360,9 @@ pub fn analyze(options: &SurfaceOptions) -> Result<Surface, SurfaceError> {
let reached = graph.reachable_from(&seeds);
let directly_called: BTreeSet<String> = seeds.into_iter().collect();
+ let library = options.library_symbols.as_ref();
+ refuse_library_mismatch(&declared, library)?;
+
let functions: Vec<Function> = declared
.iter()
.map(|item| Function {
@@ -331,7 +371,7 @@ pub fn analyze(options: &SurfaceOptions) -> Result<Surface, SurfaceError> {
result: item.result.clone(),
header: item.header.clone(),
line: item.line,
- exported: graph.get(&item.name).is_none_or(|node| node.exported),
+ exported: exported_by(&item.name, &graph, library),
complexity: Complexity {
own: graph.danger(&item.name),
accumulated: graph.accumulated_danger(&item.name),
@@ -411,6 +451,65 @@ void ctx_set_read(struct ctx *c, void *user, read_fn fn) { (void)c; (void)user;
tree(label, &files)
}
+ #[test]
+ fn a_built_library_decides_which_declared_functions_are_really_exported() {
+ let root = fixture("intersection", &[]);
+ let exported_of = |surface: &Surface, name: &str| {
+ surface
+ .ranking
+ .candidates
+ .iter()
+ .find(|candidate| candidate.name == name)
+ .map(|candidate| (candidate.exported, candidate.score))
+ };
+
+ let headers_only = analyze(&SurfaceOptions::new(&root)).unwrap();
+ let (reader_alone, _) = exported_of(&headers_only, "ctx_read_header").unwrap();
+ let (compare_alone, compare_score_alone) =
+ exported_of(&headers_only, "quick_sig_cmp").unwrap();
+ assert!(reader_alone && compare_alone, "headers alone trust both");
+
+ let mut options = SurfaceOptions::new(&root);
+ options.library_symbols = Some(
+ ["ctx_read_header".to_owned(), "ctx_set_read".to_owned()]
+ .into_iter()
+ .collect(),
+ );
+ let intersected = analyze(&options).unwrap();
+ let (reader, _) = exported_of(&intersected, "ctx_read_header").unwrap();
+ let (compare, compare_score) = exported_of(&intersected, "quick_sig_cmp").unwrap();
+
+ assert!(reader, "a name the library defines stays exported");
+ assert!(
+ !compare,
+ "a header-declared name absent from the library is not part of F_lib"
+ );
+ assert!(
+ compare_score < compare_score_alone,
+ "losing export status must cost score: {compare_score} vs {compare_score_alone}"
+ );
+ }
+
+ #[test]
+ fn a_library_that_shares_no_name_with_the_headers_is_refused_not_believed() {
+ let root = fixture("mismatch", &[]);
+ let mut options = SurfaceOptions::new(&root);
+ options.library_symbols = Some(
+ [
+ "MAGMA_ctx_read_header".to_owned(),
+ "MAGMA_ctx_set_read".to_owned(),
+ ]
+ .into_iter()
+ .collect(),
+ );
+ let refused = analyze(&options);
+ assert!(
+ matches!(refused, Err(SurfaceError::LibraryMismatch { .. })),
+ "a prefixed build shares no bare name, so reporting every entry point internal \
+ would be a silent false negative: {refused:?}"
+ );
+ }
+
#[test]
fn a_context_only_reader_outranks_a_trivial_buffer_comparator() {
let root = fixture("ranked", &[]);
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 c028d466..db5bb740 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
@@ -553,6 +553,11 @@ struct HarnessArgs {
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 = "library",
+ help = "built .a or .so of this target, repeatable; restricts entry points to the functions the library actually defines instead of trusting the headers alone"
+ )]
+ libraries: Vec<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")]
@@ -594,6 +599,11 @@ struct SurfaceArgs {
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 = "library",
+ help = "built .a or .so of this target, repeatable; restricts entry points to the functions the library actually defines instead of trusting the headers alone"
+ )]
+ libraries: Vec<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")]
@@ -714,6 +724,19 @@ fn library_vocabulary(
merged
}
+fn library_symbols(
+ libraries: &[PathBuf],
+) -> Result<Option<std::collections::BTreeSet<String>>, Box<dyn Error>> {
+ if libraries.is_empty() {
+ return Ok(None);
+ }
+ let mut symbols = std::collections::BTreeSet::new();
+ for library in libraries {
+ symbols.extend(verify::defined_functions(library)?);
+ }
+ Ok(Some(symbols))
+}
+
fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {
let mut options = SurfaceOptions::new(&args.source);
options.install.clone_from(&args.install);
@@ -722,6 +745,7 @@ fn harness(args: &HarnessArgs) -> Result<(), Box<dyn Error>> {
options.language = if args.cpp { Language::Cpp } else { Language::C };
options.ignore_harnesses = true;
options.oss_fuzz.clone_from(&args.oss_fuzz);
+ options.library_symbols = library_symbols(&args.libraries)?;
let analysis = surface::analyze(&options)?;
report_ladder(&analysis.ladder);
@@ -1129,6 +1153,7 @@ fn surface(args: &SurfaceArgs) -> Result<(), Box<dyn Error>> {
options.language = if args.cpp { Language::Cpp } else { Language::C };
options.ignore_harnesses = !args.frontier;
options.oss_fuzz.clone_from(&args.oss_fuzz);
+ options.library_symbols = library_symbols(&args.libraries)?;
let analysis = surface::analyze(&options)?;