use dashmap::DashMap;
use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::net::IpAddr;
use std::sync::atomic::{AtomicBool, AtomicU8, AtomicU64, AtomicUsize, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use std::time::{Duration, Instant};
use tokio::sync::broadcast;
use tokio::sync::broadcast::error::{RecvError, TryRecvError};
use tracing::error;
use crate::config::ServiceDetection;
use crate::detect::compute::DetectionRunRecord;
use crate::info;
use crate::journal::settle::{Outcome, Settled, Settlements};
use crate::model::exclusion::Exclusions;
use crate::model::host::Host;
use crate::model::ip::range::IpRange;
use crate::model::ip::scoped::{ScopedIp, Zone, ZoneMap};
use crate::model::ip::set::{IpSet, Positions};
use crate::model::mac::MacAddr;
use crate::model::port::{PortState, Protocol};
use crate::report::ScannerKind;
use crate::report::{Attachment, AttachmentSource, Pass, ProbeStats, Refusal, ScannerFailure};
use crate::scanner::handle::ScanHandle;
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Hash)]
pub enum Stage {
#[default]
Discovery,
Ports,
Services,
Detections,
Tls,
Os,
Traceroute,
Filters,
IpProtocols,
Listening,
Finishing,
}
impl Stage {
pub const ALL: &'static [Self] = &[
Self::Discovery,
Self::Ports,
Self::Services,
Self::Detections,
Self::Tls,
Self::Os,
Self::Traceroute,
Self::Filters,
Self::IpProtocols,
Self::Listening,
Self::Finishing,
];
const fn code(self) -> u8 {
match self {
Stage::Discovery => 0,
Stage::Ports => 1,
Stage::Services => 2,
Stage::Detections => 3,
Stage::Tls => 4,
Stage::Os => 5,
Stage::Traceroute => 6,
Stage::Filters => 7,
Stage::IpProtocols => 8,
Stage::Listening => 9,
Stage::Finishing => 10,
}
}
const fn from_code(code: u8) -> Self {
match code {
1 => Stage::Ports,
2 => Stage::Services,
3 => Stage::Detections,
4 => Stage::Tls,
5 => Stage::Os,
6 => Stage::Traceroute,
7 => Stage::Filters,
8 => Stage::IpProtocols,
9 => Stage::Listening,
10 => Stage::Finishing,
_ => Stage::Discovery,
}
}
}
impl std::fmt::Display for Stage {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
let name = match self {
Stage::Discovery => "discovery",
Stage::Ports => "ports",
Stage::Services => "services",
Stage::Detections => "detections",
Stage::Tls => "tls",
Stage::Os => "os",
Stage::Traceroute => "traceroute",
Stage::Filters => "filters",
Stage::IpProtocols => "ip protocols",
Stage::Listening => "listening",
Stage::Finishing => "finishing",
};
f.write_str(name)
}
}
#[derive(Debug, Default)]
pub(crate) struct Stages {
current: AtomicU8,
done: AtomicU64,
total: AtomicU64,
planned: Vec<Stage>,
reached: AtomicUsize,
shown: Mutex<(u64, u64)>,
}
impl Stages {
fn new(planned: Vec<Stage>) -> Self {
Self {
planned,
..Self::default()
}
}
fn overall(&self, within: Option<(u64, u64)>) -> Option<(u64, u64)> {
let stages = u64::try_from(self.planned.len()).ok().filter(|n| *n > 0)?;
let reached = u64::try_from(self.reached.load(Ordering::Relaxed)).unwrap_or(0);
let reading = match within.filter(|_| self.planned.contains(&self.stage())) {
Some((done, total)) => (reached * total + done.min(total), stages * total),
None => (reached.min(stages), stages),
};
let mut shown = self.shown.lock().unwrap_or_else(|held| held.into_inner());
let behind = u128::from(reading.0) * u128::from(shown.1)
< u128::from(shown.0) * u128::from(reading.1);
if shown.1 == 0 || !behind {
*shown = reading;
}
Some(*shown)
}
fn enter(&self, stage: Stage, total: Option<u64>) -> bool {
let total = total.unwrap_or(0);
let reached = self
.planned
.iter()
.filter(|planned| planned.code() < stage.code())
.count();
self.reached.fetch_max(reached, Ordering::Relaxed);
if self.current.swap(stage.code(), Ordering::Relaxed) == stage.code() {
self.total.fetch_add(total, Ordering::Relaxed);
return false;
}
self.done.store(0, Ordering::Relaxed);
self.total.store(total, Ordering::Relaxed);
true
}
fn advance(&self) {
self.done.fetch_add(1, Ordering::Relaxed);
}
fn stage(&self) -> Stage {
Stage::from_code(self.current.load(Ordering::Relaxed))
}
fn done(&self) -> u64 {
self.done.load(Ordering::Relaxed)
}
fn total(&self) -> Option<u64> {
match self.total.load(Ordering::Relaxed) {
0 => None,
total => Some(total),
}
}
}
#[derive(Debug, Clone)]
#[non_exhaustive]
pub enum ScanEvent {
HostUpdated(ScopedIp),
ScannerFailed {
scanner: ScannerKind,
reason: String,
},
StageChanged {
stage: Stage,
},
EventsDropped {
count: u64,
},
}
#[derive(Debug, Clone, Default)]
pub struct HostStore {
inner: Arc<DashMap<ScopedIp, Host>>,
}
impl HostStore {
fn new(inner: Arc<DashMap<ScopedIp, Host>>) -> Self {
Self { inner }
}
pub fn get(&self, ip: impl Into<ScopedIp>) -> Option<Host> {
self.inner
.get(&ip.into())
.map(|entry| entry.value().clone())
}
pub fn read<R>(&self, ip: impl Into<ScopedIp>, read: impl FnOnce(&Host) -> R) -> Option<R> {
self.inner.get(&ip.into()).map(|entry| read(entry.value()))
}
pub fn contains(&self, ip: impl Into<ScopedIp>) -> bool {
self.inner.contains_key(&ip.into())
}
pub fn len(&self) -> usize {
self.inner.len()
}
pub fn is_empty(&self) -> bool {
self.inner.is_empty()
}
pub fn snapshot(&self) -> Vec<Host> {
let mut hosts: Vec<Host> = self
.inner
.iter()
.map(|entry| entry.value().clone())
.collect();
hosts.sort_by_cached_key(Host::scoped_ip);
hosts
}
#[cfg(test)]
pub(crate) fn insert(&self, ip: impl Into<ScopedIp>, host: Host) {
self.inner.insert(ip.into(), host);
}
}
#[derive(Debug)]
pub struct ScanEvents {
rx: broadcast::Receiver<ScanEvent>,
}
impl ScanEvents {
pub const CAPACITY: usize = 1024;
pub async fn recv(&mut self) -> Option<ScanEvent> {
match self.rx.recv().await {
Ok(event) => Some(event),
Err(RecvError::Lagged(count)) => Some(ScanEvent::EventsDropped { count }),
Err(RecvError::Closed) => None,
}
}
pub fn try_recv(&mut self) -> Option<ScanEvent> {
match self.rx.try_recv() {
Ok(event) => Some(event),
Err(TryRecvError::Lagged(count)) => Some(ScanEvent::EventsDropped { count }),
Err(TryRecvError::Empty | TryRecvError::Closed) => None,
}
}
}
#[derive(Debug, Clone)]
pub struct Progress {
settlements: Arc<Settlements>,
planned: Option<u64>,
plan_stage: Stage,
stages: Arc<Stages>,
}
impl Progress {
fn new(
settlements: Arc<Settlements>,
planned: Option<u64>,
plan_stage: Stage,
stages: Arc<Stages>,
) -> Self {
Self {
settlements,
planned,
plan_stage,
stages,
}
}
pub fn stage(&self) -> Stage {
self.stages.stage()
}
pub fn stage_done(&self) -> u64 {
self.stages.done()
}
pub fn stage_total(&self) -> Option<u64> {
self.stages.total()
}
pub fn settled(&self) -> u64 {
self.settlements.settled_count()
}
pub const fn planned(&self) -> Option<u64> {
self.planned
}
pub fn remaining(&self) -> Option<u64> {
self.planned
.map(|planned| planned.saturating_sub(self.settled()))
}
pub fn fraction(&self) -> Option<f64> {
let (done, total) = self.counted()?;
Some(ratio(done, total))
}
pub fn overall(&self) -> Option<(u64, u64)> {
self.stages.overall(self.counted())
}
pub fn counted(&self) -> Option<(u64, u64)> {
match self.stage_total() {
Some(total) => Some((self.stage_done(), total)),
None if self.stage() == self.plan_stage => {
let planned = self.planned?;
let settlements = &self.settlements;
let unprobed = settlements.count(Outcome::Skipped { position: 0 })
+ settlements.count(Outcome::Withheld { position: 0 })
+ settlements.count(Outcome::Unreachable { position: 0 });
let undecided = settlements.count(Outcome::Undecided);
Some((
self.settled().saturating_sub(unprobed),
planned.saturating_sub(unprobed + undecided),
))
}
None => None,
}
}
}
fn ratio(done: u64, total: u64) -> f64 {
if total == 0 {
return 1.0;
}
(done as f64 / total as f64).min(1.0)
}
pub struct ScanSession {
store: HostStore,
events: ScanEvents,
handle: ScanHandle,
progress: Progress,
}
impl ScanSession {
pub fn hosts(&self) -> &HostStore {
&self.store
}
pub fn events(&mut self) -> &mut ScanEvents {
&mut self.events
}
pub fn handle(&self) -> &ScanHandle {
&self.handle
}
pub fn progress(&self) -> &Progress {
&self.progress
}
pub fn into_parts(self) -> (HostStore, ScanEvents, ScanHandle, Progress) {
(self.store, self.events, self.handle, self.progress)
}
}
#[derive(Debug, Default)]
pub(crate) struct ProbeStatsLog {
entries: Mutex<Vec<ProbeStats>>,
}
impl ProbeStatsLog {
fn push(&self, stats: ProbeStats) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.push(stats);
}
fn drain(&self) -> Vec<ProbeStats> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries)
}
fn snapshot(&self) -> Vec<ProbeStats> {
self.entries
.lock()
.unwrap_or_else(|e| e.into_inner())
.clone()
}
}
#[derive(Default)]
pub(crate) struct Responses {
inner: DashMap<(ScopedIp, u16, Protocol), Vec<String>>,
lost: DashMap<(ScopedIp, u16, Protocol), ()>,
}
impl Responses {
fn record(&self, ip: ScopedIp, number: u16, protocol: Protocol, banners: Vec<String>) {
let key = (ip, number, protocol);
self.lost.remove(&key);
if !banners.is_empty() {
self.inner.insert(key, banners);
}
}
fn inherit(&self, ip: ScopedIp, number: u16, protocol: Protocol) {
self.lost.insert((ip, number, protocol), ());
}
fn lost(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> bool {
self.lost.contains_key(&(ip.clone(), number, protocol))
}
fn take(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> Vec<String> {
self.inner
.remove(&(ip.clone(), number, protocol))
.map(|(_, banners)| banners)
.unwrap_or_default()
}
}
#[derive(Debug, Default)]
struct Finished {
hosts: HashSet<String>,
asked: IpSet,
}
#[derive(Debug, Default)]
pub(crate) struct Tapes {
inner: Mutex<Vec<DetectionRunRecord>>,
kept: AtomicBool,
}
impl Tapes {
pub(crate) fn record(&self, run: impl FnOnce() -> DetectionRunRecord) {
if !self.kept.load(Ordering::Acquire) {
return;
}
let run = run();
self.inner
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
.push(run);
}
fn keep(&self) {
self.kept.store(true, Ordering::Release);
}
pub(crate) fn take(&self) -> Vec<DetectionRunRecord> {
std::mem::take(
&mut self
.inner
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner),
)
}
#[cfg(feature = "journal-format")]
fn hand_back(&self, mut runs: Vec<DetectionRunRecord>) {
if runs.is_empty() {
return;
}
let mut inner = self
.inner
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
runs.append(&mut inner);
*inner = runs;
}
}
#[derive(Debug, Default)]
pub(crate) struct RefusalLog {
entries: Mutex<Vec<Refusal>>,
}
impl RefusalLog {
fn push(&self, refusal: Refusal) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
if !entries.contains(&refusal) {
entries.push(refusal);
}
}
fn drain(&self) -> Vec<Refusal> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries)
}
fn snapshot(&self) -> Vec<Refusal> {
self.entries
.lock()
.unwrap_or_else(|e| e.into_inner())
.clone()
}
}
#[derive(Debug, Default)]
pub(crate) struct UnroutableLog {
entries: Mutex<std::collections::BTreeSet<IpAddr>>,
}
impl UnroutableLog {
fn insert(&self, address: IpAddr) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(address);
}
fn contains(&self, address: IpAddr) -> bool {
let entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.contains(&address)
}
fn drain(&self) -> Vec<IpAddr> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_iter().collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct RateLimitedLog {
entries: Mutex<std::collections::BTreeSet<IpAddr>>,
}
impl RateLimitedLog {
fn insert(&self, address: IpAddr) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(address);
}
fn drain(&self) -> Vec<IpAddr> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_iter().collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct PassLog {
entries: Mutex<std::collections::BTreeSet<Pass>>,
}
impl PassLog {
fn insert(&self, pass: Pass) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(pass);
}
fn drain(&self) -> Vec<Pass> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_iter().collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct TimedOutLog {
entries: Mutex<std::collections::BTreeSet<IpAddr>>,
}
impl TimedOutLog {
fn insert(&self, address: IpAddr) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(address);
}
fn contains(&self, address: IpAddr) -> bool {
let entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.contains(&address)
}
fn drain(&self) -> Vec<IpAddr> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_iter().collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct SilenceLog {
entries: Mutex<Silence>,
}
#[derive(Debug, Default)]
struct Silence {
set: IpSet,
merged: usize,
added: usize,
}
impl SilenceLog {
const MERGE_AFTER: usize = 4096;
fn insert(&self, address: IpAddr) {
let mut silence = self.entries.lock().unwrap_or_else(|e| e.into_inner());
silence.set.insert(address);
silence.added += 1;
if silence.added >= Self::MERGE_AFTER.max(silence.merged) {
silence.set.canonicalize();
silence.merged = silence.set.v4().len() + silence.set.v6().len();
silence.added = 0;
}
}
fn drain(&self) -> IpSet {
let mut silence = self.entries.lock().unwrap_or_else(|e| e.into_inner());
let mut taken = std::mem::take(&mut *silence).set;
taken.canonicalize();
taken
}
}
#[derive(Debug, Default)]
pub(crate) struct ConnectLog {
entries: Mutex<IpSet>,
}
impl ConnectLog {
fn extend(&self, targets: &IpSet) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
for range in targets.v4() {
entries.push_v4_range(*range);
}
for range in targets.v6() {
entries.push_v6_range(*range);
}
}
fn drain(&self, unreached: &[IpAddr]) -> Vec<IpRange> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
let mut taken = std::mem::take(&mut *entries);
taken.canonicalize();
if !unreached.is_empty() {
let mut unreached_set = IpSet::new();
for address in unreached {
unreached_set.insert(*address);
}
unreached_set.canonicalize();
taken.subtract(&unreached_set);
}
let v4 = taken.v4().iter().copied().map(IpRange::V4);
let v6 = taken.v6().iter().copied().map(IpRange::V6);
v4.chain(v6).collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct HostClocks {
budget: Option<Duration>,
started: DashMap<IpAddr, Instant>,
}
#[derive(Debug, Default)]
pub(crate) struct HostSpacing {
minimum: Option<Duration>,
last_sent: DashMap<IpAddr, Instant>,
}
impl HostSpacing {
fn ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant> {
let minimum = self.minimum?;
let last = *self.last_sent.get(&address)?;
let ready = crate::scanner::pacing::timer::later(last, minimum);
(ready > now).then_some(ready)
}
fn sent(&self, address: IpAddr, now: Instant) {
if self.minimum.is_none() {
return;
}
self.last_sent.insert(address, now);
}
}
impl HostClocks {
fn expired(&self, address: IpAddr) -> bool {
let Some(budget) = self.budget else {
return false;
};
if let Some(started) = self.started.get(&address) {
return started.elapsed() >= budget;
}
let started = *self.started.entry(address).or_insert_with(Instant::now);
started.elapsed() >= budget
}
}
#[derive(Debug, Default)]
pub(crate) struct SweptLinks {
entries: Mutex<std::collections::BTreeMap<String, Zone>>,
}
impl SweptLinks {
fn insert(&self, zone: Zone) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(zone.name().to_owned(), zone);
}
fn drain(&self) -> Vec<Zone> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_values().collect()
}
}
#[derive(Debug, Default)]
pub(crate) struct Attachments {
entries: Mutex<std::collections::BTreeMap<(String, AttachmentSource), Attachment>>,
}
impl Attachments {
fn insert(&self, attachment: Attachment) {
let key = (attachment.link().name().to_owned(), attachment.source());
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.insert(key, attachment);
}
fn drain(&self) -> Vec<Attachment> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries).into_values().collect()
}
}
fn snapshot_of(store: &DashMap<ScopedIp, Host>) -> Vec<Host> {
let mut hosts: Vec<Host> = store.iter().map(|entry| entry.value().clone()).collect();
hosts.sort_by_cached_key(Host::scoped_ip);
hosts
}
fn changed_since(store: &DashMap<ScopedIp, Host>, changed: &ChangedHosts) -> Vec<Host> {
changed
.drain()
.into_keys()
.filter_map(|key| store.get(&key).map(|host| host.clone()))
.collect()
}
#[cfg(feature = "journal-format")]
fn changes_since(store: &DashMap<ScopedIp, Host>, changed: &ChangedHosts) -> Vec<Host> {
changed
.drain()
.into_iter()
.filter_map(|(key, pending)| {
let host = store.get(&key)?;
Some(match pending {
Pending::Ports(ports) => host.with_only_ports(&ports),
Pending::Whole => host.clone(),
})
})
.collect()
}
#[cfg(feature = "journal-format")]
fn awaits_verdict(host: &Host) -> bool {
host.status() == crate::model::host::HostStatus::Unknown
}
#[cfg(feature = "journal-format")]
#[derive(Debug, Clone, Default)]
pub(crate) struct SoFar {
pub(crate) silent: Vec<IpRange>,
pub(crate) awaiting: IpSet,
pub(crate) unheard_probes: u64,
}
#[cfg(feature = "journal-format")]
pub(crate) fn ranges_of(set: &IpSet) -> Vec<IpRange> {
let v4 = set.v4().iter().copied().map(IpRange::V4);
let v6 = set.v6().iter().copied().map(IpRange::V6);
v4.chain(v6).collect()
}
#[derive(Debug, Clone)]
pub struct ScanProgress {
store: Arc<DashMap<ScopedIp, Host>>,
changed: Arc<ChangedHosts>,
settlements: Arc<Settlements>,
failures: Arc<FailureLog>,
tapes: Arc<Tapes>,
#[cfg(feature = "journal-format")]
verdicts_pending: Arc<AtomicBool>,
#[cfg(feature = "journal-format")]
sitting: Arc<Sitting>,
#[cfg(feature = "journal-format")]
numbering: Arc<OnceLock<crate::model::target::TargetIndex>>,
}
impl ScanProgress {
pub fn settlements(&self) -> &Settlements {
&self.settlements
}
pub fn take_changed_hosts(&self) -> Vec<Host> {
changed_since(&self.store, &self.changed)
}
pub fn take_tapes(&self) -> Vec<DetectionRunRecord> {
self.tapes.take()
}
pub fn hosts_snapshot(&self) -> Vec<Host> {
snapshot_of(&self.store)
}
pub fn host_count(&self) -> usize {
self.store.len()
}
#[cfg(feature = "journal-format")]
pub(crate) fn host_keys(&self) -> Vec<ScopedIp> {
self.store.iter().map(|entry| entry.key().clone()).collect()
}
#[cfg(feature = "journal-format")]
pub(crate) fn take_changed_findings(&self) -> Vec<Host> {
changes_since(&self.store, &self.changed)
}
#[cfg(feature = "journal-format")]
pub(crate) fn standing_phases(&self, so_far: &SoFar) -> Vec<crate::report::ScanPhase> {
self.sitting.standing(self.failures.snapshot(), so_far)
}
#[cfg(feature = "journal-format")]
pub(crate) fn verdicts_so_far(&self, cursor: &crate::journal::cursor::Checkpoint) -> SoFar {
if !self.verdicts_pending.load(Ordering::Acquire) {
return SoFar::default();
}
let Some(numbering) = self.numbering.get() else {
return SoFar::default();
};
let mut silent = IpSet::new();
let mut awaiting = IpSet::new();
let mut unheard_probes = 0u64;
for entry in self.store.iter() {
let host = entry.value();
if !awaits_verdict(host) {
continue;
}
let address = entry.key().addr();
let mut owed = 0u64;
let mut settled = true;
for run in numbering.runs_at(address) {
owed += run.end - run.start;
settled &= run.clone().all(|position| cursor.is_settled(position));
}
let asked = host
.ports()
.filter(|port| port.state() != PortState::Unasked)
.count() as u64;
if owed > 0 && settled && asked == owed {
silent.insert(address);
unheard_probes += asked;
} else {
awaiting.insert(address);
}
}
silent.canonicalize();
awaiting.canonicalize();
SoFar {
silent: ranges_of(&silent),
awaiting,
unheard_probes,
}
}
#[cfg(feature = "journal-format")]
pub(crate) fn hand_back(&self, hosts: &[Host]) {
for host in hosts {
self.changed.put_back(host);
}
}
#[cfg(feature = "journal-format")]
pub(crate) fn hand_back_tapes(&self, runs: Vec<DetectionRunRecord>) {
self.tapes.hand_back(runs);
}
#[cfg(feature = "journal-format")]
pub(crate) fn findings_snapshot(&self) -> Vec<Host> {
self.hosts_snapshot()
}
pub fn record_failure(&self, scanner: ScannerKind, reason: String) {
error!(
"{} failed: {reason}",
crate::record::wire::scanner_kind_name(scanner)
);
self.failures.push(ScannerFailure::new(scanner, reason));
}
}
#[derive(Debug, Default)]
pub(crate) struct ChangedHosts {
entries: Mutex<BTreeMap<ScopedIp, Pending>>,
ports_kept: AtomicBool,
}
#[derive(Debug)]
enum Pending {
Ports(BTreeSet<(u16, Protocol)>),
Whole,
}
impl ChangedHosts {
fn insert(&self, ip: ScopedIp, touched: Option<BTreeSet<(u16, Protocol)>>) {
let touched = touched.filter(|_| self.keeps_ports());
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
match (entries.entry(ip), touched) {
(std::collections::btree_map::Entry::Vacant(slot), touched) => {
slot.insert(touched.map_or(Pending::Whole, Pending::Ports));
}
(std::collections::btree_map::Entry::Occupied(mut slot), Some(touched)) => {
if let Pending::Ports(ports) = slot.get_mut() {
ports.extend(touched);
}
}
(std::collections::btree_map::Entry::Occupied(mut slot), None) => {
slot.insert(Pending::Whole);
}
}
}
#[cfg(feature = "journal-format")]
fn put_back(&self, host: &Host) {
let ports = host
.ports()
.map(|port| (port.number(), port.protocol()))
.collect();
self.insert(host.scoped_ip(), Some(ports));
}
fn keep_ports(&self) {
self.ports_kept.store(true, Ordering::Release);
}
fn keeps_ports(&self) -> bool {
self.ports_kept.load(Ordering::Acquire)
}
fn drain(&self) -> BTreeMap<ScopedIp, Pending> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries)
}
}
#[derive(Debug, Default)]
pub(crate) struct FailureLog {
entries: Mutex<Vec<ScannerFailure>>,
}
impl FailureLog {
fn push(&self, failure: ScannerFailure) {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
entries.push(failure);
}
fn drain(&self) -> Vec<ScannerFailure> {
let mut entries = self.entries.lock().unwrap_or_else(|e| e.into_inner());
std::mem::take(&mut *entries)
}
fn snapshot(&self) -> Vec<ScannerFailure> {
self.entries
.lock()
.unwrap_or_else(|e| e.into_inner())
.clone()
}
}
#[derive(Debug, Default)]
pub(crate) struct Sitting {
phases: Mutex<SittingPhases>,
}
#[derive(Debug, Default)]
struct SittingPhases {
closed: Vec<crate::report::ScanPhase>,
open: Option<crate::scanner::recorder::Opened>,
}
impl Sitting {
fn open(&self, opened: crate::scanner::recorder::Opened) {
let mut phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
phases.open = Some(opened);
}
fn close(&self, phase: &crate::report::ScanPhase) {
let mut phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
phases.open = None;
phases.closed.push(phase.clone());
}
#[cfg(feature = "journal-format")]
fn standing(
&self,
failures: Vec<ScannerFailure>,
so_far: &SoFar,
) -> Vec<crate::report::ScanPhase> {
let phases = self.phases.lock().unwrap_or_else(|e| e.into_inner());
let mut standing = phases.closed.clone();
standing.extend(
phases
.open
.as_ref()
.map(|open| open.standing(failures, so_far)),
);
standing
}
}
#[derive(Clone)]
pub struct ScanContext {
pub(crate) handle: ScanHandle,
pub(crate) store: Arc<DashMap<ScopedIp, Host>>,
pub(crate) events_tx: broadcast::Sender<ScanEvent>,
pub(crate) failures: Arc<FailureLog>,
pub(crate) refusals: Arc<RefusalLog>,
pub(crate) probe_stats: Arc<ProbeStatsLog>,
pub(crate) unroutable: Arc<UnroutableLog>,
pub(crate) refused_by_route: Arc<UnroutableLog>,
pub(crate) withheld_neighbours: Arc<UnroutableLog>,
pub(crate) timed_out: Arc<TimedOutLog>,
pub(crate) passes_cut: Arc<PassLog>,
pub(crate) icmp_rate_limited: Arc<RateLimitedLog>,
pub(crate) reached_by_connect: Arc<ConnectLog>,
pub(crate) silent: Arc<SilenceLog>,
pub(crate) undecided: Arc<SilenceLog>,
pub(crate) unreached: Arc<AtomicU64>,
pub(crate) unheard_probes: Arc<AtomicU64>,
pub(crate) verdicts_pending: Arc<AtomicBool>,
pub(crate) sitting: Arc<Sitting>,
pub(crate) plan_stage: Stage,
pub(crate) clocks: Arc<HostClocks>,
pub(crate) spacing: Arc<HostSpacing>,
pub(crate) zones: Arc<OnceLock<ZoneMap>>,
pub(crate) capture_links: Arc<OnceLock<Vec<Zone>>>,
pub(crate) numbering: Arc<OnceLock<crate::model::target::TargetIndex>>,
pub(crate) swept_links: Arc<SweptLinks>,
pub(crate) attachments: Arc<Attachments>,
pub(crate) exclusions: Arc<Exclusions>,
pub(crate) hardware: Arc<WithheldHardware>,
pub(crate) changed: Arc<ChangedHosts>,
pub(crate) stages: Arc<Stages>,
pub(crate) settlements: Arc<Settlements>,
pub(crate) positions: Arc<Positions>,
pub(crate) order_seed: Option<u64>,
pub(crate) responses: Arc<Responses>,
pub(crate) tapes: Arc<Tapes>,
finished: Arc<Finished>,
pub(crate) detections: crate::detect::Detections,
pub(crate) forced: Arc<crate::transport::dial::ForcedSources>,
pub(crate) listen_only: Arc<BTreeSet<u16>>,
withheld_ports: Arc<crate::model::port::PortSet>,
target_names: Arc<BTreeMap<IpAddr, Arc<str>>>,
}
impl ScanContext {
pub(crate) fn target_name(&self, ip: IpAddr) -> Option<Arc<str>> {
self.target_names.get(&ip).cloned()
}
pub(crate) fn egress_toward(&self, target: IpAddr) -> crate::transport::dial::Egress {
self.forced.toward(target)
}
pub(crate) fn listens_only(&self, number: u16, protocol: Protocol) -> bool {
protocol == Protocol::Tcp && self.listen_only.contains(&number)
}
pub(crate) fn service_detection_on(
&self,
detection: ServiceDetection,
number: u16,
protocol: Protocol,
) -> ServiceDetection {
if self.listens_only(number, protocol) {
detection.min(ServiceDetection::Banner)
} else {
detection
}
}
pub(crate) fn record_responses(
&self,
ip: ScopedIp,
number: u16,
protocol: Protocol,
banners: Vec<String>,
) {
self.responses.record(ip, number, protocol, banners);
}
pub(crate) fn responses_lost(&self, ip: &ScopedIp, number: u16, protocol: Protocol) -> bool {
self.responses.lost(ip, number, protocol)
}
pub(crate) fn take_responses(
&self,
ip: &ScopedIp,
number: u16,
protocol: Protocol,
) -> Vec<String> {
self.responses.take(ip, number, protocol)
}
pub fn may_probe(&self, address: &IpAddr) -> bool {
!self.exclusions.excludes(address) && !self.hardware.withholds(address)
}
pub(crate) fn may_ask(&self, target: &crate::model::target::Target) -> bool {
self.may_probe(&target.ip) && !self.withheld_ports.contains(target.port, target.protocol)
}
pub fn write_host(
&self,
key: impl Into<ScopedIp>,
edit: impl FnOnce(&mut Host) -> bool,
) -> bool {
let key = self.key(key);
let ip = key.addr();
if self.exclusions.excludes(&ip) || self.hardware.withholds(&ip) {
info!(
verbosity = 2,
"excluded address {ip} answered a probe it was not addressed; dropping the finding"
);
return false;
}
let mut is_new = false;
let mut host = self.store.entry(key.clone()).or_insert_with(|| {
is_new = true;
let mut host = Host::new(ip);
if let Some(zone) = key.zone() {
host.set_zone(zone.clone());
}
if let Some(name) = self.target_names.get(&ip) {
host.set_hostname(Some(name.to_string()));
}
host
});
if self.changed.keeps_ports() {
host.track_touched_ports();
}
let announce = edit(&mut host);
if !self.exclusions.is_empty() {
let keep = |address: &IpAddr| !self.exclusions.excludes(address);
let before = host.ips().len();
host.retain_ips(keep);
if host.ips().len() < before {
info!(
verbosity = 2,
"an excluded address arrived beside {ip}; leaving it off the host"
);
}
if host.withhold_intermediaries(keep) {
info!(
verbosity = 2,
"an excluded router answered for a probe to {ip}; withholding its address"
);
}
if self.hardware.names(&host) {
let addresses = host.ips().clone();
drop(host);
self.store.remove(&key);
info!(
verbosity = 2,
"{ip} answered from an excluded machine's hardware address; dropping it"
);
self.hardware.withhold(addresses);
return false;
}
}
let touched = host.take_touched_ports();
drop(host);
self.changed.insert(key.clone(), touched);
if announce || is_new {
let _ = self.events_tx.send(ScanEvent::HostUpdated(key));
}
is_new
}
pub fn read_host<R>(
&self,
ip: impl Into<ScopedIp>,
read: impl FnOnce(&Host) -> R,
) -> Option<R> {
self.store
.get(&self.key(ip))
.map(|entry| read(entry.value()))
}
fn key(&self, ip: impl Into<ScopedIp>) -> ScopedIp {
let key = ip.into();
match key.is_unusable() {
true => self
.zones
.get()
.map_or(key.clone(), |zones| zones.key(key.addr())),
false => key,
}
}
pub(crate) fn capture_on(&self, links: Vec<Zone>) {
let _ = self.capture_links.set(links);
}
pub(crate) fn capture_links(&self) -> Vec<Zone> {
self.capture_links
.get()
.cloned()
.unwrap_or_else(crate::transport::probe::capturable_interfaces)
}
pub(crate) fn learn_zones(&self, zones: ZoneMap) {
let _ = self.zones.set(zones);
}
pub fn contains_host(&self, ip: &ScopedIp) -> bool {
self.store.contains_key(&self.key(ip.clone()))
}
pub fn host_addresses(&self) -> Vec<ScopedIp> {
self.store.iter().map(|entry| entry.key().clone()).collect()
}
pub fn record_failure(&self, scanner: ScannerKind, reason: String) {
error!(
"{} failed: {reason}",
crate::record::wire::scanner_kind_name(scanner)
);
self.failures
.push(ScannerFailure::new(scanner, reason.clone()));
let _ = self
.events_tx
.send(ScanEvent::ScannerFailed { scanner, reason });
}
pub(crate) fn record_cut_short(&self, scanner: ScannerKind, reason: String) {
crate::warn!("{reason}");
self.file_cut_short(scanner, reason);
}
pub(crate) fn file_cut_short(&self, scanner: ScannerKind, reason: String) {
self.failures
.push(ScannerFailure::cut_short(scanner, reason.clone()));
let _ = self
.events_tx
.send(ScanEvent::ScannerFailed { scanner, reason });
}
pub fn record_refusal(&self, refusal: Refusal) {
self.refusals.push(refusal);
}
pub(crate) fn take_refusals(&self) -> Vec<Refusal> {
self.refusals.drain()
}
pub fn refusals_snapshot(&self) -> Vec<Refusal> {
self.refusals.snapshot()
}
pub fn record_probe_stats(&self, stats: ProbeStats) {
self.probe_stats.push(stats);
}
pub(crate) fn take_probe_stats(&self) -> Vec<ProbeStats> {
self.probe_stats.drain()
}
pub fn probe_stats_snapshot(&self) -> Vec<ProbeStats> {
self.probe_stats.snapshot()
}
pub(crate) fn take_failures(&self) -> Vec<ScannerFailure> {
self.failures.drain()
}
pub fn record_unroutable(&self, address: IpAddr) {
self.unroutable.insert(address);
if let Some(position) = self.positions.find(address) {
self.settlements
.record_unsettled(Outcome::Unreachable { position });
}
if let Some(index) = self.numbering.get() {
for position in index.runs_at(address).flatten() {
self.settlements
.record_unsettled(Outcome::Unreachable { position });
}
}
}
pub(crate) fn number_targets(&self, index: crate::model::target::TargetIndex) {
let _ = self.numbering.set(index);
}
pub(crate) fn settle_withheld(&self, address: IpAddr) {
if let Some(position) = self.positions.find(address) {
self.record_outcome(Outcome::Withheld { position });
}
}
pub(crate) fn withheld_by_hardware(&self) -> Vec<IpAddr> {
self.hardware.addresses()
}
pub(crate) fn take_unroutable(&self) -> Vec<IpAddr> {
self.unroutable.drain()
}
pub(crate) fn note_refused_by_route(&self, address: IpAddr) {
self.refused_by_route.insert(address);
}
pub(crate) fn take_refused_by_route(&self) -> Vec<IpAddr> {
self.refused_by_route.drain()
}
pub(crate) fn note_withheld_neighbour(&self, address: IpAddr) {
self.withheld_neighbours.insert(address);
}
pub(crate) fn take_withheld_neighbours(&self) -> Vec<IpAddr> {
self.withheld_neighbours.drain()
}
pub(crate) fn is_unroutable(&self, address: IpAddr) -> bool {
self.unroutable.contains(address)
}
pub(crate) fn left_early(&self, address: IpAddr) -> bool {
self.timed_out.contains(address)
}
pub(crate) fn await_verdicts(&self) {
self.verdicts_pending.store(true, Ordering::Release);
}
pub(crate) fn verdicts_reached(&self) {
self.verdicts_pending.store(false, Ordering::Release);
}
pub(crate) fn forget_silent(&self, keys: Vec<ScopedIp>) {
for key in keys {
self.silent.insert(key.addr());
self.forget_unheard(&key);
}
}
pub(crate) fn forget_undecided(&self, keys: Vec<ScopedIp>) {
for key in keys {
self.undecided.insert(key.addr());
self.forget_unheard(&key);
}
}
fn forget_unheard(&self, key: &ScopedIp) {
if let Some((_, host)) = self.store.remove(key) {
let (unasked, asked): (Vec<_>, Vec<_>) = host
.ports()
.partition(|port| port.state() == PortState::Unasked);
self.unheard_probes
.fetch_add(asked.len() as u64, Ordering::Relaxed);
self.record_unreached(unasked.len() as u64);
}
}
pub(crate) fn take_undecided(&self) -> IpSet {
self.undecided.drain()
}
pub(crate) fn record_unreached(&self, count: u64) {
self.unreached.fetch_add(count, Ordering::Relaxed);
}
pub(crate) fn take_unreached(&self) -> u64 {
self.unreached.swap(0, Ordering::Relaxed)
}
pub(crate) fn take_unheard_probes(&self) -> u64 {
self.unheard_probes.swap(0, Ordering::Relaxed)
}
pub fn host_expired(&self, address: IpAddr) -> bool {
if !self.clocks.expired(address) {
return false;
}
self.timed_out.insert(address);
true
}
pub(crate) fn owes_passes(&self, host: &Host) -> bool {
let finished = &self.finished;
!finished.hosts.contains(&host.scoped_ip().to_string())
|| host.ips().iter().any(|ip| finished.asked.contains(ip))
}
pub(crate) fn hosts_owed_passes(&self) -> Vec<ScopedIp> {
self.host_addresses()
.into_iter()
.filter(|key| {
self.read_host(key, |host| self.owes_passes(host))
.unwrap_or(false)
})
.collect()
}
pub fn host_ready_at(&self, address: IpAddr, now: Instant) -> Option<Instant> {
self.spacing.ready_at(address, now)
}
pub fn host_probed(&self, address: IpAddr, now: Instant) {
self.spacing.sent(address, now);
}
pub(crate) fn host_probe_interval(&self) -> Option<Duration> {
self.spacing.minimum
}
pub(crate) fn take_timed_out(&self) -> Vec<IpAddr> {
self.timed_out.drain()
}
pub(crate) fn stopping_before(&self, pass: Pass) -> bool {
let stopping = self.handle.should_stop();
if stopping {
self.passes_cut.insert(pass);
}
stopping
}
pub(crate) fn take_passes_cut(&self) -> Vec<Pass> {
self.passes_cut.drain()
}
pub(crate) fn record_icmp_rate_limited(&self, address: IpAddr) {
self.icmp_rate_limited.insert(address);
}
pub(crate) fn take_icmp_rate_limited(&self) -> Vec<IpAddr> {
self.icmp_rate_limited.drain()
}
pub fn record_reached_by_connect(&self, targets: &IpSet) {
self.reached_by_connect.extend(targets);
}
pub(crate) fn take_reached_by_connect(&self, unreached: &[IpAddr]) -> Vec<IpRange> {
self.reached_by_connect.drain(unreached)
}
pub fn record_sweep(&self, zone: Zone) {
self.swept_links.insert(zone);
}
pub(crate) fn take_swept_links(&self) -> Vec<Zone> {
self.swept_links.drain()
}
pub fn record_attachment(&self, attachment: Attachment) {
self.attachments.insert(attachment);
}
pub(crate) fn take_attachments(&self) -> Vec<Attachment> {
self.attachments.drain()
}
pub(crate) fn open_phase(&self, opened: crate::scanner::recorder::Opened) {
self.sitting.open(opened);
}
pub(crate) fn close_phase(&self, phase: &crate::report::ScanPhase) {
self.sitting.close(phase);
}
pub fn record_outcome(&self, outcome: Outcome) {
self.settlements.record(outcome);
}
pub fn enter_stage(&self, stage: Stage, total: Option<u64>) {
if self.stages.enter(stage, total) {
let _ = self.events_tx.send(ScanEvent::StageChanged { stage });
}
}
pub fn stage_advanced(&self) {
self.stages.advance();
}
pub fn record_many_outcomes(&self, outcome: Outcome, count: u64) {
self.settlements.record_many(outcome, count);
}
pub(crate) fn record_address_outcomes(&self, outcome: Outcome, count: u64) {
if self.plan_stage != Stage::Ports {
self.settlements.record_many(outcome, count);
}
}
pub fn settle_address(&self, ip: IpAddr, settled: Settled) {
if let Some(position) = self.positions.find(ip) {
self.record_outcome(settled.at(position));
}
if settled == Settled::Exhausted {
self.silent.insert(ip);
}
}
pub(crate) fn take_silent(&self) -> IpSet {
self.silent.drain()
}
pub fn settlements(&self) -> &Settlements {
&self.settlements
}
pub fn restore_hosts(&self, hosts: &[Host]) {
let keep = |address: &IpAddr| !self.exclusions.excludes(address);
for host in hosts {
let mut host = host.clone();
if !host.retain_ips(keep) {
info!(
verbosity = 2,
"every address of {} in the journal is excluded; leaving it out of this sitting",
host.primary_ip()
);
continue;
}
host.withhold_intermediaries(keep);
host.withhold_ports(&self.withheld_ports);
let key = host.scoped_ip();
for port in host.ports() {
if port.state() == PortState::Open {
self.responses
.inherit(key.clone(), port.number(), port.protocol());
}
}
match self.store.get_mut(&key) {
Some(mut existing) => {
existing.merge(host);
let _ = existing.take_touched_ports();
}
None => {
self.store.insert(key.clone(), host);
}
}
let _ = self.events_tx.send(ScanEvent::HostUpdated(key));
}
}
pub fn progress(&self) -> ScanProgress {
self.tapes.keep();
self.changed.keep_ports();
ScanProgress {
store: Arc::clone(&self.store),
changed: Arc::clone(&self.changed),
settlements: Arc::clone(&self.settlements),
failures: Arc::clone(&self.failures),
tapes: Arc::clone(&self.tapes),
#[cfg(feature = "journal-format")]
verdicts_pending: Arc::clone(&self.verdicts_pending),
#[cfg(feature = "journal-format")]
sitting: Arc::clone(&self.sitting),
#[cfg(feature = "journal-format")]
numbering: Arc::clone(&self.numbering),
}
}
pub fn hosts_snapshot(&self) -> Vec<Host> {
let mut hosts: Vec<Host> = self
.store
.iter()
.map(|entry| entry.value().clone())
.collect();
hosts.sort_by_cached_key(Host::scoped_ip);
hosts
}
pub fn host_count(&self) -> usize {
self.store.len()
}
pub fn take_changed_hosts(&self) -> Vec<Host> {
changed_since(&self.store, &self.changed)
}
pub fn failures_snapshot(&self) -> Vec<ScannerFailure> {
self.failures.snapshot()
}
pub fn update_host(&self, ip: impl Into<ScopedIp>, update: impl FnOnce(&mut Host)) -> bool {
self.write_host(ip, |host| {
update(host);
true
})
}
}
#[derive(Debug, Default)]
pub(crate) struct WithheldHardware {
macs: BTreeSet<MacAddr>,
addresses: Mutex<BTreeSet<IpAddr>>,
}
impl WithheldHardware {
fn read(exclusions: &Exclusions, table: Vec<(IpAddr, Option<MacAddr>)>) -> Self {
let macs = exclusions.hardware_in(table.iter().copied());
let tied = exclusions.tied_to(&macs, table);
if !macs.is_empty() {
info!(
verbosity = 1,
"excluding {} by hardware address too",
crate::counted(macs.len() as u128, "machine", "machines")
);
}
Self {
macs,
addresses: Mutex::new(tied),
}
}
fn names(&self, host: &Host) -> bool {
!self.macs.is_empty()
&& host
.hardware()
.is_some_and(|hardware| hardware.macs().keys().any(|mac| self.macs.contains(mac)))
}
fn withholds(&self, address: &IpAddr) -> bool {
!self.macs.is_empty()
&& self
.addresses
.lock()
.expect("the withheld addresses are never poisoned")
.contains(address)
}
fn withhold(&self, addresses: impl IntoIterator<Item = IpAddr>) {
self.addresses
.lock()
.expect("the withheld addresses are never poisoned")
.extend(addresses);
}
fn addresses(&self) -> Vec<IpAddr> {
self.addresses
.lock()
.expect("the withheld addresses are never poisoned")
.iter()
.copied()
.collect()
}
}
#[derive(Debug, Default, Clone, Copy)]
enum Order {
#[default]
Drawn,
Seeded(u64),
Planned,
}
#[must_use]
#[derive(Debug, Default)]
pub struct SessionBuilder {
exclusions: Exclusions,
settled: crate::journal::cursor::Checkpoint,
positions: Positions,
planned: Option<u64>,
plan_stage: Stage,
staging: Vec<Stage>,
detections: crate::detect::Detections,
host_timeout: Option<Duration>,
scan_timeout: Option<Duration>,
host_probe_interval: Option<Duration>,
order: Order,
send_source: Vec<IpAddr>,
listen_only: Option<BTreeSet<u16>>,
withheld_ports: crate::model::port::PortSet,
neighbours: Option<Vec<(IpAddr, Option<MacAddr>)>>,
finished: Finished,
target_names: BTreeMap<IpAddr, String>,
}
impl SessionBuilder {
pub fn excluding(mut self, exclusions: Exclusions) -> Self {
self.exclusions = exclusions;
self
}
pub fn naming(mut self, names: BTreeMap<IpAddr, String>) -> Self {
self.target_names = names;
self
}
#[cfg(test)]
pub(crate) fn with_neighbours(mut self, table: Vec<(IpAddr, Option<MacAddr>)>) -> Self {
self.neighbours = Some(table);
self
}
pub fn resuming(mut self, settled: &crate::journal::cursor::Checkpoint) -> Self {
self.settled = settled.clone();
self
}
#[cfg(feature = "journal-format")]
pub(crate) fn finished(mut self, hosts: HashSet<String>, asked: IpSet) -> Self {
self.finished = Finished { hosts, asked };
self
}
pub fn counting(mut self, positions: Positions) -> Self {
self.positions = positions;
self
}
pub fn ordering(mut self, seed: Option<u64>) -> Self {
self.order = match seed {
Some(seed) => Order::Seeded(seed),
None => Order::Planned,
};
self
}
pub fn planning(mut self, stage: Stage, total: Option<u64>) -> Self {
self.plan_stage = stage;
self.planned = total;
self
}
pub fn staging(mut self, stages: Vec<Stage>) -> Self {
self.staging = stages;
self
}
pub fn detections(mut self, detections: crate::detect::Detections) -> Self {
self.detections = detections;
self
}
pub fn host_timeout(mut self, budget: Option<Duration>) -> Self {
self.host_timeout = budget;
self
}
pub fn scan_timeout(mut self, budget: Option<Duration>) -> Self {
self.scan_timeout = budget;
self
}
pub fn host_probe_interval(mut self, minimum: Option<Duration>) -> Self {
self.host_probe_interval = minimum;
self
}
pub fn send_source(mut self, sources: Vec<IpAddr>) -> Self {
self.send_source = sources;
self
}
pub fn listening_only_to(mut self, ports: BTreeSet<u16>) -> Self {
self.listen_only = Some(ports);
self
}
#[cfg(feature = "journal-format")]
pub(crate) fn withholding_ports(mut self, ports: crate::model::port::PortSet) -> Self {
self.withheld_ports = ports;
self
}
pub fn build(self) -> (ScanSession, ScanContext) {
let store = Arc::new(DashMap::new());
let handle = ScanHandle::bounded(self.scan_timeout);
let (events_tx, rx) = broadcast::channel(ScanEvents::CAPACITY);
let order_seed = match self.order {
Order::Drawn => Some(rand::random()),
Order::Seeded(seed) => Some(seed),
Order::Planned => None,
};
let walk = order_seed
.zip(self.planned)
.map(|(seed, total)| crate::model::order::Permutation::new(seed, total));
let settlements = Arc::new(Settlements::walking(&self.settled, walk));
let stages = Arc::new(Stages::new(self.staging));
let session = ScanSession {
store: HostStore::new(store.clone()),
events: ScanEvents { rx },
handle: handle.clone(),
progress: Progress::new(
settlements.clone(),
self.planned,
self.plan_stage,
stages.clone(),
),
};
let ctx = ScanContext {
handle,
store,
events_tx,
failures: Arc::new(FailureLog::default()),
refusals: Arc::new(RefusalLog::default()),
probe_stats: Arc::new(ProbeStatsLog::default()),
unroutable: Arc::new(UnroutableLog::default()),
refused_by_route: Arc::new(UnroutableLog::default()),
withheld_neighbours: Arc::new(UnroutableLog::default()),
timed_out: Arc::new(TimedOutLog::default()),
passes_cut: Arc::new(PassLog::default()),
icmp_rate_limited: Arc::new(RateLimitedLog::default()),
reached_by_connect: Arc::new(ConnectLog::default()),
silent: Arc::new(SilenceLog::default()),
undecided: Arc::new(SilenceLog::default()),
unreached: Arc::new(AtomicU64::new(0)),
unheard_probes: Arc::new(AtomicU64::new(0)),
verdicts_pending: Arc::new(AtomicBool::new(false)),
sitting: Arc::new(Sitting::default()),
plan_stage: self.plan_stage,
clocks: Arc::new(HostClocks {
budget: self.host_timeout,
started: DashMap::new(),
}),
spacing: Arc::new(HostSpacing {
minimum: self.host_probe_interval,
last_sent: DashMap::new(),
}),
zones: Arc::new(OnceLock::new()),
capture_links: Arc::new(OnceLock::new()),
numbering: Arc::new(OnceLock::new()),
swept_links: Arc::new(SweptLinks::default()),
attachments: Arc::new(Attachments::default()),
hardware: Arc::new(WithheldHardware::read(
&self.exclusions,
self.neighbours.unwrap_or_else(|| {
if self.exclusions.is_empty() {
return Vec::new();
}
crate::system::neighbor_cache::neighbour_table()
}),
)),
exclusions: Arc::new(self.exclusions),
changed: Arc::new(ChangedHosts::default()),
stages,
settlements,
positions: Arc::new(self.positions),
order_seed,
responses: Arc::new(Responses::default()),
tapes: Arc::new(Tapes::default()),
finished: Arc::new(self.finished),
detections: self.detections,
forced: Arc::new(crate::transport::dial::ForcedSources::new(
&self.send_source,
)),
listen_only: Arc::new(
self.listen_only
.unwrap_or_else(|| crate::config::RAW_PRINT_PORTS.iter().copied().collect()),
),
withheld_ports: Arc::new(self.withheld_ports),
target_names: Arc::new(
self.target_names
.into_iter()
.map(|(ip, name)| (ip, Arc::from(name)))
.collect(),
),
};
(session, ctx)
}
}
impl ScanSession {
pub fn new() -> (Self, ScanContext) {
Self::builder().build()
}
pub fn builder() -> SessionBuilder {
SessionBuilder::default()
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::host::{EvidenceSource, Hop, HostStatus, StatusProtocol, StatusReason};
#[test]
fn a_whole_run_reads_as_one_figure_rather_than_one_per_stage() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Ports, Some(4))
.staging(vec![Stage::Ports, Stage::Services, Stage::Detections])
.build();
ctx.enter_stage(Stage::Ports, None);
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_outcome(Outcome::Answered { position: 1 });
let (done, total) = session.progress().overall().expect("a staged run");
assert_eq!(
done * 6,
total,
"half of one stage in three: {done}/{total}"
);
ctx.enter_stage(Stage::Services, Some(2));
ctx.stage_advanced();
let (done, total) = session.progress().overall().expect("a staged run");
assert_eq!(done * 2, total, "half the run: {done}/{total}");
}
#[test]
fn a_scans_figure_only_grows_and_is_whole_only_at_its_end() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Ports, Some(1_000))
.staging(vec![
Stage::Discovery,
Stage::Ports,
Stage::Services,
Stage::Detections,
Stage::Os,
Stage::Traceroute,
Stage::Filters,
Stage::IpProtocols,
])
.build();
let progress = session.progress().clone();
let mut readings: Vec<(&str, (u64, u64))> = Vec::new();
let mut read = |what| readings.push((what, progress.overall().expect("staged")));
ctx.enter_stage(Stage::Discovery, None);
read("liveness");
ctx.enter_stage(Stage::Ports, None);
for position in 10..1_000 {
ctx.record_outcome(Outcome::Skipped { position });
}
read("silent hosts passed over");
let passed_over = progress.fraction().expect("the plan's own stage");
for position in 0..10 {
ctx.record_outcome(Outcome::Answered { position });
}
read("ports probed");
ctx.enter_stage(Stage::Services, Some(4));
for _ in 0..4 {
ctx.stage_advanced();
}
read("tcp services");
ctx.enter_stage(Stage::Services, Some(4));
read("udp services begun");
for _ in 0..4 {
ctx.stage_advanced();
}
read("udp services");
for stage in [
Stage::Detections,
Stage::Os,
Stage::Traceroute,
Stage::Filters,
Stage::IpProtocols,
] {
ctx.enter_stage(stage, None);
read("a later pass");
}
ctx.enter_stage(Stage::Finishing, None);
read("finishing");
let share = |(done, total): (u64, u64)| done as f64 / total as f64;
assert_eq!(
passed_over, 0.0,
"silent hosts passed over read as ports probed"
);
for pair in readings.windows(2) {
assert!(
share(pair[1].1) >= share(pair[0].1),
"the figure stepped back from {:?} to {:?}",
pair[0],
pair[1]
);
}
let (last, others) = readings.split_last().expect("readings");
assert_eq!(share(last.1), 1.0, "a finished scan reads whole");
for (what, reading) in others {
assert!(share(*reading) < 1.0, "{what} read whole: {reading:?}");
}
}
#[test]
fn a_stage_with_nothing_to_do_is_stepped_over_rather_than_waited_for() {
let (session, ctx) = ScanSession::builder()
.staging(vec![
Stage::Ports,
Stage::Services,
Stage::Detections,
Stage::Os,
])
.build();
ctx.enter_stage(Stage::Ports, Some(1));
ctx.stage_advanced();
ctx.enter_stage(Stage::Os, None);
let (done, total) = session.progress().overall().expect("a staged run");
assert_eq!(done * 4, total * 3, "three stages of four: {done}/{total}");
}
#[test]
fn a_session_with_no_running_order_reports_no_whole_run_figure() {
let (session, ctx) = ScanSession::new();
ctx.enter_stage(Stage::Services, Some(4));
ctx.stage_advanced();
let progress = session.progress();
assert_eq!(progress.overall(), None, "nothing said how many stages");
assert_eq!(
progress.counted(),
Some((1, 4)),
"the stage still answers for itself"
);
}
#[test]
fn a_stage_that_counted_itself_answers_for_itself() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Ports, Some(4))
.build();
ctx.enter_stage(Stage::Ports, None);
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_outcome(Outcome::Answered { position: 1 });
ctx.record_outcome(Outcome::Answered { position: 2 });
ctx.record_outcome(Outcome::Answered { position: 3 });
assert_eq!(
session.progress().fraction(),
Some(1.0),
"the ports are done"
);
ctx.enter_stage(Stage::Detections, Some(8));
ctx.stage_advanced();
ctx.stage_advanced();
let progress = session.progress();
assert_eq!(progress.stage(), Stage::Detections);
assert_eq!(progress.stage_done(), 2);
assert_eq!(progress.stage_total(), Some(8));
assert_eq!(
progress.fraction(),
Some(0.25),
"a quarter through the detections, not finished with the scan"
);
assert_eq!(progress.settled(), 4, "the plan is still settled in full");
}
#[test]
fn an_unsized_stage_that_is_not_the_plans_own_reports_nothing() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Ports, Some(1_000))
.build();
ctx.enter_stage(Stage::Discovery, None);
let progress = session.progress();
assert_eq!(progress.stage(), Stage::Discovery);
assert_eq!(
progress.fraction(),
None,
"a liveness pass is not nought percent of a port plan"
);
ctx.enter_stage(Stage::Ports, None);
assert_eq!(
session.progress().fraction(),
Some(0.0),
"the stage the plan was drawn for reads from the plan"
);
}
#[test]
fn re_entering_a_stage_adds_to_it_rather_than_starting_it_over() {
let (mut session, ctx) = ScanSession::new();
ctx.enter_stage(Stage::Services, Some(3));
ctx.stage_advanced();
ctx.enter_stage(Stage::Services, Some(2));
let progress = session.progress().clone();
assert_eq!(progress.stage_total(), Some(5), "both runs' ports");
assert_eq!(progress.stage_done(), 1, "and the one already finished");
let mut announced = 0;
while let Some(event) = session.events().try_recv() {
if matches!(event, ScanEvent::StageChanged { .. }) {
announced += 1;
}
}
assert_eq!(announced, 1, "one stage, announced once");
}
#[test]
fn the_list_of_stages_holds_every_one_of_them_in_running_order() {
let codes: Vec<u8> = Stage::ALL.iter().map(|stage| stage.code()).collect();
let mut sorted = codes.clone();
sorted.sort_unstable();
sorted.dedup();
assert_eq!(codes, sorted, "the stages are listed in the order they run");
assert_eq!(
codes.len(),
Stage::ALL.len(),
"a stage is listed once and no stage twice"
);
for &stage in Stage::ALL {
assert_eq!(
Stage::from_code(stage.code()),
stage,
"{stage} does not survive its own code"
);
}
}
#[test]
fn a_stage_announces_itself_as_it_begins() {
let (mut session, ctx) = ScanSession::new();
ctx.enter_stage(Stage::Os, None);
let Some(ScanEvent::StageChanged { stage }) = session.events().try_recv() else {
panic!("entering a stage announces it");
};
assert_eq!(stage, Stage::Os);
}
#[test]
fn an_uncounted_plan_settles_targets_but_reports_no_fraction() {
let (session, ctx) = ScanSession::new();
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_outcome(Outcome::Exhausted { position: 1 });
let progress = session.progress();
assert_eq!(progress.settled(), 2, "both targets settled");
assert_eq!(
progress.planned(),
None,
"nothing said how big the plan was"
);
assert_eq!(
progress.fraction(),
None,
"so there is nothing to divide into"
);
assert_eq!(progress.remaining(), None);
}
#[test]
fn settling_targets_advances_the_fraction() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Discovery, Some(4))
.build();
assert_eq!(
session.progress().fraction(),
Some(0.0),
"nothing settled yet"
);
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_outcome(Outcome::Exhausted { position: 1 });
let progress = session.progress();
assert_eq!(progress.settled(), 2);
assert_eq!(progress.remaining(), Some(2));
let fraction = progress.fraction().expect("a counted plan has a fraction");
assert!(
(fraction - 0.5).abs() < f64::EPSILON,
"two of four settled is half the plan, got {fraction}"
);
}
#[test]
fn an_unsettled_outcome_does_not_advance_the_plan() {
let (session, ctx) = ScanSession::builder()
.planning(Stage::Discovery, Some(2))
.build();
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_many_outcomes(Outcome::Unasked, 1);
let progress = session.progress();
assert_eq!(progress.settled(), 1, "only the answered target settled");
assert_eq!(
progress.remaining(),
Some(1),
"the unasked one is still owed"
);
}
#[test]
fn a_resumed_sitting_starts_part_way_through_the_plan() {
let earlier = crate::journal::cursor::Checkpoint::new(6, []);
let (session, ctx) = ScanSession::builder()
.resuming(&earlier)
.planning(Stage::Discovery, Some(8))
.build();
assert_eq!(
session.progress().settled(),
6,
"what the earlier sitting settled is already covered"
);
ctx.record_outcome(Outcome::Answered { position: 6 });
let fraction = session
.progress()
.fraction()
.expect("a counted plan has a fraction");
assert!(
(fraction - 0.875).abs() < f64::EPSILON,
"seven of eight, got {fraction}"
);
}
#[test]
fn a_fraction_saturates_rather_than_passing_one() {
let (empty, _ctx) = ScanSession::builder()
.planning(Stage::Discovery, Some(0))
.build();
assert_eq!(
empty.progress().fraction(),
Some(1.0),
"an empty plan is complete"
);
let (session, ctx) = ScanSession::builder()
.planning(Stage::Discovery, Some(1))
.build();
ctx.record_outcome(Outcome::Answered { position: 0 });
ctx.record_outcome(Outcome::Answered { position: 1 });
assert_eq!(
session.progress().fraction(),
Some(1.0),
"more settled than planned still reads as done"
);
assert_eq!(session.progress().remaining(), Some(0));
}
#[test]
fn an_excluded_address_reaches_neither_the_store_nor_the_stream() {
let excluded: IpAddr = "198.51.100.7".parse().expect("literal");
let allowed: IpAddr = "203.0.113.7".parse().expect("literal");
let mut ips = crate::model::ip::set::IpSet::new();
ips.insert_range("198.51.100.0/24".parse().expect("a valid range"));
let (mut session, ctx) = ScanSession::builder()
.excluding(Exclusions::new(ips))
.build();
assert!(
!ctx.write_host(excluded, |_| unreachable!(
"an excluded address must not reach the caller's edit"
)),
"an excluded address is never reported as a new host"
);
assert!(ctx.write_host(allowed, |_| true));
assert_eq!(ctx.store.len(), 1);
assert!(!ctx.store.contains_key(&ScopedIp::unscoped(excluded)));
let ScanEvent::HostUpdated(announced) =
session.events().try_recv().expect("the allowed host")
else {
panic!("expected a host update");
};
assert_eq!(announced, ScopedIp::unscoped(allowed));
assert!(session.events().try_recv().is_none());
}
#[test]
fn two_link_locals_on_different_segments_are_two_hosts() {
let shared: IpAddr = "fe80::1".parse().expect("literal");
let (_session, ctx) = ScanSession::new();
ctx.write_host(ScopedIp::scoped(shared, Zone::new(1, "en0")), |host| {
host.set_status(HostStatus::Up);
true
});
ctx.write_host(ScopedIp::scoped(shared, Zone::new(2, "en1")), |host| {
host.set_status(HostStatus::Up);
true
});
assert_eq!(ctx.store.len(), 2, "two segments, two machines");
let mut zones: Vec<String> = ctx
.store
.iter()
.filter_map(|entry| entry.value().zone().map(|zone| zone.name().to_owned()))
.collect();
zones.sort();
assert_eq!(zones, ["en0", "en1"]);
}
#[test]
fn a_port_verdict_on_a_bare_link_local_lands_on_the_host_the_scan_named() {
use crate::model::ip::range::Ipv6Range;
let address: IpAddr = "fe80::1".parse().expect("literal");
let (_session, ctx) = ScanSession::new();
let mut zones = ZoneMap::new();
let IpAddr::V6(v6) = address else {
panic!("a v6 literal");
};
zones.insert(
Ipv6Range::scoped(v6, v6, Some(1)).expect("a scoped range"),
&[(1, "en0")],
);
ctx.learn_zones(zones);
ctx.write_host(ScopedIp::scoped(address, Zone::new(1, "en0")), |host| {
host.set_status(HostStatus::Up);
true
});
ctx.write_host(address, |host| {
host.set_status(HostStatus::Up);
true
});
assert_eq!(ctx.store.len(), 1, "one machine, one record");
assert!(
ctx.read_host(address, |host| host.zone().is_some())
.expect("the bare address reaches it too"),
"and it is still the host on en0"
);
}
#[test]
fn one_global_address_seen_on_two_interfaces_is_one_host() {
let global: IpAddr = "2001:db8::1".parse().expect("literal");
let (_session, ctx) = ScanSession::new();
ctx.write_host(ScopedIp::scoped(global, Zone::new(1, "en0")), |_| true);
ctx.write_host(ScopedIp::scoped(global, Zone::new(2, "en1")), |_| true);
assert_eq!(ctx.store.len(), 1, "one address, one machine");
}
#[test]
fn a_finding_written_back_under_a_key_from_the_store_lands_on_the_same_host() {
let shared: IpAddr = "fe80::1".parse().expect("literal");
let (_session, ctx) = ScanSession::new();
ctx.write_host(ScopedIp::scoped(shared, Zone::new(1, "en0")), |host| {
host.set_status(HostStatus::Up);
true
});
for key in ctx.host_addresses() {
ctx.write_host(key, |host| {
host.add_reason(StatusReason::new(StatusProtocol::IcmpEcho, "echo answered"));
true
});
}
assert_eq!(ctx.store.len(), 1, "the same host, enriched");
assert_eq!(
ctx.store
.iter()
.next()
.expect("the host")
.value()
.reasons()
.len(),
1,
"and the finding reached it"
);
}
#[test]
fn a_failure_survives_a_consumer_that_never_listens() {
let (session, ctx) = ScanSession::new();
drop(session);
ctx.record_failure(ScannerKind::Routed, "raw socket unavailable".into());
let failures = ctx.take_failures();
assert_eq!(failures.len(), 1);
assert_eq!(failures[0].scanner(), ScannerKind::Routed);
assert_eq!(failures[0].reason(), "raw socket unavailable");
}
#[test]
fn a_failure_reaches_both_the_log_and_the_stream() {
let (mut session, ctx) = ScanSession::new();
ctx.record_failure(ScannerKind::Local, "eth0: no address".into());
match session.events().try_recv() {
Some(ScanEvent::ScannerFailed { scanner, reason }) => {
assert_eq!(scanner, ScannerKind::Local);
assert_eq!(reason, "eth0: no address");
}
other => panic!("expected a ScannerFailed event, got {other:?}"),
}
assert_eq!(ctx.take_failures().len(), 1);
}
#[test]
fn snapshotting_failures_leaves_them_for_the_report() {
let (_session, ctx) = ScanSession::new();
ctx.record_failure(ScannerKind::Local, "eth0: no address".into());
assert_eq!(ctx.failures_snapshot().len(), 1);
assert_eq!(ctx.failures_snapshot().len(), 1, "reading is not taking");
assert_eq!(ctx.take_failures().len(), 1, "and the report still gets it");
}
#[test]
fn a_failure_is_said_under_the_name_the_report_files_it_by() {
let (_session, ctx) = ScanSession::new();
let lines = crate::logging::logged(|| {
ctx.record_failure(ScannerKind::SynPort, "the capture would not open".into());
});
let said: Vec<&str> = lines.iter().map(|line| line.message.as_str()).collect();
assert_eq!(said, ["syn_port failed: the capture would not open"]);
}
#[test]
fn taking_failures_empties_the_log() {
let (_session, ctx) = ScanSession::new();
ctx.record_failure(ScannerKind::Connect, "refused".into());
assert_eq!(ctx.take_failures().len(), 1);
assert!(ctx.take_failures().is_empty());
}
#[test]
fn failures_from_every_clone_land_in_one_log() {
let (_session, ctx) = ScanSession::new();
let clone = ctx.clone();
ctx.record_failure(ScannerKind::Local, "eth0".into());
clone.record_failure(ScannerKind::Routed, "gateway".into());
assert_eq!(ctx.take_failures().len(), 2);
}
#[test]
fn a_resuming_session_starts_from_the_earlier_cursor() {
use crate::journal::cursor::Checkpoint;
let settled = Checkpoint {
watermark: 12,
settled_above: vec![14],
walked: None,
};
let (_session, ctx) = ScanSession::builder()
.excluding(Exclusions::none())
.resuming(&settled)
.build();
assert_eq!(ctx.settlements().settled_count(), 13);
assert_eq!(ctx.settlements().checkpoint(), settled);
let (_session, fresh) = ScanSession::new();
assert_eq!(fresh.settlements().settled_count(), 0);
}
#[test]
fn a_session_left_to_itself_draws_a_seed_and_one_told_otherwise_does_not() {
let (_session, left) = ScanSession::new();
let (_session, other) = ScanSession::builder().build();
let (_session, told) = ScanSession::builder().ordering(None).build();
let (_session, given) = ScanSession::builder().ordering(Some(0x5EED)).build();
assert!(left.order_seed.is_some(), "no seed drawn");
assert_ne!(left.order_seed, other.order_seed, "two sessions, one order");
assert_eq!(told.order_seed, None);
assert_eq!(given.order_seed, Some(0x5EED));
}
#[test]
fn a_walked_scan_checkpoints_what_is_in_flight_rather_than_what_it_settled() {
use crate::journal::settle::Outcome;
use crate::model::order::Permutation;
use rand::seq::SliceRandom;
const PLAN: u64 = 1 << 16;
const BATCH: usize = 256;
let (_session, ctx) = ScanSession::builder()
.planning(Stage::Ports, Some(PLAN))
.ordering(Some(0x5EED))
.build();
let walk: Vec<u64> = Permutation::new(0x5EED, PLAN).iter().collect();
let mut rng = rand::rng();
let mut most_waiting = 0;
for batch in walk[..walk.len() / 2].chunks(BATCH) {
let mut batch = batch.to_vec();
batch.shuffle(&mut rng);
for position in batch {
ctx.record_outcome(Outcome::Answered { position });
}
most_waiting = most_waiting.max(ctx.settlements().checkpoint().settled_above.len());
}
assert_eq!(ctx.settlements().settled_count(), PLAN / 2);
assert!(
most_waiting < BATCH,
"{most_waiting} settled positions waited in the checkpoint at once, \
where a batch is {BATCH}"
);
}
#[test]
fn a_write_nobody_needs_announcing_is_still_a_write() {
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
let (mut session, ctx) = ScanSession::new();
ctx.update_host(ip, |host| host.set_status(HostStatus::Up));
assert_eq!(ctx.take_changed_hosts().len(), 1);
assert!(
session.events().try_recv().is_some(),
"a new host is announced"
);
ctx.write_host(ip, |host| {
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::IcmpEcho, "echo reply to an OS probe"),
);
false
});
let changed = ctx.take_changed_hosts();
assert_eq!(
changed.len(),
1,
"the record moved, so a journal has something to write"
);
assert!(
changed[0]
.reasons()
.iter()
.any(|reason| reason.protocol == StatusProtocol::IcmpEcho),
"and what it writes is what the pass learned"
);
assert!(
session.events().try_recv().is_none(),
"a host already announced is not announced again"
);
}
#[test]
fn a_stream_nobody_reads_drops_the_oldest_and_says_how_many() {
let flooded: IpAddr = "192.0.2.1".parse().expect("literal");
let last: IpAddr = "192.0.2.2".parse().expect("literal");
let (mut session, ctx) = ScanSession::new();
let overflow = 64;
let sent = ScanEvents::CAPACITY + overflow;
for _ in 0..sent - 1 {
ctx.update_host(flooded, |host| host.set_status(HostStatus::Up));
}
ctx.update_host(last, |host| host.set_status(HostStatus::Up));
assert_eq!(
ctx.store.len(),
2,
"a full event buffer does not stop the scan writing findings"
);
let mut dropped = 0u64;
let mut delivered = Vec::new();
while let Some(event) = session.events().try_recv() {
match event {
ScanEvent::EventsDropped { count } => dropped += count,
ScanEvent::HostUpdated(ip) => delivered.push(ip),
other => panic!("unexpected event {other:?}"),
}
}
assert_eq!(
delivered.len(),
ScanEvents::CAPACITY,
"the stream holds its stated capacity and no more"
);
assert_eq!(
dropped as usize + delivered.len(),
sent,
"every event is either delivered or declared missing"
);
assert_eq!(
delivered.last(),
Some(&ScopedIp::unscoped(last)),
"the newest event survives, which is what drop-oldest means"
);
}
#[test]
fn a_scan_with_no_host_budget_leaves_no_host() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
assert!(!ctx.host_expired(ip));
assert!(!ctx.host_expired(ip));
assert!(ctx.take_timed_out().is_empty());
}
#[test]
fn a_spent_host_budget_is_filed_once() {
let (_session, ctx) = ScanSession::builder()
.host_timeout(Some(Duration::ZERO))
.build();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
assert!(ctx.host_expired(ip));
assert!(ctx.host_expired(ip));
assert_eq!(ctx.take_timed_out(), vec![ip]);
}
#[test]
fn a_scan_with_no_gap_never_holds_a_probe() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
let now = Instant::now();
assert!(ctx.host_ready_at(ip, now).is_none());
ctx.host_probed(ip, now);
assert!(
ctx.host_ready_at(ip, now).is_none(),
"a recorded send moves nothing while there is no gap to move it against"
);
}
#[test]
fn the_longest_gap_holds_a_host_rather_than_panicking() {
let (_session, ctx) = ScanSession::builder()
.host_probe_interval(Some(Duration::MAX))
.build();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
let now = Instant::now();
ctx.host_probed(ip, now);
let ready = ctx.host_ready_at(ip, now).expect("asked too recently");
assert!(ready > now + Duration::from_secs(365 * 24 * 60 * 60));
}
#[test]
fn a_gap_starts_at_the_first_probe_and_runs_from_the_last() {
let gap = Duration::from_secs(3600);
let (_session, ctx) = ScanSession::builder()
.host_probe_interval(Some(gap))
.build();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
let now = Instant::now();
assert!(
ctx.host_ready_at(ip, now).is_none(),
"an address nothing has probed is ready"
);
ctx.host_probed(ip, now);
let ready = ctx.host_ready_at(ip, now).expect("asked too recently");
assert_eq!(ready, now + gap);
assert!(
ctx.host_ready_at(ip, now + gap).is_none(),
"the gap having run, the host is ready again"
);
}
#[test]
fn a_gap_at_one_host_leaves_every_other_host_ready() {
let (_session, ctx) = ScanSession::builder()
.host_probe_interval(Some(Duration::from_secs(3600)))
.build();
let probed: IpAddr = "192.0.2.1".parse().expect("an address");
let other: IpAddr = "192.0.2.2".parse().expect("an address");
let now = Instant::now();
ctx.host_probed(probed, now);
assert!(ctx.host_ready_at(probed, now).is_some());
assert!(ctx.host_ready_at(other, now).is_none());
}
#[test]
fn a_budget_still_running_leaves_the_host_alone() {
let (_session, ctx) = ScanSession::builder()
.host_timeout(Some(Duration::from_secs(3600)))
.build();
let ip: IpAddr = "192.0.2.1".parse().expect("an address");
assert!(!ctx.host_expired(ip));
assert!(ctx.take_timed_out().is_empty());
}
#[test]
fn a_resume_leaves_out_an_address_this_sitting_may_not_report() {
let excluded: IpAddr = "198.51.100.7".parse().expect("literal");
let allowed: IpAddr = "203.0.113.7".parse().expect("literal");
let mut ips = crate::model::ip::set::IpSet::new();
ips.insert_range("198.51.100.0/24".parse().expect("a valid range"));
let (mut session, ctx) = ScanSession::builder()
.excluding(Exclusions::new(ips))
.build();
let restored = |ip: IpAddr| {
let mut host = Host::new(ip);
host.set_status(HostStatus::Up);
host
};
ctx.restore_hosts(&[restored(excluded), restored(allowed)]);
assert!(
!ctx.store.contains_key(&ScopedIp::unscoped(excluded)),
"the journal's own record of an excluded address must not come back"
);
assert!(
ctx.store.contains_key(&ScopedIp::unscoped(allowed)),
"and everything else still does"
);
assert_eq!(ctx.store.len(), 1);
let Some(ScanEvent::HostUpdated(announced)) = session.events().try_recv() else {
panic!("a restored host is announced");
};
assert_eq!(announced.addr(), allowed);
assert!(
session.events().try_recv().is_none(),
"an excluded address is not announced either"
);
}
fn forbidding(address: IpAddr) -> (ScanSession, ScanContext) {
let mut ips = crate::model::ip::set::IpSet::new();
ips.insert(address);
ScanSession::builder()
.excluding(Exclusions::new(ips))
.build()
}
#[test]
fn an_address_an_edit_attaches_is_held_to_the_exclusions() {
let key: IpAddr = "192.0.2.60".parse().expect("literal");
let excluded: IpAddr = "192.0.2.61".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
ctx.write_host(key, |host| host.add_ip(excluded));
let ips = ctx
.read_host(key, |host| host.ips().clone())
.expect("the permitted key is recorded");
assert!(!ips.contains(&excluded), "{ips:?}");
assert!(ips.contains(&key));
}
#[test]
fn an_address_filed_unreachable_settles_its_targets() {
use crate::model::ip::set::Positions;
use crate::model::target::{TargetIndex, TargetMap, TargetSet};
let unreachable: IpAddr = "192.0.2.2".parse().expect("literal");
let sweep: IpSet = "192.0.2.1-192.0.2.3".parse().expect("a range");
let (_session, ctx) = ScanSession::builder()
.counting(Positions::of(&sweep))
.build();
ctx.record_unroutable(unreachable);
ctx.record_unroutable(unreachable);
let settled = ctx.settlements();
assert!(
settled.checkpoint().is_settled(1),
"the address is still owed"
);
assert_eq!(settled.checkpoint().settled_count(), 1);
assert_eq!(settled.count(Outcome::Unreachable { position: 0 }), 1);
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(sweep, "1-3".parse().expect("ports")));
let (_session, ctx) = ScanSession::new();
ctx.number_targets(TargetIndex::of(&map));
ctx.record_outcome(Outcome::Exhausted { position: 4 });
ctx.record_unroutable(unreachable);
let checkpoint = ctx.settlements().checkpoint();
assert_eq!(
(0..9)
.filter(|position| checkpoint.is_settled(*position))
.collect::<Vec<_>>(),
[3, 4, 5],
"the three ports of the second address, and nothing else"
);
assert_eq!(
ctx.settlements()
.count(Outcome::Unreachable { position: 0 }),
2
);
}
#[test]
fn a_machine_an_exclusion_names_is_withheld_at_its_other_addresses() {
use crate::model::mac::MacAddr;
use crate::report::{ScanKind, TargetScope};
use crate::scanner::recorder::PhaseRecorder;
let excluded: IpAddr = "192.0.2.30".parse().expect("literal");
let machine = MacAddr::new(0x02, 0, 0, 0, 0, 0x30);
let neighbour_mac = MacAddr::new(0x02, 0, 0, 0, 0, 0x31);
let (link_local, global, neighbour): (IpAddr, IpAddr, IpAddr) = (
"2001:db8::30".parse().expect("literal"),
"2001:db8::3030".parse().expect("literal"),
"2001:db8::31".parse().expect("literal"),
);
let mut ips = IpSet::new();
ips.insert(excluded);
let (session, ctx) = ScanSession::builder()
.excluding(Exclusions::new(ips))
.with_neighbours(vec![(excluded, Some(machine))])
.build();
let mut scope_ips = IpSet::new();
scope_ips.insert(neighbour);
let recorder = PhaseRecorder::start(
ScanKind::Discovery,
crate::system::privilege::Privilege::Raw,
TargetScope::from_ip_set(&mut scope_ips, &ctx.exclusions),
&crate::config::ZondConfig::default(),
);
let answered = |address: IpAddr, mac: MacAddr| {
ctx.write_host(address, |host| {
host.set_status(crate::model::host::HostStatus::Up);
host.record_mac(mac);
true
});
};
answered(link_local, machine);
answered(neighbour, neighbour_mac);
ctx.update_host(global, |host| {
host.set_status(crate::model::host::HostStatus::Up)
});
answered(global, machine);
for address in [link_local, global] {
assert!(
session.hosts().get(address).is_none(),
"{address} answered from the excluded machine and was recorded"
);
assert!(!ctx.may_probe(&address), "{address} may still be asked");
}
assert!(session.hosts().get(neighbour).is_some());
assert!(ctx.may_probe(&neighbour));
let report = recorder.finish(&ctx);
let listed: Vec<IpAddr> = report.phases()[0]
.targets()
.excluded()
.iter()
.map(|range| range.start_addr())
.collect();
for address in [excluded, link_local, global] {
assert!(listed.contains(&address), "{address} not in {listed:?}");
}
}
#[test]
fn an_excluded_address_does_not_become_the_one_a_host_is_reached_at() {
let key: IpAddr = "fe80::10".parse().expect("literal");
let excluded: IpAddr = "2001:db8::5".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
ctx.write_host(key, |host| host.consider_primary_ip(excluded));
let (primary, ips) = ctx
.read_host(key, |host| (host.primary_ip(), host.ips().clone()))
.expect("the permitted key is recorded");
assert_eq!(primary, key, "led by the address the policy allows");
assert!(!ips.contains(&excluded), "{ips:?}");
}
fn traced_through(target: IpAddr, router: IpAddr) -> [Hop; 3] {
[
Hop::answered(
1,
"203.0.113.1".parse().expect("literal"),
Some(Duration::from_millis(1)),
),
Hop::answered(2, router, Some(Duration::from_millis(4))),
Hop::answered(3, target, None),
]
}
#[test]
fn a_router_the_exclusions_forbid_is_withheld_from_a_traced_hosts_path() {
let target: IpAddr = "203.0.113.9".parse().expect("literal");
let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
ctx.write_host(target, |host| {
for hop in traced_through(target, excluded) {
host.record_hop(hop);
}
true
});
let path = ctx
.read_host(target, |host| host.path().clone())
.expect("the traced host is recorded");
assert!(
path.hops()
.iter()
.all(|hop| hop.address() != Some(excluded)),
"{path:?}"
);
let at_two = path.hops()[1];
assert_eq!(at_two.distance(), 2, "the router keeps its place");
assert!(at_two.is_withheld(), "a router answered there: {at_two:?}");
assert_eq!(at_two.rtt(), None, "its timing is a fact about the router");
assert_eq!(path.length(), Some(3));
assert_eq!(path.at(1), Some("203.0.113.1".parse().expect("literal")));
}
#[test]
fn a_resume_withholds_a_router_this_sitting_may_not_report() {
let target: IpAddr = "203.0.113.9".parse().expect("literal");
let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
let mut journalled = Host::new(target);
for hop in traced_through(target, excluded) {
journalled.record_hop(hop);
}
ctx.restore_hosts(&[journalled]);
let path = ctx
.read_host(target, |host| host.path().clone())
.expect("the host is restored");
assert!(
path.hops()
.iter()
.all(|hop| hop.address() != Some(excluded)),
"{path:?}"
);
assert!(path.hops()[1].is_withheld(), "{path:?}");
}
fn unreachable_from(sender: IpAddr) -> StatusReason {
StatusReason::new(StatusProtocol::IcmpUnreachable, "destination unreachable")
.from_source(sender)
}
#[test]
fn an_excluded_middlebox_is_withheld_from_a_permitted_hosts_evidence() {
let target: IpAddr = "203.0.113.9".parse().expect("literal");
let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
ctx.write_host(target, |host| {
host.record_evidence(HostStatus::Down, unreachable_from(excluded));
true
});
let (status, reasons) = ctx
.read_host(target, |host| (host.status(), host.reasons().clone()))
.expect("the host the evidence is about is recorded");
assert_eq!(status, HostStatus::Down, "the evidence still counts");
let sources: Vec<EvidenceSource> = reasons.iter().map(|reason| reason.source).collect();
assert_eq!(sources, [EvidenceSource::Withheld], "{reasons:?}");
}
#[test]
fn a_resume_withholds_a_middlebox_this_sitting_may_not_report() {
let target: IpAddr = "203.0.113.9".parse().expect("literal");
let excluded: IpAddr = "198.51.100.1".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
let mut journalled = Host::new(target);
journalled.record_evidence(HostStatus::Down, unreachable_from(excluded));
ctx.restore_hosts(&[journalled]);
let sources: Vec<EvidenceSource> = ctx
.read_host(target, |host| {
host.reasons().iter().map(|reason| reason.source).collect()
})
.expect("the host is restored");
assert_eq!(sources, [EvidenceSource::Withheld]);
}
#[test]
fn a_resume_brings_back_none_of_a_hosts_excluded_addresses() {
let key: IpAddr = "192.0.2.60".parse().expect("literal");
let excluded: IpAddr = "192.0.2.61".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
let mut host = Host::new(key);
host.add_ip(excluded);
ctx.restore_hosts(&[host]);
let ips = ctx
.read_host(key, |host| host.ips().clone())
.expect("the host is restored");
assert!(!ips.contains(&excluded), "{ips:?}");
}
#[test]
fn a_resumed_host_led_by_an_excluded_address_is_kept_at_its_others() {
let other: IpAddr = "fe80::10".parse().expect("literal");
let excluded: IpAddr = "2001:db8::5".parse().expect("literal");
let (_session, ctx) = forbidding(excluded);
let mut host = Host::new(other);
host.consider_primary_ip(excluded);
host.set_status(HostStatus::Up);
assert_eq!(host.primary_ip(), excluded, "test premise");
ctx.restore_hosts(&[host]);
let (primary, ips) = ctx
.read_host(other, |host| (host.primary_ip(), host.ips().clone()))
.expect("the host is kept at the address the policy allows");
assert_eq!(primary, other);
assert!(!ips.contains(&excluded), "{ips:?}");
}
#[test]
fn a_liveness_pass_leaves_a_port_scans_counters_alone() {
let (_session, ports) = ScanSession::builder()
.planning(Stage::Ports, Some(1_024))
.build();
ports.record_address_outcomes(Outcome::Unasked, 300);
assert_eq!(ports.settlements().count(Outcome::Unasked), 0);
let (_session, sweep) = ScanSession::builder()
.planning(Stage::Discovery, Some(1_024))
.build();
sweep.record_address_outcomes(Outcome::Unasked, 300);
assert_eq!(sweep.settlements().count(Outcome::Unasked), 300);
}
}