use boon::{Compiler, Schemas};
use regex::Regex;
use serde_json::Value;
use std::collections::BTreeSet;
use crate::config::{OsDetection, ScanEffort, ServiceDetection};
use crate::diff::{Coverage, Significance};
use crate::export::diff::schema::{coverage_name, significance_name};
use crate::export::schema::{SCHEMA_VERSION, scan_effort_name, send_mode_name};
use crate::export::{ExportOptions, Exporter, JsonExporter, Redaction, fixture};
use crate::model::confidence::Confidence;
use crate::model::finding::{DetectionClass, Severity};
use crate::model::host::status::StatusProtocol;
use crate::model::host::{
Filtering, HostStatus, IpProtocolState, NameKind, NameSource, NetworkRole,
};
use crate::model::port::{PortState, Protocol};
use crate::model::technique::{SctpScanTechnique, TcpScanTechnique};
use crate::model::tls::{Interruption, SuiteFault, SuiteStrength, TlsVersion};
use crate::record::wire::{
attachment_source_name, confidence_name, detection_class_name, filtering_name,
host_status_name, ip_protocol_state_name, liveness_skip_name, name_kind_name, name_source_name,
network_role_name, pass_name, port_state_name, protocol_name, scan_kind_name,
scanner_kind_name, severity_name, stop_reason_name,
};
use crate::report::{AttachmentSource, LivenessSkip, Pass, ScanKind, ScannerKind, StopReason};
use crate::transport::probe::SendMode;
const SCHEMA: &str = include_str!("../../assets/schema/zond-report-v1.schema.json");
const LINES_SCHEMA: &str = include_str!("../../assets/schema/zond-lines-v1.schema.json");
const DIFF_SCHEMA: &str = include_str!("../../assets/schema/zond-diff-v1.schema.json");
const SCHEMA_URL: &str = "https://zond.rs/schema/zond-report-v1.schema.json";
const LINES_SCHEMA_URL: &str = "https://zond.rs/schema/zond-lines-v1.schema.json";
const DIFF_SCHEMA_URL: &str = "https://zond.rs/schema/zond-diff-v1.schema.json";
struct Validator {
schemas: Schemas,
index: boon::SchemaIndex,
}
impl Validator {
fn new() -> Self {
Self::over(SCHEMA_URL)
}
fn lines() -> Self {
Self::over(LINES_SCHEMA_URL)
}
fn diff() -> Self {
Self::over(DIFF_SCHEMA_URL)
}
fn over(url: &str) -> Self {
let mut schemas = Schemas::new();
let mut compiler = Compiler::new();
for (id, text) in [
(SCHEMA_URL, SCHEMA),
(LINES_SCHEMA_URL, LINES_SCHEMA),
(DIFF_SCHEMA_URL, DIFF_SCHEMA),
] {
let document: Value =
serde_json::from_str(text).expect("the schema file is valid JSON");
compiler
.add_resource(id, document)
.expect("the schema file is a usable resource");
}
let index = compiler
.compile(url, &mut schemas)
.expect("the schema file compiles");
Self { schemas, index }
}
fn check(&self, document: &Value) {
if let Err(error) = self.schemas.validate(document, self.index) {
panic!("the exported document does not match the published schema:\n{error:#}");
}
}
fn accepts(&self, document: &Value) -> bool {
self.schemas.validate(document, self.index).is_ok()
}
}
fn document(options: ExportOptions) -> Value {
let mut bytes = Vec::new();
JsonExporter::new(options)
.export(&fixture::report(), &mut bytes)
.expect("the export succeeds");
serde_json::from_slice(&bytes).expect("the export parses as JSON")
}
#[test]
fn the_published_schema_compiles() {
let _ = Validator::new();
}
#[test]
fn the_schema_pins_the_version_the_code_emits() {
let schema: Value = serde_json::from_str(SCHEMA).expect("valid JSON");
assert_eq!(
schema["properties"]["schema_version"]["const"],
Value::from(SCHEMA_VERSION)
);
}
fn enumerations() -> Vec<(&'static str, Vec<String>)> {
let named = |names: Vec<&'static str>| names.into_iter().map(str::to_owned).collect();
vec![
(
"/$defs/settings/properties/tcp_technique/enum",
named(TcpScanTechnique::ALL.iter().map(|t| t.name()).collect()),
),
(
"/$defs/accepted_version/properties/version/enum",
named(TlsVersion::ALL.iter().map(|v| v.name()).collect()),
),
(
"/$defs/unfinished_version/properties/version/enum",
named(TlsVersion::ALL.iter().map(|v| v.name()).collect()),
),
(
"/$defs/unfinished_version/properties/interruption/enum",
named(Interruption::ALL.iter().map(|i| i.name()).collect()),
),
(
"/$defs/accepted_suite/properties/strength/enum",
named(SuiteStrength::ALL.iter().map(|s| s.name()).collect()),
),
(
"/$defs/accepted_suite/properties/faults/items/enum",
named(SuiteFault::ALL.iter().map(|f| f.name()).collect()),
),
(
"/$defs/settings/properties/sctp_technique/enum",
named(SctpScanTechnique::ALL.iter().map(|t| t.name()).collect()),
),
(
"/$defs/settings/properties/send_mode/enum",
named(SendMode::ALL.iter().copied().map(send_mode_name).collect()),
),
(
"/$defs/settings/properties/os_detection/enum",
named(OsDetection::ALL.iter().map(|d| d.name()).collect()),
),
(
"/$defs/settings/properties/service_detection/enum",
named(ServiceDetection::ALL.iter().map(|d| d.name()).collect()),
),
(
"/$defs/settings/properties/detection/enum",
named(
DetectionClass::ALL
.iter()
.copied()
.map(detection_class_name)
.collect(),
),
),
(
"/$defs/retry/properties/effort/enum",
named(
ScanEffort::ALL
.iter()
.copied()
.map(scan_effort_name)
.collect(),
),
),
(
"/$defs/host/properties/status/enum",
named(
HostStatus::ALL
.iter()
.copied()
.map(host_status_name)
.collect(),
),
),
(
"/$defs/host/properties/names/items/properties/source/enum",
named(
NameSource::ALL
.iter()
.copied()
.map(name_source_name)
.collect(),
),
),
(
"/$defs/host/properties/names/items/properties/kind/enum",
named(NameKind::ALL.iter().copied().map(name_kind_name).collect()),
),
(
"/$defs/host/properties/roles/items/enum",
named(
NetworkRole::ALL
.iter()
.copied()
.map(network_role_name)
.collect(),
),
),
(
"/$defs/reason/properties/protocol/anyOf/0/enum",
StatusProtocol::ALL
.iter()
.map(|protocol| crate::record::wire::status_protocol_name(protocol).into_owned())
.collect(),
),
(
"/$defs/host/properties/filtering/items/enum",
named(Filtering::ALL.iter().copied().map(filtering_name).collect()),
),
(
"/$defs/host/properties/ip_protocols/items/properties/state/enum",
named(
IpProtocolState::ALL
.iter()
.copied()
.map(ip_protocol_state_name)
.collect(),
),
),
(
"/$defs/port/properties/state/enum",
named(
PortState::ALL
.iter()
.copied()
.map(port_state_name)
.collect(),
),
),
(
"/$defs/protocol/enum",
named(Protocol::ALL.iter().copied().map(protocol_name).collect()),
),
(
"/$defs/finding/properties/severity/enum",
named(Severity::ALL.iter().copied().map(severity_name).collect()),
),
(
"/$defs/finding/properties/confidence/enum",
named(
Confidence::ALL
.iter()
.copied()
.map(confidence_name)
.collect(),
),
),
(
"/$defs/finding/properties/class/enum",
named(
DetectionClass::ALL
.iter()
.copied()
.map(detection_class_name)
.collect(),
),
),
(
"/$defs/phase/properties/passes_cut/items/enum",
named(Pass::ALL.iter().copied().map(pass_name).collect()),
),
(
"/$defs/phase/properties/kind/enum",
named(ScanKind::ALL.iter().copied().map(scan_kind_name).collect()),
),
(
"/$defs/phase/properties/liveness_skipped/enum",
named(
LivenessSkip::ALL
.iter()
.copied()
.map(liveness_skip_name)
.collect(),
),
),
(
"/$defs/scanner_kind/enum",
named(
ScannerKind::ALL
.iter()
.copied()
.map(scanner_kind_name)
.collect(),
),
),
(
"/$defs/probe_stats/properties/stop_reason/enum",
named(
StopReason::ALL
.iter()
.copied()
.map(stop_reason_name)
.collect(),
),
),
(
"/$defs/attachment/properties/source/enum",
named(
AttachmentSource::ALL
.iter()
.copied()
.map(attachment_source_name)
.collect(),
),
),
]
}
fn diff_enumerations() -> Vec<(&'static str, Vec<String>)> {
let coverage: Vec<String> = Coverage::ALL
.iter()
.copied()
.map(|coverage| coverage_name(coverage).to_owned())
.collect();
let significance: Vec<String> = Significance::ALL
.iter()
.copied()
.map(|significance| significance_name(significance).to_owned())
.collect();
vec![
(
"/$defs/host_delta/properties/coverage/oneOf/0/enum",
coverage.clone(),
),
(
"/$defs/port_delta/properties/coverage/oneOf/0/enum",
coverage,
),
("/properties/significance/enum", significance.clone()),
(
"/$defs/host_delta/properties/significance/enum",
significance.clone(),
),
(
"/$defs/port_delta/properties/significance/enum",
significance,
),
]
}
#[test]
fn the_comparison_schema_lists_exactly_the_enumerated_values_the_engine_writes() {
let schema: Value = serde_json::from_str(DIFF_SCHEMA).expect("valid JSON");
check_enumerations(&schema, diff_enumerations());
}
#[test]
fn the_schema_lists_exactly_the_enumerated_values_the_engine_writes() {
let schema: Value = serde_json::from_str(SCHEMA).expect("valid JSON");
check_enumerations(&schema, enumerations());
}
fn check_enumerations(schema: &Value, enumerations: Vec<(&'static str, Vec<String>)>) {
for (pointer, emitted) in enumerations {
let accepted: BTreeSet<String> = schema
.pointer(pointer)
.unwrap_or_else(|| panic!("the schema has no enumeration at {pointer}"))
.as_array()
.unwrap_or_else(|| panic!("{pointer} is not a list of names"))
.iter()
.map(|value| {
value
.as_str()
.unwrap_or_else(|| panic!("{pointer} holds something that is not a name"))
.to_owned()
})
.collect();
let emitted: BTreeSet<String> = emitted.into_iter().collect();
assert_eq!(
emitted.difference(&accepted).collect::<Vec<_>>(),
Vec::<&String>::new(),
"{pointer} does not accept a value this build can write"
);
assert_eq!(
accepted.difference(&emitted).collect::<Vec<_>>(),
Vec::<&String>::new(),
"{pointer} advertises a value this build cannot write, which a third \
party producing this format would find refused on the way back in"
);
}
}
#[test]
fn a_full_report_matches_the_schema() {
Validator::new().check(&document(ExportOptions::new()));
}
#[test]
fn an_ordinary_report_matches_the_schema() {
let plain = fixture::compared().0;
let mut bytes = Vec::new();
JsonExporter::new(ExportOptions::new())
.export(&plain, &mut bytes)
.expect("the export succeeds");
let document: Value = serde_json::from_slice(&bytes).expect("the export parses as JSON");
let settings = &document["phases"][0]["settings"];
assert!(settings["evasion"].is_null(), "the fixture altered packets");
assert!(settings["idle_scan"].is_null(), "the fixture read a zombie");
assert!(
document["phases"][0]["attachments"].is_null(),
"the fixture found managed equipment"
);
Validator::new().check(&document);
}
#[test]
fn the_schema_marks_optional_exactly_the_fields_a_writer_leaves_out() {
const OMITTED: &[(&str, &str)] = &[
("accepted_version", "unrecognised"),
("attachment", "device_mac"),
("attachment", "device_name"),
("attachment", "management_address"),
("attachment", "native_vlan"),
("attachment", "port"),
("failure", "cut_short"),
("finding", "cpe"),
("finding", "cpes"),
("finding", "excerpt"),
("finding", "remediation"),
("hardware", "cpe23"),
("hardware", "family"),
("hardware", "model"),
("hardware", "product"),
("hardware", "serial_number"),
("hardware", "version"),
("origin", "label"),
("phase", "attachments"),
("phase", "icmp_rate_limited"),
("phase", "liveness_skipped"),
("phase", "open"),
("phase", "origin"),
("phase", "passes_cut"),
("phase", "reached_by_connect"),
("phase", "refusals"),
("phase", "refused_by_route"),
("phase", "silent"),
("phase", "stopped"),
("phase", "timed_out"),
("phase", "undecided"),
("phase", "unheard_probes"),
("phase", "unreached"),
("report", "timed_out"),
("report", "undecided"),
("report", "unreached"),
("scope", "listened"),
("security", "accepts"),
("security", "unfinished"),
("settings", "evasion"),
("settings", "excluded_ports"),
("settings", "idle_scan"),
];
const OMITTED_WHOLESALE: &[&str] = &["evasion", "idle_scan"];
let schema: Value = serde_json::from_str(SCHEMA).expect("valid JSON");
let definitions = schema["$defs"]
.as_object()
.expect("the schema defines types");
let mut optional: Vec<(String, String)> = Vec::new();
let report = String::from("report");
for (name, definition) in definitions.iter().chain([(&report, &schema)]) {
let Some(properties) = definition["properties"].as_object() else {
continue;
};
let required: BTreeSet<&str> = definition["required"]
.as_array()
.map(|names| names.iter().filter_map(Value::as_str).collect())
.unwrap_or_default();
if OMITTED_WHOLESALE.contains(&name.as_str()) {
assert!(
required.is_empty(),
"`{name}` describes one technique's profile and every part of it \
is optional; `{required:?}` says otherwise"
);
continue;
}
for field in properties.keys() {
if !required.contains(field.as_str()) {
optional.push((name.clone(), field.clone()));
}
}
}
optional.sort();
let expected: Vec<(String, String)> = OMITTED
.iter()
.map(|(object, field)| ((*object).to_string(), (*field).to_string()))
.collect();
assert_eq!(
optional, expected,
"the schema's optional fields are not the ones `schema`'s module \
documentation tells a consumer to expect"
);
}
#[test]
fn a_redacted_report_matches_the_schema() {
Validator::new().check(&document(
ExportOptions::new().with_redaction(Redaction::Standard),
));
}
#[test]
fn the_schema_rejects_a_document_it_should_reject() {
let validator = Validator::new();
let mut missing_field = document(ExportOptions::new());
missing_field
.as_object_mut()
.expect("an object")
.remove("summary");
assert!(
!validator.accepts(&missing_field),
"a report with no summary must not validate"
);
let mut unknown_field = document(ExportOptions::new());
unknown_field["hosts"][0]["surprise"] = Value::from("undocumented");
assert!(
!validator.accepts(&unknown_field),
"a field the schema does not describe must not validate - that failure \
is what stops the schema drifting away from the DTO"
);
let mut float_timestamp = document(ExportOptions::new());
float_timestamp["generated_at"] = Value::from(1_770_000_000.5);
assert!(
!validator.accepts(&float_timestamp),
"an epoch float must not pass where an RFC 3339 string is promised"
);
let mut rounded_count = document(ExportOptions::new());
rounded_count["phases"][0]["targets"]["addresses"] = Value::from(256);
assert!(
!validator.accepts(&rounded_count),
"a count that can exceed 2^53 must be a string, not a number"
);
}
#[cfg(feature = "export-jsonl")]
#[test]
fn every_exported_line_matches_the_lines_schema() {
let validator = Validator::lines();
for options in [
ExportOptions::new(),
ExportOptions::new().with_redaction(Redaction::Standard),
] {
let mut bytes = Vec::new();
crate::export::JsonLinesExporter::new(options)
.export(&fixture::report(), &mut bytes)
.expect("the export succeeds");
let text = String::from_utf8(bytes).expect("utf-8");
let mut records = 0;
for line in text.lines() {
let record: Value = serde_json::from_str(line).expect("a line parses on its own");
validator.check(&record);
records += 1;
}
assert_eq!(records, 4, "a report record and three hosts");
}
}
#[cfg(feature = "export-jsonl")]
#[test]
fn the_lines_schema_rejects_a_record_it_should_reject() {
let validator = Validator::lines();
let host = document(ExportOptions::new())["hosts"][0].clone();
assert!(
!validator.accepts(&host),
"a host object with no `type` is not a record"
);
let mut mislabelled = host.clone();
mislabelled["type"] = Value::from("report");
assert!(
!validator.accepts(&mislabelled),
"a host wearing the report tag must not validate as either"
);
let mut tagged = host;
tagged["type"] = Value::from("host");
assert!(validator.accepts(&tagged), "a tagged host is a host record");
let mut surprising = tagged;
surprising["surprise"] = Value::from("undocumented");
assert!(
!validator.accepts(&surprising),
"a field the schema does not describe must not validate"
);
}
fn comparison(
baseline: &crate::report::ScanReport,
current: &crate::report::ScanReport,
options: ExportOptions,
) -> Value {
use crate::diff::ScanDiff;
use crate::export::diff::{DiffExporter, JsonDiffExporter};
let diff = ScanDiff::between(baseline, current);
let mut bytes = Vec::new();
JsonDiffExporter::new(options)
.export(&diff, &mut bytes)
.expect("the export succeeds");
serde_json::from_slice(&bytes).expect("the export parses as JSON")
}
#[test]
fn the_published_comparison_schema_compiles() {
let _ = Validator::diff();
}
#[test]
fn the_comparison_schema_pins_the_version_the_code_emits() {
let schema: Value = serde_json::from_str(DIFF_SCHEMA).expect("valid JSON");
assert_eq!(
schema["properties"]["schema_version"]["const"],
Value::from(crate::format::DIFF_SCHEMA_VERSION)
);
}
#[test]
fn a_comparison_matches_the_published_schema() {
let (before, after) = fixture::compared();
let document = comparison(&before, &after, ExportOptions::new());
Validator::diff().check(&document);
}
#[test]
fn an_unchanged_comparison_matches_the_published_schema() {
let report = fixture::report();
let document = comparison(&report, &report, ExportOptions::new());
Validator::diff().check(&document);
assert_eq!(document["unchanged"], Value::Bool(true));
assert_eq!(document["hosts"].as_array().map(Vec::len), Some(0));
}
#[test]
fn a_redacted_comparison_masks_what_a_redacted_report_masks() {
let (before, after) = fixture::compared();
let document = comparison(
&before,
&after,
ExportOptions::new().with_redaction(Redaction::Standard),
);
Validator::diff().check(&document);
let rendered = document.to_string();
assert!(
!rendered.contains("router.local") && !rendered.contains("gateway.local"),
"a hostname survived redaction into the comparison"
);
assert!(
document
.pointer("/hosts/0/changes")
.is_some_and(|changes| changes.to_string().contains("name_gained"))
&& !rendered.contains("ROUTER")
&& !rendered.contains("GATEWAY"),
"a name the host gave for itself survived redaction into the comparison"
);
assert!(
!rendered.contains("2c:cf:67:00:00:01"),
"a hardware address survived redaction into the comparison"
);
}
#[test]
fn redaction_masks_the_switch_a_phase_says_it_was_plugged_into() {
let report = fixture::report();
let options = ExportOptions::new().with_redaction(Redaction::Standard);
let attachment = report.phases()[0]
.attachments()
.first()
.expect("the fixture records one");
let name = attachment.device_name().expect("a device name");
let mac = attachment
.device_mac()
.expect("a device address")
.to_string();
let mut json = Vec::new();
JsonExporter::new(options.clone())
.export(&report, &mut json)
.expect("the report exports");
let json = String::from_utf8(json).expect("valid UTF-8");
assert!(
!json.contains(name),
"the switch's name survived redaction: {json}"
);
assert!(
!json.contains(&mac),
"the switch's hardware address survived redaction"
);
assert!(
json.contains("GigabitEthernet1/0/14"),
"the port is not a name or an address and is what the finding is for"
);
let mut lines = Vec::new();
crate::export::JsonLinesExporter::new(options)
.export(&report, &mut lines)
.expect("the report exports");
let lines = String::from_utf8(lines).expect("valid UTF-8");
assert!(
!lines.contains(name) && !lines.contains(&mac),
"the header of a record-per-line document leaked what the single \
document masked"
);
}
#[test]
fn every_change_the_fixtures_produce_is_a_token_the_schema_accepts() {
let schema: Value = serde_json::from_str(DIFF_SCHEMA).expect("valid JSON");
let accepted: Vec<&str> = schema["$defs"]["change"]["properties"]["kind"]["enum"]
.as_array()
.expect("the schema names the tokens it accepts")
.iter()
.filter_map(Value::as_str)
.collect();
let (before, after) = fixture::compared();
let document = comparison(&before, &after, ExportOptions::new());
let mut seen = 0usize;
for host in document["hosts"].as_array().expect("hosts") {
for change in host["changes"].as_array().expect("changes") {
let kind = change["kind"].as_str().expect("a token");
assert!(accepted.contains(&kind), "'{kind}' is not in the schema");
seen += 1;
}
for port in host["ports"].as_array().expect("ports") {
for change in port["changes"].as_array().expect("changes") {
let kind = change["kind"].as_str().expect("a token");
assert!(accepted.contains(&kind), "'{kind}' is not in the schema");
seen += 1;
}
}
}
assert!(seen > 0, "the fixtures produced no changes to check");
}
fn emitted_change_kinds() -> BTreeSet<String> {
const SOURCE: &str = include_str!("diff/schema.rs");
let pattern = Regex::new(
r#"Self::(?:between|gained|lost|optional|set)\(\s*"([a-z_]+)"(?:\s*,\s*"([a-z_]+)")?"#,
)
.expect("a valid pattern");
let mut kinds = BTreeSet::new();
for captures in pattern.captures_iter(SOURCE) {
for group in [1, 2] {
if let Some(kind) = captures.get(group) {
kinds.insert(kind.as_str().to_string());
}
}
}
kinds
}
fn accepted_change_kinds() -> BTreeSet<String> {
let schema: Value = serde_json::from_str(DIFF_SCHEMA).expect("the schema parses");
schema["$defs"]["change"]["properties"]["kind"]["enum"]
.as_array()
.expect("the kind enum is a list")
.iter()
.map(|kind| kind.as_str().expect("every kind is a string").to_string())
.collect()
}
#[test]
fn the_schema_accepts_exactly_the_change_kinds_the_exporter_emits() {
let emitted = emitted_change_kinds();
let accepted = accepted_change_kinds();
assert!(
!emitted.is_empty(),
"the source scan found no change kinds, so it is checking nothing"
);
let unlisted: Vec<&String> = emitted.difference(&accepted).collect();
let unemitted: Vec<&String> = accepted.difference(&emitted).collect();
assert!(
unlisted.is_empty(),
"the exporter emits kinds the published schema rejects: {unlisted:?}"
);
assert!(
unemitted.is_empty(),
"the schema lists kinds nothing emits: {unemitted:?}"
);
}
#[test]
fn the_journal_and_the_report_spell_a_host_the_same_way() {
use crate::record::HostRecord;
const RECORD_ONLY: &[&str] = &[
"os_evidence",
"rtts",
"hop_counter",
"rtt",
"elapsed",
"first_reply",
"last_reply",
"zone",
"retry_effort",
"retry_max_attempts",
"retry_timeout_scale",
"retry_dampen_silent_hosts",
"secs_since_epoch",
"nanos_since_epoch",
"secs",
"nanos",
"detection",
"source",
];
const REPORT_ONLY: &[&str] = &[
"alive",
"families",
"at",
"decoration",
"fe80",
"mac",
"vendor",
"redaction",
"family",
"complete",
"kind",
"position",
"data",
"trip",
"samples",
"jitter_us",
"rtt_avg_us",
"rtt_max_us",
"rtt_median_us",
"rtt_min_us",
"rtt_us",
"elapsed_us",
"first_reply_us",
"last_reply_us",
"probe_stats",
"retry",
"services",
"systems",
"code",
"strength",
"faults",
"deprecated",
];
let report = fixture::report();
let host = report.hosts().next().expect("the fixture has a host");
let recorded: Value =
serde_json::to_value(HostRecord::from(host)).expect("a host records as JSON");
let exported = &document(ExportOptions::new())["hosts"][0];
let record_names = field_names(&recorded);
let export_names = field_names(exported);
let unmatched_record: Vec<&String> = record_names
.difference(&export_names)
.filter(|name| !RECORD_ONLY.contains(&name.as_str()))
.collect();
let unmatched_export: Vec<&String> = export_names
.difference(&record_names)
.filter(|name| !REPORT_ONLY.contains(&name.as_str()))
.collect();
assert!(
unmatched_record.is_empty(),
"the journal names fields the report does not, and they are not listed as \
journal-only: {unmatched_record:?}"
);
assert!(
unmatched_export.is_empty(),
"the report names fields the journal does not, and they are not listed as \
report-only: {unmatched_export:?}"
);
}
fn field_names(value: &Value) -> BTreeSet<String> {
let mut names = BTreeSet::new();
fn walk(value: &Value, names: &mut BTreeSet<String>) {
match value {
Value::Object(map) => {
for (key, child) in map {
names.insert(key.clone());
walk(child, names);
}
}
Value::Array(items) => items.iter().for_each(|item| walk(item, names)),
_ => {}
}
}
walk(value, &mut names);
names
}
#[test]
fn the_hostile_fixture_poisons_every_string_the_schema_declares() {
const ENGINE_WRITTEN: &[&str] = &[
"algorithm",
"at",
"class",
"code",
"confidence",
"digest",
"device_mac",
"digest_algorithm",
"end",
"engine_version",
"excluded_ports",
"family",
"first_seen",
"flags",
"generated_at",
"kind",
"label",
"last_seen",
"link",
"mac",
"macs",
"management_address",
"name",
"primary_ip",
"produced_by",
"protocol",
"public_key",
"reason",
"scanner",
"severity",
"signature",
"source_ip",
"spec",
"spoof_mac",
"start",
"started_at",
"state",
"status",
"stop_reason",
"targets",
"timestamp",
"validity_end",
"validity_start",
"version",
"withheld",
"zombie",
"zone",
];
let mut bytes = Vec::new();
JsonExporter::new(ExportOptions::new())
.export(&fixture::hostile(), &mut bytes)
.expect("the hostile export succeeds");
let document: Value = serde_json::from_slice(&bytes).expect("it parses as JSON");
fn declared(value: &Value, out: &mut BTreeSet<String>) {
let Some(map) = value.as_object() else {
return;
};
if let Some(Value::Object(properties)) = map.get("properties") {
for (name, property) in properties {
let is_string = property.get("type").and_then(Value::as_str) == Some("string")
|| property
.get("type")
.and_then(Value::as_array)
.is_some_and(|any| any.iter().any(|t| t.as_str() == Some("string")));
if is_string {
out.insert(name.clone());
}
declared(property, out);
}
}
for key in ["items", "additionalProperties", "$defs", "definitions"] {
if let Some(sub) = map.get(key) {
declared(sub, out);
}
}
if let Some(Value::Object(defs)) = map.get("$defs") {
for sub in defs.values() {
declared(sub, out);
}
}
for key in ["oneOf", "anyOf", "allOf"] {
if let Some(Value::Array(items)) = map.get(key) {
for item in items {
declared(item, out);
}
}
}
}
fn poisoned(value: &Value, out: &mut BTreeSet<String>) {
match value {
Value::Object(map) => {
for (name, sub) in map {
if sub
.as_str()
.is_some_and(|text| text.contains(fixture::HOSTILE))
{
out.insert(name.clone());
}
if let Value::Array(items) = sub
&& items
.iter()
.any(|i| i.as_str().is_some_and(|t| t.contains(fixture::HOSTILE)))
{
out.insert(name.clone());
}
poisoned(sub, out);
}
}
Value::Array(items) => {
for item in items {
poisoned(item, out);
}
}
_ => {}
}
}
let schema: Value = serde_json::from_str(SCHEMA).expect("the schema file is valid JSON");
let mut names = BTreeSet::new();
declared(&schema, &mut names);
let mut carried = BTreeSet::new();
poisoned(&document, &mut carried);
let clean: Vec<&String> = names
.iter()
.filter(|name| !carried.contains(*name) && !ENGINE_WRITTEN.contains(&name.as_str()))
.collect();
assert!(
clean.is_empty(),
"the schema declares these strings and the hostile fixture leaves them clean, so no \
escaping test covers them: {clean:?}\n\nEither give the field a hostile value in \
`fixture::hostile`, or — if no remote host can influence it — add it to \
ENGINE_WRITTEN with that reasoning."
);
}
fn named_renderings(options: &ExportOptions) -> Vec<(String, String)> {
use crate::diff::ScanDiff;
use crate::export::diff::DiffExporter;
use crate::merge::{Merge, MergeOptions};
use crate::report::ScanReport;
let mut rendered = Vec::new();
let mut write = |format: String, export: &dyn Fn(&mut Vec<u8>)| {
let mut bytes = Vec::new();
export(&mut bytes);
rendered.push((format, String::from_utf8(bytes).expect("utf-8")));
};
let mut reports = |label: &str, report: &ScanReport| {
for format in crate::export::ExportFormat::all() {
write(format!("{label}{}", format.extension()), &|bytes| {
format
.exporter(options.clone())
.export(report, bytes)
.expect("the report exports");
});
}
};
let (before, after) = fixture::named();
reports("", &after);
let (old, new) = fixture::renamed();
let mut merge = Merge::new(MergeOptions::default());
merge.add(old).add(new);
reports("merged ", &merge.finish());
let (unnamed, _) = fixture::named_late();
for (label, baseline) in [("", &before), (" named late", &unnamed)] {
let diff = ScanDiff::between(baseline, &after);
write(format!("diff json{label}"), &|bytes| {
crate::export::diff::JsonDiffExporter::new(options.clone())
.export(&diff, bytes)
.expect("the comparison exports");
});
#[cfg(feature = "export-html")]
write(format!("diff html{label}"), &|bytes| {
crate::export::diff::HtmlDiffExporter::new(options.clone())
.export(&diff, bytes)
.expect("the comparison exports");
});
}
rendered
}
fn as_searched(text: &str) -> String {
text.replace(r#"<span class="ctl">U+0000</span>"#, "")
.replace("\\u0000", "")
.replace("�", "")
.replace("�", "")
.replace('\0', "")
.to_lowercase()
}
#[test]
fn no_format_carries_a_name_the_host_gave_under_redaction() {
let names: Vec<String> = [fixture::NAMED_HOST, fixture::NAMED_DOMAIN]
.iter()
.map(|name| name.to_lowercase())
.collect();
for (format, text) in named_renderings(&ExportOptions::new()) {
let searched = as_searched(&text);
assert!(
names.iter().all(|name| searched.contains(name)),
"the unredacted {format} does not carry the names, so this test checks nothing"
);
}
let redacted = ExportOptions::new().with_redaction(Redaction::Standard);
let leaks: Vec<String> = named_renderings(&redacted)
.into_iter()
.flat_map(|(format, text)| {
let searched = as_searched(&text);
names
.iter()
.filter(move |name| searched.contains(name.as_str()))
.map(move |name| format!("the redacted {format} still names `{name}`"))
})
.collect();
assert!(leaks.is_empty(), "{leaks:#?}");
}
fn host_string_paths() -> BTreeSet<String> {
fn walk(
node: &Value,
path: &str,
defs: &Value,
within: &mut Vec<String>,
out: &mut BTreeSet<String>,
) {
if let Some(reference) = node.get("$ref").and_then(Value::as_str) {
let name = reference
.rsplit('/')
.next()
.expect("a reference names a definition");
if !within.iter().any(|seen| seen == name) {
within.push(name.to_owned());
walk(&defs[name], path, defs, within, out);
within.pop();
}
return;
}
for key in ["oneOf", "anyOf", "allOf"] {
if let Some(Value::Array(branches)) = node.get(key) {
for branch in branches {
walk(branch, path, defs, within, out);
}
}
}
let is_string = match node.get("type") {
Some(Value::String(kind)) => kind == "string",
Some(Value::Array(kinds)) => kinds.iter().any(|kind| kind == "string"),
_ => false,
};
if is_string {
out.insert(path.to_owned());
}
if let Some(items) = node.get("items") {
walk(items, &format!("{path}[]"), defs, within, out);
}
if let Some(Value::Object(properties)) = node.get("properties") {
for (name, property) in properties {
walk(property, &format!("{path}.{name}"), defs, within, out);
}
}
}
let schema: Value = serde_json::from_str(SCHEMA).expect("the schema file is valid JSON");
let defs = &schema["$defs"];
let mut paths = BTreeSet::new();
walk(&defs["host"], "host", defs, &mut Vec::new(), &mut paths);
paths
}
fn host_paths_naming(host: &Value) -> BTreeSet<String> {
fn walk(value: &Value, path: &str, out: &mut BTreeSet<String>) {
match value {
Value::Object(map) => {
for (key, sub) in map {
walk(sub, &format!("{path}.{key}"), out);
}
}
Value::Array(items) => {
for item in items {
walk(item, &format!("{path}[]"), out);
}
}
Value::String(text) => {
let searched = as_searched(text);
if [fixture::NAMED_HOST, fixture::NAMED_DOMAIN]
.iter()
.any(|name| searched.contains(&name.to_lowercase()))
{
out.insert(path.to_owned());
}
}
_ => {}
}
}
let mut paths = BTreeSet::new();
walk(host, "host", &mut paths);
paths
}
#[test]
fn redaction_masks_the_host_s_words_in_every_field_its_replies_fill() {
const UNFILLABLE: &[&str] = &[
"host.findings[].content_hash",
"host.findings[].id",
"host.findings[].version",
"host.first_seen",
"host.hardware.mac",
"host.hardware.macs[]",
"host.ip_protocols[].name",
"host.ips[]",
"host.last_seen",
"host.path[].address",
"host.ports[].discovery.reason",
"host.ports[].discovery.source_ip",
"host.ports[].discovery.timestamp",
"host.ports[].findings[].content_hash",
"host.ports[].findings[].id",
"host.ports[].findings[].version",
"host.ports[].security.accepts[].suites[].code",
"host.ports[].security.accepts[].suites[].name",
"host.ports[].security.accepts[].unrecognised[]",
"host.ports[].security.alpn[]",
"host.ports[].security.certificate.fingerprint_sha256",
"host.ports[].security.certificate.pubkey_type",
"host.ports[].security.certificate.validity_end",
"host.ports[].security.certificate.validity_start",
"host.ports[].security.cipher_suite",
"host.ports[].security.tls_version",
"host.primary_ip",
"host.reasons[].protocol",
"host.reasons[].source_ip",
"host.zone",
];
let (_, after) = fixture::named();
let render = |options: ExportOptions| -> Value {
let mut bytes = Vec::new();
JsonExporter::new(options)
.export(&after, &mut bytes)
.expect("the report exports");
serde_json::from_slice::<Value>(&bytes).expect("it parses")["hosts"][0].clone()
};
let declared = host_string_paths();
let named = host_paths_naming(&render(ExportOptions::new()));
let unfillable: BTreeSet<String> = UNFILLABLE.iter().map(|path| path.to_string()).collect();
let stale: Vec<&String> = unfillable.difference(&declared).collect();
assert!(
stale.is_empty(),
"the schema declares no such string, so the exemption is stale: {stale:?}"
);
let contradicted: Vec<&String> = unfillable.intersection(&named).collect();
assert!(
contradicted.is_empty(),
"the fixture names the host in a string listed as one no host can fill: {contradicted:?}"
);
let unnamed: Vec<&String> = declared
.iter()
.filter(|path| !named.contains(*path) && !unfillable.contains(*path))
.collect();
assert!(
unnamed.is_empty(),
"the named fixture leaves these strings without the host's name, so no redaction \
test covers them: {unnamed:?}\n\nEither name the host in them in \
`fixture::named`, or, if no host can fill one, add it to UNFILLABLE with that \
reasoning."
);
let host = render(ExportOptions::new().with_redaction(Redaction::Standard));
let ports = host["ports"].as_array().expect("ports");
let smb = ports
.iter()
.find(|port| port["port"] == 445)
.expect("the SMB port");
assert_eq!(smb["findings"][0]["title"], "SMBv1 is enabled on XXXXX");
assert_eq!(
smb["findings"][0]["excerpt"],
crate::export::redact::WITHHELD_EXCERPT
);
assert_eq!(smb["service"]["extrainfo"], "workgroup: COXXXXXSO");
assert_eq!(smb["service"]["cpes"][0], "cpe:/a:samba:samba:4.15:XXXXX");
let banner = ports
.iter()
.find(|port| port["port"] == 40390)
.expect("the port named by its banner");
assert_eq!(banner["service"]["name"], "banner: zq7 node fsXXXXXle ok");
assert_eq!(host["hardware"]["product"], "PowerEdge XXXXX");
assert_eq!(
host["os"]["cpes"][0],
"cpe:/o:microsoft:windows_server_2019:XXXXX"
);
let details: Vec<&Value> = host["reasons"]
.as_array()
.expect("reasons")
.iter()
.map(|reason| &reason["details"])
.collect();
assert!(
details.contains(&&Value::from("syn-ack from XXXXX")),
"{details:?}"
);
let smtp = ports
.iter()
.find(|port| port["port"] == 25)
.expect("the SMTP port");
assert_eq!(
smtp["findings"][0]["excerpt"],
"220 fsXXXXXle Microsoft ESMTP MAIL Service ready"
);
let ssh = ports
.iter()
.find(|port| port["port"] == 22)
.expect("the SSH port");
let correlated = &ssh["findings"][0];
assert_eq!(correlated["cpe"], "cpe:/a:openbsd:openssh:XXXXX");
assert_eq!(correlated["cpes"][0], "cpe:/a:openbsd:openssh:XXXXX");
assert_eq!(correlated["references"][0]["value"], "CVE-2023-38408");
assert_eq!(
correlated["references"][1]["value"],
"https://advisories.example/XXXXX"
);
}