pub struct ScanReport { /* private fields */ }Expand description
Everything known about a completed scan.
Obtained from ScanTask::join once a scan
finishes. See the module documentation for how it relates to the
live ScanSession.
Implementations§
Source§impl ScanReport
impl ScanReport
Sourcepub fn new(phase: ScanPhase, hosts: impl IntoIterator<Item = Host>) -> Self
pub fn new(phase: ScanPhase, hosts: impl IntoIterator<Item = Host>) -> Self
Builds a single-phase report over the hosts a scan produced.
Hosts are keyed by their reported address (with interface where needed), so a host with several addresses appears once and two link-locals on different segments stay two.
Sourcepub fn from_phases(
phases: Vec<ScanPhase>,
hosts: impl IntoIterator<Item = Host>,
) -> Self
pub fn from_phases( phases: Vec<ScanPhase>, hosts: impl IntoIterator<Item = Host>, ) -> Self
A report over the phases of a job that ran in more than one sitting.
For a resumed scan, whose earlier sittings are restored from a journal. phases
is kept in the order given.
Attributed to this build, which is continuing the job. Use
recorded to rebuild a report nothing is continuing.
Sourcepub fn recorded(
engine_version: impl Into<String>,
phases: Vec<ScanPhase>,
hosts: impl IntoIterator<Item = Host>,
) -> Self
pub fn recorded( engine_version: impl Into<String>, phases: Vec<ScanPhase>, hosts: impl IntoIterator<Item = Host>, ) -> Self
A report rebuilt from what an earlier scan wrote down, attributed to the engine that ran it.
For reading a finished scan back from a journal or an exported report. The version comes from the record, so a scan run by 0.11 still says 0.11 when 0.12 reads it.
Sourcepub fn engine_version(&self) -> &str
pub fn engine_version(&self) -> &str
The engine version that produced this report.
Sourcepub fn phases(&self) -> &[ScanPhase]
pub fn phases(&self) -> &[ScanPhase]
The phases that contributed to this report, in the order they ran.
A report a scan produced has at least one. One rebuilt with
recorded can have none, if the scan stopped before writing
a phase.
Sourcepub fn is_merged(&self) -> bool
pub fn is_merged(&self) -> bool
Whether this report was folded out of documents rather than measured by one run.
True when any phase carries a PhaseOrigin, which only
merge writes.
For a merged report elapsed sums several scanners’ working
time and is not the duration of anything; the span is
finished_at less started_at.
Sourcepub fn host_count(&self) -> usize
pub fn host_count(&self) -> usize
The number of hosts recorded.
Sourcepub fn host(&self, ip: &IpAddr) -> Option<&Host>
pub fn host(&self, ip: &IpAddr) -> Option<&Host>
Looks up a host by the address it is reported under.
For two link-locals with the same number on different segments, this answers
with the first; host_scoped can tell them apart.
Sourcepub fn host_scoped(&self, ip: &ScopedIp) -> Option<&Host>
pub fn host_scoped(&self, ip: &ScopedIp) -> Option<&Host>
Looks up a host by the address it is reported under, together with the interface that address is valid on.
The exact lookup, for a link-local: fe80::1%en0 and fe80::1%en1 are two
hosts.
Sourcepub fn into_phases(self) -> Vec<ScanPhase>
pub fn into_phases(self) -> Vec<ScanPhase>
Takes this report’s phases, consuming it.
For assembling a new report out of several. Read the hosts through
hosts first.
Sourcepub fn started_at(&self) -> SystemTime
pub fn started_at(&self) -> SystemTime
When the earliest phase began.
Sourcepub fn finished_at(&self) -> SystemTime
pub fn finished_at(&self) -> SystemTime
When the latest phase stopped looking.
The moment the findings are as of, for judging them against a clock: a
certificate’s remaining validity, staleness, which report is later. Each phase
ends at its own started_at + elapsed.
A phase whose end cannot be represented is placed at its start. An imported
document’s elapsed (nmap’s is unbounded decimal seconds) may exceed what a
SystemTime holds, and the checked addition avoids a panic; the understatement
is safe.
Sourcepub fn observed_at(&self) -> SystemTime
pub fn observed_at(&self) -> SystemTime
The moment this report is judged to have happened.
finished_at for a report with phases. For a merged report,
taking the earliest start would judge tonight’s certificates against last
quarter.
A report without phases is placed by the latest time any host was seen.
The clock merge and diff order documents by;
public so a caller can order them the same way.
Sourcepub fn elapsed(&self) -> Duration
pub fn elapsed(&self) -> Duration
How long the engine spent scanning, summed over the phases.
Working time, excluding whatever the caller did between phases. For the
wall-clock span, use finished_at less
started_at.
Sourcepub fn failures(&self) -> impl Iterator<Item = &ScannerFailure>
pub fn failures(&self) -> impl Iterator<Item = &ScannerFailure>
Every strategy failure across all phases, in the order they were recorded.
Sourcepub fn probe_stats(&self) -> impl Iterator<Item = &ProbeStats>
pub fn probe_stats(&self) -> impl Iterator<Item = &ProbeStats>
Every instrumented scanner’s counters, across all phases.
Sourcepub fn is_partial(&self) -> bool
pub fn is_partial(&self) -> bool
Whether the findings are narrower than the caller asked for.
True wherever part of the request went unanswered: a strategy that did not
complete, a refusal, a host its budget left early that no
phase finished (timed_out), an address with no verdict
(undecided), a port recorded
Unasked, a target never asked that
no host holds (unreached), a pass a stop left
(passes_cut), or a phase killed before it closed
(ScanPhase::is_open).
Read over the whole report: what one phase left open and another (a resumed sitting, a merged source) closed is closed. Failures and refusals always count, since neither says which ground it cost.
Not counted: unreachable addresses (ScanPhase::unroutable) and their unasked
ports, addresses an exclusion withheld, and a journal that could not be written,
none of which is coverage that fell short.
Sourcepub fn left_open(&self) -> bool
pub fn left_open(&self) -> bool
Whether a phase here is open and no later phase of its kind from the same account closed: the report of a job whose last sitting was killed, or is still running.
On the terms passes_cut gives.
Sourcepub fn passes_cut(&self) -> Vec<Pass>
pub fn passes_cut(&self) -> Vec<Pass>
The passes a stop left that no later sitting of the same account ran, in the order a scan runs them.
Stands until a later phase of the same kind from the same account, as with
unreached: a resumed sitting runs the passes over every host
the stopped one found. Across accounts a pass stands.
Sourcepub fn unreached(&self) -> u128
pub fn unreached(&self) -> u128
How many port targets this report’s phases never asked and hold on no host, and no later sitting of the same account took up.
A phase’s unreached count is replaced by a later phase
of the same kind from the same account, since a resumed sitting walks what the
earlier one left. The account is the document a phase came from, or this engine’s
own run for a phase with no origin.
Across accounts a count stands, since it names no targets.
Sourcepub fn undecided(&self) -> Vec<IpRange>
pub fn undecided(&self) -> Vec<IpRange>
The addresses whose presence this report reached no verdict on,
ascending: named undecided by some phase, and
decided by none.
An address is decided by a phase that walked it without naming it undecided, by
a live host at it, or by some phase finding it unreachable. So a resumed sitting
or a later merged sweep closes what an earlier one left open. Read by
is_partial and comparisons.
Sourcepub fn timed_out(&self) -> Vec<IpAddr>
pub fn timed_out(&self) -> Vec<IpAddr>
The addresses a phase’s own time budget left early and no phase finished, ascending.
A phase of the same kind that walked an address without running out of time
finishes it; a sweep says nothing about ports a port scan left unasked. Each
phase keeps its own timed_out list.
Sourcepub fn summary(&self) -> ScanSummary
pub fn summary(&self) -> ScanSummary
Counts derived from the recorded hosts.
Sourcepub fn alive_targets(&self, ports: PortSet) -> TargetMap
pub fn alive_targets(&self, ports: PortSet) -> TargetMap
The hosts this report found alive, as targets for a port scan.
The join between the two phases: sweep a range cheaply, then port-scan only what answered.
use zond_engine::{PortSet, ZondConfig, discover, scan};
use zond_engine::detect::Detections;
use zond_engine::model::parse::ip::to_set;
let cfg = ZondConfig::default();
let (_, sweep) = discover(to_set(&["192.0.2.0/24"], None, None)?, &cfg).await?;
let mut report = sweep.join().await?;
// The sweep established these hosts answer, so skip a second liveness pass.
let mut scanning = cfg.clone();
scanning.assume_up = true;
let targets = report.alive_targets(PortSet::try_from("22,80,443")?);
let (_, ports) = scan(targets, &scanning, Detections::embedded()).await?;
report.merge(ports.join().await?);Only hosts for which Host::is_alive holds, so Down and
Unknown hosts are left out.
One address per host, Host::primary_ip, so a dual-stack host is scanned
once. Build the set from Host::ips to scan every address.
A link-local address carries the interface it was found on.
Sourcepub fn merge(&mut self, other: ScanReport)
pub fn merge(&mut self, other: ScanReport)
Folds a later phase of the same job into this report.
Hosts present in both are combined with Host::merge, so a host
discovered in the first phase keeps its MAC and telemetry when the second
adds its ports. Phases and their failures are appended in call order.
The engine version is left as this report’s.
Trait Implementations§
Source§impl Clone for ScanReport
impl Clone for ScanReport
Auto Trait Implementations§
impl Freeze for ScanReport
impl RefUnwindSafe for ScanReport
impl Send for ScanReport
impl Sync for ScanReport
impl Unpin for ScanReport
impl UnsafeUnpin for ScanReport
impl UnwindSafe for ScanReport
Blanket Implementations§
Source§impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedExplicit<'a, E> for Twhere
T: 'a,
Source§impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
impl<'a, T, E> AsTaggedImplicit<'a, E> for Twhere
T: 'a,
Source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
Source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
Source§impl<T> Instrument for T
impl<T> Instrument for T
Source§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
Source§fn in_current_span(self) -> Instrumented<Self> ⓘ
fn in_current_span(self) -> Instrumented<Self> ⓘ
Source§impl<T> IntoEither for T
impl<T> IntoEither for T
Source§fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left is true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read moreSource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
self into a Left variant of Either<Self, Self>
if into_left(&self) returns true.
Converts self into a Right variant of Either<Self, Self>
otherwise. Read more