Skip to main content

ScanReport

Struct ScanReport 

Source
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

Source

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.

Source

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.

Source

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.

Source

pub fn engine_version(&self) -> &str

The engine version that produced this report.

Source

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.

Source

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.

Source

pub fn hosts(&self) -> impl Iterator<Item = &Host>

Every host recorded, ordered by primary IP.

Source

pub fn host_count(&self) -> usize

The number of hosts recorded.

Source

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.

Source

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.

Source

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.

Source

pub fn started_at(&self) -> SystemTime

When the earliest phase began.

Source

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.

Source

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.

Source

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.

Source

pub fn failures(&self) -> impl Iterator<Item = &ScannerFailure>

Every strategy failure across all phases, in the order they were recorded.

Source

pub fn refusals(&self) -> impl Iterator<Item = &Refusal>

Every refusal, across all phases.

Source

pub fn probe_stats(&self) -> impl Iterator<Item = &ProbeStats>

Every instrumented scanner’s counters, across all phases.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn summary(&self) -> ScanSummary

Counts derived from the recorded hosts.

Source

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.

Source

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

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for ScanReport

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<'a, T, E> AsTaggedExplicit<'a, E> for T
where T: 'a,

Source§

fn explicit(self, class: Class, tag: u32) -> TaggedParser<'a, Explicit, Self, E>

Source§

impl<'a, T, E> AsTaggedImplicit<'a, E> for T
where T: 'a,

Source§

fn implicit( self, class: Class, constructed: bool, tag: u32, ) -> TaggedParser<'a, Implicit, Self, E>

Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> IntoEither for T

Source§

fn into_either(self, into_left: bool) -> Either<Self, Self> ⓘ

Converts 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 more
Source§

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self> ⓘ
where F: FnOnce(&Self) -> bool,

Converts 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
Source§

impl<T> Pointable for T

Source§

const ALIGN: usize

The alignment of pointer.
Source§

type Init = T

The type for initializers.
Source§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
Source§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
Source§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
Source§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more