use std::net::IpAddr;
use std::time::{Duration, Instant};
use async_trait::async_trait;
use pnet::packet::tcp::TcpPacket;
use tokio::sync::mpsc;
use crate::core::config::ProbeTuning;
use crate::core::models::deadline::AdaptiveDeadline;
use crate::core::models::host::{HostStatus, StatusProtocol, StatusReason};
use crate::core::models::port::{PortState, Protocol};
use crate::core::models::retry::{Due, ProbeLedger, RetryPolicy};
use crate::core::models::target::Target;
use crate::core::session::{ScanContext, ScannerKind};
use crate::error;
use crate::network::probe::{ProbeKind, ProbeTransport};
use crate::protocols::tcp::{self, ProbeResponse};
use crate::scanner::{PortScanner, service};
use crate::system::interface::SourceResolver;
use super::{DEADLINE_CONFIG, RETRY_POLICY, SynToken, send_syn};
type ProbeTarget = (IpAddr, u16);
type Ledger = ProbeLedger<ProbeTarget, SynToken>;
const MAX_IN_FLIGHT: usize = 4_096;
pub struct SynPortScanner {
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
deadline: AdaptiveDeadline,
ledger: Ledger,
due: Vec<Due<ProbeTarget>>,
}
impl SynPortScanner {
pub fn new(
resolver: SourceResolver,
ctx: ScanContext,
target_count: usize,
tuning: ProbeTuning,
) -> anyhow::Result<Self> {
let transport = ProbeTransport::open_with(ProbeKind::TcpSyn, tuning.send_mode)?;
Ok(Self::build(
resolver,
ctx,
transport,
target_count,
RETRY_POLICY.configured(tuning.retry),
))
}
#[cfg(any(test, feature = "test-support"))]
pub fn with_transport(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
target_count: usize,
) -> Self {
Self::build(resolver, ctx, transport, target_count, RETRY_POLICY)
}
fn build(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
target_count: usize,
retry: RetryPolicy,
) -> Self {
let deadline_config = DEADLINE_CONFIG.allowing_for(retry.worst_case_probe_lifetime());
Self {
resolver,
ctx,
transport,
deadline: AdaptiveDeadline::new(deadline_config, target_count),
ledger: Ledger::new(retry, target_count.min(MAX_IN_FLIGHT)),
due: Vec::new(),
}
}
fn send_probe(&mut self, target: Target) {
if target.protocol != Protocol::Tcp {
return;
}
self.probe(target.ip, target.port, Instant::now());
}
fn probe(&mut self, ip: IpAddr, port: u16, now: Instant) {
let Some(src_addr) = self.resolver.resolve(ip) else {
error!(verbosity = 2, "No route to {ip}; skipping {ip}:{port}");
return;
};
if let Some(token) = send_syn(self.transport.tx.as_ref(), src_addr, ip, port) {
self.ledger.arm(ip, (ip, port), token, now);
}
}
fn handle_reply(&mut self, ip: IpAddr, bytes: &[u8], now: Instant) {
let Some(tcp_packet) = TcpPacket::new(bytes) else {
return;
};
let Some(response) = tcp::classify_probe_response(&tcp_packet) else {
return;
};
let token = SynToken {
seq: tcp_packet.get_acknowledgement().wrapping_sub(1),
src_port: tcp_packet.get_destination(),
};
let key = (ip, tcp_packet.get_source());
let Some(resolution) = self.ledger.resolve(&key, Some(token), now) else {
return;
};
self.deadline.mark_activity();
if let Some(rtt) = resolution.rtt {
self.deadline.record_rtt(rtt);
}
let state = match response {
ProbeResponse::Open => PortState::Open,
ProbeResponse::Closed => PortState::Closed,
};
self.record_port(ip, key.1, state);
}
fn service_retries(&mut self, now: Instant) {
self.ledger.drain_due(now, &mut self.due);
let due = std::mem::take(&mut self.due);
for event in &due {
match *event {
Due::Retry {
key: (ip, port), ..
} => self.probe(ip, port, now),
Due::Exhausted((ip, port)) => self.record_port(ip, port, PortState::Filtered),
}
}
self.due = due;
self.due.clear();
}
fn resolve_remaining_as_filtered(&mut self) {
for (ip, port) in self.ledger.drain_unresolved() {
self.record_port(ip, port, PortState::Filtered);
}
}
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 record_port(&mut self, ip: IpAddr, port_num: u16, state: PortState) {
let port = crate::fingerprinting::baseline_port(port_num, Protocol::Tcp, state);
let evidence = match state {
PortState::Open => Some("syn-ack from a probed port"),
PortState::Closed => Some("rst from a probed port"),
_ => None,
};
self.ctx.update_host(ip, |host| {
host.add_port(port);
if let Some(details) = evidence {
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::TcpSyn, details),
);
}
});
}
}
#[async_trait]
impl PortScanner for SynPortScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::SynPort
}
fn supported_protocols(&self) -> Vec<Protocol> {
vec![Protocol::Tcp]
}
async fn scan(&mut self, mut targets: mpsc::Receiver<Target>) -> anyhow::Result<()> {
let mut sending_finished = false;
loop {
let now = Instant::now();
self.service_retries(now);
if self.ctx.handle.should_stop() || self.deadline.hard_deadline_passed() {
break;
}
if sending_finished && self.ledger.is_empty() {
break;
}
if self.ledger.is_empty() && self.deadline.has_expired() {
break;
}
let admitting = !sending_finished && self.ledger.len() < MAX_IN_FLIGHT;
let tick = self.tick_delay(now);
tokio::select! {
target = targets.recv(), if admitting => {
match target {
Some(target) => self.send_probe(target),
None => sending_finished = true,
}
}
res = self.transport.rx.recv() => {
match res {
Some(reply) => {
self.handle_reply(reply.source, &reply.bytes, Instant::now());
}
None => break,
}
}
_ = tokio::time::sleep(tick) => {}
}
}
self.resolve_remaining_as_filtered();
Ok(())
}
async fn detect_services(&mut self, ctx: &ScanContext) {
service::detect(ctx).await;
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::Ipv4Addr;
use pnet::ipnetwork::{IpNetwork, Ipv4Network};
use pnet::packet::tcp::MutableTcpPacket;
use crate::core::session::ScanSession;
use crate::network::probe::{MockSender, ProbeTransport};
const SYN: u8 = 1 << 1;
const RST: u8 = 1 << 2;
const ACK: u8 = 1 << 4;
const TARGET: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 200));
fn on_link_interface() -> pnet::datalink::NetworkInterface {
pnet::datalink::NetworkInterface {
name: "test0".to_string(),
description: String::new(),
index: 0,
mac: None,
ips: vec![IpNetwork::V4(
Ipv4Network::new(Ipv4Addr::new(192, 168, 1, 50), 24).unwrap(),
)],
flags: 0,
}
}
fn tcp_segment(src_port: u16, token: SynToken, flags: u8) -> Vec<u8> {
let mut buf = vec![0u8; 20];
let mut tcp = MutableTcpPacket::new(&mut buf).unwrap();
tcp.set_source(src_port);
tcp.set_destination(token.src_port);
tcp.set_data_offset(5);
tcp.set_acknowledgement(token.seq.wrapping_add(1));
tcp.set_flags(flags);
buf
}
type SentProbes = std::sync::Arc<std::sync::Mutex<Vec<crate::network::probe::SentProbe>>>;
fn scanner_with_mock() -> (SynPortScanner, ScanSession, SentProbes) {
let (session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::unbounded_channel();
let sender = MockSender::default();
let sent = sender.sent.clone();
let transport = ProbeTransport::from_parts(Box::new(sender), reply_rx);
let resolver = SourceResolver::from_interfaces(&[on_link_interface()]);
let scanner = SynPortScanner::with_transport(resolver, ctx, transport, 8);
(scanner, session, sent)
}
fn probe(scanner: &mut SynPortScanner, sent: &SentProbes, port: u16) -> SynToken {
let before = sent.lock().unwrap().len();
scanner.send_probe(Target {
ip: TARGET,
port,
protocol: Protocol::Tcp,
});
let sent = sent.lock().unwrap();
let (segment, _, _) = sent.get(before).expect("probe reached the wire");
let tcp = TcpPacket::new(segment).expect("probe is a TCP segment");
SynToken {
seq: tcp.get_sequence(),
src_port: tcp.get_source(),
}
}
fn port_state(session: &ScanSession, port: u16) -> Option<PortState> {
session
.store
.get(&TARGET)
.and_then(|h| h.ports().find(|p| p.number() == port).map(|p| p.state()))
}
#[test]
fn syn_ack_matching_probe_is_open() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
scanner.handle_reply(TARGET, &tcp_segment(80, token, SYN | ACK), Instant::now());
assert_eq!(port_state(&session, 80), Some(PortState::Open));
assert!(!scanner.ledger.contains(&(TARGET, 80)));
}
#[test]
fn rst_matching_probe_is_closed() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 81);
scanner.handle_reply(TARGET, &tcp_segment(81, token, RST | ACK), Instant::now());
assert_eq!(port_state(&session, 81), Some(PortState::Closed));
}
#[test]
fn reply_with_wrong_ack_is_ignored() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 82);
let stray = SynToken {
seq: token.seq.wrapping_add(999),
..token
};
scanner.handle_reply(TARGET, &tcp_segment(82, stray, SYN | ACK), Instant::now());
assert_eq!(port_state(&session, 82), None);
assert!(scanner.ledger.contains(&(TARGET, 82)));
}
#[test]
fn reply_to_a_port_we_never_sent_from_is_ignored() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 83);
let elsewhere = SynToken {
src_port: token.src_port.wrapping_add(1),
..token
};
scanner.handle_reply(
TARGET,
&tcp_segment(83, elsewhere, SYN | ACK),
Instant::now(),
);
assert_eq!(port_state(&session, 83), None);
assert!(scanner.ledger.contains(&(TARGET, 83)));
}
#[test]
fn reply_for_unprobed_port_is_ignored() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
scanner.handle_reply(TARGET, &tcp_segment(1234, token, SYN | ACK), Instant::now());
assert_eq!(port_state(&session, 1234), None);
assert!(scanner.ledger.contains(&(TARGET, 80)));
}
#[test]
fn unanswered_probes_resolve_as_filtered() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 443);
scanner.resolve_remaining_as_filtered();
assert_eq!(port_state(&session, 443), Some(PortState::Filtered));
assert!(scanner.ledger.is_empty());
}
#[test]
fn non_tcp_targets_are_not_probed() {
let (mut scanner, _session, _sent) = scanner_with_mock();
scanner.send_probe(Target {
ip: TARGET,
port: 53,
protocol: Protocol::Udp,
});
assert!(scanner.ledger.is_empty());
}
#[test]
fn an_unanswered_probe_is_sent_again() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
scanner.service_retries(Instant::now() + Duration::from_secs(1));
assert_eq!(sent.lock().unwrap().len(), 2, "the probe was not retried");
assert!(scanner.ledger.contains(&(TARGET, 80)));
assert_eq!(port_state(&session, 80), None, "no verdict has been earned");
}
#[test]
fn a_port_is_filtered_only_once_every_attempt_is_spent() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
let mut now = Instant::now();
for _ in 0..RETRY_POLICY.max_attempts + 2 {
now += Duration::from_secs(4);
scanner.service_retries(now);
}
assert_eq!(port_state(&session, 80), Some(PortState::Filtered));
assert_eq!(
sent.lock().unwrap().len(),
usize::from(RETRY_POLICY.max_attempts),
);
assert!(scanner.ledger.is_empty());
}
#[test]
fn an_answered_probe_is_never_retried() {
let (mut scanner, _session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
scanner.handle_reply(TARGET, &tcp_segment(80, token, SYN | ACK), Instant::now());
scanner.service_retries(Instant::now() + Duration::from_secs(10));
assert_eq!(sent.lock().unwrap().len(), 1);
}
#[test]
fn a_reply_to_a_superseded_attempt_still_resolves_the_port() {
let (mut scanner, session, sent) = scanner_with_mock();
let first = probe(&mut scanner, &sent, 80);
scanner.service_retries(Instant::now() + Duration::from_secs(1));
let second = {
let sent = sent.lock().unwrap();
let (segment, _, _) = sent.last().expect("retry sent");
let tcp = TcpPacket::new(segment).unwrap();
SynToken {
seq: tcp.get_sequence(),
src_port: tcp.get_source(),
}
};
assert_ne!(first.seq, second.seq, "each attempt needs its own identity");
scanner.handle_reply(TARGET, &tcp_segment(80, first, SYN | ACK), Instant::now());
assert_eq!(port_state(&session, 80), Some(PortState::Open));
}
#[test]
fn a_duplicate_reply_resolves_nothing_further() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(80, token, SYN | ACK);
scanner.handle_reply(TARGET, &reply, Instant::now());
scanner.handle_reply(TARGET, &reply, Instant::now());
let host = session.store.get(&TARGET).expect("host recorded");
assert_eq!(host.ports().filter(|p| p.number() == 80).count(), 1);
}
#[test]
fn the_scan_budget_covers_the_whole_retry_schedule() {
let lifetime = RETRY_POLICY.worst_case_probe_lifetime();
let budget = DEADLINE_CONFIG
.allowing_for(lifetime)
.max_budget
.for_target_count(1);
assert!(
budget > lifetime,
"a {budget:?} scan cannot finish a {lifetime:?} probe"
);
}
}