use std::collections::{HashMap, VecDeque};
use std::net::IpAddr;
use std::time::{Duration, Instant};
use async_trait::async_trait;
use pnet::packet::ip::IpNextHeaderProtocols;
use crate::config::ProbeTuning;
use crate::error;
use crate::fingerprint::os;
use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
use crate::protocols::icmp;
use crate::scanner::audit::ProbeAudit;
use crate::scanner::pacing::retry::{Due, ProbeLedger, RetryPolicy};
use crate::scanner::report::StopReason;
use crate::scanner::session::{ScanContext, ScannerKind};
use crate::scanner::strategy::{HostScanner, StrategyError};
use crate::success;
use crate::system::interface::SourceResolver;
use crate::transport::capture::CapturedSegment;
use crate::transport::probe::{ProbeKind, ProbeTransport};
const PAYLOAD: &[u8] = b"zond-os-probe";
const RETRY_POLICY: RetryPolicy = RetryPolicy::new(
2,
Duration::from_millis(200),
Duration::from_millis(25),
Duration::from_secs(2),
2.0,
0.2,
None,
);
const SEND_TICK: Duration = Duration::from_millis(1);
const QUIET_FLOOR: Duration = Duration::from_secs(1);
pub struct OsEchoScanner {
ctx: ScanContext,
transport: ProbeTransport,
resolver: SourceResolver,
identifier: u16,
next_sequence: u16,
pending: VecDeque<IpAddr>,
retries: VecDeque<IpAddr>,
ledger: ProbeLedger<IpAddr, u16>,
by_sequence: HashMap<u16, IpAddr>,
due: Vec<Due<IpAddr>>,
deadline: Instant,
audit: ProbeAudit,
send_failure: Option<String>,
}
impl OsEchoScanner {
pub fn new(
ctx: ScanContext,
targets: Vec<IpAddr>,
tuning: ProbeTuning,
) -> Result<Self, StrategyError> {
let identifier = rand::random();
let transport =
ProbeTransport::open_with(ProbeKind::IcmpEcho { identifier }, tuning.send_mode)?;
Ok(Self::with_identifier(ctx, targets, transport, identifier))
}
pub fn with_transport(
ctx: ScanContext,
targets: Vec<IpAddr>,
transport: ProbeTransport,
) -> Self {
Self::with_identifier(ctx, targets, transport, rand::random())
}
fn with_identifier(
ctx: ScanContext,
targets: Vec<IpAddr>,
transport: ProbeTransport,
identifier: u16,
) -> Self {
let send_duration = SEND_TICK.saturating_mul(targets.len() as u32);
let target_count = targets.len();
Self {
ctx,
transport,
resolver: SourceResolver::from_system(),
identifier,
next_sequence: 0,
pending: targets.into(),
retries: VecDeque::new(),
ledger: ProbeLedger::new(RETRY_POLICY, 256),
by_sequence: HashMap::with_capacity(target_count),
due: Vec::new(),
deadline: Instant::now()
+ RETRY_POLICY.worst_case_probe_lifetime()
+ send_duration
+ QUIET_FLOOR,
audit: ProbeAudit::new(),
send_failure: None,
}
}
fn service_retries(&mut self, now: Instant) {
self.ledger.drain_due(now, &mut self.due);
for event in self.due.drain(..) {
if let Due::Retry { key, .. } = event {
self.retries.push_back(key);
}
}
}
fn send_one(&mut self, now: Instant) {
let target = match self
.retries
.pop_front()
.or_else(|| self.pending.pop_front())
{
Some(target) => target,
None => return,
};
let Some(source) = self.resolver.resolve(target) else {
return;
};
let sequence = self.next_sequence;
let message = match icmp::create_echo_request_message(
source,
target,
icmp::ECHO_PROBE_CODE,
self.identifier,
sequence,
PAYLOAD,
) {
Ok(message) => message,
Err(e) => {
error!(verbosity = 2, "Cannot build an echo for {target}: {e}");
self.audit.record_send(false);
return;
}
};
let sent = match self.transport.tx.send(&message, source, target) {
Ok(()) => {
success!(verbosity = 2, "Sent OS echo probe to {target}");
true
}
Err(e) => {
error!(
verbosity = 2,
"Failed to send OS echo probe to {target}: {e:#}"
);
self.send_failure = Some(format!("{e:#}"));
false
}
};
self.audit.record_send(sent);
if sent {
self.next_sequence = self.next_sequence.wrapping_add(1);
self.by_sequence.insert(sequence, target);
self.ledger.arm(target, target, sequence, now);
}
}
fn handle_reply(&mut self, reply: CapturedSegment, now: Instant) {
if reply.protocol != IpNextHeaderProtocols::Icmp
&& reply.protocol != IpNextHeaderProtocols::Icmpv6
{
self.audit.record_off_target();
return;
}
let over_ipv6 = reply.source.is_ipv6();
let icmp::EchoReply::Ours { sequence } =
icmp::classify_echo_reply(&reply.bytes, self.identifier, over_ipv6)
else {
self.audit.record_off_target();
return;
};
let Some(&target) = self.by_sequence.get(&sequence) else {
self.audit.record_off_target();
return;
};
let resolution = self.ledger.resolve(&target, Some(sequence), now);
if resolution.is_none() {
self.audit.record_reply_without_rtt();
return;
}
let rtt = resolution.and_then(|r| r.rtt);
self.audit
.record_host_found(resolution.and_then(|r| r.answered_attempt));
self.ctx.write_host(target, |host| {
let was_up = host.status().is_up();
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::IcmpEcho, "echo reply to an OS probe"),
);
if let Some(rtt) = rtt {
host.add_rtt(rtt);
}
!was_up
});
self.identify(target, &reply);
}
fn identify(&self, target: IpAddr, reply: &CapturedSegment) {
let Some(observation) = reply.observation else {
return;
};
let Some(observed) =
os::EchoObservation::from_echo_reply(observation, &reply.bytes, PAYLOAD)
else {
return;
};
let Some(verdict) = os::classify(os::RuleDb::global(), &observed.into()) else {
return;
};
self.ctx.update_host(target, |host| {
os::identify(host, [verdict.as_evidence()]);
});
}
}
#[async_trait]
impl HostScanner for OsEchoScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::OsEcho
}
async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
let mut send_tick = tokio::time::interval(SEND_TICK);
send_tick.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.pending.is_empty() && self.retries.is_empty() && self.ledger.is_empty() {
break StopReason::AttemptsSpent;
}
if now >= self.deadline {
break StopReason::DeadlineExpired;
}
let sending = !self.pending.is_empty() || !self.retries.is_empty();
let until_due = self
.ledger
.next_due()
.map_or(Duration::from_millis(50), |due| {
due.saturating_duration_since(now)
.min(Duration::from_millis(50))
});
tokio::select! {
res = self.transport.rx.recv() => {
match res {
Some(reply) => {
self.audit.record_segment();
self.handle_reply(reply, Instant::now());
}
None => break StopReason::StreamClosed,
}
}
_ = send_tick.tick(), if sending => {
self.send_one(Instant::now());
}
_ = tokio::time::sleep(until_due), if !sending => {}
}
};
if self.audit.sends_failed > 0 {
self.ctx.record_failure(
ScannerKind::OsEcho,
format!(
"{} of {} echo probes could not be sent: {}",
self.audit.sends_attempted,
self.audit.sends_attempted,
self.send_failure.as_deref().unwrap_or("cause unrecorded"),
),
);
}
let capture = self.transport.capture_counts();
let targets = self.next_sequence as u128;
self.audit.report("os-echo", targets, reason, capture);
self.ctx.record_probe_stats(self.audit.stats(
ScannerKind::OsEcho,
targets,
reason,
capture,
));
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::Ipv4Addr;
use tokio::sync::mpsc;
use crate::model::capture::{IpObservation, Ipv4Observation};
use crate::scanner::session::ScanSession;
use crate::transport::capture::CaptureStream;
use crate::transport::probe::{ProbeSender, SendError};
const TARGET: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 10));
fn echo_reply(request: &[u8], hops: u8) -> CapturedSegment {
let identifier = u16::from_be_bytes([request[4], request[5]]);
let sequence = u16::from_be_bytes([request[6], request[7]]);
let mut message = Vec::with_capacity(8 + PAYLOAD.len());
message.extend_from_slice(&[0, icmp::ECHO_PROBE_CODE, 0, 0]);
message.extend_from_slice(&identifier.to_be_bytes());
message.extend_from_slice(&sequence.to_be_bytes());
message.extend_from_slice(PAYLOAD);
CapturedSegment {
source: TARGET,
protocol: IpNextHeaderProtocols::Icmp,
observation: Some(IpObservation::V4(Ipv4Observation {
ttl: hops,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})),
source_mac: None,
bytes: message,
}
}
struct Echoing {
hops: u8,
replies: mpsc::UnboundedSender<CapturedSegment>,
}
impl ProbeSender for Echoing {
fn send(&self, segment: &[u8], _src: IpAddr, _dst: IpAddr) -> Result<(), SendError> {
let _ = self.replies.send(echo_reply(segment, self.hops));
Ok(())
}
}
fn scanner(
ctx: &ScanContext,
hops: u8,
) -> (OsEchoScanner, mpsc::UnboundedSender<CapturedSegment>) {
let (tx, rx) = mpsc::unbounded_channel();
let link = Echoing {
hops,
replies: tx.clone(),
};
let transport = ProbeTransport::from_parts(Box::new(link), rx as CaptureStream);
(
OsEchoScanner::with_transport(ctx.clone(), vec![TARGET], transport),
tx,
)
}
#[tokio::test(flavor = "current_thread")]
async fn a_windows_hop_counter_in_an_echo_reply_names_windows() {
let (session, ctx) = ScanSession::new();
let (mut scanner, _tx) = scanner(&ctx, 128);
scanner.discover_hosts().await.expect("the phase runs");
let host = session.hosts().get(&TARGET).expect("the host is recorded");
let found = host
.os()
.expect("an echo reply with a Windows hop counter names Windows");
assert_eq!(found.family(), Some("Windows"));
assert!(
found.evidence().unwrap_or_default().contains("echo"),
"the finding says what it was read off: {found}"
);
assert_eq!(host.status(), HostStatus::Up);
}
#[tokio::test(flavor = "current_thread")]
async fn a_unix_hop_counter_in_an_echo_reply_names_nothing() {
let (session, ctx) = ScanSession::new();
let (mut scanner, _tx) = scanner(&ctx, 64);
scanner.discover_hosts().await.expect("the phase runs");
let host = session.hosts().get(&TARGET).expect("the host is recorded");
assert!(
host.os().is_none(),
"an echo reply at 64 hops is not evidence for any family, and saying \
nothing beats the least bad guess"
);
assert_eq!(host.status(), HostStatus::Up);
}
#[tokio::test(flavor = "current_thread")]
async fn somebody_elses_ping_is_not_our_answer() {
struct Silent;
impl ProbeSender for Silent {
fn send(&self, _s: &[u8], _src: IpAddr, _dst: IpAddr) -> Result<(), SendError> {
Ok(())
}
}
let (session, ctx) = ScanSession::new();
let (tx, rx) = mpsc::unbounded_channel();
let transport = ProbeTransport::from_parts(Box::new(Silent), rx);
let mut scanner = OsEchoScanner::with_transport(ctx.clone(), vec![TARGET], transport);
let mut message = Vec::with_capacity(8 + PAYLOAD.len());
message.extend_from_slice(&[0, 0, 0, 0]);
message.extend_from_slice(&0xBEEFu16.to_be_bytes()); message.extend_from_slice(&0u16.to_be_bytes());
message.extend_from_slice(PAYLOAD);
let theirs = CapturedSegment {
source: TARGET,
protocol: IpNextHeaderProtocols::Icmp,
observation: Some(IpObservation::V4(Ipv4Observation {
ttl: 128,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})),
source_mac: None,
bytes: message,
};
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(20)).await;
let _ = tx.send(theirs);
});
scanner.discover_hosts().await.expect("the phase runs");
assert!(
session.hosts().get(&TARGET).is_none(),
"a foreign identifier resolves nothing, records nothing"
);
}
}