Skip to main content

Module diff

Module diff 

Source
Expand description

§Comparing two scans

Scan a network, scan it again a week later, and ask what changed: a host that appeared, a port that opened, a service that moved a version, a certificate that rotated or is about to lapse. ScanDiff holds all of that as a structure, computed from two ScanReports, and leaves presentation to the caller.

use zond_engine::diff::{ScanDiff, Significance};
let diff = ScanDiff::between(last_week, today);

let summary = diff.summary();
println!(
    "{} hosts appeared, {} gone, {} ports opened",
    summary.hosts_added.total, summary.hosts_removed.total, summary.ports_opened.total,
);

for host in diff.hosts() {
    if host.significance() < Significance::Notable {
        continue;
    }
    for port in host.ports() {
        if port.is_opened() {
            println!("{}:{} is open", host.address(), port.number());
        }
    }
}

§Which of it matters

Two scans of a live network always differ somewhere, mostly in things like reverse names. Significance grades each change by how much it is worth acting on, and significance holds the whole policy behind that grade.

Whether a change happened at all is a separate question, answered by Presence::is_confirmed below. The two meet only at the delta, where a caller wants one number to sort by.

§Any two reports

The comparison takes ScanReports from any source: a scan this process just ran, one read back from a journal, or a report built from another scanner’s output. Comparing last quarter’s nmap output against tonight’s scan is the same call as comparing two of this engine’s own runs.

So nothing here depends on a field only this engine fills in. A report with no phases, scope, probe statistics or hardware addresses still compares, and answers “unstated” where its record has nothing to say (see below).

§Verdicts are compared, evidence is not

A report carries findings about the network and measurements about the scan, which report keeps apart. Only the findings are compared.

A host’s status, a port’s state and a service’s identity are compared; the probe, packet or confidence behind each is not. An operating system is compared by what it names, and only where the current scan named one: a scan that identified no system or saw no hardware address found nothing out about either, so their absence is not a change.

Left out entirely: round-trip times, hop counters, measured routes, capture counters, per-scanner probe statistics, first- and last-seen timestamps, and strategy failures. All of them move between two scans of an unchanged network.

§What “gone” can mean

A host in last week’s report and missing from tonight’s either went away or was not scanned, and a monitoring tool that cannot tell those apart raises an alarm every time somebody narrows a scan. So every appearance and disappearance carries Coverage: what the other scan says about whether it covered that target.

That comes from TargetScope. Each phase records the ranges it walked after exclusions and the ranges its policy withheld, so an address falls in one, the other, or neither. A report with no scope answers Coverage::Unstated, and Presence::is_confirmed is the test that separates a host that went away from a host nobody asked about.

A phase stopped partway names the addresses it never reached a verdict on in ScanPhase::undecided. Those addresses and their endpoints answer Coverage::Unreached, so a sweep cut short reports the hosts it never got to as unreached.

Ports are a weaker case. A scope records the addresses a phase walked but not the ports it walked on each, so an endpoint of a covered address answers Unstated. Where the address itself was withheld or out of scope, the endpoint inherits that.

A port the scan named and never reached is recorded PortState::Unasked. That record says how far the scan got, which is more than the scope says, so it overrules the scope and the endpoint answers Coverage::Unreached.

Such a port is read as a side with no record at all. Read as a state, 443 unasked against 443 open would be a state that moved: a Presence::Both where Presence::is_confirmed answers true, telling a consumer that alerts on it that a port opened when the scan never looked. Read as no record, a run the wall clock cut short reports the ports it never got to as unreached.

Findings ask the same question one level down. A finding drawn from what a TLS endpoint accepts rests on the version walks that drew it; where the current scan cut one short or made no enumeration, the finding’s absence only says how far the scan got, and PortChange::Findings carries it as unsettled. A finding drawn from a certificate’s posture is unsettled when the current scan recorded no certificate (a failed handshake, or a leaf that would not parse). A vulnerability correlation is unsettled when the current scan identified nothing on the endpoint, labelled it by port number alone, or named the software without a version.

§Which record continues which

Hosts do not pair by address alone: a machine can change address between two scans, and one scan can see as a single host what another sees as two. That decision belongs to HostIdentity, a field of DiffOptions, and pairing explains how it is made.

§Which clock a certificate is judged against

“Expiring within thirty days” depends on the moment it is asked, so each side is judged against its own scan’s clock: the baseline at the baseline’s start time, the current side at the current scan’s. An untouched certificate then crosses the threshold once, between the two scans that straddle it, which makes it a change.

A report with no phases has no start time, so the latest sighting among its hosts is used. DiffOptions::as_of overrides the current side’s clock, for a caller asking where things stand today.

Re-exports§

pub use crate::diff::change::Change;
pub use crate::diff::change::Coverage;
pub use crate::diff::change::Presence;
pub use crate::diff::host::HostChange;
pub use crate::diff::host::HostDelta;
pub use crate::diff::pairing::HostIdentity;
pub use crate::diff::port::CertificateChange;
pub use crate::diff::port::PortChange;
pub use crate::diff::port::PortDelta;
pub use crate::diff::port::SecurityChange;
pub use crate::diff::port::ServiceChange;
pub use crate::diff::significance::Significance;

Modules§

change
The building blocks of every delta
host
What changed about one host
pairing
Deciding which record describes which host
port
What changed about one endpoint
significance
How much a change is worth somebody’s attention

Structs§

Confirmed
A count of records, and how many of them the other scan is known to have looked for.
DiffOptions
What a comparison is allowed to assume.
DiffSummary
Counts derived from a comparison.
Provenance
Which scan one side of a comparison was.
ScanDiff
What changed between two scans.

Constants§

DEFAULT_EXPIRY_THRESHOLD
How long before a certificate lapses it counts as expiring, when a caller does not say.