Skip to main content

SessionBuilder

Struct SessionBuilder 

Source
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

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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.

Source

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

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Default for SessionBuilder

Source§

fn default() -> Self

Returns the “default value” for a type. 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> 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, 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