pub struct ScanContext { /* private fields */ }Expand description
The shared, cloneable handles that every scanning strategy needs: somewhere to write discovered hosts, somewhere to announce updates, a way to check for abort, and somewhere to record its own failure.
Every field is pub(crate). A scanner writes findings through
write_host, which keeps the lock-then-announce
ordering. A consumer reads through ScanSession.
Implementations§
Source§impl ScanContext
impl ScanContext
Sourcepub fn may_probe(&self, address: &IpAddr) -> bool
pub fn may_probe(&self, address: &IpAddr) -> bool
Whether this scan may address a probe to address.
The send-side half of what Exclusions promises, for addresses a
strategy learns while it runs. A segment sweep takes leads off the wire,
from mDNS records and unsolicited advertisements, and asks each directly.
None was in the target list, and write_host sees
only the answer, so this check keeps the question off the wire.
Asked by whoever turns a learned address into a probe. A target the caller named was withheld by address up front, and is asked this only for the machine behind it, by the walk that hands a port scan its targets.
An address a machine the policy names answers at is held to it as well, from the moment the neighbour tables or a reply tie the two; see the machine an address names.
Sourcepub fn write_host(
&self,
key: impl Into<ScopedIp>,
edit: impl FnOnce(&mut Host) -> bool,
) -> bool
pub fn write_host( &self, key: impl Into<ScopedIp>, edit: impl FnOnce(&mut Host) -> bool, ) -> bool
The single place a host finding enters the store.
Upserts the host at ip, runs edit against it while the store guard is
held, then releases that guard before emitting
ScanEvent::HostUpdated, so the DashMap lock is never held across the
channel send. Returns true if this call created the host.
edit returns whether the change is worth announcing: false suppresses
the event, e.g. for a duplicate reply that revealed nothing new. A newly
created host is always announced.
Anything a caller must do without the guard held, such as hostname
resolution or adaptive-deadline bookkeeping, keys off the returned flag
and runs after this call. Callers that always announce their change use
update_host.
§Exclusions
A key the scan’s Exclusions forbid is dropped here: edit is not run,
no host is created, no event is emitted, and this returns false. Every
other address edit attaches to the host (later replies from the same
machine, a merged sighting, an mDNS record’s other addresses) is held to
the same policy once it has run, so none reaches the report or becomes
the address the host is reached at. A router on the host’s path that the
policy names, measured or spliced in from another trace, keeps its
distance and loses its address; see
Hop::withheld. A router or
firewall the policy names that sent second-hand evidence, such as an ICMP
unreachable, leaves its evidence on the host and its address off it; see
EvidenceSource::Withheld.
Every finding reaches the store through this function, so this one branch covers what a target-list subtraction cannot: ARP and neighbour-advertisement replies, the host’s own neighbour table, mDNS records, and, since they read the store to decide what to probe, the service, OS-series and SNMP phases that run afterwards.
A host whose record, once edit has run, holds the hardware address of a
machine the policy names is that machine at another address, and is
dropped whole: its record leaves the store, no event is emitted, and
every address it held is refused a probe from then on and listed with
the phase’s exclusions. See
the machine an address names.
A drop is logged, not counted: a reader can check that no excluded
address appears in the report against the ranges it records. The
addresses a machine’s drop withholds are counted once, when the phase
closes; see TargetScope::withheld.
Sourcepub fn read_host<R>(
&self,
ip: impl Into<ScopedIp>,
read: impl FnOnce(&Host) -> R,
) -> Option<R>
pub fn read_host<R>( &self, ip: impl Into<ScopedIp>, read: impl FnOnce(&Host) -> R, ) -> Option<R>
Reads the host at ip, if there is one, without cloning it.
The store’s guard is held for the duration of read and released before
this returns, so a caller cannot keep it across an await.
read must not touch this context again: reaching back into the store
under its own guard deadlocks.
Sourcepub fn contains_host(&self, ip: &ScopedIp) -> bool
pub fn contains_host(&self, ip: &ScopedIp) -> bool
Whether anything is recorded under ip.
The writing half’s HostStore::contains.
A question about the key: a host is recorded under one of its addresses, so this says whether there is a record here, not whether the machine is known.
Sourcepub fn host_addresses(&self) -> Vec<ScopedIp>
pub fn host_addresses(&self) -> Vec<ScopedIp>
Every address a host is currently recorded under.
A snapshot, so a caller may call write_host while
walking it; holding a live iterator over the map would deadlock.
Sourcepub fn record_failure(&self, scanner: ScannerKind, reason: String)
pub fn record_failure(&self, scanner: ScannerKind, reason: String)
The single place a strategy failure enters the record.
Logs it, files it for the final report, and announces it to any live consumer, in that order, so the durable copy exists before the notification that might be dropped. The scan continues with the strategies that remain.
Public so a caller running strategies themselves can file failures the way the engine’s own orchestration does.
The console line names the strategy as the report files it, then the reason.
Sourcepub fn record_refusal(&self, refusal: Refusal)
pub fn record_refusal(&self, refusal: Refusal)
The single place a refusal enters the record.
A refusal is the engine working out, before anything is sent, that part
of what it was asked has no strategy behind it: an SCTP port on a host
with no raw sockets, a prefix too large to walk, a technique a connect
scan cannot express. Nothing broke, so it is not announced on the event
stream and no strategy is blamed; see Refusal.
Filed once per distinct refusal, so a plan that declines the same range on two links says it once.
Not logged: a front end prints the report’s refusals at every verbosity, and logging would show each twice.
Public, like record_failure, so a caller
assembling their own scan can say what they declined.
Sourcepub fn refusals_snapshot(&self) -> Vec<Refusal>
pub fn refusals_snapshot(&self) -> Vec<Refusal>
The refusals filed so far, left in place.
The reading counterpart of record_refusal, as
failures_snapshot is for failures, for a
caller driving strategies themselves.
Sourcepub fn record_probe_stats(&self, stats: ProbeStats)
pub fn record_probe_stats(&self, stats: ProbeStats)
Files what an instrumented scanner observed about its own run.
Called once per scanner, as its receive loop exits. Not announced on the event stream, since it describes the run and changes no finding.
Public, like record_failure, so a custom
strategy can account for its own run in the report’s audit.
Sourcepub fn probe_stats_snapshot(&self) -> Vec<ProbeStats>
pub fn probe_stats_snapshot(&self) -> Vec<ProbeStats>
The probe counters filed so far, left in place.
The reading counterpart of record_probe_stats,
for a caller driving strategies themselves, who never reaches the phase
that drains these into a ScanReport.
It leaves the log in place, so the report still gets them.
Sourcepub fn record_unroutable(&self, address: IpAddr)
pub fn record_unroutable(&self, address: IpAddr)
Records that this host could not reach address, so no probe was sent
to it: no route or source address led there, or the neighbour never
answered address resolution.
Neither a failure nor an event. It is recorded so the report says why a target the caller asked about is missing.
Every target the plan numbers at the address is settled here as
Unreachable, unless it earned a verdict of its
own first: the address in a sweep’s numbering, and each of its ports in
a port scan’s, whichever phase filed it. See
Outcome::Unreachable for why that is settled.
Sourcepub fn host_expired(&self, address: IpAddr) -> bool
pub fn host_expired(&self, address: IpAddr) -> bool
Whether address has spent the per-host budget this scan was given,
starting its clock on the first probe aimed at it.
Every pass asks this before probing a host again. A host that answers
true writes itself into the phase’s
timed_out list, so no strategy
can leave a host early without the report saying so.
Always false, and cheap, for a scan with no budget. See
ZondConfig::host_timeout.
Sourcepub fn probe_ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant>
pub fn probe_ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant>
When a probe to address may next leave, or None if it may now.
For choosing which probe to try: another pass may take the slot before
the send. claim_probe decides.
Being turned away is not a verdict. The probe has not been sent, so
a caller that drops it reports an unasked port as silent. Hold it and
try again at the instant returned, or file it
Unasked.
Always None, and cheap, for a scan that keeps no gap. See
ZondConfig::host_probe_interval
and ZondConfig::probe_interval.
Sourcepub fn claim_probe(&self, address: IpAddr) -> Result<ProbeClaim, Instant>
pub fn claim_probe(&self, address: IpAddr) -> Result<ProbeClaim, Instant>
Takes the slot for one probe to address, or says when one will be
free.
Every send site asks this immediately before sending, beside
host_expired. An expired host is finished with
and goes into the phase’s
timed_out list; a host turned
away here will be ready at the instant returned. As with
probe_ready_at, a probe turned away is owed a
send or an Unasked, never a silence.
The decision and the record are one operation, so concurrent passes
share one bound. A send the kernel refuses gives the slot back with
refund_probe.
Always granted for a scan that keeps no gap, and then nothing is locked or stored.
Sourcepub fn refund_probe(&self, claim: ProbeClaim)
pub fn refund_probe(&self, claim: ProbeClaim)
Gives back the slot claim took, for a probe that never reached the
wire.
A probe the kernel refused must not spend a slot, as
RawProbeScan::record_send keeps it out of the congestion window. A
slot another probe has been recorded over since stays spent, which can
only lengthen a gap.
Sourcepub fn claim_group_probe(&self, group: IpAddr) -> Result<ProbeClaim, Instant>
pub fn claim_group_probe(&self, group: IpAddr) -> Result<ProbeClaim, Instant>
Takes the slot for one frame sent to group, a broadcast or multicast
address, or says when one will be free.
A frame to a group spends the scan-wide gap like any probe, but moves no
host’s clock, since it singles out no machine. A frame that asks about
one address, as a broadcast ARP request does, is aimed at that address
and claims with claim_probe.
Otherwise as claim_probe: taken immediately
before the send, a frame turned away is owed a send later, and one the
kernel refused gives its slot back with
refund_probe.
Sourcepub fn group_probe_ready_at(&self, now: Instant) -> Option<Instant>
pub fn group_probe_ready_at(&self, now: Instant) -> Option<Instant>
When a frame sent to a group may next leave, or None if it may now;
see claim_group_probe.
This is also when any probe may next leave as far as the scan-wide gap
goes. Always None for a scan that keeps no scan-wide gap.
Sourcepub fn record_reached_by_connect(&self, targets: &IpSet)
pub fn record_reached_by_connect(&self, targets: &IpSet)
Records that targets were reached by TCP connect in a phase that held
the privilege its raw strategies need.
For a strategy that, inside a raw phase, reaches its targets by connect:
loopback in any raw phase, and whatever self-built frames cannot reach
when frames are all the process has. Its findings are connect evidence,
which the phase’s privilege alone would present as raw. Ignored by a
phase recorded at
Privilege::Connect,
which reached everything this way. See
ScanPhase::reached_by_connect.
Sourcepub fn record_sweep(&self, zone: Zone)
pub fn record_sweep(&self, zone: Zone)
Records that this phase swept a whole link, beyond the addresses on it that were named.
Called by a strategy that sent a probe every host on the segment must
answer. See TargetScope::links:
a comparison can then tell a new host on a watched link from one on
ground nobody covered.
Sourcepub fn record_attachment(&self, attachment: Attachment)
pub fn record_attachment(&self, attachment: Attachment)
Records which switch port this machine turned out to be plugged into.
Called by whatever read an announcement off a link; see Attachment
for why this belongs to the phase. A device re-announcing itself
replaces the previous reading for that link and protocol.
Sourcepub fn record_outcome(&self, outcome: Outcome)
pub fn record_outcome(&self, outcome: Outcome)
Records what became of one target, for a later resume.
Separate from the verdict: a target reaches the store with a port
state, and this says whether the scan earned it or assigned it
because the run ended. See Outcome.
Call this only once the target’s finding is in the store. A checkpoint
reads the settlements before it takes the changed hosts, so settling
first could write a cursor that skips the target beside a findings file
without it, and a resume would never report the finding. See
checkpoint.
Sourcepub fn enter_stage(&self, stage: Stage, total: Option<u64>)
pub fn enter_stage(&self, stage: Stage, total: Option<u64>)
Announces the stage the scan has moved into, with how much work it holds where that is known before any of it is done.
Entering the stage that is already current adds to its total, so service detection running once per protocol reports one stage the size of both runs.
Sourcepub fn stage_advanced(&self)
pub fn stage_advanced(&self)
Counts one unit of the current stage as finished.
Called where the work completes. A stage that submits into a pool hands out all its work long before any of it is done.
Sourcepub fn record_many_outcomes(&self, outcome: Outcome, count: u64)
pub fn record_many_outcomes(&self, outcome: Outcome, count: u64)
Records count targets ending the same way, for the outcomes that carry
no position. See Settlements::record_many.
Sourcepub fn settle_address(&self, ip: IpAddr, settled: Settled)
pub fn settle_address(&self, ip: IpAddr, settled: Settled)
Records what became of one address, in a scan counted in addresses.
The position comes from the plan this scan is numbered in, so a strategy needs only the address and what came back.
Nothing is settled in two cases. A scan not counted in addresses has no numbering, so a port scan’s liveness pass settles nothing. An address the plan does not name, such as a neighbour a sweep found unasked, has no position. Either way the address is asked again on the next sitting, which is the safe direction.
Silence is recorded in both cases, for two readers. The port phase after
a liveness pass settles the ports of a host found down; see
Outcome::Skipped. And every discovery phase names the addresses it
reached no verdict on: its scope less what answered and what was asked
to exhaustion; see
ScanPhase::undecided.
Call this only once the answer’s finding is in the store; see
record_outcome.
Sourcepub fn settlements(&self) -> &Settlements
pub fn settlements(&self) -> &Settlements
How far the scan has got, and what became of what it did not settle.
Sourcepub fn restore_hosts(&self, hosts: &[Host])
pub fn restore_hosts(&self, hosts: &[Host])
Seeds the store with hosts an earlier sitting found.
Merged, so a host this sitting has already seen keeps both readings.
Each restored host is announced, since to a caller watching the stream it has just appeared. It is not marked changed, since it came from the journal.
This sitting’s exclusions apply to what comes back, address by address,
as in write_host, since a journal written before
an exclusion was added may hold addresses it now forbids. A host loses
each of those, and is restored under its best remaining address if its
key was among them; a host with no address left is left out. Routers on
its path and senders of evidence the policy names lose their addresses
as they would in write_host.
The journal itself is left as recorded; only what this sitting reports changes.
Sourcepub fn progress(&self) -> ScanProgress
pub fn progress(&self) -> ScanProgress
What a journal needs from a running scan.
A ScanContext carries the event sender, and a checkpoint task
holding one would keep the event stream open after the scan ended: a
caller waiting for the stream to end would wait for the checkpoint task,
which waits for the caller to stop it.
A failure recorded through this reaches the report but not the stream, since a checkpoint that could not be written is about the journal, not a scanning strategy.
From the first call on, the detection phase keeps its runs’ tapes for
ScanProgress::take_tapes, and which ports of a host changed is
tracked too.
Sourcepub fn hosts_snapshot(&self) -> Vec<Host>
pub fn hosts_snapshot(&self) -> Vec<Host>
Every host found so far, cloned, ordered by the address each is keyed under.
For a journal compacting its findings. Ordered so the same findings produce the same file.
Sourcepub fn host_count(&self) -> usize
pub fn host_count(&self) -> usize
How many hosts have been found so far.
Sourcepub fn take_changed_hosts(&self) -> Vec<Host>
pub fn take_changed_hosts(&self) -> Vec<Host>
Takes the hosts whose findings have changed since this was last called, with their current state.
For a journal writing findings down as a scan produces them. Draining, so a host is written once per change.
Sourcepub fn failures_snapshot(&self) -> Vec<ScannerFailure>
pub fn failures_snapshot(&self) -> Vec<ScannerFailure>
The strategy failures filed so far, left in place.
The reading counterpart of record_failure, like
probe_stats_snapshot, for a caller
driving strategies themselves who wants failures before a phase closes.
Leaves the log in place for
PhaseRecorder::finish
to drain into the report.
Sourcepub fn update_host(
&self,
ip: impl Into<ScopedIp>,
update: impl FnOnce(&mut Host),
) -> bool
pub fn update_host( &self, ip: impl Into<ScopedIp>, update: impl FnOnce(&mut Host), ) -> bool
Upserts the host at ip, applies update, and unconditionally announces
the change. The convenience form of write_host for
paths that always record a finding worth emitting, such as a port state
or a merged host. Returns true if this call created the host.
Trait Implementations§
Auto Trait Implementations§
impl !RefUnwindSafe for ScanContext
impl !UnwindSafe for ScanContext
impl Freeze for ScanContext
impl Send for ScanContext
impl Sync for ScanContext
impl Unpin for ScanContext
impl UnsafeUnpin for ScanContext
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