Skip to main content

ScanContext

Struct ScanContext 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub fn settlements(&self) -> &Settlements

How far the scan has got, and what became of what it did not settle.

Source

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.

Source

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.

Source

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.

Source

pub fn host_count(&self) -> usize

How many hosts have been found so far.

Source

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.

Source

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.

Source

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§

Source§

impl Clone for ScanContext

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

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