use std::io::BufRead;
use serde::{Deserialize, Serialize};
use crate::cve::{Catalogue, CatalogueError, MAX_DOCUMENT_BYTES};
pub const KEV_ID: &str = "cisa:kev";
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum KevError {
#[error("the KEV catalogue could not be read: {0}")]
Io(#[from] std::io::Error),
#[error("the KEV catalogue is malformed: {0}")]
Malformed(String),
#[error("the KEV catalogue is longer than the {limit} byte limit")]
TooLarge {
limit: u64,
},
#[error("the converted catalogue was refused: {0}")]
Rejected(#[from] CatalogueError),
}
pub fn to_document(input: &mut dyn BufRead) -> Result<String, KevError> {
let mut source = String::new();
let read = {
use std::io::Read as _;
std::io::Read::take(input, MAX_DOCUMENT_BYTES.saturating_add(1))
.read_to_string(&mut source)?
};
if read as u64 > MAX_DOCUMENT_BYTES {
return Err(KevError::TooLarge {
limit: MAX_DOCUMENT_BYTES,
});
}
let feed: Feed =
serde_json::from_str(&source).map_err(|error| KevError::Malformed(error.to_string()))?;
let document = Document {
id: KEV_ID.to_string(),
version: catalogue_version(&feed.catalog_version),
vulnerability: feed.vulnerabilities.iter().map(Entry::from).collect(),
};
toml::to_string(&document).map_err(|error| KevError::Malformed(error.to_string()))
}
pub fn read(input: &mut dyn BufRead) -> Result<Catalogue, KevError> {
let document = to_document(input)?;
Ok(Catalogue::read(&mut document.as_bytes())?)
}
pub fn cpe_identity(name: &str) -> String {
let mut out = String::with_capacity(name.len());
let mut pending_separator = false;
for character in name.chars() {
if character.is_ascii_alphanumeric() || matches!(character, '-' | '.' | '_') {
if pending_separator && !out.is_empty() {
out.push('_');
}
pending_separator = false;
out.push(character.to_ascii_lowercase());
} else {
pending_separator = true;
}
}
out
}
fn catalogue_version(declared: &str) -> String {
let parts: Vec<&str> = declared.split('.').collect();
if parts.len() != 3
|| !parts
.iter()
.all(|part| part.chars().all(|c| c.is_ascii_digit()))
{
return declared.to_string();
}
parts
.iter()
.map(|part| part.trim_start_matches('0'))
.map(|part| if part.is_empty() { "0" } else { part })
.collect::<Vec<_>>()
.join(".")
}
#[derive(Debug, Deserialize)]
struct Feed {
#[serde(default, rename = "catalogVersion")]
catalog_version: String,
#[serde(default)]
vulnerabilities: Vec<KevEntry>,
}
#[derive(Debug, Deserialize)]
struct KevEntry {
#[serde(default, rename = "cveID")]
cve_id: String,
#[serde(default, rename = "vendorProject")]
vendor_project: String,
#[serde(default)]
product: String,
#[serde(default, rename = "vulnerabilityName")]
vulnerability_name: String,
#[serde(default, rename = "requiredAction")]
required_action: String,
#[serde(default, rename = "knownRansomwareCampaignUse")]
known_ransomware_campaign_use: String,
#[serde(default)]
cwes: Vec<String>,
}
#[derive(Debug, Serialize)]
struct Document {
id: String,
version: String,
vulnerability: Vec<Entry>,
}
#[derive(Debug, Serialize)]
struct Entry {
cve: String,
title: String,
severity: String,
vendor: String,
product: String,
affected: String,
#[serde(skip_serializing_if = "Option::is_none")]
cwe: Option<u32>,
#[serde(skip_serializing_if = "Option::is_none")]
remediation: Option<String>,
}
impl From<&KevEntry> for Entry {
fn from(entry: &KevEntry) -> Self {
Self {
cve: entry.cve_id.clone(),
title: match entry.vulnerability_name.trim().is_empty() {
true => format!("{} known exploited vulnerability", entry.cve_id),
false => entry.vulnerability_name.clone(),
},
severity: match entry
.known_ransomware_campaign_use
.eq_ignore_ascii_case("known")
{
true => "critical",
false => "high",
}
.to_string(),
vendor: cpe_identity(&entry.vendor_project),
product: cpe_identity(&entry.product),
affected: "*".to_string(),
cwe: entry.cwes.first().and_then(|cwe| {
cwe.trim()
.strip_prefix("CWE-")
.and_then(|number| number.parse().ok())
}),
remediation: match entry.required_action.trim().is_empty() {
true => None,
false => Some(entry.required_action.clone()),
},
}
}
}
#[cfg(test)]
mod tests {
use super::*;
const FEED: &str = r#"{
"title": "CISA Catalog of Known Exploited Vulnerabilities",
"catalogVersion": "2026.09.03",
"count": 2,
"vulnerabilities": [
{
"cveID": "CVE-2021-41773",
"vendorProject": "Apache",
"product": "HTTP Server",
"vulnerabilityName": "Apache HTTP Server Path Traversal Vulnerability",
"dateAdded": "2021-11-03",
"shortDescription": "Apache HTTP Server contains a path traversal vulnerability.",
"requiredAction": "Apply updates per vendor instructions.",
"dueDate": "2021-11-17",
"knownRansomwareCampaignUse": "Unknown",
"notes": "",
"cwes": ["CWE-22"]
},
{
"cveID": "CVE-2023-4966",
"vendorProject": "Citrix",
"product": "NetScaler ADC and NetScaler Gateway",
"vulnerabilityName": "Citrix NetScaler Buffer Overflow Vulnerability",
"dateAdded": "2023-10-18",
"shortDescription": "Sensitive information disclosure.",
"requiredAction": "Apply mitigations per vendor instructions.",
"dueDate": "2023-11-08",
"knownRansomwareCampaignUse": "Known",
"notes": "",
"cwes": ["CWE-119"]
}
]
}"#;
fn converted() -> Catalogue {
read(&mut FEED.as_bytes()).expect("the feed converts")
}
#[test]
fn a_display_name_becomes_the_identity_a_cpe_carries() {
assert_eq!(cpe_identity("Apache"), "apache");
assert_eq!(cpe_identity("HTTP Server"), "http_server");
assert_eq!(cpe_identity("OpenBSD"), "openbsd");
assert_eq!(cpe_identity("D-Link"), "d-link");
assert_eq!(cpe_identity("Windows Server 2019"), "windows_server_2019");
assert_eq!(cpe_identity("Foo Bar"), "foo_bar");
assert_eq!(cpe_identity(" Leading"), "leading");
assert_eq!(cpe_identity(""), "");
}
#[test]
fn a_name_cpe_spells_differently_does_not_normalise_to_it() {
assert_eq!(
cpe_identity("Adaptive Security Appliance (ASA)"),
"adaptive_security_appliance_asa",
"CPE says 'adaptive_security_appliance', so this entry will not match"
);
}
#[test]
fn the_feeds_own_version_becomes_the_catalogues() {
assert_eq!(catalogue_version("2026.09.03"), "2026.9.3");
assert_eq!(catalogue_version("2026.10.30"), "2026.10.30");
assert_eq!(catalogue_version("2026.01.01"), "2026.1.1");
assert_eq!(catalogue_version("not-a-date"), "not-a-date");
}
#[test]
fn a_converted_feed_is_a_document_the_catalogue_reader_accepts() {
let catalogue = converted();
assert_eq!(catalogue.id(), KEV_ID);
assert_eq!(catalogue.version().to_string(), "2026.9.3");
assert_eq!(catalogue.len(), 2);
}
#[test]
fn an_entry_carries_what_the_correlator_matches_on() {
let document = to_document(&mut FEED.as_bytes()).expect("converts");
assert!(document.contains(r#"cve = "CVE-2021-41773""#));
assert!(document.contains(r#"vendor = "apache""#));
assert!(document.contains(r#"product = "http_server""#));
assert!(document.contains(r#"affected = "*""#));
assert!(document.contains("cwe = 22"));
assert!(document.contains("Apply updates per vendor instructions."));
}
#[test]
fn ransomware_use_is_the_one_distinction_the_feed_offers() {
let document = to_document(&mut FEED.as_bytes()).expect("converts");
assert!(
document.contains(r#"severity = "critical""#),
"the Citrix row"
);
assert!(document.contains(r#"severity = "high""#), "the Apache row");
}
#[test]
fn a_kev_finding_says_that_no_version_was_checked() {
use crate::model::confidence::Confidence;
use crate::model::host::Host;
use crate::model::port::{Port, PortState, Protocol, Service};
let catalogue = converted();
let mut host = Host::new("192.0.2.1".parse().expect("an address"));
let service = Service::new("http", 90).with_cpe("cpe:/a:apache:http_server:2.4.62");
host.add_port(Port::new(80, Protocol::Tcp, PortState::Open).with_service(service));
crate::cve::correlate_with(&mut host, &catalogue);
let port = host
.ports()
.find(|port| port.number() == 80)
.expect("the port");
let finding = port
.findings()
.find(|finding| finding.detection().id() == KEV_ID)
.expect("the entry matched on the product");
assert_eq!(
finding.confidence(),
Confidence::Weak,
"an entry that checked no version must not read as one that did"
);
assert!(
finding.excerpt().as_str().contains("not checked"),
"the excerpt has to say the version was never in question"
);
}
#[test]
fn a_feed_past_the_ceiling_is_refused() {
let huge = format!(
r#"{{"catalogVersion":"2026.1.1","vulnerabilities":[],"pad":"{}"}}"#,
"x".repeat(MAX_DOCUMENT_BYTES as usize + 16)
);
assert!(matches!(
to_document(&mut huge.as_bytes()),
Err(KevError::TooLarge { .. })
));
}
#[test]
fn what_is_not_the_feed_is_refused() {
for text in ["", "not json", "{}", r#"{"vulnerabilities": 3}"#] {
let outcome = read(&mut text.as_bytes());
assert!(
outcome.is_err(),
"'{text}' produced a catalogue rather than an error"
);
}
}
#[test]
fn a_name_carrying_toml_syntax_does_not_become_toml_structure() {
let hostile = r#"{
"catalogVersion": "2026.1.1",
"vulnerabilities": [{
"cveID": "CVE-2026-0001",
"vendorProject": "Acme",
"product": "Widget\", affected = \"*\"\nmalicious = \"yes",
"vulnerabilityName": "Title\"\nseverity = \"info\"\ninjected = \"yes",
"requiredAction": "",
"knownRansomwareCampaignUse": "Unknown",
"cwes": []
}]
}"#;
let document = to_document(&mut hostile.as_bytes()).expect("converts");
let parsed: toml::Value = toml::from_str(&document).expect("the document parses");
let table = parsed.as_table().expect("a table");
assert_eq!(
table.keys().collect::<Vec<_>>(),
vec!["id", "version", "vulnerability"],
"a name opened a key of its own"
);
let entries = table["vulnerability"].as_array().expect("an array");
assert_eq!(entries.len(), 1, "one entry in, one entry out");
let entry = entries[0].as_table().expect("a table");
assert!(
!entry.contains_key("injected") && !entry.contains_key("malicious"),
"a name opened a key inside the entry"
);
assert_eq!(
entry["severity"].as_str(),
Some("high"),
"the title's injected severity did not take"
);
let catalogue = read(&mut hostile.as_bytes()).expect("reads");
assert_eq!(catalogue.len(), 1, "one entry in, one entry out");
use crate::model::finding::Severity;
use crate::model::host::Host;
use crate::model::port::{Port, PortState, Protocol, Service};
let mut host = Host::new("192.0.2.1".parse().expect("an address"));
let service =
Service::new("http", 90).with_cpe("cpe:/a:acme:widget_affected_malicious_yes:1.0");
host.add_port(Port::new(80, Protocol::Tcp, PortState::Open).with_service(service));
crate::cve::correlate_with(&mut host, &catalogue);
let port = host
.ports()
.find(|port| port.number() == 80)
.expect("the port");
let finding = port.findings().next().expect("the entry matched");
assert_eq!(
finding.severity(),
Severity::High,
"the title's injected severity did not take"
);
}
}