pub struct SessionBuilder { /* private fields */ }Expand description
Builds a ScanSession and the ScanContext the strategies behind it
write into.
Everything a session can be given beyond its defaults, most of which a caller leaves alone. Each setting is named once, and an unset one keeps its neutral value.
use zond_engine::scanner::session::ScanSession;
let (session, ctx) = ScanSession::builder().build();Implementations§
Source§impl SessionBuilder
impl SessionBuilder
Sourcepub fn excluding(self, exclusions: Exclusions) -> Self
pub fn excluding(self, exclusions: Exclusions) -> Self
Addresses the scan may not record a finding against.
A caller orchestrating their own scan under an exclusion policy has to
set this as well as subtracting the addresses from their target list,
since a segment sweep reaches beyond the addresses named. See
Exclusions for what each of the two enforcements is for.
A policy naming an address on a segment this host has spoken to
recently names the machine there too, whatever other addresses it
answers at: build reads the host’s neighbour tables for
its hardware address. See Exclusions.
Sourcepub fn naming(self, names: BTreeMap<IpAddr, String>) -> Self
pub fn naming(self, names: BTreeMap<IpAddr, String>) -> Self
The name each address was asked for by, where a target named a host.
A host recorded at one of these addresses carries its name as its
hostname from the moment it is recorded, and its web ports are asked
for by it; see
ZondConfig::target_names.
Sourcepub fn resuming(self, settled: &Checkpoint) -> Self
pub fn resuming(self, settled: &Checkpoint) -> Self
The cursor this scan checkpoints from, for one continuing an earlier sitting.
Without it a resumed scan writes a cursor covering only its own sitting, and the journal forgets everything the first one settled.
Sourcepub fn counting(self, positions: Positions) -> Self
pub fn counting(self, positions: Positions) -> Self
How this scan numbers an address, for one counted in addresses.
A sweep sets this so a strategy that has earned a verdict for an address
can settle it without knowing where in the plan it sits; see
ScanContext::settle_address.
A port scan leaves it alone. It numbers address-and-port pairs on its target stream, so the discovery strategies in its liveness pass settle nothing, and the port plan’s watermark does not advance over probes nobody sent.
Sourcepub fn ordering(self, seed: Option<u64>) -> Self
pub fn ordering(self, seed: Option<u64>) -> Self
The seed of the order this scan asks its targets in.
With a seed, the scan walks a permutation of the whole index space, so a
sweep of a range does not have the address-order shape correlating
sensors look for. See Permutation.
Left unset, the session draws its own seed when built, so the dispatcher’s streams and the sweeps that hold their own first attempts all walk one order.
Pass None for plan order, shuffled within a batch, which is the
fallback for a plan that cannot be addressed by position. A sitting
continuing a journal that recorded no seed must pass it, since its
checkpoint counts along the plan.
A caller journalling their scan should pass the journal’s seed, so a
resumed sitting continues in the first one’s order, as
scan_with_journal does.
Sourcepub fn planning(self, stage: Stage, total: Option<u64>) -> Self
pub fn planning(self, stage: Stage, total: Option<u64>) -> Self
How many targets the plan holds, and which Stage does that work.
This is the denominator Progress::fraction divides into while that
stage is running, so it has to be counted in the same unit the stage
settles in: addresses for a sweep, address-and-port pairs for a port
scan. Positions::total and
TargetIndex::total are
those two counts, and each has a companion that says whether it covered
the whole plan.
The stage matters in a scan with more than one: a port scan’s liveness pass measured against address-and-port pairs would read nought percent throughout.
Left unset, a consumer gets only a running count of what has settled, which is all an uncountable plan can offer.
Sourcepub fn staging(self, stages: Vec<Stage>) -> Self
pub fn staging(self, stages: Vec<Stage>) -> Self
The stages this scan expects to run, in the order it will run them.
What Progress::overall measures a whole run against. Pass a
superset: a listed stage that is skipped moves the figure forward over
it, while an unlisted stage that runs leaves the figure still until the
next listed one.
discover and scan
derive this from their settings. A caller orchestrating their own scan
lists the stages they mean to run, or reads progress one stage at a time.
Sourcepub fn detections(self, detections: Detections) -> Self
pub fn detections(self, detections: Detections) -> Self
The corpus the detection phase runs, the shipped one unless set otherwise.
scan sets the corpus it was given here; a caller
orchestrating their own scan sets it directly so their detections run in it.
Sourcepub fn host_timeout(self, budget: Option<Duration>) -> Self
pub fn host_timeout(self, budget: Option<Duration>) -> Self
The wall-clock budget each host gets before the scan leaves it.
A caller orchestrating their own scan sets this to have the same bound
scan applies from
ZondConfig::host_timeout.
Every strategy that probes a host reads it through
ScanContext::host_expired.
Sourcepub fn scan_timeout(self, budget: Option<Duration>) -> Self
pub fn scan_timeout(self, budget: Option<Duration>) -> Self
The wall-clock budget the whole scan gets before it winds down.
Starts when build is called, and reaches every strategy
through the ScanHandle they already read. See
ZondConfig::scan_timeout.
Sourcepub fn host_probe_interval(self, minimum: Option<Duration>) -> Self
pub fn host_probe_interval(self, minimum: Option<Duration>) -> Self
The shortest gap the scan keeps between two probes aimed at one host.
A caller orchestrating their own scan sets this to have the same spacing
scan applies from
ZondConfig::host_probe_interval.
Every pass that sends claims its slots through
ScanContext::claim_probe, which says what being turned away means
for a probe.
None is no gap. Some(Duration::MAX) is the longest gap there is,
one probe per host for the rest of the scan, not “no limit”; see the
config field.
Sourcepub fn probe_interval(self, minimum: Option<Duration>) -> Self
pub fn probe_interval(self, minimum: Option<Duration>) -> Self
The shortest gap the scan keeps between any two probes it sends, whatever host each is aimed at.
A caller orchestrating their own scan sets this to have the same spacing
scan applies from
ZondConfig::probe_interval.
Claimed through ScanContext::claim_probe alongside the per-host gap,
on the same terms.
Sourcepub fn send_source(self, sources: Vec<IpAddr>) -> Self
pub fn send_source(self, sources: Vec<IpAddr>) -> Self
The source addresses the connections this scan opens are forced to, one per family.
A caller orchestrating their own scan sets this to have the same pinning
scan applies from
ZondConfig::send_source:
every connection to a routed target, from the connect scan or the
service pass, leaves from the forced source and its interface, as the
raw probes do.
Sourcepub fn listening_only_to(self, ports: BTreeSet<u16>) -> Self
pub fn listening_only_to(self, ports: BTreeSet<u16>) -> Self
The TCP ports this scan only connects to and listens on, sending nothing.
Left unset, the printers’ ports,
RAW_PRINT_PORTS, as
scan uses by default. A caller
orchestrating their own scan sets this to what
ZondConfig::listen_only_ports
says, and an empty set probes every port alike.
Sourcepub fn build(self) -> (ScanSession, ScanContext)
pub fn build(self) -> (ScanSession, ScanContext)
Opens the session and the context.
The scan’s own clock starts here, so building late still gets the full budget.
Trait Implementations§
Source§impl Debug for SessionBuilder
impl Debug for SessionBuilder
Auto Trait Implementations§
impl !RefUnwindSafe for SessionBuilder
impl !UnwindSafe for SessionBuilder
impl Freeze for SessionBuilder
impl Send for SessionBuilder
impl Sync for SessionBuilder
impl Unpin for SessionBuilder
impl UnsafeUnpin for SessionBuilder
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> 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