mod port_scan;
mod udp_scan;
use std::{
collections::{HashMap, VecDeque},
net::IpAddr,
time::{Duration, Instant},
};
use crate::core::config::ProbeTuning;
use crate::core::models::deadline::{AdaptiveDeadline, AdaptiveDeadlineConfig};
use crate::core::models::host::{HostStatus, StatusProtocol, StatusReason};
use crate::core::models::ip::set::IpSet;
use crate::core::models::retry::{Due, ProbeLedger, Resolution, RetryPolicy, SilentHostPolicy};
use crate::core::models::timer::ScanBudget;
use crate::core::session::ScanContext;
use crate::network::probe::{ProbeKind, ProbeSender, ProbeTransport};
use crate::protocols as protocol;
use crate::system::interface::RoutedTarget;
use crate::{error, success};
use async_trait::async_trait;
use pnet::packet::tcp::TcpPacket;
use tokio::sync::mpsc::UnboundedSender;
use super::audit::ProbeAudit;
use super::{NetworkExplorer, payload};
use crate::core::report::StopReason;
use crate::core::session::ScannerKind;
pub use port_scan::SynPortScanner;
pub use udp_scan::UdpPortScanner;
const DEADLINE_CONFIG: AdaptiveDeadlineConfig = AdaptiveDeadlineConfig::new(
ScanBudget::new(
Duration::from_millis(2_000),
Duration::from_millis(1),
Duration::from_secs(60),
),
ScanBudget::new(
Duration::from_millis(300),
Duration::from_micros(500),
Duration::from_secs(10),
),
Duration::from_millis(400),
Duration::from_secs(3),
4.0,
20,
);
const RETRY_POLICY: RetryPolicy = RetryPolicy::new(
3,
Duration::from_millis(200),
Duration::from_millis(25),
Duration::from_secs(2),
2.0,
0.2,
Some(SilentHostPolicy::new(32, 2)),
);
const PROBE_RATE_PER_SEC: u32 = 4_000;
const MIN_SEND_TICK: Duration = Duration::from_millis(1);
fn pacing_for(rate_per_sec: u32) -> (Duration, usize) {
let rate = f64::from(rate_per_sec.max(1));
let batch = (rate * MIN_SEND_TICK.as_secs_f64()).round().max(1.0);
(Duration::from_secs_f64(batch / rate), batch as usize)
}
type SeqNum = u32;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SynToken {
pub seq: SeqNum,
pub src_port: u16,
}
fn send_syn(
sender: &dyn ProbeSender,
src_addr: IpAddr,
dst_addr: IpAddr,
dst_port: u16,
) -> Option<SynToken> {
let src_port: u16 = rand::random_range(50_000..u16::MAX);
let seq_num: u32 = rand::random_range(0..=u32::MAX);
let packet =
match protocol::tcp::create_packet(&src_addr, &dst_addr, src_port, dst_port, seq_num) {
Ok(pkt) => pkt,
Err(e) => {
error!(
verbosity = 2,
"Failed to create SYN packet for {dst_addr}:{dst_port}: {e}"
);
return None;
}
};
match sender.send(&packet, src_addr, dst_addr) {
Ok(_) => {
success!(verbosity = 2, "Sent SYN probe to {dst_addr}:{dst_port}");
Some(SynToken {
seq: seq_num,
src_port,
})
}
Err(e) => {
error!(
verbosity = 2,
"Failed to send SYN probe to {dst_addr}:{dst_port}: {e}"
);
None
}
}
}
fn send_udp(
sender: &dyn ProbeSender,
src_port: u16,
src_addr: IpAddr,
dst_addr: IpAddr,
dst_port: u16,
) -> Option<()> {
let payload = payload::for_port(dst_port).to_vec();
let packet = match crate::protocols::udp::create_packet(
&src_addr, &dst_addr, src_port, dst_port, payload,
) {
Ok(pkt) => pkt,
Err(e) => {
error!(
verbosity = 2,
"Failed to create UDP packet for {dst_addr}:{dst_port}: {e}"
);
return None;
}
};
match sender.send(&packet, src_addr, dst_addr) {
Ok(_) => {
success!(verbosity = 2, "Sent UDP probe to {dst_addr}:{dst_port}");
Some(())
}
Err(e) => {
error!(
verbosity = 2,
"Failed to send UDP probe to {dst_addr}:{dst_port}: {e}"
);
None
}
}
}
pub struct RoutedScanner {
ctx: ScanContext,
sources: HashMap<IpAddr, IpAddr>,
ips: IpSet,
transport: ProbeTransport,
deadline: AdaptiveDeadline,
dns_tx: Option<UnboundedSender<IpAddr>>,
ledger: ProbeLedger<IpAddr, SynToken>,
due: Vec<Due<IpAddr>>,
pending: std::vec::IntoIter<IpAddr>,
retries: VecDeque<IpAddr>,
send_tick: Duration,
batch: usize,
responded_count: usize,
audit: ProbeAudit,
}
#[async_trait]
impl NetworkExplorer for RoutedScanner {
async fn discover_hosts(mut self: Box<Self>) -> anyhow::Result<()> {
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.service_retries(now);
let all_responded = self.ips.len() == self.responded_count as u128;
if self.ctx.handle.should_stop() {
break StopReason::Aborted;
}
if all_responded {
break StopReason::AllResponded;
}
if self.nothing_left_to_send() && self.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.tick_delay(now);
tokio::select! {
res = self.transport.rx.recv() => {
match res {
Some(reply) => {
self.audit.record_segment();
self.handle_discovery_reply(reply.source, &reply.bytes, Instant::now());
}
None => break StopReason::StreamClosed,
}
},
_ = send_tick.tick(), if sending => {
self.send_allowance(Instant::now());
}
_ = tokio::time::sleep(tick), if !sending => {}
}
};
let capture = self.transport.capture_counts();
let targets = self.ips.len();
self.audit
.report("routed-discovery", targets, reason, capture);
self.ctx.record_probe_stats(self.audit.stats(
ScannerKind::Routed,
targets,
reason,
capture,
));
Ok(())
}
}
impl RoutedScanner {
pub fn new(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
) -> anyhow::Result<Self> {
let transport = ProbeTransport::open_with(ProbeKind::TcpSyn, tuning.send_mode)?;
Ok(Self::build(
targets,
ctx,
dns_tx,
transport,
RETRY_POLICY.configured(tuning.retry),
tuning.max_probe_rate.unwrap_or(PROBE_RATE_PER_SEC).max(1),
))
}
#[cfg(any(test, feature = "test-support"))]
pub fn with_transport(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
transport: ProbeTransport,
) -> Self {
Self::build(
targets,
ctx,
dns_tx,
transport,
RETRY_POLICY,
PROBE_RATE_PER_SEC,
)
}
fn build(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
transport: ProbeTransport,
retry: RetryPolicy,
rate_per_sec: u32,
) -> 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();
let target_count = sources.len();
let (send_tick, batch) = pacing_for(rate_per_sec);
let send_duration = Duration::from_secs_f64(target_count as f64 / f64::from(rate_per_sec));
let deadline_config =
DEADLINE_CONFIG.allowing_for(retry.worst_case_probe_lifetime() + send_duration);
Self {
ctx,
sources,
ips,
transport,
deadline: AdaptiveDeadline::new(deadline_config, target_count),
dns_tx,
ledger: ProbeLedger::new(retry, target_count),
due: Vec::new(),
pending: order.into_iter(),
retries: VecDeque::new(),
send_tick,
batch,
responded_count: 0,
audit: ProbeAudit::new(),
}
}
fn handle_discovery_reply(&mut self, ip: IpAddr, bytes: &[u8], now: Instant) {
if !self.ips.contains(&ip) {
self.audit.record_off_target();
return;
}
let resolution = self.resolve_probe(ip, bytes, now);
let rtt = resolution.and_then(|resolution| resolution.rtt);
if rtt.is_none() {
self.audit.record_reply_without_rtt();
}
let is_new = self.ctx.write_host(ip, |host| {
let was_up = host.status().is_up();
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::TcpSyn, "tcp reply to a discovery probe"),
);
if let Some(rtt) = rtt {
host.add_rtt(rtt);
return true;
}
!was_up
});
if is_new {
self.responded_count += 1;
self.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 = TcpPacket::new(bytes).map(|tcp| SynToken {
seq: tcp.get_acknowledgement().wrapping_sub(1),
src_port: tcp.get_destination(),
});
token
.and_then(|token| self.ledger.resolve(&ip, Some(token), now))
.or_else(|| self.ledger.resolve(&ip, None, now))
}
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 nothing_left_to_send(&self) -> bool {
self.retries.is_empty() && self.pending.len() == 0
}
fn send_allowance(&mut self, now: Instant) {
for _ in 0..self.batch {
let target = match self.retries.pop_front() {
Some(target) => target,
None => match self.pending.next() {
Some(target) => target,
None => return,
},
};
self.probe(target, now);
}
}
fn tick_delay(&self, now: Instant) -> Duration {
let until_deadline_tick = self.deadline.time_until_next_tick();
match self.ledger.next_due() {
Some(due) => until_deadline_tick.min(due.saturating_duration_since(now)),
None => until_deadline_tick,
}
}
fn probe(&mut self, target: IpAddr, now: Instant) {
const DST_PORT: u16 = 443;
let Some(&source) = self.sources.get(&target) else {
return;
};
let token = send_syn(self.transport.tx.as_ref(), source, target, DST_PORT);
self.audit.record_send(token.is_some());
if let Some(token) = token {
self.ledger.arm(target, target, token, now);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn effective_rate(rate_per_sec: u32) -> f64 {
let (tick, batch) = pacing_for(rate_per_sec);
batch as f64 / tick.as_secs_f64()
}
#[test]
fn a_fast_rate_is_expressed_as_a_batch_on_the_shortest_tick() {
assert_eq!(pacing_for(2_000), (MIN_SEND_TICK, 2));
assert_eq!(pacing_for(100_000), (MIN_SEND_TICK, 100));
}
#[test]
fn a_slow_rate_lengthens_the_tick_rather_than_doubling_the_rate() {
assert_eq!(pacing_for(500), (Duration::from_millis(2), 1));
assert_eq!(pacing_for(100), (Duration::from_millis(10), 1));
}
#[test]
fn every_rate_is_paced_at_the_rate_it_asked_for() {
for rate in [1, 100, 500, 999, 1_000, 1_500, 2_000, 4_000, 16_000] {
let effective = effective_rate(rate);
let error = (effective - f64::from(rate)).abs() / f64::from(rate);
assert!(
error < 0.01,
"{rate}/s is paced at {effective}/s, off by {:.0}%",
error * 100.0
);
}
}
#[test]
fn a_zero_rate_still_sends() {
let (tick, batch) = pacing_for(0);
assert_eq!(batch, 1);
assert!(tick <= Duration::from_secs(1));
}
}