mod discovery;
mod ipv6;
mod probes;
use std::collections::{HashMap, HashSet, VecDeque};
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use std::time::{Duration, Instant};
use async_trait::async_trait;
use pnet::datalink::{MacAddr, NetworkInterface};
use pnet::packet::ethernet::EthernetPacket;
use tokio::sync::mpsc::UnboundedSender;
use tokio::time::Interval;
use crate::config::RetryConfig;
use crate::journal::settle::{Outcome, Settled};
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::scanner::audit::ProbeAudit;
use crate::scanner::pacing::deadline::{AdaptiveDeadline, AdaptiveDeadlineConfig};
use crate::scanner::pacing::retry::{Due, ProbeLedger, RetryPolicy};
use crate::scanner::pacing::timer::ScanBudget;
use crate::scanner::report::StopReason;
use crate::scanner::session::{ScanContext, ScannerKind};
use crate::scanner::strategy::{HostScanner, StrategyError};
use crate::system::interface::NetworkInterfaceExtension;
use crate::transport::channel::{self, EthernetHandle};
use crate::transport::mac::IntoCoreMac;
use crate::{error, info};
use discovery::{
ArpProtocol, DhcpProtocol, DiscoveryProtocol, Icmpv6EchoProtocol, NdpProtocol, ProtocolMatch,
Reading, RouterAdvertProtocol,
};
use ipv6::Ipv6Discovery;
type Ledger = ProbeLedger<IpAddr, ()>;
const RETRY_POLICY: RetryPolicy = RetryPolicy::new(
3,
Duration::from_millis(150),
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),
}
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);
#[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 resolve(intf: &NetworkInterface, ip_set: &IpSet) -> Result<Self, StrategyError> {
let mac = intf.mac.ok_or_else(|| StrategyError::Interface {
interface: intf.name.clone(),
reason: "it has no MAC address, and every probe here is an Ethernet frame",
})?;
let mut ipv4 = None;
for net in intf.get_ipv4_nets() {
if ipv4.is_none() && !net.ip().is_loopback() {
ipv4 = Some(net.ip());
}
if ip_set
.v4()
.iter()
.any(|range| net.contains(range.start_addr()))
{
ipv4 = Some(net.ip());
break;
}
}
let link_local_ipv6 = intf
.get_ipv6_nets()
.into_iter()
.find(|net| net.ip().is_unicast_link_local())
.map(|net| net.ip());
Ok(Self {
mac,
ipv4,
link_local_ipv6,
zone: Zone::new(intf.index, intf.name.clone()),
})
}
}
pub struct LocalScanner {
ctx: ScanContext,
ip_set: IpSet,
identity: SourceIdentity,
eth_handle: EthernetHandle,
deadline: AdaptiveDeadline,
protocols: Vec<Box<dyn DiscoveryProtocol>>,
ledger: Ledger,
due: Vec<Due<IpAddr>>,
retries: VecDeque<IpAddr>,
dns_tx: Option<UnboundedSender<IpAddr>>,
mac_to_ip: HashMap<MacAddr, IpAddr>,
declared: HashMap<MacAddr, HashSet<NetworkRole>>,
scope: Scope,
responded: HashSet<IpAddr>,
audit: ProbeAudit,
send_failure: Option<String>,
ipv6: Ipv6Discovery,
}
#[async_trait]
impl HostScanner for LocalScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::Local
}
async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
let mut packet_iter = probes::eth_packet_iter(
&self.identity.mac,
&self.identity.ipv4,
&self.identity.link_local_ipv6,
&self.ip_set,
);
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 dispatched: u128 = 0;
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.service_retries(now);
if self.ctx.handle.should_stop() {
break StopReason::Aborted;
}
if self.deadline.hard_deadline_passed() {
break StopReason::DeadlineExpired;
}
if sending_finished && self.all_targets_responded() {
break StopReason::AllResponded;
}
if sending_finished && self.idle(now) && self.deadline.has_expired() {
break StopReason::DeadlineExpired;
}
let sending = !sending_finished
|| !self.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(bytes) => {
self.audit.record_segment();
_ = self.process_eth_packet(&bytes, Instant::now());
}
None => break StopReason::StreamClosed,
}
}
_ = send_interval.tick(), if sending => {
let now = Instant::now();
if let Some(target) = self.retries.pop_front() {
self.send_probe(target, now);
} else if let Some(target) = self.ipv6.next_confirmation() {
self.send_confirmation(target, now);
} else if self.ipv6.solicitation().is_due(now) {
self.send_solicitation(now);
} else if !sending_finished {
match packet_iter.next() {
Some((packet, ip)) => {
if self.emit(&packet, "first attempt") {
self.record_probe(ip, Instant::now());
}
dispatched += 1;
},
None => {
sending_finished = true;
},
}
}
}
_ = tokio::time::sleep(idle_delay), if !sending => {}
}
};
let outstanding = self.ledger.drain_unresolved().len() as u64;
self.ctx.record_many(Outcome::Interrupted, outstanding);
self.ctx.record_many(
Outcome::Unasked,
u64::try_from(self.ip_set.len().saturating_sub(dispatched)).unwrap_or(u64::MAX),
);
if self.ipv6.unanswered_confirmations() > 0 {
info!(
verbosity = 2,
"{} of the addresses asked about directly never answered",
self.ipv6.unanswered_confirmations()
);
}
if self.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.audit.sends_failed,
self.audit.sends_attempted,
self.identity.zone,
self.send_failure.as_deref().unwrap_or("cause unrecorded"),
),
);
}
let targets = self.ip_set.len();
self.audit
.report("local-discovery", targets, reason, None, None);
self.ctx.record_probe_stats(self.audit.stats(
ScannerKind::Local,
targets,
reason,
None,
None,
));
Ok(())
}
}
impl LocalScanner {
pub fn new(
intf: NetworkInterface,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
retry: RetryConfig,
) -> Result<Self, StrategyError> {
let eth_handle: EthernetHandle = channel::start_capture(&intf)?;
Self::build(
intf,
ip_set,
ctx,
dns_tx,
scope,
eth_handle,
RETRY_POLICY.configured(retry),
)
}
pub fn with_handle(
intf: NetworkInterface,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
eth_handle: EthernetHandle,
) -> Result<Self, StrategyError> {
Self::build(intf, ip_set, ctx, dns_tx, scope, eth_handle, RETRY_POLICY)
}
#[allow(clippy::too_many_arguments)]
fn build(
intf: NetworkInterface,
ip_set: IpSet,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
scope: Scope,
eth_handle: EthernetHandle,
retry: RetryPolicy,
) -> Result<Self, StrategyError> {
let identity = SourceIdentity::resolve(&intf, &ip_set)?;
let target_count = ip_set.len() as usize;
let probe_lifetime = retry
.worst_case_probe_lifetime()
.max(ipv6::NDP_RETRY_POLICY.worst_case_probe_lifetime());
let deadline_config = DEADLINE_CONFIG.allowing_for(probe_lifetime);
let deadline = AdaptiveDeadline::new(deadline_config, target_count);
Ok(Self {
ctx,
ip_set,
identity,
eth_handle,
deadline,
protocols: vec![
Box::new(ArpProtocol),
Box::new(NdpProtocol),
Box::new(RouterAdvertProtocol),
Box::new(DhcpProtocol),
Box::new(Icmpv6EchoProtocol),
],
ledger: Ledger::new(retry, target_count),
due: Vec::new(),
retries: VecDeque::new(),
dns_tx,
mac_to_ip: HashMap::new(),
declared: HashMap::new(),
scope,
responded: HashSet::new(),
ipv6: Ipv6Discovery::new(target_count),
audit: ProbeAudit::new(),
send_failure: None,
})
}
fn emit(&mut self, packet: &[u8], what: &str) -> bool {
match self.eth_handle.tx.send_to(packet, None) {
Some(Ok(())) => {
self.audit.record_send(true);
true
}
outcome => {
self.audit.record_send(false);
self.send_failure.get_or_insert_with(|| match outcome {
Some(Err(e)) => format!("{what}: {e}"),
_ => format!("{what}: the link-layer channel accepted no frame"),
});
false
}
}
}
fn record_probe(&mut self, ip: IpAddr, now: Instant) {
if ip.is_ipv6() {
self.ipv6.record_asked(ip, now);
} else {
self.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;
}
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::create_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::create_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::create_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::create_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 send_probe(&mut self, target: IpAddr, now: Instant) {
let packet = match target {
IpAddr::V4(target_v4) => {
let Some(source_v4) = self.identity.ipv4 else {
return;
};
protocol::arp::create_request(&self.identity.mac, &source_v4, target_v4)
}
IpAddr::V6(target_v6) => {
let Some(source_v6) = self.identity.link_local_ipv6 else {
return;
};
protocol::ndp::create_neighbor_solicitation(
&self.identity.mac,
&source_v6,
target_v6,
)
}
};
self.emit(&packet, "probe");
if target.is_ipv6() {
self.ipv6.record_asked(target, now);
} else {
self.ledger.arm(target, target, (), (), now);
}
}
fn absorb_mdns(&mut self, frame: &EthernetPacket) -> 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 service_retries(&mut self, now: Instant) {
let mut due = std::mem::take(&mut self.due);
self.ledger.drain_due(now, &mut due);
self.ipv6.drain_due(now, &mut due);
for event in due.drain(..) {
match event {
Due::Retry { key, .. } => self.retries.push_back(key),
Due::Exhausted { key, .. } => self.ctx.settle_address(key, Settled::Exhausted),
}
}
self.due = due;
}
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.ledger.resolve(address, None, now)
}
}
fn idle(&self, now: Instant) -> bool {
self.retries.is_empty() && self.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.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, bytes: &[u8], now: Instant) -> anyhow::Result<()> {
let eth_frame: EthernetPacket = ethernet::parse(bytes)?;
let source_mac = eth_frame.get_source();
if source_mac == self.identity.mac {
self.audit.record_off_target();
return Err(FrameRejected::SelfSourcedPacket.into());
}
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.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.audit.record_off_target();
return Err(FrameRejected::AddressOutOfRange(subject).into());
}
if subject != source_addr {
info!(
verbosity = 2,
"{subject} answered from {source_addr}, which is another of its addresses"
);
}
let mut answered_attempt = None;
let rtt = match reading.matched {
ProtocolMatch::Unhandled => return Ok(()),
ProtocolMatch::Solicited(_) => match self.resolve_probe(&subject, now) {
Some(resolution) => {
answered_attempt = resolution.answered_attempt;
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)
);
}
resolution.rtt.map(|rtt| (rtt, RttSource::Direct))
}
None => 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
}
},
},
ProtocolMatch::Unsolicited => {
self.confirm(subject);
None
}
ProtocolMatch::AllNodes {
identifier,
sequence,
} => {
if self.ipv6.solicitation().nothing_sent() {
return Err(FrameRejected::UnmappedRttSource(subject).into());
}
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
}
}
}
};
if self.ip_set.contains(&subject) {
self.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 all_targets_responded(&self) -> bool {
matches!(self.scope, Scope::Targeted) && self.responded.len() as u128 >= self.ip_set.len()
}
fn interpret_response(&mut self, frame: &EthernetPacket) -> 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 = 1, "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(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>,
) {
self.ctx.settle_address(source_addr, Settled::Answered);
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 is_new_host = self.ctx.write_host(primary_ip, |host| {
host.record_mac(source_mac.into_core());
host.set_zone(self.identity.zone.clone());
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(rtt),
Some((rtt, RttSource::SegmentWide)) => host.add_segment_wide_rtt(rtt),
None => {}
}
is_new_ip = !host.ips().contains(&source_addr);
changed |= host.consider_primary_ip(source_addr) || is_new_ip;
changed
});
if is_new_host {
self.deadline.mark_activity();
}
if first_sighting {
self.audit.record_host_found(answered_attempt);
}
if rtt.is_none() {
self.audit.record_reply_without_rtt();
}
if let Some((rtt, source)) = rtt {
let asked = match source {
RttSource::Direct => "",
RttSource::SegmentWide => " to the all-nodes echo",
};
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);
}
}
}