use std::num::NonZeroU32;
use std::{
collections::HashMap,
net::IpAddr,
time::{Duration, Instant},
};
use crate::config::ProbeTuning;
use crate::evasion::SegmentShaping;
use crate::info;
use crate::journal::settle::{Outcome, Settled};
use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
use crate::model::ip::set::IpSet;
use crate::model::port::set::COMMON_DISCOVERY_PORTS;
use crate::model::port::{PortSet, Protocol, TCP_BY_PREVALENCE};
use crate::model::technique::{TcpReply, TcpScanTechnique};
use crate::protocols as protocol;
use crate::scanner::dispatcher::WalkOrder;
use crate::scanner::pacing::deadline::{AdaptiveDeadline, AdaptiveDeadlineConfig, HeldAllowance};
use crate::scanner::pacing::retry::{ProbeLedger, Resolution, RetryPolicy};
use crate::scanner::session::ScanContext;
use crate::system::interface::RoutedTarget;
use crate::transport::capture::CapturedSegment;
use crate::transport::probe::{Emission, ProbeKind, ProbeTransport};
use async_trait::async_trait;
use pnet_packet::ip::{IpNextHeaderProtocol, IpNextHeaderProtocols};
use tokio::sync::mpsc::UnboundedSender;
use crate::report::ScannerKind;
use crate::report::StopReason;
use crate::scanner::strategy::raw::{
DEADLINE_CONFIG, EvasionParts, RETRY_POLICY, SendFaults, SynToken, pacing_for, rate_within,
send_init, send_syn,
};
use crate::scanner::strategy::sweep::HostSweep;
use crate::scanner::strategy::{HostScanner, StrategyError};
pub(super) const PROBE_RATE_PER_SEC: NonZeroU32 = NonZeroU32::new(4_000).expect("a non-zero rate");
fn answers_a_syn_probe(bytes: &[u8]) -> bool {
protocol::tcp::parse(bytes)
.ok()
.and_then(|tcp| protocol::tcp::classify_probe_response(&tcp))
.is_some_and(|reply| !matches!(reply, TcpReply::ChallengeAck))
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SynPorts {
ports: [u16; Self::CAPACITY],
len: u8,
}
impl SynPorts {
pub const SCAN_PORTS: usize = 3;
pub const CAPACITY: usize = COMMON_DISCOVERY_PORTS.len() + Self::SCAN_PORTS;
pub fn common() -> Self {
let mut set = Self {
ports: [0; Self::CAPACITY],
len: 0,
};
for &port in COMMON_DISCOVERY_PORTS {
set.push(port);
}
set
}
pub fn only(port: u16) -> Self {
let mut set = Self {
ports: [0; Self::CAPACITY],
len: 0,
};
set.push(port);
set
}
pub fn for_scan(scan: &PortSet) -> Self {
let mut set = Self::common();
let common = set.len();
let ranked = TCP_BY_PREVALENCE
.iter()
.copied()
.filter(|&port| scan.has_tcp(port));
let unranked = scan
.ranges(Protocol::Tcp)
.iter()
.flat_map(|range| range.clone())
.filter(|port| !TCP_BY_PREVALENCE.contains(port));
for port in ranked.chain(unranked) {
if set.len() == common + Self::SCAN_PORTS {
break;
}
if !set.as_slice().contains(&port) {
set.push(port);
}
}
set
}
pub fn as_slice(&self) -> &[u16] {
&self.ports[..usize::from(self.len)]
}
pub fn len(&self) -> usize {
usize::from(self.len)
}
pub fn is_empty(&self) -> bool {
self.len == 0
}
pub(crate) fn excluding(self, excluded: &PortSet) -> Self {
let mut kept = Self {
ports: [0; Self::CAPACITY],
len: 0,
};
for &port in self.as_slice() {
if !excluded.has_tcp(port) {
kept.push(port);
}
}
kept
}
fn push(&mut self, port: u16) {
self.ports[usize::from(self.len)] = port;
self.len += 1;
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SweepProbe {
Syn {
src_port: Option<u16>,
dst_ports: SynPorts,
},
Init {
src_port: u16,
dst_port: u16,
},
}
impl SweepProbe {
pub fn syn(src_port: Option<u16>) -> Self {
Self::syn_to(src_port, SynPorts::common())
}
pub const fn syn_to(src_port: Option<u16>, dst_ports: SynPorts) -> Self {
Self::Syn {
src_port,
dst_ports,
}
}
pub const fn init(src_port: u16, dst_port: u16) -> Self {
Self::Init { src_port, dst_port }
}
const fn leaving_from(self, port: Option<u16>) -> Self {
match (self, port) {
(Self::Syn { dst_ports, .. }, Some(port)) => Self::Syn {
src_port: Some(port),
dst_ports,
},
(Self::Init { dst_port, .. }, Some(port)) => Self::Init {
src_port: port,
dst_port,
},
(probe, _) => probe,
}
}
const fn transport(self) -> ProbeKind {
match self {
Self::Syn { .. } => ProbeKind::TcpSyn,
Self::Init { src_port, .. } => ProbeKind::Sctp {
reply_port: src_port,
},
}
}
fn packets_per_attempt(self) -> u32 {
match self {
Self::Syn { dst_ports, .. } => dst_ports.len() as u32,
Self::Init { .. } => 1,
}
}
const fn scanner_kind(self) -> ScannerKind {
match self {
Self::Syn { .. } => ScannerKind::Routed,
Self::Init { .. } => ScannerKind::RoutedSctp,
}
}
const fn answered_under(self) -> IpNextHeaderProtocol {
match self {
Self::Syn { .. } => IpNextHeaderProtocols::Tcp,
Self::Init { .. } => IpNextHeaderProtocols::Sctp,
}
}
fn answers(self, reply: &CapturedSegment) -> bool {
if reply.protocol != self.answered_under().0 {
return false;
}
match self {
Self::Syn { .. } => answers_a_syn_probe(&reply.bytes),
Self::Init { .. } => protocol::sctp::parse(&reply.bytes)
.ok()
.and_then(|packet| protocol::sctp::classify_probe_response(&packet))
.is_some(),
}
}
fn token_of(self, bytes: &[u8], padding: u16) -> Option<SweepToken> {
match self {
Self::Syn { .. } => protocol::tcp::parse(bytes).ok().map(|tcp| {
SweepToken::Syn(SynToken {
seq: protocol::tcp::echoed_nonce(TcpScanTechnique::Syn, &tcp, padding),
src_port: tcp.destination_port(),
})
}),
Self::Init { .. } => protocol::sctp::parse(bytes)
.ok()
.map(|packet| SweepToken::Init(protocol::sctp::echoed_nonce(&packet))),
}
}
fn evidence(self) -> StatusReason {
match self {
Self::Syn { .. } => {
StatusReason::new(StatusProtocol::TcpSyn, "tcp reply to a discovery probe")
}
Self::Init { .. } => {
StatusReason::new(StatusProtocol::Sctp, "sctp reply to a discovery probe")
}
}
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum SweepToken {
Syn(SynToken),
Init(u32),
}
pub struct RoutedScanner {
ctx: ScanContext,
sources: HashMap<IpAddr, IpAddr>,
ips: IpSet,
transport: ProbeTransport,
probe: SweepProbe,
emission: Emission,
shaping: SegmentShaping,
decoys: Vec<IpAddr>,
deadline: AdaptiveDeadline,
dns_tx: Option<UnboundedSender<IpAddr>>,
sweep: HostSweep<SweepToken>,
pending: std::vec::IntoIter<IpAddr>,
held: std::collections::VecDeque<IpAddr>,
held_allowed: HeldAllowance,
send_tick: Duration,
batch: usize,
faults: SendFaults,
}
#[async_trait]
impl HostScanner for RoutedScanner {
fn kind(&self) -> ScannerKind {
self.probe.scanner_kind()
}
async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
let mut send_tick = tokio::time::interval(self.send_tick);
send_tick.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
let reason = loop {
let now = Instant::now();
self.read_waiting_replies();
self.sweep.service_retries(&self.ctx, now);
let all_responded = self.sweep.all_responded(self.ips.len());
if let Some(cause) = self.ctx.handle.stopped() {
break cause.into();
}
if all_responded {
break StopReason::AllResponded;
}
if self.nothing_left_to_send() && self.sweep.ledger.is_empty() {
break StopReason::AttemptsSpent;
}
if self.deadline.hard_deadline_passed() {
break StopReason::DeadlineExpired;
}
let sending = !self.nothing_left_to_send();
let tick = self.sweep.idle_delay(&self.deadline, now);
tokio::select! {
res = self.transport.rx.recv() => {
match res {
Some(reply) => {
self.sweep.audit.record_segment();
self.handle_discovery_reply(&reply, reply.received_at);
}
None => break StopReason::StreamClosed,
}
},
_ = send_tick.tick(), if sending => {
self.send_allowance(Instant::now());
}
_ = tokio::time::sleep(tick), if !sending => {}
}
};
self.finish(reason);
Ok(())
}
}
const SEND_SLACK: f64 = 1.5;
fn schedule(
target_count: usize,
probe: SweepProbe,
retry: &RetryPolicy,
rate_per_sec: NonZeroU32,
host_gap: Option<Duration>,
) -> (Duration, usize, AdaptiveDeadlineConfig) {
let addresses_per_sec = NonZeroU32::new(rate_per_sec.get() / probe.packets_per_attempt())
.unwrap_or(NonZeroU32::MIN);
let (send_tick, batch) = pacing_for(addresses_per_sec);
let per_address = Duration::from_secs_f64(
SEND_SLACK * f64::from(retry.max_attempts) / f64::from(addresses_per_sec.get()),
);
let deadline_config = DEADLINE_CONFIG
.allowing_for(retry.longest_spaced_probe_lifetime(host_gap))
.allowing_pace_of(per_address, target_count);
(send_tick, batch, deadline_config)
}
impl RoutedScanner {
pub fn new(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
) -> Result<Self, StrategyError> {
Self::over_tcp(targets, ctx, dns_tx, tuning, SynPorts::common())
}
pub fn over_tcp(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
ports: SynPorts,
) -> Result<Self, StrategyError> {
Self::asking(
SweepProbe::syn_to(tuning.evasion.source_port, ports),
targets,
ctx,
dns_tx,
tuning,
)
}
pub fn over_sctp(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
dst_port: u16,
) -> Result<Self, StrategyError> {
let src_port = tuning
.evasion
.source_port
.unwrap_or_else(|| rand::random_range(50_000..u16::MAX));
Self::asking(
SweepProbe::init(src_port, dst_port),
targets,
ctx,
dns_tx,
tuning,
)
}
fn asking(
probe: SweepProbe,
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
) -> Result<Self, StrategyError> {
let transport = ProbeTransport::open_capturing(
probe.transport(),
tuning.evasion.effective_send_mode(tuning.send_mode),
&ctx.capture_links(),
)?;
Ok(Self::build(
targets,
ctx,
dns_tx,
transport,
probe,
tuning.evasion.emission(),
tuning.evasion.segment_shaping(),
tuning.evasion.decoys.clone(),
RETRY_POLICY.configured(tuning.retry),
rate_within(
tuning.max_probe_rate,
tuning.min_probe_rate,
PROBE_RATE_PER_SEC,
),
))
}
pub fn with_transport(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
transport: ProbeTransport,
) -> Self {
Self::with_transport_asking(targets, ctx, dns_tx, transport, SweepProbe::syn(None))
}
pub fn with_transport_asking(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
transport: ProbeTransport,
probe: SweepProbe,
) -> Self {
Self::build(
targets,
ctx,
dns_tx,
transport,
probe,
Emission::routed(),
SegmentShaping::default(),
Vec::new(),
RETRY_POLICY,
PROBE_RATE_PER_SEC,
)
}
#[allow(clippy::too_many_arguments)]
fn build(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
transport: ProbeTransport,
probe: SweepProbe,
emission: Emission,
shaping: SegmentShaping,
decoys: Vec<IpAddr>,
retry: RetryPolicy,
rate_per_sec: NonZeroU32,
) -> Self {
let mut ips = IpSet::new();
let mut order = Vec::with_capacity(targets.len());
let mut sources = HashMap::with_capacity(targets.len());
for RoutedTarget { target, source } in targets {
ips.insert(target);
if sources.insert(target, source).is_none() {
order.push(target);
}
}
ips.canonicalize();
if let Some(walk) = WalkOrder::of(&ips, &ctx) {
walk.arrange(&mut order);
}
let target_count = sources.len();
let probe = probe.leaving_from(transport.reply_port());
let (send_tick, batch, deadline_config) = schedule(
target_count,
probe,
&retry,
rate_per_sec,
ctx.host_probe_interval(),
);
Self {
ctx,
sources,
ips,
transport,
probe,
emission,
shaping,
decoys,
deadline: AdaptiveDeadline::new(deadline_config, target_count),
dns_tx,
sweep: HostSweep::new(ProbeLedger::new(retry, target_count)),
pending: order.into_iter(),
held: std::collections::VecDeque::new(),
held_allowed: HeldAllowance::default(),
send_tick,
batch,
faults: SendFaults::default(),
}
}
fn finish(&mut self, reason: StopReason) {
let kind = self.kind();
let label = match self.probe {
SweepProbe::Init { .. } => "sctp-discovery",
_ => "routed-discovery",
};
let interrupted = self.sweep.ledger.drain_unresolved();
let unasked: Vec<IpAddr> = self.held.drain(..).chain(self.pending.by_ref()).collect();
self.ctx
.record_address_outcomes(Outcome::Interrupted, interrupted.len() as u64);
self.ctx
.record_address_outcomes(Outcome::Unasked, unasked.len() as u64);
if !unasked.is_empty() && !matches!(reason, StopReason::Aborted | StopReason::TimedOut) {
self.ctx.record_failure(
self.kind(),
format!(
"{} of {} addresses were never asked: {reason} with them \
still queued",
unasked.len(),
self.sources.len(),
),
);
}
self.ctx
.record_address_outcomes(Outcome::Unroutable, self.faults.addresses.len() as u64);
self.faults.file(
&self.ctx,
kind,
"probes",
self.sweep.audit.sends_attempted,
self.sweep.audit.sends_failed,
);
if let Some((address, _)) = &self.faults.unroutable {
match self.faults.addresses.len().saturating_sub(1) {
0 => info!(verbosity = 1, "{address} unreachable"),
1 => info!(verbosity = 1, "{address} and 1 other address unreachable"),
more => info!(
verbosity = 1,
"{address} and {more} other addresses unreachable"
),
}
}
let capture = self.transport.capture_counts();
let targets = self.ips.len();
self.sweep
.report(&self.ctx, label, kind, targets, reason, capture);
}
fn handle_discovery_reply(&mut self, reply: &CapturedSegment, now: Instant) {
let ip = reply.source;
if !self.ips.contains(&ip) {
self.sweep.audit.record_off_target();
return;
}
if !self.probe.answers(reply) {
self.sweep.audit.record_off_target();
return;
}
let resolution = self.resolve_probe(ip, &reply.bytes, now);
let rtt = resolution.and_then(|resolution| resolution.rtt);
if rtt.is_none() {
self.sweep.audit.record_reply_without_rtt();
}
let evidence = self.probe.evidence();
self.ctx.write_host(ip, |host| {
let was_up = host.status().is_up();
host.record_evidence(HostStatus::Up, evidence.clone());
if let Some(rtt) = rtt {
host.add_rtt_from(rtt, evidence.protocol.clone());
return true;
}
!was_up
});
self.ctx.settle_address(ip, Settled::Answered);
if self.sweep.responded.insert(ip) {
self.sweep
.audit
.record_host_found(resolution.and_then(|resolution| resolution.answered_attempt));
self.deadline.mark_activity();
if let Some(dns) = &self.dns_tx {
let _ = dns.send(ip);
}
}
if let Some(rtt) = rtt {
self.deadline.record_rtt(rtt);
}
}
fn resolve_probe(&mut self, ip: IpAddr, bytes: &[u8], now: Instant) -> Option<Resolution> {
let token = self
.probe
.token_of(bytes, self.shaping.padding.unwrap_or(0));
token
.and_then(|token| self.sweep.ledger.resolve(&ip, Some(token), now))
.or_else(|| self.sweep.ledger.resolve(&ip, None, now))
}
fn read_waiting_replies(&mut self) {
let waiting = self.transport.rx.len();
for _ in 0..waiting {
let Ok(reply) = self.transport.rx.try_recv() else {
return;
};
self.sweep.audit.record_segment();
self.handle_discovery_reply(&reply, reply.received_at);
}
}
fn nothing_left_to_send(&self) -> bool {
self.sweep.retries.is_empty() && self.held.is_empty() && self.pending.len() == 0
}
fn send_allowance(&mut self, now: Instant) {
for _ in 0..self.batch {
if let Some(target) = self.next_ready_retry(now) {
self.reprobe(target, now);
} else if let Some(target) = self.next_unheld(now) {
self.probe(target, now);
} else if let Some(target) = self.pending.next() {
self.probe(target, now);
} else {
return;
}
}
}
fn next_ready_retry(&mut self, now: Instant) -> Option<IpAddr> {
for _ in 0..self.sweep.retries.len() {
let target = self.sweep.retries.pop_front()?;
if !self.sweep.ledger.contains(&target) {
continue;
}
if self.ctx.host_ready_at(target, now).is_some()
|| self.faults.held_until(target, now).is_some()
{
self.sweep.retries.push_back(target);
continue;
}
return Some(target);
}
None
}
fn next_unheld(&mut self, now: Instant) -> Option<IpAddr> {
let ready = self
.held
.iter()
.position(|target| self.faults.held_until(*target, now).is_none())?;
self.held.remove(ready)
}
fn held_down(&mut self, target: IpAddr, now: Instant) -> bool {
let Some(until) = self.faults.held_until(target, now) else {
return false;
};
self.deadline
.allow_for_holding(self.held_allowed.take(now, until));
true
}
fn probe(&mut self, target: IpAddr, now: Instant) {
match self.send_attempt(target, now) {
Some(token) => self.sweep.ledger.arm(target, target, token, (), now),
None if self.held_down(target, now) => self.held.push_back(target),
None => {}
}
}
fn reprobe(&mut self, target: IpAddr, now: Instant) {
match self.send_attempt(target, now) {
Some(token) => self.sweep.ledger.rearm(target, target, token, now),
None if self.held_down(target, now) => self.sweep.retries.push_back(target),
None => self.sweep.ledger.resume(&target, now),
}
}
fn send_attempt(&mut self, target: IpAddr, now: Instant) -> Option<SweepToken> {
let &source = self.sources.get(&target)?;
let token = match self.probe {
SweepProbe::Syn {
src_port,
dst_ports,
} => {
let token = SynToken::fresh(src_port);
let mut sent = false;
for &dst_port in dst_ports.as_slice() {
if self.faults.held_until(target, now).is_some() {
break;
}
let left = send_syn(
self.transport.tx.as_ref(),
source,
target,
None,
dst_port,
token,
EvasionParts {
emission: self.emission,
shaping: self.shaping,
decoys: &self.decoys,
},
&mut self.faults,
);
self.sweep.audit.record_send(left);
sent |= left;
}
sent.then_some(SweepToken::Syn(token))
}
SweepProbe::Init { src_port, dst_port } => {
let tag = send_init(
self.transport.tx.as_ref(),
source,
target,
None,
dst_port,
src_port,
&self.decoys,
self.emission,
&mut self.faults,
);
self.sweep.audit.record_send(tag.is_some());
tag.map(SweepToken::Init)
}
};
if token.is_some() {
self.ctx.host_probed(target, now);
}
token
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::Ipv4Addr;
use pnet_packet::icmp::IcmpTypes;
use pnet_packet::icmp::destination_unreachable::{
IcmpCodes, MutableDestinationUnreachablePacket,
};
use crate::config::RetryConfig;
use crate::model::technique::SctpReply;
use crate::protocols::craft::{self, Field};
use crate::scanner::session::{ScanContext, ScanSession};
use crate::transport::probe::MockSender;
fn asked_for(spec: &str) -> Vec<u16> {
SynPorts::for_scan(&PortSet::try_from(spec).expect("a port specification"))
.as_slice()
.to_vec()
}
#[test]
fn a_sweep_leaves_from_the_port_its_transport_hears_replies_on() {
let (_session, ctx) = ScanSession::new();
let (_reply_tx, rx) = tokio::sync::mpsc::channel(1);
let transport = ProbeTransport::from_parts(Box::new(MockSender::default()), rx)
.opened_for(ProbeKind::Sctp { reply_port: 5_000 });
let sweep = RoutedScanner::with_transport_asking(
Vec::new(),
ctx,
None,
transport,
SweepProbe::init(4_000, 80),
);
assert_eq!(sweep.probe, SweepProbe::init(5_000, 80));
let unfixed = SweepProbe::syn(None);
assert_eq!(
unfixed.leaving_from(None),
unfixed,
"a transport fixing none"
);
}
#[test]
fn the_common_set_is_the_list_the_unprivileged_sweep_asks() {
assert_eq!(SynPorts::common().as_slice(), COMMON_DISCOVERY_PORTS);
}
#[test]
fn a_scan_of_a_short_list_has_all_of_it_asked() {
assert_eq!(
asked_for("8443,3306"),
[COMMON_DISCOVERY_PORTS, &[8443, 3306]].concat(),
"the catalogue ranks 8443 ahead of 3306, so it leaves first"
);
}
#[test]
fn a_broad_scan_adds_its_highest_ranked_ports_up_to_the_limit() {
let asked = asked_for("1-65535");
assert_eq!(asked.len(), SynPorts::CAPACITY);
assert_eq!(
asked[COMMON_DISCOVERY_PORTS.len()..],
TCP_BY_PREVALENCE[5..8],
"the three ranked straight after the common five"
);
}
#[test]
fn a_port_the_catalogue_does_not_rank_comes_after_one_it_does() {
assert_eq!(
asked_for("40001,40000,8080")[COMMON_DISCOVERY_PORTS.len()..],
[8080, 40000, 40001]
);
}
#[test]
fn a_scan_port_among_the_common_five_is_asked_once() {
assert_eq!(asked_for("22,443"), COMMON_DISCOVERY_PORTS);
}
#[test]
fn an_excluded_port_is_not_asked_and_the_rest_keep_their_order() {
let excluded = |spec: &str| PortSet::try_from(spec).expect("a port specification");
let asked = SynPorts::for_scan(&excluded("8443"));
assert_eq!(
asked.excluding(&excluded("22,445,u:80")).as_slice(),
[80, 443, 3389, 8443]
);
assert!(
SynPorts::common()
.excluding(&excluded("1-65535"))
.is_empty()
);
assert_eq!(
SynPorts::common().excluding(&PortSet::new()),
SynPorts::common()
);
}
fn hard_deadline(targets: usize, retry: RetryConfig, rate: NonZeroU32) -> Duration {
let (_, _, deadline) = schedule(
targets,
SweepProbe::syn(None),
&RETRY_POLICY.configured(retry),
rate,
None,
);
deadline.max_budget.for_target_count(targets)
}
fn every_packet_sent(targets: usize, attempts: u8, rate: u32) -> Duration {
let packets = targets * usize::from(attempts) * SynPorts::common().len();
Duration::from_secs_f64(packets as f64 / f64::from(rate))
}
#[test]
fn a_sweep_outlasts_the_time_its_pacing_needs_to_send_every_attempt() {
const SLASH_16: usize = 1 << 16;
let default_rate = PROBE_RATE_PER_SEC;
let thorough = RetryConfig {
effort: crate::config::ScanEffort::Thorough,
..RetryConfig::default()
};
let cases = [
(
"a /16 by default",
SLASH_16,
RetryConfig::default(),
3,
default_rate,
),
("a /16 at thorough", SLASH_16, thorough, 5, default_rate),
(
"a /16 at 1000 packets a second",
SLASH_16,
RetryConfig::default(),
3,
NonZeroU32::new(1_000).expect("non-zero"),
),
(
"a /15 by default",
2 * SLASH_16,
RetryConfig::default(),
3,
default_rate,
),
];
for (case, targets, retry, attempts, rate) in cases {
let needed = every_packet_sent(targets, attempts, rate.get());
let given = hard_deadline(targets, retry, rate);
assert!(
given >= needed,
"{case}: needs {needed:?} to send every attempt and is given {given:?}"
);
}
}
#[test]
fn a_sweep_outlasts_a_probe_timed_at_the_ceiling_on_every_attempt() {
let thorough = RetryConfig {
effort: crate::config::ScanEffort::Thorough,
..RetryConfig::default()
};
for (case, retry) in [
("by default", RetryConfig::default()),
("at thorough", thorough),
] {
let needed = RETRY_POLICY.configured(retry).longest_probe_lifetime();
let given = hard_deadline(1, retry, PROBE_RATE_PER_SEC);
assert!(
given >= needed,
"one address {case}: its schedule at the ceiling takes {needed:?} \
and the sweep is given {given:?}"
);
}
}
#[test]
fn a_spaced_sweep_outlasts_every_attempt_waiting_out_the_gap() {
let gap = Duration::from_secs(60);
let (_, _, deadline) = schedule(
1,
SweepProbe::syn(None),
&RETRY_POLICY,
PROBE_RATE_PER_SEC,
Some(gap),
);
let needed = gap * u32::from(RETRY_POLICY.max_attempts);
let given = deadline.max_budget.for_target_count(1);
assert!(
given >= needed,
"three attempts a {gap:?} gap apart take {needed:?} and the sweep \
is given {given:?}"
);
}
fn sweep_with_first_attempts(
targets: &[Ipv4Addr],
asked: usize,
) -> (RoutedScanner, ScanContext) {
let (_session, ctx) = ScanSession::new();
let (_replies, rx) = tokio::sync::mpsc::channel(8);
let mut scanner = RoutedScanner::with_transport(
targets
.iter()
.map(|&target| RoutedTarget {
target: target.into(),
source: LOCAL.into(),
})
.collect(),
ctx.clone(),
None,
ProbeTransport::from_parts(Box::new(MockSender::default()), rx),
);
for _ in 0..asked {
let next = scanner.pending.next().expect("a target still queued");
scanner.probe(next, Instant::now());
}
(scanner, ctx)
}
#[tokio::test]
async fn a_seeded_sweep_asks_in_the_order_the_seed_names() {
use crate::model::ip::set::Positions;
const SEED: u64 = 0x5EED;
let targets: IpSet = "198.51.100.0/26".parse().expect("a prefix");
let (_session, ctx) = ScanSession::builder()
.ordering(Some(SEED))
.counting(Positions::of(&targets))
.build();
let mut walk = crate::scanner::dispatcher::dispatch_addresses_of(
targets.clone(),
1,
Some(SEED),
Some(std::sync::Arc::clone(&ctx.positions)),
&ctx.handle,
);
let mut expected = Vec::new();
while let Some(ip) = walk.recv().await {
expected.push(ip);
}
assert_ne!(
expected,
targets.iter().collect::<Vec<_>>(),
"the walk the seed names is not the range"
);
let (_replies, rx) = tokio::sync::mpsc::channel(8);
let scanner = RoutedScanner::with_transport(
targets
.iter()
.map(|target| RoutedTarget {
target,
source: LOCAL.into(),
})
.collect(),
ctx,
None,
ProbeTransport::from_parts(Box::new(MockSender::default()), rx),
);
assert_eq!(scanner.pending.collect::<Vec<_>>(), expected);
}
const THREE: [Ipv4Addr; 3] = [
Ipv4Addr::new(198, 51, 100, 1),
Ipv4Addr::new(198, 51, 100, 2),
Ipv4Addr::new(198, 51, 100, 3),
];
#[test]
fn a_sweep_cut_short_reports_what_it_never_asked() {
let (mut scanner, ctx) = sweep_with_first_attempts(&THREE, 1);
scanner.finish(StopReason::DeadlineExpired);
let failures: Vec<String> = ctx
.take_failures()
.iter()
.map(|failure| failure.reason().to_owned())
.collect();
assert_eq!(
failures,
["2 of 3 addresses were never asked: deadline expired with them still queued"],
"the result is partial and says by how much"
);
assert_eq!(ctx.settlements().count(Outcome::Unasked), 2);
assert_eq!(
ctx.settlements().count(Outcome::Interrupted),
1,
"the one still mid-schedule has no verdict either"
);
assert!(ctx.take_silent().is_empty(), "none of them was silent");
}
#[test]
fn an_unreachable_address_is_named_only_beyond_the_default_console() {
let (mut scanner, ctx) = sweep_with_first_attempts(&THREE, THREE.len());
let [first, second, _] = THREE;
scanner.faults.unroutable = Some((first.into(), "no route to host".to_owned()));
scanner.faults.unroutable_count = 2;
scanner.faults.addresses = [first.into(), second.into()].into();
let said = crate::logging::logged(|| scanner.finish(StopReason::AttemptsSpent));
let unroutable: Vec<_> = said
.iter()
.filter(|line| line.message.contains("unreachable"))
.collect();
assert_eq!(unroutable.len(), 1, "said once: {said:?}");
assert_eq!(
unroutable[0].message,
"198.51.100.1 and 1 other address unreachable"
);
assert!(
unroutable[0].verbosity >= 1,
"a default console already has the count: {said:?}"
);
assert_eq!(ctx.take_unroutable().len(), 2, "both are recorded");
}
#[test]
fn a_refused_send_is_one_failure_and_an_unroutable_address_is_filed_against_itself() {
let (mut scanner, ctx) = sweep_with_first_attempts(&THREE, THREE.len());
let [first, ..] = THREE;
let attempted = scanner.sweep.audit.sends_attempted;
scanner.sweep.audit.sends_failed = 3;
scanner.faults.broken = Some("refused for the test".to_owned());
scanner.faults.unroutable = Some((first.into(), "no route to host".to_owned()));
scanner.faults.unroutable_count = 1;
scanner.faults.addresses = [first.into()].into();
scanner.finish(StopReason::AttemptsSpent);
let failures: Vec<String> = ctx
.take_failures()
.iter()
.map(|failure| failure.reason().to_owned())
.collect();
assert_eq!(
failures,
[format!(
"2 of {attempted} probes could not be sent: refused for the test"
)]
);
assert_eq!(ctx.take_unroutable(), [IpAddr::from(first)]);
}
#[cfg(unix)]
#[test]
fn an_attempt_refused_for_a_hold_down_is_made_after_it() {
use crate::transport::probe::{ProbeSender, SendError};
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
struct HeldDown {
holding: Arc<AtomicBool>,
taken: Arc<AtomicUsize>,
}
impl ProbeSender for HeldDown {
fn send(
&self,
_s: &[u8],
_src: IpAddr,
_dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), SendError> {
if self.holding.load(Ordering::SeqCst) {
return Err(SendError::from_io(std::io::Error::from_raw_os_error(
libc::EHOSTDOWN,
)));
}
self.taken.fetch_add(1, Ordering::SeqCst);
Ok(())
}
}
for held_again in [false, true] {
let (_session, ctx) = ScanSession::new();
let (_replies, rx) = tokio::sync::mpsc::channel(8);
let holding = Arc::new(AtomicBool::new(true));
let taken = Arc::new(AtomicUsize::new(0));
let sender = HeldDown {
holding: Arc::clone(&holding),
taken: Arc::clone(&taken),
};
let mut scanner = RoutedScanner::with_transport_asking(
vec![RoutedTarget {
target: TARGET.into(),
source: LOCAL.into(),
}],
ctx.clone(),
None,
ProbeTransport::from_parts(Box::new(sender), rx),
SweepProbe::syn(None),
);
let target = IpAddr::from(TARGET);
scanner.send_allowance(Instant::now());
holding.store(held_again, Ordering::SeqCst);
scanner.send_allowance(Instant::now());
assert!(
!scanner.sweep.ledger.contains(&target) && taken.load(Ordering::SeqCst) == 0,
"asked inside the hold-down"
);
scanner.faults.held_down.lift(target);
scanner.send_allowance(Instant::now());
if held_again {
assert!(!scanner.sweep.ledger.contains(&target));
assert_eq!(scanner.faults.addresses, [target].into(), "held down twice");
} else {
assert!(
scanner.faults.addresses.is_empty(),
"filed on one hold-down"
);
assert!(
scanner.sweep.ledger.contains(&target),
"not asked after the hold-down"
);
}
assert!(scanner.faults.broken.is_none(), "blamed on this machine");
}
}
#[test]
fn a_sweep_the_caller_stopped_names_what_it_never_asked_without_failing() {
let (mut scanner, ctx) = sweep_with_first_attempts(&THREE, 0);
scanner.finish(StopReason::Aborted);
assert!(ctx.take_failures().is_empty());
assert_eq!(
ctx.settlements().count(Outcome::Unasked),
THREE.len() as u64
);
assert!(ctx.take_silent().is_empty(), "none of them was silent");
}
#[test]
fn a_sweep_that_spent_its_attempts_reports_nothing_unasked() {
let (mut scanner, ctx) = sweep_with_first_attempts(&THREE, THREE.len());
scanner.sweep.ledger.drain_unresolved();
scanner.finish(StopReason::AttemptsSpent);
assert!(ctx.take_failures().is_empty());
assert_eq!(ctx.settlements().count(Outcome::Unasked), 0);
assert_eq!(ctx.settlements().count(Outcome::Interrupted), 0);
}
const LOCAL: Ipv4Addr = Ipv4Addr::new(192, 0, 2, 1);
const TARGET: Ipv4Addr = Ipv4Addr::new(198, 51, 100, 7);
const SCAN_PORT: u16 = 50_000;
fn init_sweep_with_a_probe_out() -> (RoutedScanner, ScanSession, Vec<u8>) {
let (session, ctx) = ScanSession::new();
let (_replies, rx) = tokio::sync::mpsc::channel(8);
let sender = MockSender::default();
let sent = sender.sent.clone();
let mut scanner = RoutedScanner::with_transport_asking(
vec![RoutedTarget {
target: TARGET.into(),
source: LOCAL.into(),
}],
ctx,
None,
ProbeTransport::from_parts(Box::new(sender), rx),
SweepProbe::init(SCAN_PORT, 3868),
);
scanner.probe(TARGET.into(), Instant::now());
let (probe, _, _) = sent.lock().unwrap().first().cloned().expect("an INIT");
(scanner, session, probe)
}
fn protocol_unreachable(probe: &[u8], identification: u16) -> CapturedSegment {
let header = craft::Ipv4 {
identification: Field::Exact(identification),
protocol: Field::Exact(IpNextHeaderProtocols::Sctp.0),
..craft::Ipv4::new(LOCAL, TARGET)
}
.header_bytes(probe.len() as u16)
.expect("an IPv4 header");
let quoted = [header.as_slice(), probe].concat();
let mut bytes =
vec![0u8; MutableDestinationUnreachablePacket::minimum_packet_size() + quoted.len()];
{
let mut icmp =
MutableDestinationUnreachablePacket::new(&mut bytes).expect("an ICMP buffer");
icmp.set_icmp_type(IcmpTypes::DestinationUnreachable);
icmp.set_icmp_code(IcmpCodes::DestinationProtocolUnreachable);
icmp.set_payload("ed);
}
CapturedSegment::synthetic(TARGET.into(), IpNextHeaderProtocols::Icmp.0, bytes)
}
#[test]
fn an_icmp_error_is_not_read_as_an_sctp_answer() {
let (mut scanner, session, probe) = init_sweep_with_a_probe_out();
let error = protocol_unreachable(&probe, 0x0600);
assert_eq!(
protocol::sctp::parse(&error.bytes)
.ok()
.and_then(|packet| protocol::sctp::classify_probe_response(&packet)),
Some(SctpReply::Abort),
"the fixture no longer spells the chunk it exists to spell"
);
scanner.handle_discovery_reply(&error, Instant::now());
let credited_to_sctp = session
.hosts()
.get(IpAddr::from(TARGET))
.is_some_and(|host| {
host.reasons()
.iter()
.any(|reason| reason.protocol == StatusProtocol::Sctp)
});
assert!(
!credited_to_sctp,
"an ICMP error was credited as an SCTP reply"
);
assert!(
scanner.sweep.ledger.contains(&IpAddr::from(TARGET)),
"the probe was retired by an answer it never drew"
);
}
struct StalledAfterAnswering {
stall: Duration,
replies: tokio::sync::mpsc::Sender<CapturedSegment>,
answered: std::sync::atomic::AtomicBool,
}
impl crate::transport::probe::ProbeSender for StalledAfterAnswering {
fn send(
&self,
segment: &[u8],
_src: IpAddr,
dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), crate::transport::probe::SendError> {
if self
.answered
.swap(true, std::sync::atomic::Ordering::Relaxed)
{
return Ok(());
}
self.replies
.try_send(syn_ack(segment, dst))
.expect("room for the answer");
std::thread::sleep(self.stall);
Ok(())
}
}
fn syn_ack(segment: &[u8], dst: IpAddr) -> CapturedSegment {
let probe = protocol::tcp::parse(segment).expect("a whole segment");
let mut reply = vec![0u8; 20];
let mut tcp = pnet_packet::tcp::MutableTcpPacket::new(&mut reply).expect("20 bytes");
tcp.set_source(probe.destination_port());
tcp.set_destination(probe.source_port());
tcp.set_data_offset(5);
tcp.set_flags(pnet_packet::tcp::TcpFlags::SYN | pnet_packet::tcp::TcpFlags::ACK);
tcp.set_acknowledgement(probe.sequence().wrapping_add(1));
CapturedSegment::synthetic(dst, IpNextHeaderProtocols::Tcp.0, reply)
}
struct AnsweringThroughABacklog {
backlog: Duration,
replies: tokio::sync::mpsc::Sender<CapturedSegment>,
}
impl crate::transport::probe::ProbeSender for AnsweringThroughABacklog {
fn send(
&self,
segment: &[u8],
_src: IpAddr,
dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), crate::transport::probe::SendError> {
let answer = syn_ack(segment, dst);
let (backlog, replies) = (self.backlog, self.replies.clone());
std::thread::spawn(move || {
std::thread::sleep(backlog);
let _ = replies.blocking_send(answer);
});
Ok(())
}
}
#[tokio::test]
async fn an_answer_waiting_when_its_probe_runs_out_still_finds_the_host() {
let (session, ctx) = ScanSession::new();
let (replies, rx) = tokio::sync::mpsc::channel(16);
let retry = RETRY_POLICY.configured(RetryConfig {
max_attempts: std::num::NonZeroU8::new(1),
..RetryConfig::default()
});
let stall = retry.initial_rto.mul_f64(1.0 + retry.jitter) + Duration::from_millis(200);
let transport = ProbeTransport::from_parts(
Box::new(StalledAfterAnswering {
stall,
replies,
answered: std::sync::atomic::AtomicBool::new(false),
}),
rx,
);
let mut scanner = RoutedScanner::build(
vec![RoutedTarget {
target: TARGET.into(),
source: LOCAL.into(),
}],
ctx,
None,
transport,
SweepProbe::syn(None),
Emission::routed(),
SegmentShaping::default(),
Vec::new(),
retry,
PROBE_RATE_PER_SEC,
);
scanner.discover_hosts().await.expect("the sweep runs");
assert!(
session
.hosts()
.get(IpAddr::from(TARGET))
.is_some_and(|host| host.status().is_up()),
"the host answered and is not on record as up"
);
}
#[tokio::test]
async fn a_reply_read_late_is_timed_from_its_capture() {
let (session, ctx) = ScanSession::new();
let (replies, rx) = tokio::sync::mpsc::channel(16);
let backlog = Duration::from_millis(100);
let retry = RETRY_POLICY.configured(RetryConfig {
max_attempts: std::num::NonZeroU8::new(1),
timeout_scale: crate::config::TimeoutScale::new(10.0),
..RetryConfig::default()
});
let transport =
ProbeTransport::from_parts(Box::new(AnsweringThroughABacklog { backlog, replies }), rx);
let mut scanner = RoutedScanner::build(
vec![RoutedTarget {
target: TARGET.into(),
source: LOCAL.into(),
}],
ctx,
None,
transport,
SweepProbe::syn(None),
Emission::routed(),
SegmentShaping::default(),
Vec::new(),
retry,
PROBE_RATE_PER_SEC,
);
scanner.discover_hosts().await.expect("the sweep runs");
let rtt = session
.hosts()
.get(IpAddr::from(TARGET))
.expect("the host answered")
.min_rtt()
.expect("and was timed");
assert!(
rtt < backlog / 2,
"an immediate answer read {backlog:?} late was timed at {rtt:?}"
);
}
}