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.
- Diff
Options - What a comparison is allowed to assume.
- Diff
Summary - Counts derived from a comparison.
- Provenance
- Which scan one side of a comparison was.
- Scan
Diff - 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.