mod icmp_error;
mod os_echo;
mod os_series;
mod port_scan;
mod probe_scan;
pub mod traceroute;
mod udp_scan;
use std::{
collections::{HashMap, HashSet, VecDeque},
net::IpAddr,
time::{Duration, Instant},
};
use crate::config::ProbeTuning;
use crate::journal::settle::{Outcome, Settled};
use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
use crate::model::ip::set::IpSet;
use crate::model::technique::{TcpReply, TcpScanTechnique};
use crate::protocols as protocol;
use crate::scanner::pacing::congestion::WindowLimits;
use crate::scanner::pacing::deadline::{AdaptiveDeadline, AdaptiveDeadlineConfig};
use crate::scanner::pacing::retry::{Due, ProbeLedger, Resolution, RetryPolicy, SilentHostPolicy};
use crate::scanner::pacing::timer::ScanBudget;
use crate::scanner::session::ScanContext;
use crate::system::interface::RoutedTarget;
use crate::transport::probe::{Emission, ProbeKind, ProbeSender, ProbeTransport, SendError};
use crate::{error, info, success};
use async_trait::async_trait;
use pnet::packet::tcp::TcpPacket;
use tokio::sync::mpsc::UnboundedSender;
use crate::scanner::audit::ProbeAudit;
use crate::scanner::payload;
use crate::scanner::report::StopReason;
use crate::scanner::session::ScannerKind;
use crate::scanner::strategy::{HostScanner, StrategyError};
pub use os_echo::OsEchoScanner;
pub use os_series::{ACTIVE_SAMPLES, AGGRESSIVE_SAMPLES, OsSeriesScanner, SeriesTarget};
pub use port_scan::TcpPortScanner;
pub use udp_scan::UdpPortScanner;
pub use probe_scan::{AuditLabels, ProbeTarget, RawPortScan, RawProbeScan, run};
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 PORT_RETRY_POLICY: RetryPolicy = RetryPolicy::new(
3,
Duration::from_millis(200),
Duration::from_millis(25),
Duration::from_secs(2),
3.0,
0.3,
Some(SilentHostPolicy::new(32, 2)),
);
const TCP_PORT_WINDOW: WindowLimits = WindowLimits::new(32, 16, 1_024, 64);
const TCP_PORT_UNRESOLVED: usize = 8_192;
const TCP_PORT_RATE_CEILING: u32 = 20_000;
const UDP_PORT_RATE_PER_SEC: u32 = 400;
const MIN_SEND_TICK: Duration = Duration::from_millis(1);
pub(super) 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,
faults: &mut SendFaults,
) -> 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_probe(
TcpScanTechnique::Syn,
&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, Emission::routed()) {
Ok(_) => {
success!(verbosity = 2, "sent SYN probe to {dst_addr}:{dst_port}");
Some(SynToken {
seq: seq_num,
src_port,
})
}
Err(e) => {
if e.is_unroutable() {
if faults.unroutable.is_none() {
info!(verbosity = 1, "no route to {dst_addr}: {e:#}");
}
} else if faults.broken.is_none() {
error!(
verbosity = 2,
"failed to send SYN probe to {dst_addr}:{dst_port}: {e:#}"
);
}
faults.record(dst_addr, &e);
None
}
}
}
fn send_udp(
sender: &dyn ProbeSender,
src_port: u16,
src_addr: IpAddr,
dst_addr: IpAddr,
dst_port: u16,
reason: &mut Option<String>,
) -> 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, Emission::routed()) {
Ok(_) => {
success!(verbosity = 2, "sent UDP probe to {dst_addr}:{dst_port}");
Some(())
}
Err(e) => {
if reason.is_none() {
error!(
verbosity = 2,
"failed to send UDP probe to {dst_addr}:{dst_port}: {e:#}"
);
*reason = Some(format!("{e:#}"));
}
None
}
}
}
fn answers_a_syn_probe(bytes: &[u8]) -> bool {
TcpPacket::new(bytes)
.and_then(|tcp| protocol::tcp::classify_probe_response(&tcp))
.is_some_and(|reply| !matches!(reply, TcpReply::ChallengeAck))
}
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: HashSet<IpAddr>,
audit: ProbeAudit,
faults: SendFaults,
}
#[derive(Debug, Default)]
struct SendFaults {
broken: Option<String>,
unroutable: Option<(IpAddr, String)>,
unroutable_count: u64,
addresses: std::collections::BTreeSet<IpAddr>,
}
impl SendFaults {
fn record(&mut self, target: IpAddr, error: &SendError) {
if error.is_unroutable() {
self.unroutable_count += 1;
self.addresses.insert(target);
self.unroutable
.get_or_insert_with(|| (target, error.to_string()));
} else {
self.broken.get_or_insert_with(|| error.to_string());
}
}
}
#[async_trait]
impl HostScanner for RoutedScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::Routed
}
async fn discover_hosts(&mut self) -> Result<(), StrategyError> {
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.len() 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 outstanding = self.ledger.drain_unresolved().len() as u64;
self.ctx.record_many(Outcome::Interrupted, outstanding);
self.ctx
.record_many(Outcome::Unasked, self.pending.len() as u64);
self.ctx
.record_many(Outcome::Unroutable, self.faults.addresses.len() as u64);
if let Some(reason) = &self.faults.broken {
let broken = self.audit.sends_failed - self.faults.unroutable_count;
self.ctx.record_failure(
ScannerKind::Routed,
format!(
"{broken} of {} probes could not be sent: {reason}",
self.audit.sends_attempted,
),
);
}
for address in &self.faults.addresses {
self.ctx.record_unroutable(*address);
}
if let Some((address, _)) = &self.faults.unroutable {
match self.faults.unroutable_count.saturating_sub(1) {
0 => info!("no route to {address}"),
1 => info!("no route to {address} and 1 other address"),
more => info!("no route to {address} and {more} other addresses"),
}
}
let capture = self.transport.capture_counts();
let targets = self.ips.len();
self.audit
.report("routed-discovery", targets, reason, capture, None);
self.ctx.record_probe_stats(self.audit.stats(
ScannerKind::Routed,
targets,
reason,
capture,
None,
));
Ok(())
}
}
impl RoutedScanner {
pub fn new(
targets: Vec<RoutedTarget>,
ctx: ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
) -> Result<Self, StrategyError> {
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),
))
}
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: HashSet::new(),
audit: ProbeAudit::new(),
faults: SendFaults::default(),
}
}
fn handle_discovery_reply(&mut self, ip: IpAddr, bytes: &[u8], now: Instant) {
if !self.ips.contains(&ip) {
self.audit.record_off_target();
return;
}
if !answers_a_syn_probe(bytes) {
self.audit.record_off_target();
return;
}
self.ctx.settle_address(ip, Settled::Answered);
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();
}
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 self.responded.insert(ip) {
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: protocol::tcp::echoed_nonce(TcpScanTechnique::Syn, &tcp),
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(..) {
match event {
Due::Retry { key, .. } => self.retries.push_back(key),
Due::Exhausted { key, .. } => self.ctx.settle_address(key, Settled::Exhausted),
}
}
}
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,
&mut self.faults,
);
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::*;
#[test]
fn a_missing_route_is_counted_apart_from_a_broken_send_path() {
let unreachable = |address: &str| {
SendError::from_io(
anyhow::Error::new(std::io::Error::new(
std::io::ErrorKind::HostUnreachable,
"No route to host",
))
.context(format!("failed to send to {address}")),
)
};
let mut faults = SendFaults::default();
let first: IpAddr = "2001:db8::1".parse().expect("literal");
let second: IpAddr = "2001:db8::2".parse().expect("literal");
faults.record(first, &unreachable("2001:db8::1"));
faults.record(second, &unreachable("2001:db8::2"));
assert_eq!(faults.unroutable_count, 2);
assert_eq!(
faults.unroutable.as_ref().map(|(address, _)| *address),
Some(first),
"the first address is kept, not the last"
);
assert!(
faults.broken.is_none(),
"no route to somewhere is not a scan that could not run"
);
faults.record(
first,
&SendError::from_io(anyhow::Error::new(std::io::Error::new(
std::io::ErrorKind::PermissionDenied,
"Operation not permitted",
))),
);
assert!(faults.broken.is_some(), "and this one is");
assert_eq!(faults.unroutable_count, 2, "which is a separate tally");
}
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));
}
}