mod ipv6;
mod probes;
use std::collections::{HashMap, HashSet};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use std::time::{Duration, Instant};
use crate::model::mac::MacAddr;
use crate::protocols::ethernet::Frame;
use async_trait::async_trait;
use tokio::sync::mpsc::UnboundedSender;
use tokio::time::Interval;
use crate::config::RetryConfig;
use crate::info;
use crate::journal::settle::{Outcome, Settled};
use crate::logging::error;
use crate::model::host::telemetry::RttSource;
use crate::model::host::{HostStatus, NetworkRole, StatusProtocol, StatusReason};
use crate::model::ip::scoped::Zone;
use crate::model::ip::set::IpSet;
use crate::protocols::{self as protocol, ethernet};
use crate::report::ScannerKind;
use crate::report::{Attachment, AttachmentSource, StopReason};
use crate::scanner::dispatcher::WalkOrder;
use crate::scanner::pacing::deadline::{AdaptiveDeadline, AdaptiveDeadlineConfig};
use crate::scanner::pacing::retry::{ProbeLedger, RetryPolicy};
use crate::scanner::pacing::timer::ScanBudget;
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::sweep::HostSweep;
use crate::scanner::strategy::{HostScanner, StrategyError};
use crate::system::interface::{self, Link};
use crate::transport::capture::CapturedFrame;
use crate::transport::channel::{self, EthernetHandle};
use crate::transport::frame::LinkType;
use crate::transport::neighbor;
use crate::scanner::strategy::frames::{self, DiscoveryProtocol, ProtocolMatch, Reading};
use ipv6::Ipv6Discovery;
fn sweep_filter() -> String {
let mut clauses: Vec<&'static str> = frames::sweep_protocols()
.iter()
.map(|protocol| protocol.capture_clause())
.collect();
clauses.extend(ABSORBED_CLAUSES);
clauses.sort_unstable();
clauses.dedup();
clauses.join(" or ")
}
const ABSORBED_CLAUSES: [&str; 3] = [
"(udp port 5353)",
"(ether proto 0x88cc)",
"(ether dst 01:00:0c:cc:cc:cc)",
];
type Ledger = ProbeLedger<IpAddr, ()>;
const RETRY_POLICY: RetryPolicy = RetryPolicy::new(
3,
Duration::from_secs(1),
Duration::from_millis(25),
Duration::from_secs(1),
2.0,
0.2,
None,
);
const MAX_DECLARING_MACS: usize = 64;
#[derive(Debug, thiserror::Error)]
pub(crate) enum FrameRejected {
#[error("unmapped RTT source: {0}")]
UnmappedRttSource(IpAddr),
#[error("packet originated from this host")]
SelfSourcedPacket,
#[error("{0} is not in the scanned range")]
AddressOutOfRange(IpAddr),
#[error("the frame came off a link that prepends no Ethernet header")]
UnreadableLink,
#[error("{0}")]
Malformed(#[from] crate::protocols::error::PacketError),
}
const DEADLINE_CONFIG: AdaptiveDeadlineConfig = AdaptiveDeadlineConfig::new(
ScanBudget::new(
Duration::from_millis(2_000),
Duration::from_millis(20),
Duration::from_secs(120),
),
ScanBudget::new(
Duration::from_millis(800),
Duration::from_millis(7),
Duration::from_millis(5_000),
),
Duration::from_millis(250),
Duration::from_millis(2_000),
4.0,
20,
);
const SEND_INTERVAL: Duration = Duration::from_micros(1000);
fn deadline_for(target_count: usize, retry: &RetryPolicy) -> AdaptiveDeadlineConfig {
let probe_lifetime = retry
.longest_probe_lifetime()
.max(ipv6::NDP_RETRY_POLICY.longest_probe_lifetime());
let attempts = retry.max_attempts.max(ipv6::NDP_RETRY_POLICY.max_attempts);
DEADLINE_CONFIG
.allowing_for(probe_lifetime)
.allowing_pace_of(SEND_INTERVAL * u32::from(attempts), target_count)
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Scope {
Sweep,
Targeted,
}
struct SourceIdentity {
mac: MacAddr,
ipv4: Option<Ipv4Addr>,
link_local_ipv6: Option<Ipv6Addr>,
zone: Zone,
}
impl SourceIdentity {
fn key_for(&self, addr: std::net::IpAddr) -> crate::model::ip::scoped::ScopedIp {
crate::model::ip::scoped::ScopedIp::scoped(addr, self.zone.clone())
}
fn resolve(link: &Link, ip_set: &IpSet) -> Result<Self, StrategyError> {
let mac = link.mac().ok_or_else(|| StrategyError::Interface {
interface: link.name().to_owned(),
reason: "it has no MAC address, and every probe here is an Ethernet frame",
})?;
let mut ipv4 = None;
for held in link.addresses() {
let IpAddr::V4(address) = held.address() else {
continue;
};
if ipv4.is_none() && !address.is_loopback() {
ipv4 = Some(address);
}
if ip_set
.v4()
.iter()
.any(|range| held.contains(&IpAddr::V4(range.start_addr())))
{
ipv4 = Some(address);
break;
}
}
let link_local_ipv6 = link
.ipv6()
.map(|(address, _)| address)
.find(Ipv6Addr::is_unicast_link_local);
Ok(Self {
mac,
ipv4,
link_local_ipv6,
zone: link.zone(),
})
}
}
struct ProbeCorrelation {
rtt: Option<(Duration, RttSource)>,
answered_attempt: Option<u8>,
}
enum Dispatched {
Sent,
Drained,
Nothing,
}
pub struct LocalScanner {
ctx: ScanContext,
ip_set: IpSet,
identity: SourceIdentity,
eth_handle: EthernetHandle,
deadline: AdaptiveDeadline,
protocols: Vec<Box<dyn DiscoveryProtocol>>,
sweep: HostSweep<()>,
dns_tx: Option<UnboundedSender<IpAddr>>,
mac_to_ip: HashMap<MacAddr, IpAddr>,
declared: HashMap<MacAddr, HashSet<NetworkRole>>,
scope: Scope,
send_failure: Option<String>,
ipv6: Ipv6Discovery,
prefixes: interface::OnLinkTable,
refuses: fn(IpAddr) -> bool,
}
#[async_trait]
impl HostScanner for LocalScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::Local
}
async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
crate::model::mac::load_vendors().await;
self.deadline.start();
let mut packet_iter = probes::eth_packet_iter(
&self.identity.mac,
&self.identity.ipv4,
&self.identity.link_local_ipv6,
&self.ip_set,
WalkOrder::of(&self.ip_set, &self.ctx).as_ref(),
);
if matches!(self.scope, Scope::Sweep) && self.identity.link_local_ipv6.is_some() {
self.ipv6.arm_solicitation(Instant::now());
self.ctx.record_sweep(self.identity.zone.clone());
}
self.solicit_routers();
self.ask_for_configuration();
let mut sending_finished = false;
let mut send_interval: Interval = tokio::time::interval(SEND_INTERVAL);
send_interval.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay);
let reason = loop {
let now = Instant::now();
self.read_waiting_frames();
self.sweep.service_retries(&self.ctx, now);
self.sweep
.service_second_ledger(&self.ctx, self.ipv6.ledger_mut(), now);
if let Some(reason) = self.stop_reason(now, sending_finished) {
break reason;
}
let sending = !sending_finished
|| !self.sweep.retries.is_empty()
|| self.ipv6.confirmations_pending()
|| self.ipv6.solicitation().is_due(now);
let idle_delay = self.tick_delay(now);
tokio::select! {
pkt = self.eth_handle.rx.recv() => {
match pkt {
Some(frame) => {
self.sweep.audit.record_segment();
_ = self.process_eth_packet(&frame, frame.received_at);
}
None => break StopReason::StreamClosed,
}
}
_ = send_interval.tick(), if sending => {
let now = Instant::now();
match self.send_next(&mut packet_iter, sending_finished, now) {
Dispatched::Drained => sending_finished = true,
Dispatched::Sent | Dispatched::Nothing => {}
}
}
_ = tokio::time::sleep(idle_delay), if !sending => {}
}
};
let unasked: Vec<IpAddr> = if sending_finished {
Vec::new()
} else {
packet_iter.map(|(_, ip)| ip).collect()
};
self.report_outcome(reason, &unasked);
Ok(())
}
}
impl LocalScanner {
pub fn new(
link: Link,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
retry: RetryConfig,
) -> Result<Self, StrategyError> {
let eth_handle: EthernetHandle = channel::start_capture(&link, &sweep_filter())?;
Self::build(
link,
ip_set,
ctx,
dns_tx,
scope,
eth_handle,
RETRY_POLICY.configured(retry),
)
}
pub fn with_handle(
link: Link,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
eth_handle: EthernetHandle,
) -> Result<Self, StrategyError> {
Self::build(link, ip_set, ctx, dns_tx, scope, eth_handle, RETRY_POLICY)
}
#[allow(clippy::too_many_arguments)]
fn build(
link: Link,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
eth_handle: EthernetHandle,
retry: RetryPolicy,
) -> Result<Self, StrategyError> {
let identity = SourceIdentity::resolve(&link, &ip_set)?;
let target_count = usize::try_from(ip_set.len()).unwrap_or(usize::MAX);
let deadline = AdaptiveDeadline::new(deadline_for(target_count, &retry), target_count);
Ok(Self {
ctx,
ip_set,
identity,
eth_handle,
deadline,
protocols: frames::sweep_protocols(),
sweep: HostSweep::new(Ledger::new(retry, target_count)),
dns_tx,
mac_to_ip: HashMap::new(),
declared: HashMap::new(),
scope,
ipv6: Ipv6Discovery::new(target_count),
send_failure: None,
prefixes: interface::OnLinkTable::from_links(std::slice::from_ref(&link)),
refuses: interface::refuses_neighbour,
})
}
fn read_waiting_frames(&mut self) {
let waiting = self.eth_handle.rx.len();
for _ in 0..waiting {
let Ok(frame) = self.eth_handle.rx.try_recv() else {
return;
};
self.sweep.audit.record_segment();
_ = self.process_eth_packet(&frame, frame.received_at);
}
}
fn stop_reason(&self, now: Instant, sending_finished: bool) -> Option<StopReason> {
if let Some(cause) = self.ctx.handle.stopped() {
return Some(cause.into());
}
if sending_finished && self.all_targets_responded() {
return Some(StopReason::AllResponded);
}
let spent = sending_finished && self.idle(now);
if self.deadline.hard_deadline_passed() {
return Some(if spent {
StopReason::AttemptsSpent
} else {
StopReason::DeadlineExpired
});
}
if spent && self.deadline.has_expired() {
return Some(StopReason::AttemptsSpent);
}
None
}
fn send_next(
&mut self,
packet_iter: &mut probes::PacketIter,
sending_finished: bool,
now: Instant,
) -> Dispatched {
if let Some(target) = self.next_live_retry() {
self.send_probe(target, now);
Dispatched::Sent
} else if let Some(target) = self.ipv6.next_confirmation() {
self.send_confirmation(target, now);
Dispatched::Sent
} else if self.ipv6.solicitation().is_due(now) {
self.send_solicitation(now);
Dispatched::Sent
} else if !sending_finished {
match packet_iter.next() {
Some((packet, ip)) => {
if self.emit(&packet, "first attempt") {
self.record_probe(ip, Instant::now());
}
Dispatched::Sent
}
None => Dispatched::Drained,
}
} else {
Dispatched::Nothing
}
}
fn report_outcome(&mut self, reason: StopReason, unasked: &[IpAddr]) {
let interrupted = self.sweep.ledger.drain_unresolved();
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(
ScannerKind::Local,
format!(
"{} of {} addresses on {} were never asked: {reason} with them \
still queued",
unasked.len(),
self.ip_set.len(),
self.identity.zone,
),
);
}
if self.ipv6.unanswered_confirmations() > 0 {
info!(
verbosity = 2,
"{} of the addresses asked about directly never answered",
self.ipv6.unanswered_confirmations()
);
}
if self.sweep.audit.sends_failed > 0 {
self.ctx.record_failure(
ScannerKind::Local,
format!(
"{} of {} frames never reached {}, so those addresses are \
reported absent without having been asked: {}",
self.sweep.audit.sends_failed,
self.sweep.audit.sends_attempted,
self.identity.zone,
self.send_failure.as_deref().unwrap_or("cause unrecorded"),
),
);
}
let capture = self.eth_handle.capture_counts();
let targets = self.ip_set.len();
self.sweep.report(
&self.ctx,
"local-discovery",
ScannerKind::Local,
targets,
reason,
capture,
);
}
fn emit(&mut self, packet: &[u8], what: &str) -> bool {
match self.eth_handle.tx.send_frame(packet) {
Ok(()) => {
self.sweep.audit.record_send(true);
true
}
Err(reason) => {
self.sweep.audit.record_send(false);
self.send_failure
.get_or_insert_with(|| format!("{what}: {reason}"));
false
}
}
}
fn record_probe(&mut self, ip: IpAddr, now: Instant) {
if ip.is_ipv6() {
self.ipv6.record_asked(ip, now);
} else {
self.sweep.ledger.arm(ip, ip, (), (), now);
}
}
fn confirm(&mut self, address: IpAddr) {
if !address.is_ipv6()
|| !matches!(self.scope, Scope::Sweep)
|| self.identity.link_local_ipv6.is_none()
{
return;
}
if !self.ctx.may_probe(&address) {
info!(
verbosity = 2,
"{address} was overheard and is excluded, so it is not asked about"
);
return;
}
let on_a_prefix = self.prefixes.source_for(address).is_some();
if on_a_prefix && (self.refuses)(address) {
info!(
verbosity = 2,
"{address} was overheard and a route refuses it, so it is not asked about"
);
return;
}
self.ipv6.note_overheard(address);
}
fn send_confirmation(&mut self, target: IpAddr, now: Instant) {
let (IpAddr::V6(target_v6), Some(source_v6)) = (target, self.identity.link_local_ipv6)
else {
return;
};
let packet =
protocol::ndp::build_neighbor_solicitation(self.identity.mac, source_v6, target_v6);
self.emit(&packet, "confirming solicitation");
self.ipv6.record_confirmation_sent(target, now);
info!(
verbosity = 2,
"asked {target} directly, having only overheard it"
);
}
fn solicit_routers(&mut self) {
let Some(link_local) = self.identity.link_local_ipv6 else {
return;
};
let packet = protocol::ndp::build_router_solicitation(self.identity.mac, link_local);
self.emit(&packet, "router solicitation");
}
fn ask_for_configuration(&mut self) {
let Some(source) = self.identity.ipv4 else {
return;
};
let packet = protocol::dhcp::build_inform(self.identity.mac, source);
self.emit(&packet, "dhcp inform");
}
fn send_solicitation(&mut self, now: Instant) {
let Some(link_local) = self.identity.link_local_ipv6 else {
return;
};
let packet = protocol::icmp::build_all_nodes_echo_request_v6(
self.identity.mac,
link_local,
self.ipv6.solicitation().identifier,
self.ipv6.solicitation().next_sequence(),
);
self.emit(&packet, "all-nodes solicitation");
self.ipv6.record_solicitation_sent(now);
}
fn next_live_retry(&mut self) -> Option<IpAddr> {
while let Some(target) = self.sweep.retries.pop_front() {
let outstanding = if target.is_ipv6() {
self.ipv6.ledger_mut().contains(&target)
} else {
self.sweep.ledger.contains(&target)
};
if outstanding {
return Some(target);
}
}
None
}
fn send_probe(&mut self, target: IpAddr, now: Instant) {
let packet = match target {
IpAddr::V4(target_v4) => self
.identity
.ipv4
.map(|source| protocol::arp::build_request(self.identity.mac, source, target_v4)),
IpAddr::V6(target_v6) => self.identity.link_local_ipv6.map(|source| {
protocol::ndp::build_neighbor_solicitation(self.identity.mac, source, target_v6)
}),
};
let left = packet.is_some_and(|packet| self.emit(&packet, "probe"));
let ledger = if target.is_ipv6() {
self.ipv6.ledger_mut()
} else {
&mut self.sweep.ledger
};
if left {
ledger.rearm(target, target, (), now);
} else {
ledger.resume(&target, now);
}
}
fn absorb_announcement(
&mut self,
frame: &Frame<'_>,
source_mac: MacAddr,
captured: &CapturedFrame,
) -> bool {
let mut attachment = Attachment::new(
captured.zone.clone(),
AttachmentSource::Lldp,
captured.observed_at,
);
let mut roles: Vec<NetworkRole> = Vec::new();
if let Some(advertisement) = protocol::lldp::parse(frame) {
attachment = attachment.with_device_mac(source_mac);
if let Some(name) = advertisement.system_name {
attachment = attachment.with_device_name(name);
}
if let Some(protocol::lldp::Identifier::Text(port)) = advertisement.port_id {
attachment = attachment.with_port(port);
}
if let Some(vlan) = advertisement.port_vlan {
attachment = attachment.with_native_vlan(vlan);
}
if let Some(address) = advertisement.management_address {
attachment = attachment.with_management_address(address);
}
if let Some(capabilities) = advertisement.capabilities {
if capabilities.is_bridge() {
roles.push(NetworkRole::Switch);
}
if capabilities.is_router() {
roles.push(NetworkRole::Router);
}
}
} else if let Some(announcement) = protocol::cdp::parse(frame) {
attachment = Attachment::new(
captured.zone.clone(),
AttachmentSource::Cdp,
captured.observed_at,
)
.with_device_mac(source_mac);
if let Some(name) = announcement.device_id {
attachment = attachment.with_device_name(name);
}
if let Some(port) = announcement.port_id {
attachment = attachment.with_port(port);
}
if let Some(vlan) = announcement.native_vlan {
attachment = attachment.with_native_vlan(vlan);
}
if let Some(address) = announcement.address {
attachment = attachment.with_management_address(address);
}
if let Some(capabilities) = announcement.capabilities {
if capabilities.is_switch() {
roles.push(NetworkRole::Switch);
}
if capabilities.is_router() {
roles.push(NetworkRole::Router);
}
}
} else {
return false;
}
info!(
verbosity = 1,
"{} says this machine is on {}{}",
self.identity.zone,
attachment.device_name().unwrap_or("an unnamed device"),
match attachment.port() {
Some(port) => format!(" port {port}"),
None => String::new(),
},
);
self.ctx.record_attachment(attachment);
for role in roles {
self.note_declaration(source_mac, role);
}
true
}
fn absorb_mdns(&mut self, frame: &Frame<'_>) -> bool {
let Some(payload) = protocol::ip::udp_payload(frame, protocol::mdns::PORT) else {
return false;
};
if self.deadline.has_expired() {
return true;
}
let Ok(hosts) = protocol::mdns::extract_hosts(payload) else {
return true;
};
for host in hosts {
for ip in host.ips {
if ip.is_ipv6() && !self.ipv6.is_solicited(&ip) {
info!(
verbosity = 2,
"mDNS named {ip} as {}, which nothing has answered for", host.hostname
);
self.confirm(ip);
}
}
}
true
}
fn resolve_probe(
&mut self,
address: &IpAddr,
now: Instant,
) -> Option<crate::scanner::pacing::retry::Resolution> {
if address.is_ipv6() {
self.ipv6.resolve(address, now)
} else {
self.sweep.ledger.resolve(address, None, now)
}
}
fn answers_our_request(&self, frame: &Frame<'_>) -> bool {
frame.destination() == self.identity.mac
&& pnet_packet::arp::ArpPacket::new(frame.payload())
.is_some_and(|arp| arp.get_operation() == pnet_packet::arp::ArpOperations::Reply)
}
fn idle(&self, now: Instant) -> bool {
self.sweep.retries.is_empty() && self.sweep.ledger.is_empty() && self.ipv6.is_idle(now)
}
fn tick_delay(&self, now: Instant) -> Duration {
let mut delay = self.deadline.time_until_next_tick();
for wakeup in [self.sweep.ledger.next_due(), self.ipv6.next_wakeup()]
.into_iter()
.flatten()
{
delay = delay.min(wakeup.saturating_duration_since(now));
}
delay
}
fn process_eth_packet(
&mut self,
frame: &CapturedFrame,
now: Instant,
) -> Result<(), FrameRejected> {
if frame.link != LinkType::Ethernet {
self.sweep.audit.record_off_target();
return Err(FrameRejected::UnreadableLink);
}
let eth_frame: Frame<'_> = ethernet::parse(&frame.bytes)?;
let source_mac = eth_frame.source();
if source_mac == self.identity.mac {
self.sweep.audit.record_off_target();
return Err(FrameRejected::SelfSourcedPacket);
}
if self.absorb_announcement(ð_frame, source_mac, frame) {
return Ok(());
}
let source_addr: IpAddr = protocol::source_address(ð_frame)?;
if self.absorb_mdns(ð_frame) {
return Ok(());
}
let Some((reading, protocol)) = self.interpret_response(ð_frame) else {
self.sweep.audit.record_off_target();
return Ok(());
};
let subject = match reading.matched {
ProtocolMatch::Solicited(Some(claimed)) => claimed,
_ => source_addr,
};
let out_of_range = match self.scope {
Scope::Targeted => !self.ip_set.contains(&subject),
Scope::Sweep => subject.is_ipv4() && !self.ip_set.contains(&subject),
};
if out_of_range {
if let Some(role) = reading.declared
&& self.note_declaration(source_mac, role)
{
return Ok(());
}
self.sweep.audit.record_off_target();
return Err(FrameRejected::AddressOutOfRange(subject));
}
if protocol == StatusProtocol::Arp && subject.is_ipv4() {
neighbor::learn_neighbor(self.identity.zone.name(), subject, source_mac);
}
if subject != source_addr {
info!(
verbosity = 2,
"{subject} answered from {source_addr}, which is another of its addresses"
);
}
let mut answered_attempt = None;
let matched = match reading.matched {
ProtocolMatch::Solicited(_)
if protocol == StatusProtocol::Arp && !self.answers_our_request(ð_frame) =>
{
ProtocolMatch::Unsolicited
}
matched => matched,
};
let rtt = match matched {
ProtocolMatch::Unhandled => return Ok(()),
ProtocolMatch::Solicited(_) => {
let correlated = self.correlate_rtt(subject, &protocol, now);
answered_attempt = correlated.answered_attempt;
correlated.rtt
}
ProtocolMatch::Unsolicited => {
self.confirm(subject);
None
}
ProtocolMatch::AllNodes {
identifier,
sequence,
} => self.match_solicitation(subject, identifier, sequence, now)?,
};
if self.ip_set.contains(&subject) {
self.sweep.responded.insert(subject);
}
self.record_response(
source_mac,
subject,
rtt,
protocol.clone(),
answered_attempt,
reading.declared,
);
if subject != source_addr {
self.record_response(source_mac, source_addr, None, protocol, None, None);
}
Ok(())
}
fn correlate_rtt(
&mut self,
subject: IpAddr,
protocol: &StatusProtocol,
now: Instant,
) -> ProbeCorrelation {
match self.resolve_probe(&subject, now) {
Some(resolution) => {
if resolution.rtt.is_none() {
info!(
verbosity = 2,
"{subject} answered over {protocol:?} after {} attempts, so it is not timed{}",
resolution.attempts,
self.ipv6.since_first_asked(&subject, now)
);
}
ProbeCorrelation {
rtt: resolution.rtt.map(|rtt| (rtt, RttSource::Direct)),
answered_attempt: resolution.answered_attempt,
}
}
None => {
let rtt = match self.ipv6.take_confirmation_rtt(&subject, now) {
Some(rtt) => Some((rtt, RttSource::Direct)),
None => {
info!(
verbosity = 2,
"{subject} answered over {protocol:?} with no probe of ours outstanding{}",
self.ipv6.since_first_asked(&subject, now)
);
self.confirm(subject);
None
}
};
ProbeCorrelation {
rtt,
answered_attempt: None,
}
}
}
}
fn match_solicitation(
&self,
subject: IpAddr,
identifier: u16,
sequence: u16,
now: Instant,
) -> Result<Option<(Duration, RttSource)>, FrameRejected> {
if self.ipv6.solicitation().nothing_sent() {
return Err(FrameRejected::UnmappedRttSource(subject));
}
let rtt = match self.ipv6.solicitation().sent_at(identifier, sequence) {
Some(sent_at) => Some((
now.saturating_duration_since(sent_at),
RttSource::SegmentWide,
)),
None => {
info!(
verbosity = 2,
"{subject} answered an echo request that was not ours, so it is not timed"
);
None
}
};
Ok(rtt)
}
fn all_targets_responded(&self) -> bool {
matches!(self.scope, Scope::Targeted) && self.sweep.all_responded(self.ip_set.len())
}
fn interpret_response(&mut self, frame: &Frame<'_>) -> Option<(Reading, StatusProtocol)> {
for protocol in &self.protocols {
match protocol.interpret(frame) {
Ok(Reading {
matched: ProtocolMatch::Unhandled,
..
}) => continue,
Ok(reading) => return Some((reading, protocol.status_protocol())),
Err(e) => {
error!(verbosity = 3, "failed to interpret discovery response: {e}");
return None;
}
}
}
None
}
fn note_declaration(&mut self, source_mac: MacAddr, role: NetworkRole) -> bool {
if let Some(ip) = self.mac_to_ip.get(&source_mac).copied() {
self.ctx.write_host(self.identity.key_for(ip), |host| {
host.add_network_role(role);
true
});
return true;
}
if self.declared.len() >= MAX_DECLARING_MACS && !self.declared.contains_key(&source_mac) {
return false;
}
self.declared.entry(source_mac).or_default().insert(role);
true
}
fn record_response(
&mut self,
source_mac: MacAddr,
source_addr: IpAddr,
rtt: Option<(Duration, RttSource)>,
protocol: StatusProtocol,
answered_attempt: Option<u8>,
declared: Option<NetworkRole>,
) {
let first_sighting = !self.mac_to_ip.contains_key(&source_mac);
let primary_ip = *self.mac_to_ip.entry(source_mac).or_insert(source_addr);
let held = self.declared.remove(&source_mac);
let mut is_new_ip = false;
let zone = self.identity.zone.clone();
let is_new_host = self
.ctx
.write_host(self.identity.key_for(primary_ip), |host| {
host.set_zone(zone.clone());
host.record_mac(source_mac);
let was_up = host.status().is_up();
host.record_evidence(HostStatus::Up, StatusReason::basic(protocol.clone()));
let mut changed = rtt.is_some() || !was_up;
for role in held.into_iter().flatten() {
changed |= host.add_network_role(role);
}
if let Some(role) = declared {
changed |= host.add_network_role(role);
}
match rtt {
Some((rtt, RttSource::Direct)) => {
host.add_rtt_from(rtt, protocol.clone());
}
Some((rtt, RttSource::SegmentWide)) => {
host.add_segment_wide_rtt_from(rtt, protocol.clone());
}
Some((rtt, RttSource::FirstToNeighbour)) => {
host.add_first_to_neighbour_rtt_from(rtt, protocol.clone());
}
None => {}
}
is_new_ip = !host.ips().contains(&source_addr);
changed |= host.consider_primary_ip(source_addr) || is_new_ip;
changed
});
self.ctx.settle_address(source_addr, Settled::Answered);
if is_new_host {
self.deadline.mark_activity();
}
if first_sighting {
self.sweep.audit.record_host_found(answered_attempt);
}
if rtt.is_none() {
self.sweep.audit.record_reply_without_rtt();
}
if let Some((rtt, source)) = rtt {
let asked = match source {
RttSource::Direct => "",
RttSource::SegmentWide => " to the all-nodes echo",
RttSource::FirstToNeighbour => " before it was resolved",
};
info!(
incoming,
verbosity = 2,
"{source_addr} responded in {}ms{asked}",
rtt.as_millis()
);
self.deadline.record_rtt(rtt);
}
if (is_new_host || is_new_ip)
&& let Some(tx) = &self.dns_tx
{
let _ = tx.send(source_addr);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::mac::MacAddr;
use crate::scanner::strategy::frames::tests::{
LOCAL_MAC, PEER_MAC, advertisement_body, arp_reply_frame, arp_request_frame,
dhcp_reply_frame, echo_reply_frame, mdns_frame, ndp_frame,
};
use std::net::{Ipv4Addr, Ipv6Addr};
#[test]
fn a_segment_sweep_outlasts_the_time_its_ticker_needs_to_send_every_attempt() {
const SLASH_16: usize = 1 << 16;
let thorough = RetryConfig {
effort: crate::config::ScanEffort::Thorough,
..RetryConfig::default()
};
for (case, retry, attempts) in [
("by default", RetryConfig::default(), 3),
("at thorough", thorough, 5),
] {
let needed = SEND_INTERVAL * (SLASH_16 as u32) * attempts;
let given = deadline_for(SLASH_16, &RETRY_POLICY.configured(retry))
.max_budget
.for_target_count(SLASH_16);
assert!(
given >= needed,
"a /16 {case}: needs {needed:?} to send every attempt and is given {given:?}"
);
}
}
#[test]
fn a_segment_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 arp = RETRY_POLICY.configured(retry);
let needed = arp
.longest_probe_lifetime()
.max(ipv6::NDP_RETRY_POLICY.longest_probe_lifetime());
let given = deadline_for(1, &arp).max_budget.for_target_count(1);
assert!(
given >= needed,
"one address {case}: its schedule at the ceiling takes {needed:?} \
and the sweep is given {given:?}"
);
}
}
struct StalledAfterAnswering {
stall: Duration,
frames: tokio::sync::mpsc::Sender<CapturedFrame>,
first: Option<Ipv4Addr>,
answered: bool,
}
impl crate::transport::capture::FrameSink for StalledAfterAnswering {
fn send_frame(&mut self, frame: &[u8]) -> Result<(), String> {
let asked = ethernet::parse(frame)
.ok()
.filter(|frame| frame.ethertype() == pnet_packet::ethernet::EtherTypes::Arp.0)
.and_then(|frame| pnet_packet::arp::ArpPacket::owned(frame.payload().to_vec()))
.map(|request| request.get_target_proto_addr());
let Some(target) = asked.filter(|_| !self.answered) else {
return Ok(());
};
let Some(first) = self.first else {
self.first = Some(target);
return Ok(());
};
self.answered = true;
self.frames
.try_send(CapturedFrame {
zone: Zone::new(7, "sim0"),
link: LinkType::Ethernet,
bytes: arp_reply_frame(first),
observed_at: std::time::SystemTime::now(),
received_at: Instant::now(),
})
.expect("room for the answer");
std::thread::sleep(self.stall);
Ok(())
}
}
#[tokio::test(flavor = "current_thread")]
async fn an_answer_waiting_when_its_probe_runs_out_still_times_the_host() {
use crate::system::interface::LinkAddress;
let target = Ipv4Addr::new(192, 0, 2, 10);
let silent = Ipv4Addr::new(192, 0, 2, 11);
let (session, ctx) = crate::scanner::session::ScanSession::builder()
.ordering(None)
.build();
let retry = RETRY_POLICY.configured(RetryConfig {
max_attempts: std::num::NonZeroU8::new(1),
..RetryConfig::default()
});
let (frames, rx) = tokio::sync::mpsc::channel(16);
let stall = retry.initial_rto.mul_f64(1.0 + retry.jitter) + Duration::from_millis(200);
let handle = EthernetHandle::from_parts(
Box::new(StalledAfterAnswering {
stall,
frames,
first: None,
answered: false,
}),
rx,
);
let link = Link::new("sim0", 7)
.with_mac(LOCAL_MAC)
.with_addresses(vec![LinkAddress::new(
IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)),
24,
)]);
let mut targets = IpSet::new();
targets.insert(IpAddr::V4(target));
targets.insert(IpAddr::V4(silent));
let mut scanner =
LocalScanner::build(link, targets, ctx, None, Scope::Targeted, handle, retry)
.expect("a scanner over the simulated segment");
scanner.discover_hosts().await.expect("the sweep runs");
let host = session
.hosts()
.get(IpAddr::V4(target))
.expect("the host answered and is not on record");
assert!(
host.min_rtt().is_some(),
"the answer was read after its probe was written off"
);
}
struct AsksBeforeAnswering {
delay: Duration,
frames: tokio::sync::mpsc::Sender<CapturedFrame>,
answered: bool,
}
impl AsksBeforeAnswering {
fn captured(bytes: Vec<u8>, received_at: Instant) -> CapturedFrame {
CapturedFrame {
zone: Zone::new(7, "sim0"),
link: LinkType::Ethernet,
bytes,
observed_at: std::time::SystemTime::now(),
received_at,
}
}
}
impl crate::transport::capture::FrameSink for AsksBeforeAnswering {
fn send_frame(&mut self, frame: &[u8]) -> Result<(), String> {
let asked = ethernet::parse(frame)
.ok()
.filter(|frame| frame.ethertype() == pnet_packet::ethernet::EtherTypes::Arp.0)
.and_then(|frame| pnet_packet::arp::ArpPacket::owned(frame.payload().to_vec()))
.map(|request| request.get_target_proto_addr());
let Some(target) = asked.filter(|_| !self.answered) else {
return Ok(());
};
self.answered = true;
self.frames
.try_send(Self::captured(arp_request_frame(target), Instant::now()))
.expect("room for the neighbour's own request");
let frames = self.frames.clone();
let arrives = Instant::now() + self.delay;
tokio::spawn(async move {
tokio::time::sleep_until(arrives.into()).await;
let _ = frames
.send(Self::captured(arp_reply_frame(target), arrives))
.await;
});
Ok(())
}
}
#[tokio::test(flavor = "current_thread")]
async fn a_neighbours_own_request_does_not_answer_the_sweeps() {
use crate::system::interface::LinkAddress;
let target = Ipv4Addr::new(198, 51, 100, 2);
let delay = Duration::from_millis(80);
let (session, ctx) = crate::scanner::session::ScanSession::new();
let (frames, rx) = tokio::sync::mpsc::channel(16);
let handle = EthernetHandle::from_parts(
Box::new(AsksBeforeAnswering {
delay,
frames,
answered: false,
}),
rx,
);
let link = Link::new("sim0", 7)
.with_mac(LOCAL_MAC)
.with_addresses(vec![LinkAddress::new(
IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1)),
24,
)]);
let mut targets = IpSet::new();
targets.insert(IpAddr::V4(target));
let mut scanner = LocalScanner::build(
link,
targets,
ctx,
None,
Scope::Targeted,
handle,
RETRY_POLICY,
)
.expect("a scanner over the simulated segment");
scanner.discover_hosts().await.expect("the sweep runs");
let host = session
.hosts()
.get(IpAddr::V4(target))
.expect("the neighbour answered and is not on record");
assert!(
host.min_rtt().is_none_or(|rtt| rtt >= delay),
"a neighbour answering in {delay:?} was timed at {:?}",
host.min_rtt()
);
}
fn refuses_as_linux_does(address: IpAddr) -> bool {
crate::model::ip::scoped::ScopedIp::needs_zone(&address)
}
fn refuses_everything(_: IpAddr) -> bool {
true
}
fn overhearing_scanner() -> LocalScanner {
use crate::system::interface::LinkAddress;
let (_session, ctx) = crate::scanner::session::ScanSession::new();
let (_frames, rx) = tokio::sync::mpsc::channel(16);
let asked = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let handle = EthernetHandle::from_parts(Box::new(Asked(asked)), rx);
let link = Link::new("sim0", 7)
.with_mac(LOCAL_MAC)
.with_addresses(vec![
LinkAddress::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)), 24),
LinkAddress::new("fe80::1".parse().expect("an address"), 64),
LinkAddress::new("2001:db8::1".parse().expect("an address"), 64),
]);
let targets: IpSet = "192.0.2.0/30".parse().expect("a prefix");
LocalScanner::build(link, targets, ctx, None, Scope::Sweep, handle, RETRY_POLICY)
.expect("a scanner over the simulated segment")
}
#[tokio::test(flavor = "current_thread")]
async fn an_overheard_link_local_address_is_asked_whatever_the_table_says_without_a_zone() {
let link_local: IpAddr = "fe80::2".parse().expect("an address");
let on_link: IpAddr = "2001:db8::2".parse().expect("an address");
let mut scanner = overhearing_scanner();
scanner.refuses = refuses_as_linux_does;
scanner.confirm(link_local);
assert_eq!(
scanner.ipv6.next_confirmation(),
Some(link_local),
"an overheard link-local neighbour was read as refused by a route"
);
scanner.refuses = refuses_everything;
scanner.confirm(on_link);
assert_eq!(
scanner.ipv6.next_confirmation(),
None,
"an address the table refuses was asked about"
);
}
#[tokio::test(flavor = "current_thread")]
async fn an_overheard_address_off_the_links_prefixes_is_asked_whatever_the_table_says() {
let elsewhere: IpAddr = "2001:db8:1::2".parse().expect("an address");
let mut scanner = overhearing_scanner();
scanner.refuses = refuses_everything;
scanner.confirm(elsewhere);
assert_eq!(
scanner.ipv6.next_confirmation(),
Some(elsewhere),
"an address off the link's prefixes was read as refused by a route"
);
}
struct Asked(std::sync::Arc<std::sync::Mutex<Vec<IpAddr>>>);
impl crate::transport::capture::FrameSink for Asked {
fn send_frame(&mut self, frame: &[u8]) -> Result<(), String> {
let asked = ethernet::parse(frame)
.ok()
.filter(|frame| frame.ethertype() == pnet_packet::ethernet::EtherTypes::Arp.0)
.and_then(|frame| pnet_packet::arp::ArpPacket::owned(frame.payload().to_vec()))
.map(|request| request.get_target_proto_addr());
if let Some(target) = asked {
self.0.lock().expect("the log").push(IpAddr::V4(target));
}
Ok(())
}
}
#[tokio::test(flavor = "current_thread")]
async fn a_seeded_sweep_asks_in_the_order_the_seed_names() {
use crate::model::ip::set::Positions;
use crate::system::interface::LinkAddress;
const SEED: u64 = 0x5EED;
let targets: IpSet = "192.0.2.64/27".parse().expect("a prefix");
let (_session, ctx) = crate::scanner::session::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 asked = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
let (_frames, rx) = tokio::sync::mpsc::channel(16);
let handle = EthernetHandle::from_parts(Box::new(Asked(std::sync::Arc::clone(&asked))), rx);
let link = Link::new("sim0", 7)
.with_mac(LOCAL_MAC)
.with_addresses(vec![LinkAddress::new(
IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)),
24,
)]);
let retry = RETRY_POLICY.configured(RetryConfig {
max_attempts: std::num::NonZeroU8::new(1),
..RetryConfig::default()
});
let mut scanner =
LocalScanner::build(link, targets, ctx, None, Scope::Targeted, handle, retry)
.expect("a scanner over the simulated segment");
scanner.discover_hosts().await.expect("the sweep runs");
assert_eq!(*asked.lock().expect("the log"), expected);
}
#[test]
fn the_sweep_filter_admits_every_frame_the_sweep_can_read() {
let filter = super::sweep_filter();
let program = pcap::Capture::dead(pcap::Linktype::ETHERNET)
.expect("a dead capture")
.compile(&filter, true)
.unwrap_or_else(|e| panic!("the sweep filter `{filter}` does not compile: {e}"));
let lldp = ethernet::build_header(
PEER_MAC,
MacAddr::new(0x01, 0x80, 0xC2, 0x00, 0x00, 0x0E),
crate::protocols::lldp::ETHERTYPE,
);
let cdp = {
let group = crate::protocols::cdp::GROUP_ADDRESS;
let mut bytes = group.octets().to_vec();
bytes.extend_from_slice(&PEER_MAC.octets());
bytes.extend_from_slice(&[0x00, 0x20]);
bytes.resize(60, 0);
bytes
};
let readable: [(&str, Vec<u8>); 7] = [
(
"an ARP frame",
arp_reply_frame(Ipv4Addr::new(198, 51, 100, 2)),
),
(
"a neighbour advertisement",
ndp_frame(&advertisement_body(
Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 2),
0,
)),
),
(
"an echo reply",
echo_reply_frame(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 1)),
),
(
"a DHCP server reply",
dhcp_reply_frame(Ipv4Addr::new(192, 0, 2, 1), None),
),
("an mDNS response", mdns_frame()),
("an LLDP advertisement", lldp),
("a CDP announcement", cdp),
];
for (what, frame) in readable {
assert!(
program.filter(&frame),
"the sweep filter rejects {what}, so the sweep would never see one: {filter}"
);
}
}
#[test]
fn a_link_without_ethernet_refuses_the_sweep_filter_whole() {
const RAW: i32 = 12;
let filter = super::sweep_filter();
let tunnel = pcap::Capture::dead(pcap::Linktype(RAW)).expect("a dead capture");
assert!(
tunnel.compile(&filter, true).is_err(),
"a tunnel took the sweep filter: {filter}"
);
}
#[test]
fn the_sweep_filter_rejects_traffic_no_reader_asked_for() {
let filter = super::sweep_filter();
let program = pcap::Capture::dead(pcap::Linktype::ETHERNET)
.expect("a dead capture")
.compile(&filter, true)
.expect("the sweep filter compiles");
let ordinary_tcp = {
let datagram = crate::protocols::craft::Packet::new()
.push(crate::protocols::craft::Ipv4::new(
Ipv4Addr::new(192, 0, 2, 50),
Ipv4Addr::new(192, 0, 2, 60),
))
.push(crate::protocols::craft::Udp::new(4444, 8080).with_payload(vec![0u8; 16]))
.build()
.expect("a test datagram");
[
ethernet::build_header(
PEER_MAC,
LOCAL_MAC,
pnet_packet::ethernet::EtherTypes::Ipv4.0,
),
datagram,
]
.concat()
};
assert!(
!program.filter(&ordinary_tcp),
"the sweep filter admits traffic between two other hosts on ports \
nothing here reads, which is the copying it exists to avoid: {filter}"
);
}
}