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): M8.1 - renderers that follow OpenSSF's template, and a version field left null on purpose

CarterPerez-devfe121cbe7aa6
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
index d0afc165..66c1eefe 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/Cargo.lock
@@ -689,6 +689,7 @@ dependencies = [
"lisdex-harness",
"lisdex-ingest",
"lisdex-llm",
+ "lisdex-report",
"lisdex-surface",
"lisdex-triage",
"serde_json",
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/json.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/json.rs
new file mode 100644
index 00000000..5d4ad1c1
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/json.rs
@@ -0,0 +1,70 @@
+// ©AngelaMos | 2026
+// json.rs
+
+use serde_json::{Value, json};
+
+use crate::advisory::{Advisory, OPERATOR_INPUTS, Provenance};
+
+pub const GHSA_ECOSYSTEM_FOR_C_LIBRARIES: &str = "other";
+
+const DECLINED_REASON: &str = "reason";
+const DECLINED_FIELD: &str = "field";
+
+fn declined() -> Value {
+ Value::Array(
+ OPERATOR_INPUTS
+ .iter()
+ .map(|input| {
+ json!({
+ DECLINED_FIELD: input.field(),
+ DECLINED_REASON: input.why(),
+ })
+ })
+ .collect(),
+ )
+}
+
+fn weakness(advisory: &Advisory) -> Value {
+ advisory.weakness().map_or(
+ Value::Null,
+ |weakness| json!({ "cwe_id": weakness.id, "name": weakness.name }),
+ )
+}
+
+#[must_use]
+pub fn render(advisory: &Advisory) -> Value {
+ json!({
+ "target": advisory.target(),
+ "dedup_key": advisory.key(),
+ "class": advisory.class(),
+ "severity": advisory.severity().as_str(),
+ "severity_is_assessed": advisory.severity_is_assessed(),
+ "security_relevant": advisory.is_security_relevant(),
+ "weakness": weakness(advisory),
+ "crash_site": advisory.crash_site(),
+ "frames": advisory.frames(),
+ "crash_count": advisory.crash_count(),
+ "reproducer_bytes": advisory.reproducer_bytes(),
+ "disclosable": advisory.is_disclosable(),
+ "provenance": match advisory.provenance() {
+ Provenance::Field => "field",
+ Provenance::SyntheticBenchmark => "synthetic_benchmark",
+ },
+ "sanitizer_report": advisory.sanitizer_report(),
+ "declined": declined(),
+ "ghsa": {
+ "ecosystem": GHSA_ECOSYSTEM_FOR_C_LIBRARIES,
+ "package_name": advisory.target(),
+ "vulnerable_version_range": Value::Null,
+ "patched_versions": Value::Null,
+ "cvss_vector_string": Value::Null,
+ "cve_id": Value::Null,
+ },
+ })
+}
+
+#[must_use]
+pub fn render_string(advisory: &Advisory) -> String {
+ serde_json::to_string_pretty(&render(advisory))
+ .expect("a serde_json::Value built from owned strings and numbers always serializes")
+}
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/lib.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/lib.rs
index 64ffa815..ef8f33cb 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/lib.rs
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/lib.rs
@@ -2,4 +2,6 @@
// lib.rs
pub mod advisory;
+pub mod json;
+pub mod markdown;
pub mod weakness;
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/markdown.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/markdown.rs
new file mode 100644
index 00000000..f6d500fb
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/src/markdown.rs
@@ -0,0 +1,252 @@
+// ©AngelaMos | 2026
+// markdown.rs
+
+use std::fmt::Write;
+
+use lisdex_triage::severity::Severity;
+
+use crate::advisory::{Advisory, OperatorInput, Provenance};
+
+const NOT_ESTABLISHED: &str = "NOT ESTABLISHED";
+const OPERATOR_SUPPLIES: &str = "_(you supply this)_";
+const NOT_ASSIGNED: &str = "not assigned; see \"Filing this advisory\" below";
+const UNNAMED_SITE: &str = "an unresolved frame";
+
+const PROVENANCE_BANNER: &str = "> **DO NOT FILE THIS ADVISORY.** The crash it describes carries \
+ benchmark instrumentation in its call stack, which means it was found in a research build \
+ containing deliberately planted bugs rather than in the library as its maintainers ship it. \
+ Filing it would report a fabricated vulnerability against real, widely deployed software. \
+ lisdex renders it so the run can be audited, not so it can be sent.";
+
+const DRAFTED_BY: &str = "_Drafted by lisdex from one fuzzing campaign. Every heading below that \
+ reads NOT ESTABLISHED is a field lisdex declines to fill rather than guess, and each states \
+ why. Fill them in or delete them before sending this to anyone._";
+
+const SUMMARY_HEADING: &str = "## Summary";
+const CVE_HEADING: &str = "### CVE";
+const VERSIONS_HEADING: &str = "### Affected versions";
+const REPORTER_HEADING: &str = "### Reporter";
+const SEVERITY_HEADING: &str = "## Severity";
+const POC_HEADING: &str = "## Proof of Concept";
+const REMEDIATION_HEADING: &str = "## Remediation and Mitigation";
+const ANALYSIS_HEADING: &str = "## Further Analysis";
+const TIMELINE_HEADING: &str = "## Timeline";
+const FILING_HEADING: &str = "## Filing this advisory";
+
+const REMEDIATION_BODY: &str = "NOT ESTABLISHED. lisdex observes a crash; it does not read the \
+ surrounding code to work out which bounds check is missing, and a patch it guessed at would \
+ be a patch nobody tested. The maintainer is better placed to write the fix than the tool that \
+ found the fault.";
+
+const TIMELINE_BODY: &str = "**Date reported**:\n\n**Date fixed**:\n\n**Date disclosed**:";
+
+const DISCLOSURE_NOTE: &str = "The community norm is 90 days from private notification to \
+ publication, and Google Project Zero's 90+30 policy adds 30 days after a patch ships before \
+ technical detail goes public. Project Zero additionally began a trial in July 2025 under \
+ which it announces a report's *existence* (project, product, filing date, deadline) within a \
+ week, while withholding all technical detail until the deadline. That is Project Zero's own \
+ practice and binds nobody else, but it is the current shape of the norm.";
+
+const GHSA_ECOSYSTEM_NOTE: &str = "GitHub's advisory form requires an `ecosystem` value, and its \
+ accepted list is `rubygems, npm, pip, maven, nuget, composer, go, rust, erlang, actions, pub, \
+ other, swift`. **There is no C or C++ ecosystem**, so a library like this one is filed under \
+ `other` with a free-text package name.";
+
+const GHSA_CVE_NOTE: &str = "GitHub documents that \"Anyone with admin permissions to a security \
+ advisory can request a CVE identification number.\" Reporting privately through a \
+ repository's \"Report a vulnerability\" form adds you as a *collaborator*, which is write \
+ access, not admin. **An external reporter therefore cannot request a CVE without the \
+ maintainer**, and GitHub provides no escalation path if the maintainer never answers; its \
+ documented remedy in that case is public disclosure after a reasonable wait.";
+
+const GHSA_CREDIT_NOTE: &str = "GitHub's credit roles include `Tool` (\"Names of tools used in \
+ vulnerability discovery or identification\") separately from `Finder` and `Reporter`, so \
+ lisdex can be credited without displacing the person who ran it.";
+
+const PACKAGE_NAME_NOTE: &str = "The name above is whatever this campaign's target was called, \
+ which is usually the fuzz harness rather than the library as it is distributed. Check it \
+ before filing, and pass `--package` to set it.";
+
+const CVE_RECORD_VERSION_NOTE: &str = "If this is routed to a CVE record rather than a GitHub \
+ advisory, the same gap is expressible there: the record format requires `versions` or \
+ `defaultStatus` but not both, `defaultStatus` defaults to `unknown`, and the CNA Rules allow \
+ a permanent unknown status for a product suspected of being affected but not investigated. \
+ Note also that a CVE record must not be the first public disclosure of a vulnerability, so \
+ something public has to exist at or before the record.";
+
+const VERSION_NULL_NOTE: &str = "In GitHub's advisory schema `vulnerable_version_range` is a \
+ required *key* whose type is string-or-null. Leaving it null is a valid record that says the \
+ range is unestablished; inventing one is not.";
+
+const SEVERITY_SCALE_NOTE: &str = "This tier is the one lisdex's triage layer assigns, and it is \
+ not the Low/Medium/High/Critical scale advisory forms usually ask for. The two are different \
+ axes and lisdex does not translate between them, because the translation would be an opinion \
+ wearing the tier's authority.";
+
+const UNASSESSED_SEVERITY_NOTE: &str = "**Severity is unassessed for this finding.** lisdex has no \
+ labelled corpus for this class, so it reports the tier its taxonomy uses for *look at this* \
+ rather than a judgement it cannot support. Do not read it as low severity.";
+
+const NO_WEAKNESS_NOTE: &str = "No CWE is named. The observed class does not map onto exactly one \
+ published weakness, and naming the nearest one would put a wrong identifier in a permanent \
+ record.";
+
+const SECURITY_RELEVANT_NOTE: &str = "The triage layer marks this finding security-relevant.";
+const NOT_SECURITY_RELEVANT_NOTE: &str = "The triage layer does **not** mark this finding \
+ security-relevant. That is a statement about the fault it observed, not a clearance: a \
+ maintainer may still consider it a vulnerability.";
+
+fn severity_meaning(severity: Severity) -> &'static str {
+ match severity {
+ Severity::Exploitable => {
+ "the fault class and access direction match cases that have historically been steerable \
+ into more than a crash"
+ }
+ Severity::ProbablyExploitable => {
+ "the fault class is one that is often steerable, but this report does not show it here"
+ }
+ Severity::NotExploitable => {
+ "nothing in this report shows memory an attacker could steer, though a reachable crash \
+ is still a denial of service"
+ }
+ Severity::Undefined => {
+ "lisdex declines to assign a tier for this class rather than assert one it cannot \
+ support"
+ }
+ }
+}
+
+fn refusal(input: OperatorInput) -> String {
+ format!("{NOT_ESTABLISHED}. {}", input.why())
+}
+
+fn push_summary(out: &mut String, advisory: &Advisory) {
+ let site = advisory.crash_site().unwrap_or(UNNAMED_SITE);
+ let _ = write!(
+ out,
+ "{SUMMARY_HEADING}\n\nFuzzing `{}` produced a `{}` reaching `{}`. {} crash{} in this \
+ campaign share this fault's stack signature, so they are counted here as one bug, keyed \
+ `{}`. The reproducer is {} bytes.\n\n",
+ advisory.target(),
+ advisory.class(),
+ site,
+ advisory.crash_count(),
+ if advisory.crash_count() == 1 {
+ ""
+ } else {
+ "es"
+ },
+ advisory.key(),
+ advisory.reproducer_bytes()
+ );
+ let _ = write!(out, "{CVE_HEADING}\n\n{NOT_ASSIGNED}\n\n");
+ let _ = write!(
+ out,
+ "{VERSIONS_HEADING}\n\n{}\n\n",
+ refusal(OperatorInput::AffectedVersionRange)
+ );
+ let _ = write!(out, "{REPORTER_HEADING}\n\n{OPERATOR_SUPPLIES}\n\n");
+}
+
+fn push_severity(out: &mut String, advisory: &Advisory) {
+ let _ = write!(out, "{SEVERITY_HEADING}\n\n");
+ let _ = write!(
+ out,
+ "lisdex tier: **{}** ({}).\n\n{SEVERITY_SCALE_NOTE}\n\n",
+ advisory.severity().as_str(),
+ severity_meaning(advisory.severity())
+ );
+ if !advisory.severity_is_assessed() {
+ let _ = write!(out, "{UNASSESSED_SEVERITY_NOTE}\n\n");
+ }
+ match advisory.weakness() {
+ Some(weakness) => {
+ let _ = write!(out, "Weakness: **{}** {}\n\n", weakness.id, weakness.name);
+ }
+ None => {
+ let _ = write!(out, "{NO_WEAKNESS_NOTE}\n\n");
+ }
+ }
+ let _ = write!(
+ out,
+ "{}\n\n",
+ if advisory.is_security_relevant() {
+ SECURITY_RELEVANT_NOTE
+ } else {
+ NOT_SECURITY_RELEVANT_NOTE
+ }
+ );
+ let _ = write!(out, "CVSS: {}\n\n", refusal(OperatorInput::CvssVector));
+ let _ = write!(
+ out,
+ "Attacker reachability: {}\n\n",
+ refusal(OperatorInput::AttackerReachability)
+ );
+}
+
+fn push_proof_of_concept(out: &mut String, advisory: &Advisory) {
+ let _ = write!(
+ out,
+ "{POC_HEADING}\n\nA {} byte input drives `{}` into this fault. The sanitizer report it \
+ produced is reproduced verbatim below; it is the evidence, and it has not been edited.\n\n\
+ ```\n{}\n```\n\n",
+ advisory.reproducer_bytes(),
+ advisory.target(),
+ advisory.sanitizer_report().trim_end()
+ );
+}
+
+fn push_analysis(out: &mut String, advisory: &Advisory) {
+ let _ = write!(
+ out,
+ "{ANALYSIS_HEADING}\n\nCall stack as the sanitizer reported it:\n\n"
+ );
+ if advisory.frames().is_empty() {
+ let _ = write!(out, "- (the report carried no frames)\n\n");
+ return;
+ }
+ for frame in advisory.frames() {
+ let _ = writeln!(out, "- `{frame}`");
+ }
+ let _ = writeln!(out);
+}
+
+fn push_filing(out: &mut String, advisory: &Advisory) {
+ let _ = write!(out, "{FILING_HEADING}\n\n");
+ if advisory.provenance() == Provenance::SyntheticBenchmark {
+ let _ = write!(out, "{PROVENANCE_BANNER}\n\n");
+ return;
+ }
+ let _ = writeln!(out, "- {PACKAGE_NAME_NOTE}");
+ let _ = writeln!(out, "- {GHSA_ECOSYSTEM_NOTE}");
+ let _ = writeln!(out, "- {GHSA_CVE_NOTE}");
+ let _ = writeln!(out, "- {GHSA_CREDIT_NOTE}");
+ let _ = writeln!(out, "- {VERSION_NULL_NOTE}");
+ let _ = writeln!(out, "- {CVE_RECORD_VERSION_NOTE}");
+ let _ = write!(out, "- {DISCLOSURE_NOTE}\n\n");
+}
+
+#[must_use]
+pub fn render(advisory: &Advisory) -> String {
+ let mut out = String::new();
+ let site = advisory.crash_site().unwrap_or(UNNAMED_SITE);
+ let _ = write!(
+ out,
+ "# Security advisory for {}: {} in {}\n\n",
+ advisory.target(),
+ advisory.class(),
+ site
+ );
+ if advisory.provenance() == Provenance::SyntheticBenchmark {
+ let _ = write!(out, "{PROVENANCE_BANNER}\n\n");
+ }
+ let _ = write!(out, "{DRAFTED_BY}\n\n");
+ push_summary(&mut out, advisory);
+ push_severity(&mut out, advisory);
+ push_proof_of_concept(&mut out, advisory);
+ let _ = write!(out, "{REMEDIATION_HEADING}\n\n{REMEDIATION_BODY}\n\n");
+ push_analysis(&mut out, advisory);
+ let _ = write!(out, "{TIMELINE_HEADING}\n\n{TIMELINE_BODY}\n\n");
+ push_filing(&mut out, advisory);
+ out
+}
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/real_reports.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/real_reports.rs
new file mode 100644
index 00000000..6ad3d54f
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/real_reports.rs
@@ -0,0 +1,65 @@
+// ©AngelaMos | 2026
+// real_reports.rs
+
+use lisdex_core::report::SanitizerReport;
+use lisdex_report::advisory::{Provenance, provenance_of};
+
+const FIXTURES: &str = concat!(
+ env!("CARGO_MANIFEST_DIR"),
+ "/../lisdex-triage/tests/fixtures"
+);
+
+const CAPTURED_REPORTS: usize = 19;
+
+fn captured() -> Vec<(String, String)> {
+ let mut reports = Vec::new();
+ let entries = std::fs::read_dir(FIXTURES)
+ .unwrap_or_else(|err| panic!("fixture directory {FIXTURES}: {err}"));
+ for entry in entries {
+ let path = entry.expect("fixture entry").path();
+ if path.extension().is_none_or(|ext| ext != "txt") {
+ continue;
+ }
+ let name = path
+ .file_stem()
+ .expect("fixture stem")
+ .to_string_lossy()
+ .into_owned();
+ let text = std::fs::read_to_string(&path)
+ .unwrap_or_else(|err| panic!("fixture {}: {err}", path.display()));
+ reports.push((name, text));
+ }
+ reports.sort();
+ reports
+}
+
+#[test]
+fn the_captured_corpus_is_present_and_every_report_parses() {
+ let reports = captured();
+ assert_eq!(
+ reports.len(),
+ CAPTURED_REPORTS,
+ "the provenance control is only worth as much as the corpus behind it, and an empty or shrunken fixture directory would let every assertion below pass vacuously"
+ );
+ for (name, text) in &reports {
+ assert!(
+ SanitizerReport::parse(text).is_some(),
+ "{name} is a verbatim capture from a running sanitizer; a guard that cannot parse it cannot judge it either"
+ );
+ }
+}
+
+#[test]
+fn no_real_captured_report_is_mistaken_for_a_planted_benchmark_bug() {
+ let mut marked = Vec::new();
+ for (name, text) in captured() {
+ let report = SanitizerReport::parse(&text).expect(&name);
+ if provenance_of(&report) != Provenance::Field {
+ marked.push(name);
+ }
+ }
+ assert!(
+ marked.is_empty(),
+ "these reports were captured from real sanitizer runs with no benchmark instrumentation anywhere in them; marking one synthetic would silently withhold a genuine finding from disclosure: {marked:#?}"
+ );
+}
diff --git a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/rendering.rs b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/rendering.rs
new file mode 100644
index 00000000..04d76c63
--- /dev/null
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex-report/tests/rendering.rs
@@ -0,0 +1,177 @@
+// ©AngelaMos | 2026
+// rendering.rs
+
+use lisdex_core::campaign::CampaignId;
+use lisdex_core::crash::Crash;
+use lisdex_report::advisory::{Advisory, OPERATOR_INPUTS};
+use lisdex_report::json::{self, GHSA_ECOSYSTEM_FOR_C_LIBRARIES};
+use lisdex_report::markdown;
+
+const CAMPAIGN: CampaignId = CampaignId(1);
+
+const REAL_HEAP_WRITE: &str = "\
+=================================================================
+==53767==ERROR: AddressSanitizer: heap-buffer-overflow on address 0x7bd6bfde0020 at pc 0x558474e40fd9
+WRITE of size 32 at 0x7bd6bfde0020 thread T0
+ #0 0x558474e40fd8 in png_handle_iCCP /src/libpng/pngrutil.c:1447:5
+ #1 0x558474e41111 in png_read_info /src/libpng/pngread.c:160:10
+SUMMARY: AddressSanitizer: heap-buffer-overflow (/out/harness+0xcdfd8) in png_handle_iCCP
+";
+
+const CANARY_CRASH: &str = "\
+=================================================================
+==29092==ERROR: AddressSanitizer: SEGV on unknown address 0x0000000071a4 (pc 0x7fa6518a053b bp 0x1 sp 0x2 T0)
+==29092==The signal is caused by a READ memory access.
+ #0 0x7fa6518a053b in kill (/lib/x86_64-linux-gnu/libc.so.6+0x4553b)
+ #1 0x55a5aee02220 in magma_log /opt/magma/magma/src/canary.c:92:5
+ #2 0x55a5aee68dae in MAGMA_png_handle_PLTE /opt/magma-work/libpng/repo/pngrutil.c:992:4
+SUMMARY: AddressSanitizer: SEGV (/lib/x86_64-linux-gnu/libc.so.6+0x4553b) in kill
+";
+
+const UBSAN_REPORT: &str = "\
+pngrutil.c:1204:7: runtime error: left shift of negative value -1
+ #0 0x55a in png_do_read_transform pngrtran.c:1204:7
+";
+
+fn advisory(report: &str) -> Advisory {
+ let crash = Crash::from_report(CAMPAIGN, b"reproducer-bytes".to_vec(), report);
+ Advisory::draft("libpng", &crash, 44).expect("fixture must draft")
+}
+
+#[test]
+fn every_field_lisdex_declines_appears_in_the_rendered_advisory_with_its_reason() {
+ let rendered = markdown::render(&advisory(REAL_HEAP_WRITE));
+ for input in OPERATOR_INPUTS {
+ assert!(
+ rendered.contains(input.why()),
+ "{} is declined by the model but its reason never reaches the page, so a reader sees a missing field with no explanation and cannot tell a deliberate refusal from an oversight",
+ input.field()
+ );
+ }
+}
+
+#[test]
+fn the_advisory_never_states_a_version_range_or_a_cvss_vector() {
+ let rendered = markdown::render(&advisory(REAL_HEAP_WRITE));
+ assert!(
+ !rendered.contains("CVSS:3.1/") && !rendered.contains("CVSS:4.0/"),
+ "a CVSS vector in this document would be derived from the crash class alone, which is a guess wearing a number"
+ );
+ assert!(
+ rendered.contains("### Affected versions\n\nNOT ESTABLISHED"),
+ "the version heading must survive with an explicit refusal in it; dropping the heading entirely would make the advisory look complete when the field is simply unknown"
+ );
+}
+
+#[test]
+fn a_planted_benchmark_finding_is_rendered_with_a_refusal_and_no_filing_instructions() {
+ let rendered = markdown::render(&advisory(CANARY_CRASH));
+ assert!(
+ rendered.contains("DO NOT FILE THIS ADVISORY"),
+ "the refusal has to be the first thing the reader meets, not a footnote"
+ );
+ assert!(
+ !rendered.contains("Anyone with admin permissions"),
+ "an advisory for a deliberately planted bug must not carry instructions for filing it"
+ );
+}
+
+#[test]
+fn a_real_finding_is_rendered_with_the_filing_route_that_actually_applies() {
+ let rendered = markdown::render(&advisory(REAL_HEAP_WRITE));
+ assert!(!rendered.contains("DO NOT FILE THIS ADVISORY"));
+ assert!(
+ rendered.contains("There is no C or C++ ecosystem"),
+ "every target lisdex fuzzes is a C or C++ library, and GitHub's ecosystem field is required with no value for one; an operator who does not know this cannot complete the form"
+ );
+ assert!(
+ rendered.contains("cannot request a CVE without the maintainer"),
+ "requesting a CVE needs admin on the advisory, which a reporting researcher is never granted, and an advisory that implied otherwise would send them down a route that does not exist"
+ );
+}
+
+#[test]
+fn the_sanitizer_report_is_reproduced_verbatim_as_the_evidence() {
+ let rendered = markdown::render(&advisory(REAL_HEAP_WRITE));
+ assert!(
+ rendered.contains(REAL_HEAP_WRITE.trim_end()),
+ "the report is the evidence; an edited or reflowed copy is not the thing the sanitizer said"
+ );
+}
+
+#[test]
+fn an_unassessed_severity_is_flagged_rather_than_presented_as_a_low_one() {
+ let rendered = markdown::render(&advisory(UBSAN_REPORT));
+ assert!(
+ rendered.contains("Severity is unassessed for this finding"),
+ "UNDEFINED is the tier lisdex uses when it has no labelled corpus (B91); rendering it beside the other tiers with no caveat reads as an assessment that the finding is unremarkable"
+ );
+ assert!(
+ rendered.contains("No CWE is named"),
+ "the same gap applies to naming a weakness for it"
+ );
+}
+
+#[test]
+fn the_json_leaves_every_unestablished_field_null_instead_of_inventing_one() {
+ let rendered = json::render(&advisory(REAL_HEAP_WRITE));
+ let ghsa = &rendered["ghsa"];
+ for field in [
+ "vulnerable_version_range",
+ "patched_versions",
+ "cvss_vector_string",
+ "cve_id",
+ ] {
+ assert!(
+ ghsa[field].is_null(),
+ "{field} is a required key in GitHub's advisory schema whose type is string-or-null, so null is a valid record meaning 'not established' and any value lisdex put there would be fabricated"
+ );
+ }
+ assert_eq!(
+ ghsa["ecosystem"], GHSA_ECOSYSTEM_FOR_C_LIBRARIES,
+ "GitHub's ecosystem enum has no C or C++ member, so a C library is filed under other"
+ );
+}
+
+#[test]
+fn the_json_carries_the_same_refusals_the_page_does() {
+ let rendered = json::render(&advisory(REAL_HEAP_WRITE));
+ let declined = rendered["declined"]
+ .as_array()
+ .expect("declined must be an array");
+ assert_eq!(
+ declined.len(),
+ OPERATOR_INPUTS.len(),
+ "a consumer reading the JSON must see the same gaps a human reading the page sees, or the two renderings disagree about what lisdex claims to know"
+ );
+ for input in OPERATOR_INPUTS {
+ assert!(
+ declined
+ .iter()
+ .any(|entry| entry["field"] == input.field() && entry["reason"] == input.why()),
+ "{} is missing from the machine-readable refusals",
+ input.field()
+ );
+ }
+}
+
+#[test]
+fn the_json_marks_a_planted_benchmark_finding_undisclosable() {
+ let rendered = json::render(&advisory(CANARY_CRASH));
+ assert_eq!(rendered["disclosable"], false);
+ assert_eq!(rendered["provenance"], "synthetic_benchmark");
+ let real = json::render(&advisory(REAL_HEAP_WRITE));
+ assert_eq!(
+ real["disclosable"], true,
+ "marking every finding undisclosable would make the mark meaningless"
+ );
+ assert_eq!(real["provenance"], "field");
+}
+
+#[test]
+fn the_json_renders_as_a_string_a_consumer_can_parse_back() {
+ let text = json::render_string(&advisory(REAL_HEAP_WRITE));
+ let parsed: serde_json::Value =
+ serde_json::from_str(&text).expect("the emitted document must be valid JSON");
+ assert_eq!(parsed, json::render(&advisory(REAL_HEAP_WRITE)));
+}
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 7e526817..5b1655fc 100644
--- a/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml
+++ b/PROJECTS/advanced/zero-day-vulnerability-scanner/crates/lisdex/Cargo.toml
@@ -25,5 +25,6 @@ lisdex-build.workspace = true
lisdex-surface.workspace = true
lisdex-harness.workspace = true
lisdex-llm.workspace = true
+lisdex-report.workspace = true
lisdex-triage.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 8d278e2a..2b46b895 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
@@ -29,6 +29,8 @@ use lisdex_harness::synth;
use lisdex_harness::verify::{Bench, Corpus, Toolchain, Verdict};
use lisdex_ingest::acquire::{self, Source};
use lisdex_ingest::detect;
+use lisdex_report::advisory::Advisory;
+use lisdex_report::{json, markdown};
use lisdex_surface::extract::{self, Language};
use lisdex_surface::surface::{self, SurfaceOptions};
use lisdex_triage::classify::classify;
@@ -42,6 +44,9 @@ const UNKEYED_MARKER: &str = "unkeyed";
const STACK_HASH_SHORT_LEN: usize = 16;
const ORIGINAL_SUFFIX: &str = ".orig";
const MINIMIZED_SUFFIX: &str = ".min";
+const MARKDOWN_SUFFIX: &str = ".md";
+const JSON_SUFFIX: &str = ".json";
+const NOT_DISCLOSABLE_MARKER: &str = " NOT DISCLOSABLE";
const DISPLAYED_FRAMES: usize = 6;
const SOURCES_DIR: &str = "sources";
const BUILDS_DIR: &str = "builds";
@@ -93,6 +98,41 @@ enum Command {
Minimize(MinimizeArgs),
#[command(about = "report which LLM booster tier is configured and whether it answers")]
Llm(LlmArgs),
+ #[command(
+ about = "draft a coordinated-disclosure advisory for each distinct bug in a campaign"
+ )]
+ Advisory(AdvisoryArgs),
+}
+
+#[derive(Clone, Copy, clap::ValueEnum)]
+enum AdvisoryFormat {
+ Markdown,
+ Json,
+}
+
+#[derive(clap::Args)]
+struct AdvisoryArgs {
+ #[arg(long, help = "sqlite database written by a previous campaign")]
+ db: PathBuf,
+ #[arg(long, help = "campaign id whose bugs to draft advisories for")]
+ campaign: i64,
+ #[arg(
+ long,
+ value_enum,
+ default_value_t = AdvisoryFormat::Markdown,
+ help = "render a human advisory or the machine-readable form"
+ )]
+ format: AdvisoryFormat,
+ #[arg(
+ long,
+ help = "directory to write one advisory per distinct bug; omit to print to stdout"
+ )]
+ out: Option<PathBuf>,
+ #[arg(
+ long,
+ help = "the library as it is distributed; defaults to the campaign's fuzz target, which is usually the harness name rather than the package name"
+ )]
+ package: Option<String>,
}
#[derive(clap::Args)]
@@ -393,6 +433,7 @@ fn dispatch() -> Result<(), Box<dyn Error>> {
Command::Harness(args) => harness(args),
Command::Verify(args) => verify(args),
Command::Crashes(args) => crashes(args),
+ Command::Advisory(args) => advisories(args),
Command::Minimize(args) => minimize_campaign(args),
Command::Llm(args) => llm(args),
}
@@ -1340,6 +1381,86 @@ fn minimize_campaign(args: &MinimizeArgs) -> Result<(), Box<dyn Error>> {
Ok(())
}
+fn advisories(args: &AdvisoryArgs) -> Result<(), Box<dyn Error>> {
+ let store = Store::open(&args.db)?;
+ let campaign_id = CampaignId(args.campaign);
+ let campaign = store
+ .get_campaign(campaign_id)?
+ .ok_or("no such campaign in store")?;
+
+ let crashes = store.crashes_for_campaign(campaign_id)?;
+ let grouping = dedup::group_crashes(&crashes);
+
+ let mut drafted: Vec<(String, Advisory)> = Vec::new();
+ for group in grouping.groups() {
+ let Some(crash) = group.representative() else {
+ continue;
+ };
+ let stem = short_hash(crash.stack_hash());
+ let package = args.package.as_deref().unwrap_or_else(|| campaign.target());
+ match Advisory::draft(package, crash, group.len()) {
+ Some(advisory) => drafted.push((stem, advisory)),
+ None => eprintln!(
+ "warning: bug {stem} has no dedup key, so its crashes are not known to be one bug and no advisory names them"
+ ),
+ }
+ }
+
+ if grouping.unkeyed_crashes() > 0 {
+ eprintln!(
+ "warning: {} crashes carry no dedup key and are in no advisory",
+ grouping.unkeyed_crashes()
+ );
+ }
+
+ let Some(dir) = &args.out else {
+ return print_advisories(args.format, &drafted);
+ };
+
+ std::fs::create_dir_all(dir)?;
+ println!("advisories {}", drafted.len());
+ for (stem, advisory) in &drafted {
+ let (text, suffix) = match args.format {
+ AdvisoryFormat::Markdown => (markdown::render(advisory), MARKDOWN_SUFFIX),
+ AdvisoryFormat::Json => (json::render_string(advisory), JSON_SUFFIX),
+ };
+ let path = dir.join(format!("{stem}{suffix}"));
+ std::fs::write(&path, text)?;
+ println!(
+ " {stem} x{} {}{}",
+ advisory.crash_count(),
+ path.display(),
+ if advisory.is_disclosable() {
+ ""
+ } else {
+ NOT_DISCLOSABLE_MARKER
+ }
+ );
+ }
+ Ok(())
+}
+
+fn print_advisories(
+ format: AdvisoryFormat,
+ drafted: &[(String, Advisory)],
+) -> Result<(), Box<dyn Error>> {
+ match format {
+ AdvisoryFormat::Markdown => {
+ for (_, advisory) in drafted {
+ println!("{}", markdown::render(advisory));
+ }
+ }
+ AdvisoryFormat::Json => {
+ let documents: Vec<serde_json::Value> = drafted
+ .iter()
+ .map(|(_, advisory)| json::render(advisory))
+ .collect();
+ println!("{}", serde_json::to_string_pretty(&documents)?);
+ }
+ }
+ Ok(())
+}
+
fn crashes(args: &CrashesArgs) -> Result<(), Box<dyn Error>> {
let store = Store::open(&args.db)?;
let campaign_id = CampaignId(args.campaign);