use std::io::Write;
use crate::diff::ScanDiff;
use crate::export::diff::DiffExporter;
use crate::export::diff::schema::DiffDto;
use crate::export::{ExportError, ExportOptions};
const FORMAT: &str = "diff json";
#[must_use]
#[derive(Debug, Clone)]
pub struct JsonDiffExporter {
options: ExportOptions,
pretty: bool,
}
impl Default for JsonDiffExporter {
fn default() -> Self {
Self::new(ExportOptions::default())
}
}
impl JsonDiffExporter {
pub fn new(options: ExportOptions) -> Self {
Self {
options,
pretty: true,
}
}
pub fn compact(mut self) -> Self {
self.pretty = false;
self
}
pub fn pretty(mut self) -> Self {
self.pretty = true;
self
}
pub fn options(&self) -> &ExportOptions {
&self.options
}
}
impl DiffExporter for JsonDiffExporter {
fn export(&self, diff: &ScanDiff, out: &mut dyn Write) -> Result<(), ExportError> {
let document = DiffDto::new(diff, &self.options);
let result = if self.pretty {
serde_json::to_writer_pretty(&mut *out, &document)
} else {
serde_json::to_writer(&mut *out, &document)
};
result.map_err(|error| crate::export::write::render_error(FORMAT, error))?;
writeln!(out)?;
Ok(())
}
}
#[cfg(test)]
mod tests {
use serde_json::Value;
use super::*;
use crate::export::fixture;
struct FullDisk;
impl Write for FullDisk {
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
Err(std::io::Error::from(std::io::ErrorKind::StorageFull))
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
#[test]
fn a_failed_write_keeps_the_kind_the_destination_reported() {
let (before, after) = fixture::compared();
let diff = crate::diff::ScanDiff::between(&before, &after);
let error = JsonDiffExporter::new(ExportOptions::new())
.export(&diff, &mut FullDisk)
.expect_err("a destination that refuses every write");
match error {
ExportError::Io(io) => assert_eq!(io.kind(), std::io::ErrorKind::StorageFull),
other => panic!("expected an I/O failure, got {other:?}"),
}
}
fn document() -> Value {
let (before, after) = fixture::compared();
let diff = ScanDiff::between(&before, &after);
let mut bytes = Vec::new();
JsonDiffExporter::new(ExportOptions::new())
.export(&diff, &mut bytes)
.expect("the export succeeds");
serde_json::from_slice(&bytes).expect("the export parses as JSON")
}
fn changes(document: &Value) -> Vec<String> {
let mut found = Vec::new();
for host in document["hosts"].as_array().expect("hosts") {
let address = host["address"].as_str().expect("an address");
for change in host["changes"].as_array().expect("changes") {
found.push(format!(
"{address} - {} {} {}",
change["kind"].as_str().expect("a token"),
change["before"],
change["after"]
));
}
for port in host["ports"].as_array().expect("ports") {
for change in port["changes"].as_array().expect("changes") {
found.push(format!(
"{address} {}/{} {} {} {}",
port["port"],
port["protocol"].as_str().expect("a transport"),
change["kind"].as_str().expect("a token"),
change["before"],
change["after"]
));
}
}
}
found
}
#[test]
fn a_grade_is_carried_at_every_level_and_nests() {
let document = document();
let mut worst = "routine";
for host in document["hosts"].as_array().expect("hosts") {
let host_grade = host["significance"].as_str().expect("a host grade");
let address = host["address"].as_str().expect("an address");
for port in host["ports"].as_array().expect("ports") {
let port_grade = port["significance"].as_str().expect("an endpoint grade");
assert!(
rank(port_grade) <= rank(host_grade),
"{address} is {host_grade} and carries a {port_grade} endpoint"
);
}
if rank(host_grade) > rank(worst) {
worst = host_grade;
}
}
assert_eq!(
document["significance"].as_str(),
Some(worst),
"the document is not graded by its worst host"
);
assert_eq!(
worst, "urgent",
"the fixture opens a port, so something here is urgent"
);
}
fn rank(grade: &str) -> usize {
["routine", "notable", "urgent"]
.iter()
.position(|known| *known == grade)
.unwrap_or_else(|| panic!("'{grade}' is not a grade this document may carry"))
}
#[test]
fn an_endpoint_that_opened_is_the_urgent_one() {
let document = document();
let opened: Vec<&str> = document["hosts"]
.as_array()
.expect("hosts")
.iter()
.flat_map(|host| host["ports"].as_array().expect("ports"))
.filter(|port| port["opened"] == Value::Bool(true))
.map(|port| port["significance"].as_str().expect("a grade"))
.collect();
assert!(!opened.is_empty(), "the fixture opens a port");
assert!(
opened.iter().all(|grade| *grade == "urgent"),
"an endpoint that opened was graded {opened:?}"
);
}
#[test]
fn each_change_is_named_by_its_documented_token() {
let found = changes(&document());
for expected in [
r#"203.0.113.1 - hostname "router.local" "gateway.local""#,
r#"203.0.113.1 - os "Linux 5.15.0" "Linux 6.1.0""#,
r#"203.0.113.1 22/tcp service_version "8.9p1" "9.6p1""#,
r#"203.0.113.1 80/tcp port_state "open" "closed""#,
] {
assert!(
found.iter().any(|c| c == expected),
"missing {expected}\nin {found:#?}"
);
}
}
#[test]
fn a_rotation_carries_both_fingerprints() {
let found = changes(&document());
let rotation = found
.iter()
.find(|change| change.contains("certificate_rotated"))
.expect("the fixture rotates a certificate");
assert!(rotation.contains("aaaa"), "{rotation}");
assert!(rotation.contains("bbbb"), "{rotation}");
}
#[test]
fn an_expiry_crossing_carries_when_it_lapses_and_no_before() {
let document = document();
let host = document["hosts"]
.as_array()
.expect("hosts")
.iter()
.find(|host| host["address"] == "203.0.113.4")
.expect("the host whose certificate is running out");
let change = &host["ports"][0]["changes"][0];
assert_eq!(change["kind"], "certificate_expiring");
assert_eq!(change["before"], Value::Null);
assert!(
change["after"]
.as_str()
.is_some_and(|end| end.ends_with('Z')),
"an absolute moment, not a window: {}",
change["after"]
);
}
#[test]
fn confirmed_says_whether_the_other_scan_looked() {
let document = document();
let hosts = document["hosts"].as_array().expect("hosts");
let arrived = hosts
.iter()
.find(|host| host["address"] == "203.0.113.7")
.expect("the host that arrived");
assert_eq!(arrived["presence"], "added");
assert_eq!(arrived["coverage"], "covered");
assert_eq!(
arrived["confirmed"], true,
"the earlier scan walked this address and did not find it"
);
let gone = hosts
.iter()
.find(|host| host["address"] == "203.0.113.9")
.expect("the host that went");
assert_eq!(gone["presence"], "removed");
assert_eq!(gone["confirmed"], true);
let router = hosts
.iter()
.find(|host| host["address"] == "203.0.113.1")
.expect("the gateway");
let opened = router["ports"]
.as_array()
.expect("ports")
.iter()
.find(|port| port["port"] == 8080)
.expect("the port that opened");
assert_eq!(opened["presence"], "added");
assert_eq!(
opened["confirmed"], true,
"both scans stated they walked 8080"
);
assert_eq!(opened["opened"], true);
}
#[test]
fn a_change_the_other_scan_never_covered_is_not_confirmed() {
let (_, after) = fixture::compared();
let sweep = fixture::report();
let diff = ScanDiff::between(&sweep, &after);
let mut bytes = Vec::new();
JsonDiffExporter::new(ExportOptions::new())
.export(&diff, &mut bytes)
.expect("the export succeeds");
let document: Value = serde_json::from_slice(&bytes).expect("JSON");
let unconfirmed = document["hosts"]
.as_array()
.expect("hosts")
.iter()
.flat_map(|host| host["ports"].as_array().expect("ports"))
.filter(|port| port["confirmed"] == false)
.count();
assert!(
unconfirmed > 0,
"a sweep walked no ports, so nothing found on one is a finding about the network"
);
}
#[test]
fn an_unchanged_comparison_still_writes_a_document() {
let (before, _) = fixture::compared();
let diff = ScanDiff::between(&before, &before);
let mut bytes = Vec::new();
JsonDiffExporter::new(ExportOptions::new())
.export(&diff, &mut bytes)
.expect("the export succeeds");
let document: Value = serde_json::from_slice(&bytes).expect("JSON");
assert_eq!(document["unchanged"], true);
assert_eq!(document["hosts"].as_array().map(Vec::len), Some(0));
assert_eq!(document["summary"]["hosts_changed"], 0);
}
#[test]
fn the_default_exporter_is_the_one_new_builds() {
let (before, after) = fixture::compared();
let diff = ScanDiff::between(&before, &after);
let render = |exporter: &JsonDiffExporter| {
let mut bytes = Vec::new();
exporter.export(&diff, &mut bytes).expect("exports");
String::from_utf8(bytes)
.expect("utf-8")
.lines()
.filter(|line| !line.contains("\"generated_at\""))
.collect::<Vec<_>>()
.join("\n")
};
let built = render(&JsonDiffExporter::new(ExportOptions::new()));
assert_eq!(render(&JsonDiffExporter::default()), built);
assert!(
built.contains("\n "),
"the documented default is indented output"
);
}
#[test]
fn the_document_ends_with_a_newline() {
let (before, after) = fixture::compared();
let diff = ScanDiff::between(&before, &after);
let mut bytes = Vec::new();
JsonDiffExporter::new(ExportOptions::new())
.compact()
.export(&diff, &mut bytes)
.expect("the export succeeds");
assert_eq!(bytes.last(), Some(&b'\n'));
}
}