use std::io::Write;
use crate::diff::{HostDelta, Presence, ScanDiff};
use crate::export::diff::DiffExporter;
use crate::export::diff::schema::{ChangeDto, DiffDto, HostDeltaDto, PortDeltaDto};
use crate::export::html::{Plain, STYLE, TONE_FOUND, TONE_INERT, TONE_NONE, TONE_PARTIAL, Text};
use crate::export::schema::ENGINE_NAME;
use crate::export::{ExportError, ExportOptions};
use crate::scanner::report::ENGINE_VERSION;
const DEFAULT_HEADING: &str = "Scan comparison";
#[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, &document)?;
write_colophon(out, &document)?;
writeln!(out, "</div>\n</body>\n</html>")?;
Ok(())
}
}
fn write_head(out: &mut dyn Write, title: &str) -> Result<(), ExportError> {
writeln!(
out,
r#"<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="generator" content="{ENGINE_NAME} {ENGINE_VERSION}">
<meta name="robots" content="noindex, nofollow">
<title>{title}</title>
<style>
{STYLE}</style>
</head>
<body>
<input type="checkbox" id="zond-theme" class="theme-switch" aria-label="Use the other colour scheme">
<div class="sheet">"#,
title = Plain(title),
)?;
Ok(())
}
fn write_masthead(
out: &mut dyn Write,
heading: &str,
document: &DiffDto<'_>,
) -> Result<(), ExportError> {
writeln!(
out,
r#"<header class="masthead">
<div class="brand">zond<span class="brand-mark">_</span></div>
<div class="masthead-title">
<h1>{heading}</h1>
<p class="subtitle">{before} → {after}</p>
</div>
<label class="theme-label" for="zond-theme" title="Switch between light and dark"><span class="theme-icon"></span>theme</label>
</header>"#,
heading = Text(heading),
before = Text(&document.baseline.at),
after = Text(&document.current.at),
)?;
Ok(())
}
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 {
let class = if alert {
"notice notice-alert"
} else {
"notice"
};
writeln!(
out,
"<span class=\"{class}\"><span class=\"notice-key\">{key}</span><span>{text}</span></span>",
key = Text(key),
text = Text(&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"),
};
tile(out, count.total, label, ¬e)?;
}
tile(
out,
summary.hosts_changed,
"hosts changed",
"in both scans, and different",
)?;
tile(
out,
summary.certificates_rotated + summary.certificates_expiring + summary.certificates_expired,
"certificates",
"rotated, expiring or lapsed",
)?;
writeln!(out, "</div>")?;
Ok(())
}
fn tile(out: &mut dyn Write, value: usize, label: &str, note: &str) -> Result<(), ExportError> {
writeln!(
out,
"<div class=\"tile\"><div class=\"tile-value\">{value}</div><div class=\"tile-label\">{label}</div><div class=\"tile-note\">{note}</div></div>",
label = Text(label),
note = Text(note),
)?;
Ok(())
}
fn write_hosts(
out: &mut dyn Write,
diff: &ScanDiff,
document: &DiffDto<'_>,
) -> Result<(), ExportError> {
if document.hosts.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>",
document.hosts.len()
)?;
for (delta, dto) in diff.hosts().iter().zip(&document.hosts) {
write_host(out, delta, dto)?;
}
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>")?;
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") => {
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::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::scanner::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 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(192, 168, 0, 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 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:f2:51:e3"),
"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}");
}
}