Skip to main content

zond_engine/
diff.rs

1// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
2//
3// This file is part of Zond Engine, licensed under the GNU Affero General
4// Public License, version 3 or later. See the LICENSE file for details, or
5// <https://www.gnu.org/licenses/agpl-3.0.html>.
6//
7// SPDX-License-Identifier: AGPL-3.0-or-later
8
9//! # Comparing two scans
10//!
11//! Scan a network, scan it again a week later, and ask what changed: a host that
12//! appeared, a port that opened, a service that moved a version, a certificate that
13//! rotated or is about to lapse. [`ScanDiff`] holds all of that as a structure,
14//! computed from two [`ScanReport`]s, and leaves presentation to the caller.
15//!
16//! ```no_run
17//! use zond_engine::diff::{ScanDiff, Significance};
18//! # use zond_engine::report::ScanReport;
19//! # fn example(last_week: &ScanReport, today: &ScanReport) {
20//! let diff = ScanDiff::between(last_week, today);
21//!
22//! let summary = diff.summary();
23//! println!(
24//!     "{} hosts appeared, {} gone, {} ports opened",
25//!     summary.hosts_added.total, summary.hosts_removed.total, summary.ports_opened.total,
26//! );
27//!
28//! for host in diff.hosts() {
29//!     if host.significance() < Significance::Notable {
30//!         continue;
31//!     }
32//!     for port in host.ports() {
33//!         if port.is_opened() {
34//!             println!("{}:{} is open", host.address(), port.number());
35//!         }
36//!     }
37//! }
38//! # }
39//! ```
40//!
41//! ## Which of it matters
42//!
43//! Two scans of a live network always differ somewhere, mostly in things like reverse
44//! names. [`Significance`] grades each change by how much it is worth acting on, and
45//! [`significance`] holds the whole policy behind that grade.
46//!
47//! Whether a change happened at all is a separate question, answered by
48//! [`Presence::is_confirmed`] below. The two meet only at the delta, where a caller
49//! wants one number to sort by.
50//!
51//! ## Any two reports
52//!
53//! The comparison takes [`ScanReport`]s from any source: a scan this process just
54//! ran, one read back from a [`journal`](crate::journal), or a report built from
55//! another scanner's output. Comparing last quarter's nmap output against tonight's
56//! scan is the same call as comparing two of this engine's own runs.
57//!
58//! So nothing here depends on a field only this engine fills in. A report with no
59//! phases, scope, probe statistics or hardware addresses still compares, and answers
60//! "unstated" where its record has nothing to say (see below).
61//!
62//! ## Verdicts are compared, evidence is not
63//!
64//! A report carries findings about the network and measurements about the scan,
65//! which [`report`](crate::report) keeps apart. Only the findings are compared.
66//!
67//! A host's status, a port's state and a service's identity are compared; the probe,
68//! packet or confidence behind each is not. An operating system is compared by what
69//! it names, and only where the current scan named one: a scan that identified no
70//! system or saw no hardware address found nothing out about either, so their
71//! absence is not a change.
72//!
73//! Left out entirely: round-trip times, hop counters, measured routes, capture
74//! counters, per-scanner probe statistics, first- and last-seen timestamps, and
75//! strategy failures. All of them move between two scans of an unchanged network.
76//!
77//! ## What "gone" can mean
78//!
79//! A host in last week's report and missing from tonight's either went away or was
80//! not scanned, and a monitoring tool that cannot tell those apart raises an alarm
81//! every time somebody narrows a scan. So every appearance and disappearance carries
82//! [`Coverage`]: what the other scan says about whether it covered that target.
83//!
84//! That comes from [`TargetScope`](crate::report::TargetScope). Each phase records the
85//! ranges it walked after exclusions and the ranges its policy withheld, so an
86//! address falls in one, the other, or neither. A report with no scope answers
87//! [`Coverage::Unstated`], and [`Presence::is_confirmed`] is the test that separates a
88//! host that went away from a host nobody asked about.
89//!
90//! A phase stopped partway names the addresses it never reached a verdict on in
91//! [`ScanPhase::undecided`](crate::report::ScanPhase::undecided). Those addresses and
92//! their endpoints answer [`Coverage::Unreached`], so a sweep cut short reports the
93//! hosts it never got to as unreached.
94//!
95//! Ports are a weaker case. A scope records the addresses a phase walked but not the
96//! ports it walked on each, so an endpoint of a covered address answers `Unstated`.
97//! Where the address itself was withheld or out of scope, the endpoint inherits that.
98//!
99//! A port the scan named and never reached is recorded
100//! [`PortState::Unasked`](crate::model::port::PortState::Unasked). That record says
101//! how far the scan got, which is more than the scope says, so it overrules the
102//! scope and the endpoint answers [`Coverage::Unreached`].
103//!
104//! Such a port is read as a side with no record at all. Read as a state, 443 unasked
105//! against 443 open would be a state that moved: a [`Presence::Both`] where
106//! [`Presence::is_confirmed`] answers true, telling a consumer that alerts on it that
107//! a port opened when the scan never looked. Read as no record, a run the wall clock
108//! cut short reports the ports it never got to as unreached.
109//!
110//! Findings ask the same question one level down. A finding drawn from what a TLS
111//! endpoint accepts rests on the version walks that drew it; where the current scan
112//! cut one short or made no enumeration, the finding's absence only says how far
113//! the scan got, and [`PortChange::Findings`] carries it as unsettled. A finding
114//! drawn from a certificate's posture is unsettled when the current scan recorded no
115//! certificate (a failed handshake, or a leaf that would not parse). A vulnerability
116//! correlation is unsettled when the current scan identified nothing on the
117//! endpoint, labelled it by port number alone, or named the software without a
118//! version.
119//!
120//! ## Which record continues which
121//!
122//! Hosts do not pair by address alone: a machine can change address between two
123//! scans, and one scan can see as a single host what another sees as two. That
124//! decision belongs to [`HostIdentity`], a field of [`DiffOptions`], and [`pairing`]
125//! explains how it is made.
126//!
127//! ## Which clock a certificate is judged against
128//!
129//! "Expiring within thirty days" depends on the moment it is asked, so each side is
130//! judged against its own scan's clock: the baseline at the baseline's start time,
131//! the current side at the current scan's. An untouched certificate then crosses the
132//! threshold once, between the two scans that straddle it, which makes it a change.
133//!
134//! A report with no phases has no start time, so the latest sighting among its hosts
135//! is used. [`DiffOptions::as_of`] overrides the current side's clock, for a caller
136//! asking where things stand today.
137
138pub mod change;
139pub mod host;
140pub mod pairing;
141pub mod port;
142mod scope;
143pub mod significance;
144
145use std::time::{Duration, SystemTime};
146
147use crate::model::host::Host;
148use crate::report::{ScanKind, ScanReport};
149
150pub use crate::diff::change::{Change, Coverage, Presence};
151pub use crate::diff::host::{HostChange, HostDelta};
152pub use crate::diff::pairing::HostIdentity;
153pub use crate::diff::port::{
154    CertificateChange, PortChange, PortDelta, SecurityChange, ServiceChange,
155};
156pub use crate::diff::significance::Significance;
157
158use crate::diff::port::Clocks;
159use crate::diff::scope::ScopeIndex;
160
161/// How long before a certificate lapses it counts as expiring, when a caller
162/// does not say.
163///
164/// Thirty days is when the major certificate authorities send their first renewal
165/// notice, and what most monitoring templates ship with.
166pub const DEFAULT_EXPIRY_THRESHOLD: Duration = Duration::from_secs(30 * 24 * 60 * 60);
167
168/// What a comparison is allowed to assume.
169///
170/// The defaults suit two scans of the same network by the same tool. Change
171/// [`identity`](Self::with_identity) when addresses are not stable between the
172/// two, and [`as_of`](Self::as_of) to judge certificates at a moment other than
173/// when the scan ran.
174#[must_use]
175#[derive(Debug, Clone, PartialEq, Eq)]
176pub struct DiffOptions {
177    identity: HostIdentity,
178    expiry_threshold: Duration,
179    as_of: Option<SystemTime>,
180}
181
182impl Default for DiffOptions {
183    fn default() -> Self {
184        Self {
185            identity: HostIdentity::default(),
186            expiry_threshold: DEFAULT_EXPIRY_THRESHOLD,
187            as_of: None,
188        }
189    }
190}
191
192impl DiffOptions {
193    /// The defaults: hosts pair by any shared address, certificates are expiring
194    /// within [`DEFAULT_EXPIRY_THRESHOLD`], and each side is judged against its
195    /// own scan's clock.
196    pub fn new() -> Self {
197        Self::default()
198    }
199
200    /// Sets what makes two records the same host.
201    pub fn with_identity(mut self, identity: HostIdentity) -> Self {
202        self.identity = identity;
203        self
204    }
205
206    /// Sets how long before it lapses a certificate counts as expiring.
207    pub fn with_expiry_threshold(mut self, threshold: Duration) -> Self {
208        self.expiry_threshold = threshold;
209        self
210    }
211
212    /// Judges the current scan's certificates as of `at`.
213    ///
214    /// For asking where a stored scan's certificates stand today. The baseline is
215    /// still judged at its own clock, since the change is the two standings
216    /// differing.
217    pub fn as_of(mut self, at: SystemTime) -> Self {
218        self.as_of = Some(at);
219        self
220    }
221
222    /// What makes two records the same host.
223    pub fn identity(&self) -> HostIdentity {
224        self.identity
225    }
226
227    /// How long before it lapses a certificate counts as expiring.
228    pub fn expiry_threshold(&self) -> Duration {
229        self.expiry_threshold
230    }
231
232    /// The moment the current scan's certificates are judged at, if the caller
233    /// set one.
234    pub fn as_of_time(&self) -> Option<SystemTime> {
235        self.as_of
236    }
237}
238
239/// Which scan one side of a comparison was.
240///
241/// Carried so a diff can be rendered without the reports it was taken from, as a
242/// front end that computes the diff on a server and sends it to a browser must.
243#[derive(Debug, Clone, PartialEq, Eq)]
244pub struct Provenance {
245    engine_version: String,
246    at: SystemTime,
247    hosts: usize,
248    kinds: Vec<ScanKind>,
249    scope_stated: bool,
250}
251
252impl Provenance {
253    /// The engine that produced the report, as it attributed itself.
254    ///
255    /// A report built from another scanner's output says whatever its builder
256    /// recorded, so this does not prove this crate ran the scan.
257    pub fn engine_version(&self) -> &str {
258        &self.engine_version
259    }
260
261    /// The moment the scan is taken to have happened, which certificates were
262    /// judged against.
263    pub fn at(&self) -> SystemTime {
264        self.at
265    }
266
267    /// How many hosts the report held.
268    pub fn hosts(&self) -> usize {
269        self.hosts
270    }
271
272    /// Which phases the report recorded, in the order they ran. Empty for a
273    /// report that carries none.
274    pub fn kinds(&self) -> &[ScanKind] {
275        &self.kinds
276    }
277
278    /// Whether the report says what it covered.
279    ///
280    /// False makes every [`Coverage`] answer about this side
281    /// [`Unstated`](Coverage::Unstated), so an appearance or a disappearance
282    /// against it cannot be confirmed.
283    pub fn states_scope(&self) -> bool {
284        self.scope_stated
285    }
286}
287
288/// What changed between two scans.
289///
290/// Built by [`between`](Self::between) or [`compare`](Self::compare). Holds one
291/// [`HostDelta`] per host that differs, ascending by address, and nothing for
292/// the hosts that did not.
293#[derive(Debug, Clone)]
294#[must_use = "a diff is the answer to what changed; dropping it discards it"]
295pub struct ScanDiff {
296    baseline: Provenance,
297    current: Provenance,
298    hosts: Vec<HostDelta>,
299}
300
301impl ScanDiff {
302    /// Compares two scans under the default [`DiffOptions`].
303    pub fn between(baseline: &ScanReport, current: &ScanReport) -> Self {
304        Self::compare(baseline, current, &DiffOptions::default())
305    }
306
307    /// Compares two scans.
308    ///
309    /// `baseline` is the earlier scan and `current` the later one. The order is not
310    /// checked: reports handed over the other way round give a diff that reads
311    /// backwards.
312    ///
313    /// An address either scan found [`silent`](crate::report::ScanPhase::silent)
314    /// on every port, and the other lists with nothing heard from it, is compared
315    /// as no host on both sides. That case arises when one scan recorded every
316    /// address as a host and the other used its port probes as the liveness pass;
317    /// neither heard anything, so the difference is the scans' settings and not
318    /// the network.
319    pub fn compare(baseline: &ScanReport, current: &ScanReport, options: &DiffOptions) -> Self {
320        let quiet = silent_in(baseline, current);
321        let heard = |host: &&Host| {
322            host.status() != crate::model::host::HostStatus::Unknown
323                || !host.ips().iter().any(|ip| quiet.contains(ip))
324        };
325        let baseline_hosts: Vec<&Host> = baseline.hosts().filter(heard).collect();
326        let current_hosts: Vec<&Host> = current.hosts().filter(heard).collect();
327
328        let baseline_scope = ScopeIndex::of(baseline);
329        let current_scope = ScopeIndex::of(current);
330
331        let clocks = Clocks {
332            baseline: baseline.observed_at(),
333            current: options.as_of.unwrap_or_else(|| current.observed_at()),
334            expiry_threshold: options.expiry_threshold,
335        };
336
337        let components = pairing::components(&baseline_hosts, &current_hosts, options.identity);
338
339        let mut hosts: Vec<HostDelta> = components
340            .into_iter()
341            .map(|component| {
342                let before = merged(&baseline_hosts, &component.baseline);
343                let after = merged(&current_hosts, &component.current);
344
345                // Both sides' coverage is asked about the address the delta is
346                // keyed by.
347                let address = after
348                    .as_ref()
349                    .or(before.as_ref())
350                    .map(Host::primary_ip)
351                    .expect("a component holds a record on at least one side");
352
353                host::compare(
354                    before.as_ref(),
355                    after.as_ref(),
356                    component.baseline.len(),
357                    component.current.len(),
358                    &baseline_scope,
359                    &current_scope,
360                    &address,
361                    &clocks,
362                )
363            })
364            .filter(|delta| !delta.is_empty())
365            .collect();
366
367        hosts.sort_by_key(HostDelta::address);
368
369        Self {
370            baseline: Provenance {
371                engine_version: baseline.engine_version().to_owned(),
372                at: clocks.baseline,
373                hosts: baseline_hosts.len(),
374                kinds: baseline.phases().iter().map(|phase| phase.kind()).collect(),
375                scope_stated: baseline_scope.states_scope(),
376            },
377            current: Provenance {
378                engine_version: current.engine_version().to_owned(),
379                at: clocks.current,
380                hosts: current_hosts.len(),
381                kinds: current.phases().iter().map(|phase| phase.kind()).collect(),
382                scope_stated: current_scope.states_scope(),
383            },
384            hosts,
385        }
386    }
387
388    /// Which scan the baseline side was.
389    pub fn baseline(&self) -> &Provenance {
390        &self.baseline
391    }
392
393    /// Which scan the current side was.
394    pub fn current(&self) -> &Provenance {
395        &self.current
396    }
397
398    /// Every host that differs, ascending by address.
399    pub fn hosts(&self) -> &[HostDelta] {
400        &self.hosts
401    }
402
403    /// Whether the two scans describe the same network.
404    ///
405    /// True means nothing this module compares moved. The reports may still
406    /// differ in their measurements, which are not compared.
407    pub fn is_empty(&self) -> bool {
408        self.hosts.is_empty()
409    }
410
411    /// Counts derived from the deltas.
412    ///
413    /// Computed on demand, so a summary cannot disagree with the deltas it
414    /// describes.
415    pub fn summary(&self) -> DiffSummary {
416        let mut summary = DiffSummary::default();
417
418        for host in &self.hosts {
419            match host.presence() {
420                Presence::Added { .. } => summary.hosts_added.count(host.presence()),
421                Presence::Removed { .. } => summary.hosts_removed.count(host.presence()),
422                Presence::Both => {
423                    if !host.changes().is_empty() || !host.ports().is_empty() {
424                        summary.hosts_changed += 1;
425                    }
426                }
427            }
428
429            for port in host.ports() {
430                if port.is_opened() {
431                    summary.ports_opened.count(port.presence());
432                }
433                if port.is_closed() {
434                    summary.ports_closed.count(port.presence());
435                }
436                if port.presence().is_in_both() && !port.changes().is_empty() {
437                    summary.ports_changed += 1;
438                }
439
440                // No wildcard arm: a new kind of change fails to compile here
441                // until somebody decides whether it belongs in the counters.
442                let mut service_moved = false;
443                for change in port.changes() {
444                    match change {
445                        PortChange::Service(_) => service_moved = true,
446                        PortChange::Security(SecurityChange::Certificate(certificate)) => {
447                            match certificate {
448                                CertificateChange::Rotated { .. } => {
449                                    summary.certificates_rotated += 1;
450                                }
451                                CertificateChange::Expiring { .. } => {
452                                    summary.certificates_expiring += 1;
453                                }
454                                CertificateChange::Expired { .. } => {
455                                    summary.certificates_expired += 1;
456                                }
457                                // Already counted by `ports_changed`, and not
458                                // a renewal concern.
459                                CertificateChange::Presented(_)
460                                | CertificateChange::Withdrawn(_) => {}
461                            }
462                        }
463                        // Counted above, through `is_opened` and `is_closed`.
464                        PortChange::State(_) => {}
465                        // Reported in the deltas, not a headline number.
466                        PortChange::Security(
467                            SecurityChange::TlsVersion(_)
468                            | SecurityChange::CipherSuite(_)
469                            | SecurityChange::Alpn { .. },
470                        ) => {}
471                        // Readers sort findings by their own severity, read off
472                        // the delta.
473                        PortChange::Findings { .. } => {}
474                    }
475                }
476                if service_moved {
477                    summary.services_changed += 1;
478                }
479            }
480        }
481
482        summary
483    }
484}
485
486/// A count of records, and how many of them the other scan is known to have
487/// looked for.
488///
489/// Three hosts appearing is a finding when the baseline covered all three addresses,
490/// and only a wider scan when it covered none of them. A front end printing one of
491/// the two should print [`confirmed`](Self::confirmed).
492#[non_exhaustive]
493#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
494pub struct Confirmed {
495    /// How many records, whatever the other scan covered.
496    pub total: usize,
497    /// How many of them the other scan is known to have covered: the ones that
498    /// are findings about the network.
499    pub confirmed: usize,
500}
501
502impl Confirmed {
503    fn count(&mut self, presence: Presence) {
504        self.total += 1;
505        if presence.is_confirmed() {
506            self.confirmed += 1;
507        }
508    }
509}
510
511/// Counts derived from a comparison.
512///
513/// The numbers a front end leads with, all derived from [`ScanDiff::hosts`], where
514/// the detail behind each one is.
515#[non_exhaustive]
516#[derive(Debug, Clone, Default, PartialEq, Eq)]
517pub struct DiffSummary {
518    /// Hosts only the current scan has a record for.
519    pub hosts_added: Confirmed,
520    /// Hosts only the baseline has a record for.
521    pub hosts_removed: Confirmed,
522    /// Hosts both scans have, that differ.
523    pub hosts_changed: usize,
524    /// Endpoints that started accepting connections, by changing state or by
525    /// appearing.
526    pub ports_opened: Confirmed,
527    /// Endpoints that stopped accepting connections, by changing state or by
528    /// disappearing.
529    pub ports_closed: Confirmed,
530    /// Endpoints both scans have, that differ.
531    pub ports_changed: usize,
532    /// Endpoints where what is listening changed or was first identified.
533    pub services_changed: usize,
534    /// Endpoints presenting a different certificate than the baseline.
535    pub certificates_rotated: usize,
536    /// Endpoints whose certificate is inside the expiry threshold at the current
537    /// clock and was outside it at the baseline's.
538    pub certificates_expiring: usize,
539    /// Endpoints whose certificate has lapsed since the baseline ran.
540    pub certificates_expired: usize,
541}
542
543/// One side of a component as a single host: the record itself where there is
544/// one, and the records folded together where there are several.
545fn merged(hosts: &[&Host], indices: &[usize]) -> Option<Host> {
546    let (first, rest) = indices.split_first()?;
547
548    let mut merged = hosts[*first].clone();
549    for index in rest {
550        merged.merge(hosts[*index].clone());
551    }
552    Some(merged)
553}
554
555/// Every address a phase of either report names silent, as one set.
556fn silent_in(baseline: &ScanReport, current: &ScanReport) -> crate::model::ip::set::IpSet {
557    let mut quiet = crate::model::ip::set::IpSet::new();
558    for phase in baseline.phases().iter().chain(current.phases()) {
559        for range in phase.silent() {
560            quiet.insert_range(*range);
561        }
562    }
563    quiet.canonicalize();
564    quiet
565}
566
567#[cfg(test)]
568mod tests {
569    use crate::system::privilege::Privilege;
570    use std::net::{IpAddr, Ipv4Addr};
571    use std::time::Duration;
572
573    use super::*;
574    use crate::config::ZondConfig;
575    use crate::model::exclusion::Exclusions;
576    use crate::model::host::os::OsFingerprint;
577    use crate::model::host::{Host, HostStatus};
578    use crate::model::parse::ip::to_set;
579    use crate::model::port::security::CertificateInfo;
580    use crate::model::port::{Port, PortSet, PortState, Protocol, Security, Service};
581    use crate::report::{
582        PhaseParts, PortScope, ScanKind, ScanPhase, ScanReport, ScanSettings, ScopeParts,
583        TargetScope,
584    };
585
586    const DAY: Duration = Duration::from_secs(24 * 60 * 60);
587
588    fn ip(last: u8) -> IpAddr {
589        IpAddr::V4(Ipv4Addr::new(203, 0, 113, last))
590    }
591
592    fn host(last: u8) -> Host {
593        let mut host = Host::new(ip(last));
594        host.set_status(HostStatus::Up);
595        host
596    }
597
598    /// How long the phases these helpers build ran for.
599    ///
600    /// Zero, so a report's clock is the `at` its helper was given. A report is
601    /// placed by when it finished, and any duration would move its clock off the
602    /// named `at`, which the certificate tests would read as a threshold crossed
603    /// early.
604    const PROMPT: Duration = Duration::ZERO;
605
606    /// A port scan over `covered` that ran with no liveness pass and found the
607    /// addresses in `silent` quiet on every port.
608    fn found_silent(covered: &str, silent: &str, at: SystemTime) -> ScanReport {
609        let mut targets = to_set(&[covered], None, None).expect("a parseable range");
610        let silent = to_set(&[silent], None, None).expect("a parseable range");
611        let phase = ScanPhase::from_parts(PhaseParts {
612            open: false,
613            attachments: Vec::new(),
614            kind: ScanKind::PortScan,
615            started_at: at,
616            elapsed: PROMPT,
617            privilege: Some(Privilege::Raw),
618            targets: TargetScope::from_ip_set(&mut targets, &Exclusions::none()),
619            settings: ScanSettings::from(&ZondConfig::default()),
620            failures: Vec::new(),
621            refusals: Vec::new(),
622            unroutable: Vec::new(),
623            refused_by_route: Vec::new(),
624            timed_out: Vec::new(),
625            icmp_rate_limited: Vec::new(),
626            reached_by_connect: Vec::new(),
627            undecided: Vec::new(),
628            liveness_skipped: Some(crate::report::LivenessSkip::PortsNoDearer),
629            silent: silent
630                .v4()
631                .iter()
632                .copied()
633                .map(crate::model::ip::range::IpRange::V4)
634                .collect(),
635            stopped: None,
636            passes_cut: Vec::new(),
637            unreached: 0,
638            unheard_probes: 0,
639            probes: Vec::new(),
640            origin: None,
641        });
642
643        ScanReport::recorded("test", vec![phase], Vec::new())
644    }
645
646    /// A report that says nothing about what it covered, as a foreign scanner's
647    /// output reads.
648    fn unscoped(hosts: Vec<Host>) -> ScanReport {
649        ScanReport::recorded("test", Vec::new(), hosts)
650    }
651
652    /// A report whose single phase walked `covered` and was forbidden `excluded`.
653    fn scoped(hosts: Vec<Host>, covered: &str, excluded: &[&str], at: SystemTime) -> ScanReport {
654        let mut targets = to_set(&[covered], None, None).expect("a parseable range");
655        let exclusions = if excluded.is_empty() {
656            Exclusions::none()
657        } else {
658            Exclusions::new(to_set(excluded, None, None).expect("a parseable range"))
659        };
660        let scope = TargetScope::from_ip_set(&mut targets, &exclusions);
661
662        let phase = ScanPhase::from_parts(PhaseParts {
663            open: false,
664            attachments: Vec::new(),
665            kind: ScanKind::Discovery,
666            started_at: at,
667            elapsed: PROMPT,
668            privilege: Some(Privilege::Raw),
669            targets: scope,
670            settings: ScanSettings::from(&ZondConfig::default()),
671            failures: Vec::new(),
672            refusals: Vec::new(),
673            unroutable: Vec::new(),
674            refused_by_route: Vec::new(),
675            timed_out: Vec::new(),
676            icmp_rate_limited: Vec::new(),
677            reached_by_connect: Vec::new(),
678            undecided: Vec::new(),
679            liveness_skipped: None,
680            silent: Vec::new(),
681            stopped: None,
682            passes_cut: Vec::new(),
683            unreached: 0,
684            unheard_probes: 0,
685            probes: Vec::new(),
686            origin: None,
687        });
688
689        ScanReport::recorded("test", vec![phase], hosts)
690    }
691
692    /// A report whose phase walked `covered` and probed `ports` on it.
693    fn port_scanned(
694        hosts: Vec<Host>,
695        covered: &str,
696        ports: PortScope,
697        at: SystemTime,
698    ) -> ScanReport {
699        let mut targets = to_set(&[covered], None, None).expect("a parseable range");
700        let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
701        let scope = TargetScope::from_parts(ScopeParts {
702            listened: Vec::new(),
703            ranges: scope.ranges().to_vec(),
704            links: Vec::new(),
705            addresses: scope.addresses(),
706            probes: None,
707            ports,
708            protocols: vec![Protocol::Tcp],
709            excluded: Vec::new(),
710            withheld: 0,
711        });
712
713        let phase = ScanPhase::from_parts(PhaseParts {
714            open: false,
715            attachments: Vec::new(),
716            kind: ScanKind::PortScan,
717            started_at: at,
718            elapsed: PROMPT,
719            privilege: Some(Privilege::Raw),
720            targets: scope,
721            settings: ScanSettings::from(&ZondConfig::default()),
722            failures: Vec::new(),
723            refusals: Vec::new(),
724            unroutable: Vec::new(),
725            refused_by_route: Vec::new(),
726            timed_out: Vec::new(),
727            icmp_rate_limited: Vec::new(),
728            reached_by_connect: Vec::new(),
729            undecided: Vec::new(),
730            liveness_skipped: None,
731            silent: Vec::new(),
732            stopped: None,
733            passes_cut: Vec::new(),
734            unreached: 0,
735            unheard_probes: 0,
736            probes: Vec::new(),
737            origin: None,
738        });
739
740        ScanReport::recorded("test", vec![phase], hosts)
741    }
742
743    /// A report whose phase swept `covered` and also swept the link on `link`.
744    fn swept(hosts: Vec<Host>, covered: &str, link: &str, at: SystemTime) -> ScanReport {
745        use crate::model::ip::scoped::Zone;
746
747        let mut targets = to_set(&[covered], None, None).expect("a parseable range");
748        let scope = TargetScope::from_ip_set(&mut targets, &Exclusions::none());
749        let scope = TargetScope::from_parts(ScopeParts {
750            listened: Vec::new(),
751            ranges: scope.ranges().to_vec(),
752            links: vec![Zone::new(1, link)],
753            addresses: scope.addresses(),
754            probes: None,
755            ports: PortScope::NoPorts,
756            protocols: Vec::new(),
757            excluded: Vec::new(),
758            withheld: 0,
759        });
760
761        let phase = ScanPhase::from_parts(PhaseParts {
762            open: false,
763            attachments: Vec::new(),
764            kind: ScanKind::Discovery,
765            started_at: at,
766            elapsed: PROMPT,
767            privilege: Some(Privilege::Raw),
768            targets: scope,
769            settings: ScanSettings::from(&ZondConfig::default()),
770            failures: Vec::new(),
771            refusals: Vec::new(),
772            unroutable: Vec::new(),
773            refused_by_route: Vec::new(),
774            timed_out: Vec::new(),
775            icmp_rate_limited: Vec::new(),
776            reached_by_connect: Vec::new(),
777            undecided: Vec::new(),
778            liveness_skipped: None,
779            silent: Vec::new(),
780            stopped: None,
781            passes_cut: Vec::new(),
782            unreached: 0,
783            unheard_probes: 0,
784            probes: Vec::new(),
785            origin: None,
786        });
787
788        ScanReport::recorded("test", vec![phase], hosts)
789    }
790
791    /// A host reachable only at a link-local address on `link`.
792    fn neighbour(last: u16, link: &str) -> Host {
793        use crate::model::ip::scoped::Zone;
794        use std::net::Ipv6Addr;
795
796        let mut host = Host::new(IpAddr::V6(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, last)));
797        host.set_status(HostStatus::Up);
798        host.set_zone(Zone::new(1, link));
799        host
800    }
801
802    fn ports(spec: &str) -> PortSet {
803        PortSet::try_from(spec).expect("a port specification")
804    }
805
806    fn certificate(fingerprint: &str, start: SystemTime, end: SystemTime) -> Security {
807        Security::new().with_certificate(CertificateInfo::new(
808            "example.test",
809            "Test CA",
810            start,
811            end,
812            fingerprint,
813        ))
814    }
815
816    // -----------------------------------------------------------------------
817    // Nothing changed
818    // -----------------------------------------------------------------------
819
820    #[test]
821    fn two_scans_that_found_the_same_things_report_nothing() {
822        let build = || {
823            let mut h = host(10);
824            h.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
825            unscoped(vec![h])
826        };
827
828        let diff = ScanDiff::between(&build(), &build());
829
830        assert!(diff.is_empty(), "an unchanged network is an empty diff");
831        assert_eq!(diff.summary(), DiffSummary::default());
832    }
833
834    #[test]
835    fn a_round_trip_time_is_not_a_change() {
836        let mut before = host(10);
837        before.add_rtt(Duration::from_millis(4));
838        let mut after = host(10);
839        after.add_rtt(Duration::from_millis(91));
840
841        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
842
843        assert!(
844            diff.is_empty(),
845            "how fast the host answered is a measurement of the scan, not a finding"
846        );
847    }
848
849    #[test]
850    fn a_more_confident_reading_of_the_same_system_is_not_a_change() {
851        let mut before = host(10);
852        before.set_os(OsFingerprint::new("Linux", 74).with_family("Unix-like"));
853        let mut after = host(10);
854        after.set_os(OsFingerprint::new("Linux", 98).with_family("Unix-like"));
855
856        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
857
858        assert!(
859            diff.is_empty(),
860            "the fingerprinter growing surer of the same answer is not a change"
861        );
862    }
863
864    #[test]
865    fn a_different_system_is_a_change() {
866        let mut before = host(10);
867        before.set_os(OsFingerprint::new("Linux", 90));
868        let mut after = host(10);
869        after.set_os(OsFingerprint::new("Windows", 90));
870
871        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
872
873        let changes = diff.hosts()[0].changes();
874        assert!(matches!(changes[0], HostChange::Os(_)), "{changes:?}");
875    }
876
877    // -----------------------------------------------------------------------
878    // Coverage: what a missing record is allowed to mean
879    // -----------------------------------------------------------------------
880
881    #[test]
882    fn a_host_that_appeared_where_the_baseline_looked_is_confirmed() {
883        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
884        let before = scoped(vec![host(10)], "203.0.113.0/24", &[], at);
885        let after = scoped(vec![host(10), host(11)], "203.0.113.0/24", &[], at + DAY);
886
887        let diff = ScanDiff::compare(&before, &after, &DiffOptions::default());
888
889        let appeared = diff
890            .hosts()
891            .iter()
892            .find(|delta| delta.address() == ip(11))
893            .expect("the new host is in the diff");
894
895        assert_eq!(
896            appeared.presence(),
897            Presence::Added {
898                before: Coverage::Covered
899            }
900        );
901        assert!(appeared.presence().is_confirmed());
902        assert_eq!(diff.summary().hosts_added.confirmed, 1);
903    }
904
905    #[test]
906    fn a_host_that_appeared_where_the_baseline_never_looked_is_not_confirmed() {
907        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
908        // The baseline walked a quarter of the segment. The host that turns up
909        // in the wider scan was never in reach of the first one.
910        let before = scoped(vec![host(10)], "203.0.113.0/26", &[], at);
911        let after = scoped(vec![host(10), host(200)], "203.0.113.0/24", &[], at + DAY);
912
913        let diff = ScanDiff::between(&before, &after);
914
915        let appeared = diff
916            .hosts()
917            .iter()
918            .find(|delta| delta.address() == ip(200))
919            .expect("the new host is in the diff");
920
921        assert_eq!(
922            appeared.presence(),
923            Presence::Added {
924                before: Coverage::OutOfScope
925            }
926        );
927        assert!(!appeared.presence().is_confirmed());
928
929        let summary = diff.summary();
930        assert_eq!(summary.hosts_added.total, 1);
931        assert_eq!(
932            summary.hosts_added.confirmed, 0,
933            "a host nobody had looked for is not a host that appeared"
934        );
935    }
936
937    #[test]
938    fn a_host_the_current_scan_was_forbidden_reads_as_withheld() {
939        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
940        let before = scoped(vec![host(10), host(11)], "203.0.113.0/24", &[], at);
941        let after = scoped(
942            vec![host(10)],
943            "203.0.113.0/24",
944            &["203.0.113.11"],
945            at + DAY,
946        );
947
948        let diff = ScanDiff::between(&before, &after);
949
950        let gone = diff
951            .hosts()
952            .iter()
953            .find(|delta| delta.address() == ip(11))
954            .expect("the missing host is in the diff");
955
956        assert_eq!(
957            gone.presence(),
958            Presence::Removed {
959                after: Coverage::Withheld
960            },
961            "an address a policy forbade is not an address that went quiet"
962        );
963        assert!(!gone.presence().is_confirmed());
964    }
965
966    #[test]
967    fn a_report_that_states_no_scope_answers_unstated() {
968        let before = unscoped(vec![host(10), host(11)]);
969        let after = unscoped(vec![host(10)]);
970
971        let diff = ScanDiff::between(&before, &after);
972
973        let gone = diff
974            .hosts()
975            .iter()
976            .find(|delta| delta.address() == ip(11))
977            .expect("the missing host is in the diff");
978
979        assert_eq!(
980            gone.presence(),
981            Presence::Removed {
982                after: Coverage::Unstated
983            },
984            "a report that does not say what it walked cannot confirm a disappearance"
985        );
986        assert!(!gone.presence().is_confirmed());
987        assert_eq!(diff.summary().hosts_removed.confirmed, 0);
988    }
989
990    #[test]
991    fn a_host_that_went_quiet_where_the_scan_looked_is_confirmed() {
992        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
993        let before = scoped(vec![host(10), host(11)], "203.0.113.0/24", &[], at);
994        let after = scoped(vec![host(10)], "203.0.113.0/24", &[], at + DAY);
995
996        let diff = ScanDiff::between(&before, &after);
997        let summary = diff.summary();
998
999        assert_eq!(summary.hosts_removed.total, 1);
1000        assert_eq!(summary.hosts_removed.confirmed, 1);
1001    }
1002
1003    // -----------------------------------------------------------------------
1004    // Ports
1005    // -----------------------------------------------------------------------
1006
1007    #[test]
1008    fn a_port_that_opened_is_counted_once() {
1009        let mut before = host(10);
1010        before.add_port(Port::new(8080, Protocol::Tcp, PortState::Closed));
1011        let mut after = host(10);
1012        after.add_port(Port::new(8080, Protocol::Tcp, PortState::Open));
1013
1014        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
1015
1016        let delta = &diff.hosts()[0].ports()[0];
1017        assert!(delta.is_opened());
1018        assert!(!delta.is_closed());
1019        assert!(matches!(
1020            delta.changes()[0],
1021            PortChange::State(Change {
1022                before: PortState::Closed,
1023                after: PortState::Open
1024            })
1025        ));
1026
1027        let summary = diff.summary();
1028        assert_eq!(summary.ports_opened.total, 1);
1029        assert_eq!(
1030            summary.ports_opened.confirmed, 1,
1031            "both scans hold a record, so nothing is being assumed"
1032        );
1033        assert_eq!(summary.ports_closed.total, 0);
1034    }
1035
1036    #[test]
1037    fn a_port_only_the_later_scan_recorded_is_not_a_confirmed_opening() {
1038        let before = host(10);
1039        let mut after = host(10);
1040        after.add_port(Port::new(8080, Protocol::Tcp, PortState::Open));
1041
1042        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
1043
1044        let delta = &diff.hosts()[0].ports()[0];
1045        assert!(delta.is_opened());
1046        assert_eq!(
1047            delta.presence(),
1048            Presence::Added {
1049                before: Coverage::Unstated
1050            },
1051            "a scope records addresses, not the ports walked on each"
1052        );
1053
1054        let summary = diff.summary();
1055        assert_eq!(summary.ports_opened.total, 1);
1056        assert_eq!(summary.ports_opened.confirmed, 0);
1057    }
1058
1059    #[test]
1060    fn an_endpoint_identical_in_both_scans_is_left_out() {
1061        let mut before = host(10);
1062        before.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
1063        before.add_port(Port::new(80, Protocol::Tcp, PortState::Closed));
1064        let mut after = host(10);
1065        after.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
1066        after.add_port(Port::new(80, Protocol::Tcp, PortState::Open));
1067
1068        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
1069
1070        let ports = diff.hosts()[0].ports();
1071        assert_eq!(ports.len(), 1, "only the endpoint that moved: {ports:?}");
1072        assert_eq!(ports[0].number(), 80);
1073    }
1074
1075    #[test]
1076    fn a_service_version_change_is_reported() {
1077        let mut before = host(10);
1078        before.add_port(
1079            Port::new(80, Protocol::Tcp, PortState::Open)
1080                .with_service(Service::new("http", 90).with_version("1.18.0")),
1081        );
1082        let mut after = host(10);
1083        after.add_port(
1084            Port::new(80, Protocol::Tcp, PortState::Open)
1085                .with_service(Service::new("http", 90).with_version("1.24.0")),
1086        );
1087
1088        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
1089
1090        let changes = diff.hosts()[0].ports()[0].changes();
1091        let PortChange::Service(ServiceChange::Version(version)) = &changes[0] else {
1092            panic!("expected a version change, got {changes:?}");
1093        };
1094        assert_eq!(version.before.as_deref(), Some("1.18.0"));
1095        assert_eq!(version.after.as_deref(), Some("1.24.0"));
1096        assert_eq!(diff.summary().services_changed, 1);
1097    }
1098
1099    #[test]
1100    fn a_service_identified_at_a_different_confidence_is_not_a_change() {
1101        let mut before = host(10);
1102        before.add_port(
1103            Port::new(80, Protocol::Tcp, PortState::Open)
1104                .with_service(Service::new("http", 60).with_version("1.18.0")),
1105        );
1106        let mut after = host(10);
1107        after.add_port(
1108            Port::new(80, Protocol::Tcp, PortState::Open)
1109                .with_service(Service::new("http", 99).with_version("1.18.0")),
1110        );
1111
1112        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
1113
1114        assert!(
1115            diff.is_empty(),
1116            "how sure the fingerprinter was is not a finding about the service"
1117        );
1118    }
1119
1120    // -----------------------------------------------------------------------
1121    // Endpoint coverage: which ports each scan says it walked
1122    // -----------------------------------------------------------------------
1123
1124    #[test]
1125    fn a_port_that_opened_where_the_baseline_walked_it_is_confirmed() {
1126        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1127        let mut after = host(10);
1128        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1129
1130        let diff = ScanDiff::between(
1131            &port_scanned(
1132                vec![host(10)],
1133                "203.0.113.0/24",
1134                PortScope::Every(ports("1-1024")),
1135                at,
1136            ),
1137            &port_scanned(
1138                vec![after],
1139                "203.0.113.0/24",
1140                PortScope::Every(ports("1-1024")),
1141                at + DAY,
1142            ),
1143        );
1144
1145        let delta = &diff.hosts()[0].ports()[0];
1146        assert_eq!(
1147            delta.presence(),
1148            Presence::Added {
1149                before: Coverage::Covered
1150            },
1151            "the baseline walked 443 and recorded nothing there, so it opened"
1152        );
1153        assert_eq!(diff.summary().ports_opened.confirmed, 1);
1154    }
1155
1156    #[test]
1157    fn a_port_the_baseline_never_walked_is_not_a_confirmed_opening() {
1158        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1159        let mut after = host(10);
1160        after.add_port(Port::new(8080, Protocol::Tcp, PortState::Open));
1161
1162        let diff = ScanDiff::between(
1163            &port_scanned(
1164                vec![host(10)],
1165                "203.0.113.0/24",
1166                PortScope::Every(ports("1-1024")),
1167                at,
1168            ),
1169            &port_scanned(
1170                vec![after],
1171                "203.0.113.0/24",
1172                PortScope::Every(ports("1-1024,8080")),
1173                at + DAY,
1174            ),
1175        );
1176
1177        let delta = &diff.hosts()[0].ports()[0];
1178        assert_eq!(
1179            delta.presence(),
1180            Presence::Added {
1181                before: Coverage::OutOfScope
1182            },
1183            "8080 was outside the baseline's port set, so nothing there is news"
1184        );
1185        let summary = diff.summary();
1186        assert_eq!(summary.ports_opened.total, 1);
1187        assert_eq!(summary.ports_opened.confirmed, 0);
1188    }
1189
1190    /// The baseline's scope says it walked 443 and its own record says it never got
1191    /// there, so the record wins and an open port today is news about the scan.
1192    #[test]
1193    fn a_port_the_baseline_ran_short_of_is_not_a_confirmed_opening() {
1194        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1195
1196        let mut before = host(10);
1197        before.add_port(Port::new(443, Protocol::Tcp, PortState::Unasked));
1198        let mut after = host(10);
1199        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1200
1201        let diff = ScanDiff::between(
1202            &port_scanned(
1203                vec![before],
1204                "203.0.113.0/24",
1205                PortScope::Every(ports("1-1024")),
1206                at,
1207            ),
1208            &port_scanned(
1209                vec![after],
1210                "203.0.113.0/24",
1211                PortScope::Every(ports("1-1024")),
1212                at + DAY,
1213            ),
1214        );
1215
1216        let delta = &diff.hosts()[0].ports()[0];
1217        assert_eq!(
1218            delta.presence(),
1219            Presence::Added {
1220                before: Coverage::Unreached
1221            },
1222            "an unasked port read as a verdict the baseline reached"
1223        );
1224        assert!(
1225            delta.baseline().is_none(),
1226            "a port nobody probed is not a record of anything"
1227        );
1228        assert!(
1229            delta.changes().is_empty(),
1230            "an appearance carries no field-level changes"
1231        );
1232
1233        let summary = diff.summary();
1234        assert_eq!(summary.ports_opened.total, 1);
1235        assert_eq!(
1236            summary.ports_opened.confirmed, 0,
1237            "a scan that ran short confirmed an opening it never looked for"
1238        );
1239    }
1240
1241    /// The mirror case: tonight's run spent its wall-clock budget before reaching
1242    /// a port that was open last night. Nothing closed.
1243    #[test]
1244    fn a_port_the_later_scan_ran_short_of_is_not_a_confirmed_closing() {
1245        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1246
1247        let mut before = host(10);
1248        before.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1249        let mut after = host(10);
1250        after.add_port(Port::new(443, Protocol::Tcp, PortState::Unasked));
1251
1252        let diff = ScanDiff::between(
1253            &port_scanned(
1254                vec![before],
1255                "203.0.113.0/24",
1256                PortScope::Every(ports("1-1024")),
1257                at,
1258            ),
1259            &port_scanned(
1260                vec![after],
1261                "203.0.113.0/24",
1262                PortScope::Every(ports("1-1024")),
1263                at + DAY,
1264            ),
1265        );
1266
1267        let delta = &diff.hosts()[0].ports()[0];
1268        assert_eq!(
1269            delta.presence(),
1270            Presence::Removed {
1271                after: Coverage::Unreached
1272            },
1273        );
1274
1275        let summary = diff.summary();
1276        assert_eq!(summary.ports_closed.total, 1);
1277        assert_eq!(summary.ports_closed.confirmed, 0);
1278    }
1279
1280    /// A port the baseline never reached, and tonight's scan has no record for,
1281    /// gives no delta: neither side has a finding.
1282    #[test]
1283    fn an_endpoint_neither_scan_has_a_finding_for_is_reported_by_neither() {
1284        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1285
1286        let mut before = host(10);
1287        before.add_port(Port::new(443, Protocol::Tcp, PortState::Unasked));
1288
1289        let diff = ScanDiff::between(
1290            &port_scanned(
1291                vec![before],
1292                "203.0.113.0/24",
1293                PortScope::Every(ports("1-1024")),
1294                at,
1295            ),
1296            &port_scanned(
1297                vec![host(10)],
1298                "203.0.113.0/24",
1299                PortScope::Every(ports("1-1024")),
1300                at + DAY,
1301            ),
1302        );
1303
1304        assert!(diff.is_empty(), "{:?}", diff.hosts());
1305    }
1306
1307    /// Both scans walked 443; last week nothing was listening and tonight
1308    /// something is, so the grade is high.
1309    #[test]
1310    fn a_port_that_opened_on_ground_both_scans_walked_is_urgent() {
1311        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1312
1313        let mut before = host(10);
1314        before.add_port(Port::new(443, Protocol::Tcp, PortState::Closed));
1315        let mut after = host(10);
1316        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1317
1318        let diff = ScanDiff::between(
1319            &port_scanned(
1320                vec![before],
1321                "203.0.113.0/24",
1322                PortScope::Every(ports("1-1024")),
1323                at,
1324            ),
1325            &port_scanned(
1326                vec![after],
1327                "203.0.113.0/24",
1328                PortScope::Every(ports("1-1024")),
1329                at + DAY,
1330            ),
1331        );
1332
1333        assert_eq!(
1334            diff.hosts()[0].ports()[0].significance(),
1335            Significance::Urgent
1336        );
1337        assert_eq!(diff.hosts()[0].significance(), Significance::Urgent);
1338        assert_eq!(diff.significance(), Significance::Urgent);
1339    }
1340
1341    /// The same opening where the baseline ran out of wall clock before reaching
1342    /// the port. The comparison cannot say it happened, so it ranks lower.
1343    #[test]
1344    fn the_same_opening_against_a_scan_that_ran_short_is_routine() {
1345        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1346
1347        let mut before = host(10);
1348        before.add_port(Port::new(443, Protocol::Tcp, PortState::Unasked));
1349        let mut after = host(10);
1350        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1351
1352        let diff = ScanDiff::between(
1353            &port_scanned(
1354                vec![before],
1355                "203.0.113.0/24",
1356                PortScope::Every(ports("1-1024")),
1357                at,
1358            ),
1359            &port_scanned(
1360                vec![after],
1361                "203.0.113.0/24",
1362                PortScope::Every(ports("1-1024")),
1363                at + DAY,
1364            ),
1365        );
1366
1367        let port = &diff.hosts()[0].ports()[0];
1368        assert!(port.is_opened(), "the record still says the port is open");
1369        assert_eq!(
1370            port.significance(),
1371            Significance::Routine,
1372            "a port nobody had checked ranked as one that opened"
1373        );
1374        assert_eq!(diff.significance(), Significance::Routine);
1375    }
1376
1377    /// A scan widened to a range nobody had scanned before turns up hosts with
1378    /// open ports, and none of it is news.
1379    #[test]
1380    fn a_host_found_by_a_wider_scan_is_routine_open_ports_and_all() {
1381        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1382
1383        let mut arrival = host(200);
1384        arrival.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
1385
1386        let diff = ScanDiff::between(
1387            &scoped(vec![host(10)], "203.0.113.0/26", &[], at),
1388            &scoped(vec![host(10), arrival], "203.0.113.0/24", &[], at + DAY),
1389        );
1390
1391        let appeared = diff
1392            .hosts()
1393            .iter()
1394            .find(|delta| delta.address() == ip(200))
1395            .expect("the new host is in the diff");
1396
1397        assert!(!appeared.presence().is_confirmed());
1398        assert_eq!(
1399            appeared.significance(),
1400            Significance::Routine,
1401            "a host on ground nobody had walked was graded as one that arrived"
1402        );
1403        assert_eq!(diff.significance(), Significance::Routine);
1404    }
1405
1406    /// A host that starts answering for a protocol is worth reading: a machine
1407    /// newly answering for GRE is one end of a new tunnel.
1408    #[test]
1409    fn a_protocol_a_host_started_accepting_is_a_notable_change() {
1410        use crate::model::host::IpProtocolState;
1411
1412        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1413
1414        let mut before = host(10);
1415        before.record_ip_protocol(47, IpProtocolState::Closed);
1416        let mut after = host(10);
1417        after.record_ip_protocol(47, IpProtocolState::Open);
1418
1419        let diff = ScanDiff::between(
1420            &scoped(vec![before], "203.0.113.0/24", &[], at),
1421            &scoped(vec![after], "203.0.113.0/24", &[], at + DAY),
1422        );
1423
1424        let delta = &diff.hosts()[0];
1425        let moved = delta
1426            .changes()
1427            .iter()
1428            .find_map(|change| match change {
1429                HostChange::IpProtocols { changed } => Some(changed),
1430                _ => None,
1431            })
1432            .expect("the protocol moved");
1433
1434        assert_eq!(moved.len(), 1);
1435        assert_eq!(moved[0].protocol, 47);
1436        assert_eq!(moved[0].state.before, IpProtocolState::Closed);
1437        assert_eq!(moved[0].state.after, IpProtocolState::Open);
1438        assert_eq!(diff.significance(), Significance::Notable);
1439    }
1440
1441    /// The second scan asking about a protocol the first never did is the scan
1442    /// changing. It reads as an unasked port does, so enabling the pass does not
1443    /// make every host look changed.
1444    #[test]
1445    fn a_protocol_only_one_scan_established_anything_about_is_not_a_change() {
1446        use crate::model::host::IpProtocolState;
1447
1448        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1449
1450        let mut before = host(10);
1451        // Named and never reached (a run cut short), and absent for 89 (a scan
1452        // that never asked).
1453        before.record_ip_protocol(47, IpProtocolState::Unasked);
1454        let mut after = host(10);
1455        after.record_ip_protocol(47, IpProtocolState::Open);
1456        after.record_ip_protocol(89, IpProtocolState::Closed);
1457
1458        let diff = ScanDiff::between(
1459            &scoped(vec![before], "203.0.113.0/24", &[], at),
1460            &scoped(vec![after], "203.0.113.0/24", &[], at + DAY),
1461        );
1462
1463        assert!(diff.is_empty(), "{:?}", diff.hosts());
1464    }
1465
1466    /// A night of ordinary churn grades as nothing worth waking anybody for.
1467    #[test]
1468    fn a_diff_of_nothing_but_drift_is_routine() {
1469        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1470
1471        let mut before = host(10);
1472        before.set_hostname(Some("old.example.test".to_string()));
1473        let mut after = host(10);
1474        after.set_hostname(Some("new.example.test".to_string()));
1475
1476        let diff = ScanDiff::between(
1477            &scoped(vec![before], "203.0.113.0/24", &[], at),
1478            &scoped(vec![after], "203.0.113.0/24", &[], at + DAY),
1479        );
1480
1481        assert!(!diff.is_empty(), "the hostname did move");
1482        assert_eq!(diff.significance(), Significance::Routine);
1483    }
1484
1485    #[test]
1486    fn a_baseline_that_only_swept_never_walked_any_port() {
1487        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1488        let mut after = host(10);
1489        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1490
1491        let diff = ScanDiff::between(
1492            &scoped(vec![host(10)], "203.0.113.0/24", &[], at),
1493            &port_scanned(
1494                vec![after],
1495                "203.0.113.0/24",
1496                PortScope::Every(ports("1-1024")),
1497                at + DAY,
1498            ),
1499        );
1500
1501        assert_eq!(
1502            diff.hosts()[0].ports()[0].presence(),
1503            Presence::Added {
1504                before: Coverage::OutOfScope
1505            },
1506            "a sweep walks addresses; it did not probe this endpoint and can say so"
1507        );
1508    }
1509
1510    #[test]
1511    fn a_baseline_whose_addresses_disagreed_about_ports_cannot_confirm_one() {
1512        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1513        let mut after = host(10);
1514        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1515
1516        let diff = ScanDiff::between(
1517            &port_scanned(
1518                vec![host(10)],
1519                "203.0.113.0/24",
1520                PortScope::Mixed(ports("80,443")),
1521                at,
1522            ),
1523            &port_scanned(
1524                vec![after],
1525                "203.0.113.0/24",
1526                PortScope::Every(ports("80,443")),
1527                at + DAY,
1528            ),
1529        );
1530
1531        assert_eq!(
1532            diff.hosts()[0].ports()[0].presence(),
1533            Presence::Added {
1534                before: Coverage::Unstated
1535            },
1536            "443 was walked for some addresses; the scope cannot say it was for this one"
1537        );
1538    }
1539
1540    #[test]
1541    fn a_phase_that_cannot_say_vetoes_one_that_can() {
1542        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1543        let mut after = host(10);
1544        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
1545
1546        // A job of two phases: a sweep that certainly walked no ports, and a
1547        // port scan from a record that does not say which ports it walked.
1548        let sweep = scoped(vec![host(10)], "203.0.113.0/24", &[], at);
1549        let unstated = port_scanned(vec![host(10)], "203.0.113.0/24", PortScope::Unstated, at);
1550        let mut phases = sweep.phases().to_vec();
1551        phases.extend(unstated.phases().iter().cloned());
1552        let baseline = ScanReport::recorded("test", phases, vec![host(10)]);
1553
1554        let diff = ScanDiff::between(
1555            &baseline,
1556            &port_scanned(
1557                vec![after],
1558                "203.0.113.0/24",
1559                PortScope::Every(ports("1-1024")),
1560                at + DAY,
1561            ),
1562        );
1563
1564        assert_eq!(
1565            diff.hosts()[0].ports()[0].presence(),
1566            Presence::Added {
1567                before: Coverage::Unstated
1568            },
1569            "the sweep's certainty about its own half is not the job's"
1570        );
1571    }
1572
1573    // -----------------------------------------------------------------------
1574    // A link is covered ground, and no range says so
1575    // -----------------------------------------------------------------------
1576
1577    /// A sweep of a local segment reaches every IPv6 neighbour on the link, at
1578    /// addresses no target set could have named. A new device there counts as
1579    /// having appeared.
1580    #[test]
1581    fn a_neighbour_on_a_swept_link_is_covered_ground() {
1582        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1583
1584        let diff = ScanDiff::between(
1585            &swept(vec![host(10)], "203.0.113.0/24", "en1", at),
1586            &swept(
1587                vec![host(10), neighbour(0x41a, "en1")],
1588                "203.0.113.0/24",
1589                "en1",
1590                at + DAY,
1591            ),
1592        );
1593
1594        let appeared = diff
1595            .hosts()
1596            .iter()
1597            .find(|delta| delta.address().is_ipv6())
1598            .expect("the neighbour is in the diff");
1599
1600        assert_eq!(
1601            appeared.presence(),
1602            Presence::Added {
1603                before: Coverage::Covered
1604            },
1605            "the earlier scan swept this link and did not find it"
1606        );
1607        assert!(appeared.presence().is_confirmed());
1608        assert_eq!(diff.summary().hosts_added.confirmed, 1);
1609    }
1610
1611    /// And a link nobody swept claims nothing.
1612    #[test]
1613    fn a_neighbour_on_a_link_that_was_not_swept_is_not_confirmed() {
1614        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1615
1616        let diff = ScanDiff::between(
1617            // The earlier scan swept a different interface's link.
1618            &swept(vec![host(10)], "203.0.113.0/24", "en0", at),
1619            &swept(
1620                vec![host(10), neighbour(0x41a, "en1")],
1621                "203.0.113.0/24",
1622                "en1",
1623                at + DAY,
1624            ),
1625        );
1626
1627        let appeared = diff
1628            .hosts()
1629            .iter()
1630            .find(|delta| delta.address().is_ipv6())
1631            .expect("the neighbour is in the diff");
1632
1633        assert_eq!(
1634            appeared.presence(),
1635            Presence::Added {
1636                before: Coverage::OutOfScope
1637            },
1638            "fe80::1 on two interfaces is two machines"
1639        );
1640        assert_eq!(diff.summary().hosts_added.confirmed, 0);
1641    }
1642
1643    /// A host found on a swept link is covered whatever address it is keyed by.
1644    ///
1645    /// A neighbour that answers an all-nodes solicitation is often keyed under a
1646    /// global address, since this engine prefers a routable one, so checking
1647    /// whether the *address* is link-local would get this wrong.
1648    #[test]
1649    fn a_host_on_a_swept_link_is_covered_whatever_it_is_keyed_by() {
1650        use crate::model::ip::scoped::Zone;
1651
1652        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1653        let mut routable = Host::new("2001:db8::4".parse::<IpAddr>().expect("valid"));
1654        routable.set_status(HostStatus::Up);
1655        routable.set_zone(Zone::new(1, "en1"));
1656
1657        let diff = ScanDiff::between(
1658            &swept(vec![host(10), routable], "203.0.113.0/24", "en1", at),
1659            &swept(vec![host(10)], "203.0.113.0/24", "en1", at + DAY),
1660        );
1661
1662        let gone = diff
1663            .hosts()
1664            .iter()
1665            .find(|delta| delta.address().is_ipv6())
1666            .expect("the host is in the diff");
1667
1668        assert_eq!(
1669            gone.presence(),
1670            Presence::Removed {
1671                after: Coverage::Covered
1672            },
1673            "the later scan swept the link this host was found on"
1674        );
1675        assert_eq!(diff.summary().hosts_removed.confirmed, 1);
1676    }
1677
1678    /// A host nothing found on a link is not covered by having swept one.
1679    #[test]
1680    fn a_host_with_no_link_is_not_covered_by_a_sweep() {
1681        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1682        let mut routable = Host::new("2001:db8::1".parse::<IpAddr>().expect("valid"));
1683        routable.set_status(HostStatus::Up);
1684
1685        let diff = ScanDiff::between(
1686            &swept(vec![host(10)], "203.0.113.0/24", "en1", at),
1687            &swept(vec![host(10), routable], "203.0.113.0/24", "en1", at + DAY),
1688        );
1689
1690        let appeared = diff
1691            .hosts()
1692            .iter()
1693            .find(|delta| delta.address().is_ipv6())
1694            .expect("the host is in the diff");
1695
1696        assert!(
1697            !appeared.presence().is_confirmed(),
1698            "a host with no zone was not found on any link"
1699        );
1700    }
1701
1702    // -----------------------------------------------------------------------
1703    // A host is covered if the scan walked ground it stood on
1704    // -----------------------------------------------------------------------
1705
1706    /// A dual-stack machine keyed under IPv6 was in reach of a sweep of its IPv4
1707    /// range.
1708    #[test]
1709    fn a_host_is_covered_by_any_address_it_answers_at() {
1710        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000);
1711
1712        // Keyed under IPv6, and also holding an address the sweep walked.
1713        let mut dual = Host::new("2001:db8::5".parse::<IpAddr>().expect("valid"));
1714        dual.set_status(HostStatus::Up);
1715        dual.add_ip(ip(11));
1716
1717        let diff = ScanDiff::between(
1718            &scoped(vec![host(10)], "203.0.113.0/24", &[], at),
1719            &scoped(vec![host(10), dual], "203.0.113.0/24", &[], at + DAY),
1720        );
1721
1722        let appeared = diff
1723            .hosts()
1724            .iter()
1725            .find(|delta| delta.address().is_ipv6())
1726            .expect("the host is in the diff");
1727
1728        assert_eq!(
1729            appeared.presence(),
1730            Presence::Added {
1731                before: Coverage::Covered
1732            },
1733            "the earlier scan walked 203.0.113.11 and found nothing there"
1734        );
1735    }
1736
1737    // -----------------------------------------------------------------------
1738    // Certificates
1739    // -----------------------------------------------------------------------
1740
1741    #[test]
1742    fn a_rotated_certificate_is_reported() {
1743        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1744        let mut before = host(10);
1745        before.add_port(
1746            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1747                "aaaa",
1748                at - 90 * DAY,
1749                at + 300 * DAY,
1750            )),
1751        );
1752        let mut after = host(10);
1753        after.add_port(
1754            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1755                "bbbb",
1756                at,
1757                at + 365 * DAY,
1758            )),
1759        );
1760
1761        let diff = ScanDiff::between(
1762            &scoped(vec![before], "203.0.113.0/24", &[], at),
1763            &scoped(vec![after], "203.0.113.0/24", &[], at + DAY),
1764        );
1765
1766        let changes = diff.hosts()[0].ports()[0].changes();
1767        assert!(
1768            changes.iter().any(|change| matches!(
1769                change,
1770                PortChange::Security(SecurityChange::Certificate(
1771                    CertificateChange::Rotated { .. }
1772                ))
1773            )),
1774            "{changes:?}"
1775        );
1776        assert_eq!(diff.summary().certificates_rotated, 1);
1777    }
1778
1779    #[test]
1780    fn a_certificate_nobody_touched_reports_the_threshold_it_crossed() {
1781        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1782        // Ninety days of life left when the baseline ran, ten when the second
1783        // scan did. Nothing about the certificate moved; the clock did.
1784        let expires = at + 90 * DAY;
1785        let same = || certificate("aaaa", at - 90 * DAY, expires);
1786
1787        let mut before = host(10);
1788        before.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1789        let mut after = host(10);
1790        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1791
1792        let diff = ScanDiff::between(
1793            &scoped(vec![before], "203.0.113.0/24", &[], at),
1794            &scoped(vec![after], "203.0.113.0/24", &[], at + 80 * DAY),
1795        );
1796
1797        let changes = diff.hosts()[0].ports()[0].changes();
1798        let Some(PortChange::Security(SecurityChange::Certificate(CertificateChange::Expiring {
1799            remaining,
1800            ..
1801        }))) = changes.first()
1802        else {
1803            panic!("expected an expiry crossing, got {changes:?}");
1804        };
1805        assert_eq!(*remaining, 10 * DAY);
1806        assert_eq!(diff.summary().certificates_expiring, 1);
1807    }
1808
1809    /// A threshold no clock can reach is an answer, not a panic.
1810    ///
1811    /// `with_expiry_threshold` accepts any `Duration`, and `Duration::MAX` must
1812    /// not overflow `SystemTime + Duration`. Every certificate is inside such a
1813    /// horizon: the one presented at both scans was already inside it at the
1814    /// baseline and crossed nothing, and a replacement is reported because the
1815    /// baseline never saw it.
1816    #[test]
1817    fn an_expiry_horizon_past_the_end_of_time_reports_rather_than_panics() {
1818        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1819        let endpoint = |fingerprint: &str| {
1820            let mut host = host(10);
1821            host.add_port(
1822                Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1823                    fingerprint,
1824                    at - 90 * DAY,
1825                    at + 900 * DAY,
1826                )),
1827            );
1828            host
1829        };
1830        let forever = DiffOptions::new().with_expiry_threshold(Duration::MAX);
1831
1832        let untouched = ScanDiff::compare(
1833            &scoped(vec![endpoint("aaaa")], "203.0.113.0/24", &[], at),
1834            &scoped(vec![endpoint("aaaa")], "203.0.113.0/24", &[], at + DAY),
1835            &forever,
1836        );
1837        assert_eq!(untouched.summary().certificates_expiring, 0);
1838
1839        let rotated = ScanDiff::compare(
1840            &scoped(vec![endpoint("aaaa")], "203.0.113.0/24", &[], at),
1841            &scoped(vec![endpoint("bbbb")], "203.0.113.0/24", &[], at + DAY),
1842            &forever,
1843        );
1844        assert_eq!(rotated.summary().certificates_expiring, 1);
1845    }
1846
1847    /// A renewal onto a certificate that is itself expiring. Comparing whatever
1848    /// each side presented, both answer `Expiring` and the expiry cancels out; the
1849    /// standing belongs to one certificate at two moments, and the baseline never
1850    /// saw this one.
1851    #[test]
1852    fn a_rotation_onto_an_expiring_certificate_still_reports_the_expiry() {
1853        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1854
1855        // Twenty days left when the baseline ran, and the replacement installed
1856        // a week later has fifteen. Inside the threshold both times.
1857        let mut before = host(10);
1858        before.add_port(
1859            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1860                "aaaa",
1861                at - 90 * DAY,
1862                at + 20 * DAY,
1863            )),
1864        );
1865        let mut after = host(10);
1866        after.add_port(
1867            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1868                "bbbb",
1869                at,
1870                at + 22 * DAY,
1871            )),
1872        );
1873
1874        let diff = ScanDiff::between(
1875            &scoped(vec![before], "203.0.113.0/24", &[], at),
1876            &scoped(vec![after], "203.0.113.0/24", &[], at + 7 * DAY),
1877        );
1878
1879        let changes = diff.hosts()[0].ports()[0].changes();
1880        assert!(
1881            changes.iter().any(|change| matches!(
1882                change,
1883                PortChange::Security(SecurityChange::Certificate(
1884                    CertificateChange::Rotated { .. }
1885                ))
1886            )),
1887            "{changes:?}"
1888        );
1889        assert_eq!(diff.summary().certificates_rotated, 1);
1890        assert_eq!(
1891            diff.summary().certificates_expiring,
1892            1,
1893            "the certificate presented now is inside the threshold and the \
1894             baseline never saw it: {changes:?}"
1895        );
1896    }
1897
1898    /// The same, one step worse: a renewal that installs an already lapsed
1899    /// certificate.
1900    #[test]
1901    fn a_rotation_onto_an_already_lapsed_certificate_still_reports_it() {
1902        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1903
1904        let mut before = host(10);
1905        before.add_port(
1906            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1907                "aaaa",
1908                at - 400 * DAY,
1909                at - DAY,
1910            )),
1911        );
1912        let mut after = host(10);
1913        after.add_port(
1914            Port::new(443, Protocol::Tcp, PortState::Open).with_security(certificate(
1915                "bbbb",
1916                at - 400 * DAY,
1917                at - 2 * DAY,
1918            )),
1919        );
1920
1921        let diff = ScanDiff::between(
1922            &scoped(vec![before], "203.0.113.0/24", &[], at),
1923            &scoped(vec![after], "203.0.113.0/24", &[], at + DAY),
1924        );
1925
1926        assert_eq!(diff.summary().certificates_rotated, 1);
1927        assert_eq!(
1928            diff.summary().certificates_expired,
1929            1,
1930            "{:?}",
1931            diff.hosts()[0].ports()[0].changes()
1932        );
1933    }
1934
1935    #[test]
1936    fn a_certificate_that_was_already_expiring_is_not_reported_again() {
1937        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1938        // Twenty days left at the baseline, fifteen at the second scan: inside
1939        // the threshold both times, so nothing crossed it.
1940        let expires = at + 20 * DAY;
1941        let same = || certificate("aaaa", at - 90 * DAY, expires);
1942
1943        let mut before = host(10);
1944        before.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1945        let mut after = host(10);
1946        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1947
1948        let diff = ScanDiff::between(
1949            &scoped(vec![before], "203.0.113.0/24", &[], at),
1950            &scoped(vec![after], "203.0.113.0/24", &[], at + 5 * DAY),
1951        );
1952
1953        assert!(
1954            diff.is_empty(),
1955            "a renewal queue reports a certificate once, not on every scan"
1956        );
1957    }
1958
1959    #[test]
1960    fn a_certificate_that_lapsed_between_the_scans_is_reported() {
1961        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1962        let expires = at + 10 * DAY;
1963        let same = || certificate("aaaa", at - 90 * DAY, expires);
1964
1965        let mut before = host(10);
1966        before.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1967        let mut after = host(10);
1968        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1969
1970        let diff = ScanDiff::between(
1971            &scoped(vec![before], "203.0.113.0/24", &[], at),
1972            &scoped(vec![after], "203.0.113.0/24", &[], at + 40 * DAY),
1973        );
1974
1975        let changes = diff.hosts()[0].ports()[0].changes();
1976        let Some(PortChange::Security(SecurityChange::Certificate(CertificateChange::Expired {
1977            since,
1978            ..
1979        }))) = changes.first()
1980        else {
1981            panic!("expected a lapse, got {changes:?}");
1982        };
1983        assert_eq!(*since, 30 * DAY);
1984        assert_eq!(diff.summary().certificates_expired, 1);
1985    }
1986
1987    #[test]
1988    fn asking_where_a_stored_scan_stands_today_moves_only_the_current_clock() {
1989        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
1990        let expires = at + 90 * DAY;
1991        let same = || certificate("aaaa", at - 90 * DAY, expires);
1992
1993        let mut before = host(10);
1994        before.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1995        let mut after = host(10);
1996        after.add_port(Port::new(443, Protocol::Tcp, PortState::Open).with_security(same()));
1997
1998        // Both scans ran while the certificate had plenty of life left, so at
1999        // their own clocks nothing crossed.
2000        let baseline = scoped(vec![before], "203.0.113.0/24", &[], at);
2001        let current = scoped(vec![after], "203.0.113.0/24", &[], at + DAY);
2002        assert!(ScanDiff::between(&baseline, &current).is_empty());
2003
2004        let asked_later = ScanDiff::compare(
2005            &baseline,
2006            &current,
2007            &DiffOptions::new().as_of(at + 85 * DAY),
2008        );
2009
2010        assert_eq!(
2011            asked_later.summary().certificates_expiring,
2012            1,
2013            "asked as of a later moment, the certificate is inside the threshold"
2014        );
2015    }
2016
2017    // -----------------------------------------------------------------------
2018    // Which record continues which
2019    // -----------------------------------------------------------------------
2020
2021    #[test]
2022    fn a_host_whose_primary_address_moved_pairs_by_a_shared_one() {
2023        let mut before = host(10);
2024        before.add_ip(ip(11));
2025        let mut after = Host::new(ip(11));
2026        after.set_status(HostStatus::Up);
2027        after.add_ip(ip(10));
2028        after.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
2029
2030        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![after]));
2031
2032        assert_eq!(diff.hosts().len(), 1, "one machine, not two");
2033        let delta = &diff.hosts()[0];
2034        assert!(delta.presence().is_in_both());
2035        assert!(!delta.is_regrouped());
2036
2037        let summary = diff.summary();
2038        assert_eq!(summary.hosts_added.total, 0);
2039        assert_eq!(summary.hosts_removed.total, 0);
2040    }
2041
2042    #[test]
2043    fn the_strict_policy_reads_the_same_pair_as_two_hosts() {
2044        let mut before = host(10);
2045        before.add_ip(ip(11));
2046        let mut after = Host::new(ip(11));
2047        after.set_status(HostStatus::Up);
2048        after.add_ip(ip(10));
2049
2050        let diff = ScanDiff::compare(
2051            &unscoped(vec![before]),
2052            &unscoped(vec![after]),
2053            &DiffOptions::new().with_identity(HostIdentity::PrimaryAddress),
2054        );
2055
2056        let summary = diff.summary();
2057        assert_eq!(summary.hosts_added.total, 1);
2058        assert_eq!(
2059            summary.hosts_removed.total, 1,
2060            "under this policy the address is the asset"
2061        );
2062    }
2063
2064    #[test]
2065    fn one_host_seen_as_two_is_reported_as_a_regrouping() {
2066        // The baseline reached the link layer and knew the two addresses were
2067        // one machine. The second scan did not.
2068        let mut before = host(10);
2069        before.add_ip(ip(11));
2070
2071        let mut first = host(10);
2072        first.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
2073        let mut second = Host::new(ip(11));
2074        second.set_status(HostStatus::Up);
2075        second.add_port(Port::new(80, Protocol::Tcp, PortState::Open));
2076
2077        let diff = ScanDiff::between(&unscoped(vec![before]), &unscoped(vec![first, second]));
2078
2079        assert_eq!(diff.hosts().len(), 1, "one component, however it was keyed");
2080        let delta = &diff.hosts()[0];
2081        assert!(delta.is_regrouped());
2082        assert_eq!(delta.records(), (1, 2));
2083        assert!(
2084            delta.presence().is_in_both(),
2085            "both scans saw the machine; they disagreed about how to key it"
2086        );
2087
2088        // The two records were folded, so both endpoints are compared against
2089        // the baseline.
2090        let numbers: Vec<u16> = delta.ports().iter().map(PortDelta::number).collect();
2091        assert_eq!(numbers, vec![22, 80]);
2092    }
2093
2094    #[test]
2095    fn a_shared_hardware_address_pairs_a_host_that_moved_address() {
2096        use crate::model::mac::MacAddr;
2097
2098        let mac = MacAddr::new(0x2c, 0xcf, 0x67, 0xf2, 0x51, 0xe3);
2099        let mut before = host(10);
2100        before.record_mac(mac);
2101        let mut after = host(60);
2102        after.record_mac(mac);
2103
2104        let by_address = ScanDiff::between(
2105            &unscoped(vec![before.clone()]),
2106            &unscoped(vec![after.clone()]),
2107        );
2108        assert_eq!(
2109            by_address.summary().hosts_added.total,
2110            1,
2111            "nothing links the two addresses without the hardware policy"
2112        );
2113
2114        let by_hardware = ScanDiff::compare(
2115            &unscoped(vec![before]),
2116            &unscoped(vec![after]),
2117            &DiffOptions::new().with_identity(HostIdentity::Hardware),
2118        );
2119
2120        assert_eq!(by_hardware.hosts().len(), 1);
2121        let delta = &by_hardware.hosts()[0];
2122        assert!(delta.presence().is_in_both());
2123        let changes = delta.changes();
2124        assert!(
2125            changes
2126                .iter()
2127                .any(|change| matches!(change, HostChange::Addresses { .. })),
2128            "the address it moved to is the change: {changes:?}"
2129        );
2130    }
2131
2132    #[test]
2133    fn hosts_come_back_ascending_by_address() {
2134        let before = unscoped(vec![host(10)]);
2135        let after = unscoped(vec![host(30), host(10), host(20)]);
2136
2137        let diff = ScanDiff::between(&before, &after);
2138        let addresses: Vec<IpAddr> = diff.hosts().iter().map(HostDelta::address).collect();
2139
2140        assert_eq!(
2141            addresses,
2142            vec![ip(20), ip(30)],
2143            "two runs over the same reports produce the same diff"
2144        );
2145    }
2146
2147    // -----------------------------------------------------------------------
2148    // Provenance
2149    // -----------------------------------------------------------------------
2150
2151    #[test]
2152    fn a_report_with_no_phases_is_placed_by_its_latest_sighting() {
2153        let at = SystemTime::UNIX_EPOCH + Duration::from_secs(1_000_000_000);
2154        let mut old = host(10);
2155        old.restore_seen(at - DAY, at);
2156
2157        let diff = ScanDiff::between(&unscoped(vec![old]), &unscoped(vec![host(11)]));
2158
2159        assert_eq!(diff.baseline().at(), at);
2160        assert!(!diff.baseline().states_scope());
2161        assert_eq!(diff.baseline().hosts(), 1);
2162        assert!(diff.baseline().kinds().is_empty());
2163    }
2164
2165    /// The port-state grading table from [`significance`](crate::diff::significance),
2166    /// executed. It lives here because it pins the composition: the grade, and the
2167    /// presence that decides whether the grade is reported.
2168    ///
2169    /// The rows with [`PortState::Unasked`] matter most. A scan that ran out of
2170    /// budget writes the port down, so every transition into or out of `Unasked`
2171    /// reads as ground one side never reached (`Routine`, `Unreached`), never as
2172    /// a port that opened or closed. `merge` follows the same rule; see
2173    /// `fold_port`.
2174    #[test]
2175    fn every_port_state_transition_grades_the_way_the_table_says() {
2176        use crate::model::port::{Port, PortState, Protocol};
2177
2178        // before, after, expected significance, whether a delta is reported
2179        let table = [
2180            (PortState::Open, PortState::Open, None),
2181            (
2182                PortState::Open,
2183                PortState::Closed,
2184                Some(Significance::Notable),
2185            ),
2186            (
2187                PortState::Open,
2188                PortState::NoReply,
2189                Some(Significance::Notable),
2190            ),
2191            (
2192                PortState::Open,
2193                PortState::OpenOrNoReply,
2194                Some(Significance::Notable),
2195            ),
2196            (
2197                PortState::Closed,
2198                PortState::Open,
2199                Some(Significance::Urgent),
2200            ),
2201            (PortState::Closed, PortState::Closed, None),
2202            (
2203                PortState::Closed,
2204                PortState::NoReply,
2205                Some(Significance::Routine),
2206            ),
2207            (
2208                PortState::NoReply,
2209                PortState::Open,
2210                Some(Significance::Urgent),
2211            ),
2212            (
2213                PortState::NoReply,
2214                PortState::Closed,
2215                Some(Significance::Routine),
2216            ),
2217            (PortState::NoReply, PortState::NoReply, None),
2218            (
2219                PortState::OpenOrNoReply,
2220                PortState::Open,
2221                Some(Significance::Urgent),
2222            ),
2223            (PortState::OpenOrNoReply, PortState::OpenOrNoReply, None),
2224            (PortState::Unasked, PortState::Unasked, None),
2225        ];
2226
2227        for (before, after, expected) in table {
2228            let mut baseline = host(1);
2229            baseline.add_port(Port::new(80, Protocol::Tcp, before));
2230            let mut current = host(1);
2231            current.add_port(Port::new(80, Protocol::Tcp, after));
2232
2233            let diff = ScanDiff::between(&unscoped(vec![baseline]), &unscoped(vec![current]));
2234            let graded: Vec<Significance> = diff
2235                .hosts()
2236                .iter()
2237                .flat_map(|host| host.ports())
2238                .filter(|delta| delta.number() == 80)
2239                .map(|delta| delta.significance())
2240                .collect();
2241
2242            match expected {
2243                Some(grade) => assert_eq!(graded, vec![grade], "{before:?} -> {after:?}"),
2244                None => assert!(
2245                    graded.is_empty(),
2246                    "{before:?} -> {after:?} is not a change and must report none, got {graded:?}"
2247                ),
2248            }
2249        }
2250    }
2251
2252    /// A port nobody asked about is ground one side never reached, in both
2253    /// directions. The presence says which side fell short, so a reader can tell
2254    /// "we did not look" from "it went away".
2255    #[test]
2256    fn a_transition_through_unasked_reads_as_ground_nobody_walked() {
2257        use crate::model::port::{Port, PortState, Protocol};
2258
2259        for state in [
2260            PortState::Open,
2261            PortState::Closed,
2262            PortState::NoReply,
2263            PortState::OpenOrNoReply,
2264        ] {
2265            for (before, after) in [(state, PortState::Unasked), (PortState::Unasked, state)] {
2266                let mut baseline = host(1);
2267                baseline.add_port(Port::new(80, Protocol::Tcp, before));
2268                let mut current = host(1);
2269                current.add_port(Port::new(80, Protocol::Tcp, after));
2270
2271                let diff = ScanDiff::between(&unscoped(vec![baseline]), &unscoped(vec![current]));
2272                for delta in diff.hosts().iter().flat_map(|host| host.ports()) {
2273                    assert_eq!(
2274                        delta.significance(),
2275                        Significance::Routine,
2276                        "{before:?} -> {after:?} must not be graded above routine"
2277                    );
2278                    assert!(
2279                        !delta.presence().is_confirmed(),
2280                        "{before:?} -> {after:?} must not read as a confirmed change"
2281                    );
2282                }
2283            }
2284        }
2285    }
2286
2287    /// An address one scan listed as a host it heard nothing from, and the other
2288    /// found silent on every port, is the same quiet address both times: no host
2289    /// went away or arrived.
2290    #[test]
2291    fn a_quiet_address_listed_once_and_found_silent_once_is_no_change() {
2292        let start = SystemTime::UNIX_EPOCH;
2293        let mut unheard = Host::new(ip(5));
2294        unheard.add_port(Port::new(443, Protocol::Tcp, PortState::NoReply));
2295        let listed = scoped(vec![unheard], "203.0.113.0/29", &[], start);
2296        let silent = found_silent("203.0.113.0/29", "203.0.113.5", start + DAY);
2297
2298        assert!(
2299            ScanDiff::between(&listed, &silent).hosts().is_empty(),
2300            "a quiet address read as a host that went away"
2301        );
2302        assert!(
2303            ScanDiff::between(&silent, &listed).hosts().is_empty(),
2304            "or as one that arrived"
2305        );
2306    }
2307
2308    /// A host that answered and is silent now went away, as it would had a
2309    /// liveness pass found it silent: the address was covered.
2310    #[test]
2311    fn a_host_that_answered_and_is_silent_now_is_removed_from_covered_ground() {
2312        let start = SystemTime::UNIX_EPOCH;
2313        let answered = scoped(vec![host(5)], "203.0.113.0/29", &[], start);
2314        let silent = found_silent("203.0.113.0/29", "203.0.113.5", start + DAY);
2315
2316        let diff = ScanDiff::between(&answered, &silent);
2317        let [delta] = diff.hosts() else {
2318            panic!("one host changed: {:?}", diff.hosts());
2319        };
2320        assert!(
2321            matches!(
2322                delta.presence(),
2323                crate::diff::Presence::Removed {
2324                    after: Coverage::Covered
2325                }
2326            ),
2327            "{:?}",
2328            delta.presence()
2329        );
2330    }
2331}