use std::collections::{HashMap, VecDeque};
use std::net::IpAddr;
use std::time::{Duration, Instant};
use pnet_packet::ip::IpNextHeaderProtocols;
use crate::config::ProbeTuning;
use crate::fingerprint::os;
use crate::logging::error;
use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
use crate::protocols::icmp;
use crate::report::ScannerKind;
use crate::report::StopReason;
use crate::scanner::pacing::retry::{ProbeLedger, RetryPolicy};
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::StrategyError;
use crate::scanner::strategy::sweep::HostSweep;
use crate::success;
use crate::system::interface::SourceResolver;
use crate::transport::capture::CapturedSegment;
use crate::transport::probe::{Emission, 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);
fn local_millis_since_midnight() -> u32 {
const MILLIS_PER_DAY: u128 = 86_400_000;
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|since| (since.as_millis() % MILLIS_PER_DAY) as u32)
.unwrap_or(0)
}
fn take_ready(queue: &mut VecDeque<IpAddr>, ctx: &ScanContext, now: Instant) -> Option<IpAddr> {
for _ in 0..queue.len() {
let candidate = queue.pop_front()?;
if ctx.host_ready_at(candidate, now).is_none() {
return Some(candidate);
}
queue.push_back(candidate);
}
None
}
pub struct OsEchoScanner {
ctx: ScanContext,
transport: ProbeTransport,
emission: Emission,
resolver: SourceResolver,
identifier: u16,
next_sequence: u16,
pending: VecDeque<IpAddr>,
sweep: HostSweep<u16>,
by_sequence: HashMap<u16, IpAddr>,
deadline: Instant,
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,
tuning.evasion.hop_limited_emission(),
))
}
pub fn with_transport(
ctx: ScanContext,
targets: Vec<IpAddr>,
transport: ProbeTransport,
) -> Self {
Self::with_identifier(ctx, targets, transport, rand::random(), Emission::routed())
}
fn with_identifier(
ctx: ScanContext,
targets: Vec<IpAddr>,
transport: ProbeTransport,
identifier: u16,
emission: Emission,
) -> Self {
let send_duration = SEND_TICK.saturating_mul(targets.len() as u32);
let target_count = targets.len();
Self {
ctx,
transport,
emission,
resolver: SourceResolver::from_system(),
identifier,
next_sequence: 0,
pending: targets.into(),
sweep: HostSweep::new(ProbeLedger::new(RETRY_POLICY, 256)),
by_sequence: HashMap::with_capacity(target_count),
deadline: Instant::now()
+ RETRY_POLICY.worst_case_probe_lifetime()
+ send_duration
+ QUIET_FLOOR,
send_failure: None,
}
}
fn send_one(&mut self, now: Instant) {
let target = match take_ready(&mut self.sweep.retries, &self.ctx, now)
.or_else(|| take_ready(&mut self.pending, &self.ctx, now))
{
Some(target) => target,
None => return,
};
let Some(source) = self.resolver.resolve(target) else {
return;
};
let sequence = self.next_sequence;
let message = match icmp::build_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.sweep.audit.record_send(false);
return;
}
};
let sent = match self
.transport
.tx
.send(&message, source, target, None, self.emission)
{
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.sweep.audit.record_send(sent);
if sent {
self.next_sequence = self.next_sequence.wrapping_add(1);
self.by_sequence.insert(sequence, target);
self.sweep.ledger.arm(target, target, sequence, (), now);
}
self.send_timestamp(source, target);
if sent {
self.ctx.host_probed(target, now);
}
}
fn send_timestamp(&mut self, source: IpAddr, target: IpAddr) {
if !target.is_ipv4() {
return;
}
let sequence = self.next_sequence;
let message = icmp::build_timestamp_request(self.identifier, sequence);
match self
.transport
.tx
.send(&message, source, target, None, self.emission)
{
Ok(()) => {
success!(verbosity = 2, "sent OS timestamp probe to {target}");
self.next_sequence = self.next_sequence.wrapping_add(1);
self.by_sequence.insert(sequence, target);
}
Err(e) => {
error!(
verbosity = 2,
"failed to send OS timestamp probe to {target}: {e:#}"
);
}
}
}
fn handle_reply(&mut self, reply: CapturedSegment, now: Instant) {
if reply.protocol != IpNextHeaderProtocols::Icmp
&& reply.protocol != IpNextHeaderProtocols::Icmpv6
{
self.sweep.audit.record_off_target();
return;
}
let over_ipv6 = reply.source.is_ipv6();
let sequence = match icmp::classify_echo_reply(&reply.bytes, self.identifier, over_ipv6) {
icmp::EchoReply::Ours { sequence } => sequence,
icmp::EchoReply::Other { .. } if !over_ipv6 => {
return self.handle_timestamp_reply(reply, now);
}
_ => {
self.sweep.audit.record_off_target();
return;
}
};
let Some(&target) = self.by_sequence.get(&sequence) else {
self.sweep.audit.record_off_target();
return;
};
let resolution = self.sweep.ledger.resolve(&target, Some(sequence), now);
if resolution.is_none() {
self.sweep.audit.record_reply_without_rtt();
return;
}
let rtt = resolution.and_then(|r| r.rtt);
self.sweep
.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_from(rtt, StatusProtocol::IcmpEcho);
}
!was_up
});
self.identify(target, &reply);
}
fn handle_timestamp_reply(&mut self, reply: CapturedSegment, now: Instant) {
let icmp::TimestampAnswer::Ours {
sequence,
reply: readings,
} = icmp::classify_timestamp_reply(&reply.bytes, self.identifier)
else {
self.sweep.audit.record_off_target();
return;
};
let Some(&target) = self.by_sequence.get(&sequence) else {
self.sweep.audit.record_off_target();
return;
};
let resolution = self.sweep.ledger.resolve(&target, None, now);
if resolution.is_none() {
self.sweep.audit.record_reply_without_rtt();
} else {
self.sweep.audit.record_host_found(None);
}
let detail = match readings.offset_from(local_millis_since_midnight()) {
Some(offset) => format!("timestamp reply to an OS probe, clock {offset} ms from ours"),
None => {
"timestamp reply to an OS probe, on a clock that is not a time of day".to_string()
}
};
self.ctx.write_host(target, |host| {
let was_up = host.status().is_up();
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::IcmpTimestamp, detail),
);
!was_up
});
}
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()]);
});
}
}
impl OsEchoScanner {
pub async fn probe(&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.sweep.service_retries_without_settling(&self.ctx, now);
if let Some(cause) = self.ctx.handle.stopped() {
break cause.into();
}
if self.pending.is_empty()
&& self.sweep.retries.is_empty()
&& self.sweep.ledger.is_empty()
{
break StopReason::AttemptsSpent;
}
if now >= self.deadline {
break StopReason::DeadlineExpired;
}
let sending = !self.pending.is_empty() || !self.sweep.retries.is_empty();
let until_due = self
.sweep
.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.sweep.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.sweep.audit.sends_failed > 0 {
self.ctx.record_failure(
ScannerKind::OsEcho,
format!(
"{} of {} echo probes could not be sent: {}",
self.sweep.audit.sends_attempted,
self.sweep.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.sweep.report(
&self.ctx,
"os-echo",
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 {
received_at: Instant::now(),
source: TARGET,
destination: None,
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::Sender<CapturedSegment>,
}
impl ProbeSender for Echoing {
fn send(
&self,
segment: &[u8],
_src: IpAddr,
_dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), SendError> {
let _ = self.replies.try_send(echo_reply(segment, self.hops));
Ok(())
}
}
fn scanner(ctx: &ScanContext, hops: u8) -> (OsEchoScanner, mpsc::Sender<CapturedSegment>) {
let (tx, rx) = mpsc::channel(1024);
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.probe().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.probe().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,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), SendError> {
Ok(())
}
}
let (session, ctx) = ScanSession::new();
let (tx, rx) = mpsc::channel(1024);
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 {
received_at: Instant::now(),
source: TARGET,
destination: None,
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.try_send(theirs);
});
scanner.probe().await.expect("the phase runs");
assert!(
session.hosts().get(TARGET).is_none(),
"a foreign identifier resolves nothing, records nothing"
);
}
#[derive(Clone, Default)]
struct Recording(std::sync::Arc<std::sync::Mutex<Vec<Vec<u8>>>>);
impl ProbeSender for Recording {
fn send(
&self,
segment: &[u8],
_src: IpAddr,
_dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), SendError> {
self.0.lock().expect("the log").push(segment.to_vec());
Ok(())
}
}
fn recording(ctx: &ScanContext, target: IpAddr) -> (OsEchoScanner, Recording) {
use crate::system::interface::{Link, LinkAddress, SourceResolver};
use std::net::{Ipv4Addr, Ipv6Addr};
let link = Recording::default();
let (_tx, rx) = mpsc::channel(16);
let transport = ProbeTransport::from_parts(Box::new(link.clone()), rx as CaptureStream);
let mut scanner = OsEchoScanner::with_transport(ctx.clone(), vec![target], transport);
scanner.resolver =
SourceResolver::from_links(&[Link::new("test0", 0).with_addresses(vec![
LinkAddress::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)), 24),
LinkAddress::new(
IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)),
64,
),
])]);
(scanner, link)
}
fn timestamp_reply(request: &[u8], readings: [u32; 3]) -> CapturedSegment {
let mut bytes = vec![14u8, 0, 0, 0];
bytes.extend_from_slice(&request[4..8]);
for value in readings {
bytes.extend_from_slice(&value.to_be_bytes());
}
CapturedSegment {
received_at: Instant::now(),
source: TARGET,
destination: None,
protocol: IpNextHeaderProtocols::Icmp,
observation: None,
source_mac: None,
bytes,
}
}
#[tokio::test(flavor = "current_thread")]
async fn an_ipv4_target_is_asked_for_a_timestamp_as_well() {
let (_session, ctx) = ScanSession::new();
let (mut scanner, link) = recording(&ctx, TARGET);
scanner.send_one(Instant::now());
let sent = link.0.lock().expect("the log").clone();
assert_eq!(sent.len(), 2, "an echo and a timestamp");
assert_eq!(sent[0][0], 8, "an echo request");
assert_eq!(sent[1][0], 13, "a timestamp request");
assert_eq!(
&sent[0][4..6],
&sent[1][4..6],
"both carry this scan's identifier"
);
assert_ne!(
&sent[0][6..8],
&sent[1][6..8],
"and each names its own attempt"
);
}
#[tokio::test(flavor = "current_thread")]
async fn a_host_that_answers_only_a_timestamp_is_still_found() {
let (session, ctx) = ScanSession::new();
let (mut scanner, link) = recording(&ctx, TARGET);
scanner.send_one(Instant::now());
let timestamp_request = link.0.lock().expect("the log")[1].clone();
scanner.handle_reply(
timestamp_reply(×tamp_request, [0, 1_000, 1_000]),
Instant::now(),
);
let host = session.hosts().get(TARGET).expect("the host was found");
assert!(host.status().is_up());
assert!(
host.reasons()
.iter()
.any(|reason| reason.protocol == StatusProtocol::IcmpTimestamp),
"the evidence names the probe that found it"
);
}
#[tokio::test(flavor = "current_thread")]
async fn the_targets_clock_offset_reaches_the_host_record() {
let (session, ctx) = ScanSession::new();
let (mut scanner, link) = recording(&ctx, TARGET);
scanner.send_one(Instant::now());
let request = link.0.lock().expect("the log")[1].clone();
scanner.handle_reply(
timestamp_reply(&request, [0, 0x8000_0000, 0x8000_0000]),
Instant::now(),
);
let host = session.hosts().get(TARGET).expect("the host was found");
let reason = host
.reasons()
.iter()
.find(|reason| reason.protocol == StatusProtocol::IcmpTimestamp)
.expect("the timestamp evidence");
assert!(
reason
.details
.as_deref()
.unwrap_or_default()
.contains("not a time of day"),
"an unusable clock is said to be unusable: {reason:?}"
);
}
#[tokio::test(flavor = "current_thread")]
async fn an_ipv6_target_is_sent_no_timestamp() {
let (_session, ctx) = ScanSession::new();
let target = IpAddr::V6("2001:db8::10".parse().expect("an address"));
let (mut scanner, link) = recording(&ctx, target);
scanner.send_one(Instant::now());
let sent = link.0.lock().expect("the log").clone();
assert_eq!(sent.len(), 1, "the echo alone");
assert_eq!(sent[0][0], 128, "an ICMPv6 echo request");
}
#[tokio::test(flavor = "current_thread")]
async fn another_scans_timestamp_reply_finds_nothing() {
let (session, ctx) = ScanSession::new();
let (mut scanner, link) = recording(&ctx, TARGET);
scanner.send_one(Instant::now());
let request = link.0.lock().expect("the log")[1].clone();
let mut stranger = timestamp_reply(&request, [0, 1_000, 1_000]);
stranger.bytes[4] ^= 0xFF;
scanner.handle_reply(stranger, Instant::now());
assert!(
session.hosts().get(TARGET).is_none(),
"a stranger's reply found a host"
);
}
}