use std::io::Write;
use crate::diff::{HostDelta, Presence, ScanDiff, Significance};
use crate::export::diff::DiffExporter;
use crate::export::diff::schema::{ChangeDto, DiffDto, HostDeltaDto, PortDeltaDto};
use crate::export::schema::ENGINE_NAME;
use crate::export::write::{TONE_FOUND, TONE_INERT, TONE_NONE, TONE_PARTIAL, Text, esc};
use crate::export::{ExportError, ExportOptions, write};
use crate::report::ENGINE_VERSION;
const DEFAULT_HEADING: &str = "Scan comparison";
#[must_use]
#[derive(Debug, Clone, Default)]
pub struct HtmlDiffExporter {
options: ExportOptions,
heading: Option<String>,
}
impl HtmlDiffExporter {
pub fn new(options: ExportOptions) -> Self {
Self {
options,
heading: None,
}
}
pub fn with_heading(mut self, heading: impl Into<String>) -> Self {
self.heading = Some(heading.into());
self
}
pub fn options(&self) -> &ExportOptions {
&self.options
}
}
impl DiffExporter for HtmlDiffExporter {
fn export(&self, diff: &ScanDiff, out: &mut dyn Write) -> Result<(), ExportError> {
let document = DiffDto::new(diff, &self.options);
let heading = self.heading.as_deref().unwrap_or(DEFAULT_HEADING);
write::head(out, heading)?;
write_masthead(out, heading, &document)?;
write_notices(out, diff, &document)?;
write_tiles(out, &document)?;
write_hosts(out, diff, &self.options)?;
write_colophon(out, &document)?;
write::foot(out)?;
Ok(())
}
}
fn write_masthead(
out: &mut dyn Write,
heading: &str,
document: &DiffDto<'_>,
) -> Result<(), ExportError> {
let subtitle = format!(
"{before} → {after}",
before = Text(&document.baseline.at),
after = Text(&document.current.at),
);
write::masthead(out, heading, &subtitle)
}
fn write_notices(
out: &mut dyn Write,
diff: &ScanDiff,
document: &DiffDto<'_>,
) -> Result<(), ExportError> {
let mut notices: Vec<(bool, &str, String)> = Vec::new();
if document.unchanged {
notices.push((
false,
"no change",
"the two scans describe the same network".into(),
));
}
for (side, provenance) in [
("earlier scan", &document.baseline),
("later scan", &document.current),
] {
if !provenance.states_scope {
notices.push((
true,
"unstated scope",
format!("the {side} does not say what it covered, so nothing it is missing can be confirmed"),
));
}
}
let ports = |kinds: &[&'static str]| kinds.contains(&"port_scan");
match (
ports(&document.baseline.kinds),
ports(&document.current.kinds),
) {
(false, true) => notices.push((
true,
"different scans",
"only the later scan looked at ports, so most of what follows is the earlier one not having looked".into(),
)),
(true, false) => notices.push((
true,
"different scans",
"only the earlier scan looked at ports, so most of what follows is the later one not having looked".into(),
)),
_ => {}
}
if diff.baseline().at() > diff.current().at() {
notices.push((
true,
"reversed",
"the first scan is the later of the two, so this page reads backwards".into(),
));
}
if notices.is_empty() {
return Ok(());
}
writeln!(out, "<div class=\"notices\">")?;
for (alert, key, text) in notices {
write::notice(out, alert, key, &text)?;
}
writeln!(out, "</div>")?;
Ok(())
}
fn write_tiles(out: &mut dyn Write, document: &DiffDto<'_>) -> Result<(), ExportError> {
let summary = &document.summary;
writeln!(out, "<div class=\"tiles\">")?;
for (count, label) in [
(&summary.hosts_added, "hosts appeared"),
(&summary.hosts_removed, "hosts gone"),
(&summary.ports_opened, "ports opened"),
(&summary.ports_closed, "ports closed"),
] {
let note = match (count.total, count.total - count.confirmed) {
(0, _) => "none".to_string(),
(_, 0) => "all confirmed".to_string(),
(_, unconfirmed) => format!("{unconfirmed} nobody had looked for"),
};
write::tile(out, count.total, label, &esc(¬e))?;
}
write::tile(
out,
summary.hosts_changed,
"hosts changed",
&esc("in both scans, and different"),
)?;
write::tile(
out,
summary.certificates_rotated + summary.certificates_expiring + summary.certificates_expired,
"certificates",
&esc("rotated, expiring or lapsed"),
)?;
let graded = |grade: Significance| {
document
.hosts
.deltas()
.iter()
.filter(|delta| delta.significance() >= grade)
.count()
};
let urgent = graded(Significance::Urgent);
let note = match urgent {
0 => "nothing urgent".to_string(),
1 => "1 urgent".to_string(),
many => format!("{many} urgent"),
};
write::tile(
out,
graded(Significance::Notable),
"hosts to look at",
&esc(¬e),
)?;
writeln!(out, "</div>")?;
Ok(())
}
fn write_hosts(
out: &mut dyn Write,
diff: &ScanDiff,
options: &ExportOptions,
) -> Result<(), ExportError> {
let deltas = diff.hosts();
if deltas.is_empty() {
writeln!(
out,
"<section class=\"section\"><p class=\"empty\">Nothing changed between these two scans.</p></section>"
)?;
return Ok(());
}
writeln!(
out,
"<section class=\"section\">\n<h2 class=\"section-title\">Hosts <span class=\"section-count\">{}</span></h2>",
deltas.len()
)?;
for delta in deltas {
write_host(out, delta, &HostDeltaDto::new(delta, options))?;
}
writeln!(out, "</section>")?;
Ok(())
}
fn write_host(
out: &mut dyn Write,
delta: &HostDelta,
dto: &HostDeltaDto<'_>,
) -> Result<(), ExportError> {
let (border, tone, word) = match delta.presence() {
Presence::Added { .. } => ("d-added", TONE_FOUND, "appeared"),
Presence::Removed { .. } => ("d-removed", TONE_NONE, "gone"),
Presence::Both => ("d-changed", TONE_PARTIAL, "changed"),
};
write!(
out,
"<article class=\"host {border}\">\n<header class=\"host-head\"><span class=\"host-ip\">{ip}</span>",
ip = Text(&dto.address),
)?;
let named = dto
.current
.as_ref()
.or(dto.baseline.as_ref())
.and_then(|host| host.hostname.as_deref());
if let Some(hostname) = named {
write!(out, "<span class=\"host-name\">{}</span>", Text(hostname))?;
}
write!(out, "<span class=\"tag {tone}\">{word}</span>")?;
match delta.significance() {
Significance::Urgent => {
write!(out, "<span class=\"tag {TONE_FOUND}\">urgent</span>")?;
}
Significance::Notable => write!(out, "<span class=\"tag\">notable</span>")?,
Significance::Routine => {}
}
if dto.regrouped {
write!(
out,
"<span class=\"tag {TONE_INERT}\">regrouped {}→{}</span>",
dto.records.baseline, dto.records.current
)?;
}
writeln!(out, "</header>\n<div class=\"host-body\">")?;
for change in &dto.changes {
write_change(out, change)?;
}
for port in &dto.ports {
write_port(out, port)?;
}
if let Some(coverage) = delta.presence().counterpart_coverage()
&& !delta.presence().is_confirmed()
{
let other = if delta.presence().is_added() {
"the earlier scan"
} else {
"the later scan"
};
writeln!(
out,
"<span class=\"unconfirmed\">{other} is not known to have covered this host ({coverage}), so this is a fact about the scans rather than about the network.</span>",
coverage = Text(coverage_word(coverage)),
)?;
}
writeln!(out, "</div>\n</article>")?;
Ok(())
}
fn write_port(out: &mut dyn Write, port: &PortDeltaDto) -> Result<(), ExportError> {
let verdict = if port.opened {
Some(("opened", TONE_FOUND))
} else if port.closed {
Some(("closed", TONE_NONE))
} else {
None
};
write!(
out,
"<div class=\"change\"><span class=\"change-kind mono\">{port}/{protocol}</span>",
port = port.port,
protocol = Text(port.protocol),
)?;
if let Some((word, tone)) = verdict {
write!(out, "<span class=\"tag {tone}\">{word}</span>")?;
}
if !port.confirmed {
write!(
out,
"<span class=\"tag {TONE_INERT}\">not looked for</span>"
)?;
}
writeln!(out, "</div>")?;
for change in &port.changes {
write_change(out, change)?;
}
Ok(())
}
fn write_change(out: &mut dyn Write, change: &ChangeDto) -> Result<(), ExportError> {
write!(
out,
"<div class=\"change\"><span class=\"change-kind\">{kind}</span>",
kind = Text(&change.kind.replace('_', " ")),
)?;
match (&change.before, &change.after) {
(Some(before), Some(after)) => write!(
out,
"<span class=\"change-was mono\">{was}</span><span class=\"change-arrow\">→</span><span class=\"mono\">{now}</span>",
was = Text(before),
now = Text(after),
)?,
(None, Some(after)) => write!(out, "<span class=\"mono\">{}</span>", Text(after))?,
(Some(before), None)
if change.kind.ends_with("_lost") || change.kind == "finding_unsettled" =>
{
write!(
out,
"<span class=\"change-was mono\">{}</span>",
Text(before)
)?;
}
(Some(before), None) => write!(
out,
"<span class=\"change-was mono\">{}</span><span class=\"change-arrow\">→</span><span>nothing</span>",
Text(before)
)?,
(None, None) => {}
}
writeln!(out, "</div>")?;
Ok(())
}
fn coverage_word(coverage: crate::diff::Coverage) -> &'static str {
use crate::diff::Coverage;
match coverage {
Coverage::Covered => "covered",
Coverage::Withheld => "a policy forbade it",
Coverage::OutOfScope => "outside what it walked",
Coverage::Unreached => "it ran short of it",
Coverage::Unstated => "it does not say",
}
}
fn write_colophon(out: &mut dyn Write, document: &DiffDto<'_>) -> Result<(), ExportError> {
writeln!(
out,
"<footer class=\"colophon\"><p>Comparing {before} ({before_at}) with {after} ({after_at}). Written by {ENGINE_NAME} {ENGINE_VERSION} at {generated}.</p></footer>",
before = Text(&document.baseline.engine_version),
before_at = Text(&document.baseline.at),
after = Text(&document.current.engine_version),
after_at = Text(&document.current.at),
generated = Text(&document.generated_at),
)?;
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
use crate::export::Redaction;
use crate::export::fixture;
use crate::report::ScanReport;
fn page(diff: &ScanDiff) -> String {
let mut bytes = Vec::new();
HtmlDiffExporter::default()
.export(diff, &mut bytes)
.expect("the export succeeds");
String::from_utf8(bytes).expect("a page is text")
}
fn compared() -> String {
let (before, after) = fixture::compared();
page(&ScanDiff::between(&before, &after))
}
#[test]
fn the_page_is_one_file_that_fetches_nothing() {
let page = compared();
assert!(page.starts_with("<!doctype html>"), "{}", &page[..40]);
assert!(page.trim_end().ends_with("</html>"));
assert!(page.contains("<style>"), "the stylesheet is inlined");
for outside in ["http://", "https://", "<script", "<img", "@import", "src="] {
assert!(
!page.contains(outside),
"a comparison page reaches outside itself: {outside}"
);
}
}
#[test]
fn every_host_carries_what_happened_to_it() {
let page = compared();
for state in ["d-added", "d-removed", "d-changed"] {
assert!(page.contains(state), "no host is {state}: {page}");
}
for word in ["appeared", "gone", "changed"] {
assert!(page.contains(word), "{word} is not said anywhere");
}
}
#[test]
fn the_page_says_which_hosts_are_worth_opening() {
let page = compared();
assert!(
page.contains("hosts to look at"),
"the headline tile is missing: {page}"
);
assert!(
page.contains("urgent"),
"nothing on the page is graded urgent"
);
assert!(
page.contains(">notable<"),
"nothing on the page is graded notable"
);
assert!(
!page.contains(">routine<"),
"routine is written out where it says nothing: {page}"
);
}
#[test]
fn a_page_with_nothing_urgent_on_it_says_nothing_urgent() {
let (before, _) = fixture::compared();
let quiet = page(&ScanDiff::between(&before, &before));
assert!(quiet.contains("nothing urgent"), "{quiet}");
}
#[test]
fn a_headline_count_says_how_much_of_it_nobody_looked_for() {
let (before, after) = fixture::compared();
let unconfirmed = page(&ScanDiff::between(&fixture::report(), &after));
assert!(
unconfirmed.contains("nobody had looked for"),
"the page does not say how much of its counts is unconfirmed: {unconfirmed}"
);
assert!(unconfirmed.contains("not looked for"), "{unconfirmed}");
let confirmed = page(&ScanDiff::between(&before, &after));
assert!(confirmed.contains("all confirmed"), "{confirmed}");
let (before, _) = fixture::compared();
let quiet = page(&ScanDiff::between(&before, &before));
assert!(quiet.contains("tile-note\">none"), "{quiet}");
assert!(!quiet.contains("all confirmed"), "{quiet}");
}
#[test]
fn a_host_on_ground_nobody_covered_says_so_on_its_card() {
use crate::model::host::{Host, HostStatus};
use std::net::{IpAddr, Ipv4Addr};
let mut withheld = Host::new(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 200)));
withheld.set_status(HostStatus::Up);
let later = ScanReport::recorded("test", Vec::new(), vec![withheld]);
let page = page(&ScanDiff::between(&fixture::report(), &later));
assert!(
page.contains("class=\"unconfirmed\""),
"the card does not say nobody looked: {page}"
);
assert!(page.contains("a policy forbade it"), "{page}");
assert!(
page.contains("about the scans rather than about the network"),
"{page}"
);
}
#[test]
fn a_set_member_that_went_is_not_also_pointed_at_nothing() {
let (before, after) = fixture::compared();
let page = page(&ScanDiff::between(&before, &after));
for row in page.split("<div class=\"change\">") {
if row.contains("lost") {
assert!(!row.contains("nothing"), "a departure is said twice: {row}");
}
}
}
#[test]
fn a_claim_the_later_scan_did_not_settle_is_not_shown_as_gone() {
use crate::model::host::{Host, HostStatus};
use crate::model::port::{Port, PortState, Protocol, Security};
use crate::model::tls::{
CipherSuite, Interruption, TlsSupport, TlsVersion, UnfinishedVersion, VersionSupport,
};
let scanned = |support: TlsSupport| {
let findings = support.findings();
let mut port = Port::new(443, Protocol::Tcp, PortState::Open)
.with_security(Security::new().with_support(support));
for finding in findings {
port.add_finding(finding);
}
let mut host = Host::new(std::net::IpAddr::from([203, 0, 113, 10]));
host.set_status(HostStatus::Up);
host.add_port(port);
ScanReport::recorded("test", Vec::new(), vec![host])
};
let before = scanned(TlsSupport::new().accepting(VersionSupport::new(
TlsVersion::Tls10,
vec![CipherSuite::from_code(0x002F).expect("a registered suite")],
vec![],
)));
let after = scanned(TlsSupport::new().leaving_unfinished(UnfinishedVersion::new(
TlsVersion::Tls10,
Interruption::Unanswered,
)));
let page = page(&ScanDiff::between(&before, &after));
let rows: Vec<&str> = page
.split("<div class=\"change\">")
.filter(|row| row.contains("finding unsettled"))
.collect();
assert!(
!rows.is_empty(),
"no unsettled claim reached the page: {page}"
);
for row in rows {
assert!(!row.contains("nothing"), "read as resolved: {row}");
}
assert!(!page.contains("finding resolved"), "{page}");
}
#[test]
fn what_moved_is_shown_as_the_pair_it_is() {
let page = compared();
assert!(page.contains("change-was"), "no before/after pair: {page}");
assert!(
page.contains("service version"),
"an underscore reached the page"
);
assert!(page.contains("8.9p1") && page.contains("9.6p1"), "{page}");
}
#[test]
fn an_unchanged_comparison_still_writes_a_page() {
let (before, _) = fixture::compared();
let page = page(&ScanDiff::between(&before, &before));
assert!(
page.contains("Nothing changed between these two scans"),
"{page}"
);
assert!(page.contains("no change"), "{page}");
assert!(page.trim_end().ends_with("</html>"));
}
#[test]
fn every_value_a_scanned_host_chose_reaches_the_page_escaped() {
let hostile = fixture::hostile();
let page = page(&ScanDiff::between(&fixture::report(), &hostile));
assert!(
!page.contains(fixture::HOSTILE),
"an attacker-controlled string reached the page intact"
);
assert!(!page.contains("<script>"), "markup survived: {page}");
assert!(
!page.contains('\u{202e}'),
"a right-to-left override survived, which reverses the text after it"
);
assert!(
page.contains("<script>"),
"and it is on the page, escaped"
);
}
#[test]
fn redaction_reaches_the_page() {
let (before, after) = fixture::compared();
let diff = ScanDiff::between(&before, &after);
let mut bytes = Vec::new();
HtmlDiffExporter::new(ExportOptions::new().with_redaction(Redaction::Standard))
.export(&diff, &mut bytes)
.expect("the export succeeds");
let page = String::from_utf8(bytes).expect("text");
assert!(
!page.contains("gateway.local"),
"a hostname survived: {page}"
);
assert!(
!page.contains("2c:cf:67:00:00:01"),
"a MAC survived: {page}"
);
}
#[test]
fn a_caller_can_name_the_page() {
let (before, after) = fixture::compared();
let diff = ScanDiff::between(&before, &after);
let mut bytes = Vec::new();
HtmlDiffExporter::default()
.with_heading("Acme, week 32")
.export(&diff, &mut bytes)
.expect("the export succeeds");
let page = String::from_utf8(bytes).expect("text");
assert!(page.contains("<title>Acme, week 32</title>"), "{page}");
assert!(page.contains("<h1>Acme, week 32</h1>"), "{page}");
}
}