use std::net::IpAddr;
use std::time::{Duration, Instant};
use async_trait::async_trait;
use pnet_packet::ip::IpNextHeaderProtocols;
use tokio::sync::mpsc;
use crate::config::OsDetection;
use crate::config::ProbeTuning;
use crate::config::ServiceDetection;
use crate::evasion::SegmentShaping;
use crate::fingerprint::os;
use crate::journal::settle::Outcome;
use crate::model::capture::IpObservation;
use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
use crate::model::port::discovery::{Discovery as PortDiscovery, ScanResponse};
use crate::model::port::{PortState, Protocol};
use crate::model::target::PlannedTarget;
use crate::model::technique::{TcpReply, TcpScanTechnique};
use crate::protocols::tcp;
use crate::report::ScannerKind;
use crate::scanner::service;
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::{PortScanner, StrategyError};
use crate::success;
use crate::system::interface::SourceResolver;
use crate::transport::capture::CapturedSegment;
use crate::transport::probe::{Emission, ProbeKind, ProbeSender, ProbeTransport, SendError};
use super::PORT_RETRY_POLICY;
use super::{AuditLabels, CoreParts, ProbeTarget, RawPortScan, RawProbeScan};
use crate::scanner::strategy::icmp_error::{self, Unreachable};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TcpToken {
nonce: u32,
}
pub struct TcpPortScanner {
technique: TcpScanTechnique,
flags_override: Option<u8>,
core: RawProbeScan<TcpToken>,
os_detection: OsDetection,
service_detection: ServiceDetection,
}
impl TcpPortScanner {
pub fn new(
resolver: SourceResolver,
ctx: ScanContext,
technique: TcpScanTechnique,
target_count: usize,
tuning: ProbeTuning,
) -> Result<Self, StrategyError> {
let src_port: u16 = tuning
.evasion
.source_port_or(rand::random_range(50_000..u16::MAX));
let flags_override = tuning.evasion.flags;
let transport = ProbeTransport::open_with(
ProbeKind::TcpProbe {
reply_port: src_port,
icmp_errors: technique.reads_icmp_errors()
|| flags_override.is_some()
|| tuning.icmp_evidence,
},
tuning.evasion.effective_send_mode(tuning.send_mode),
)?;
Ok(Self::build(
Self::core(resolver, ctx, transport, &tuning, src_port, target_count),
technique,
flags_override,
tuning.os_detection,
tuning.service_detection,
))
}
pub fn with_transport(
resolver: SourceResolver,
ctx: ScanContext,
technique: TcpScanTechnique,
transport: ProbeTransport,
target_count: usize,
) -> Self {
let tuning = ProbeTuning::default();
Self::build(
Self::core(
resolver,
ctx,
transport,
&tuning,
rand::random_range(50_000..u16::MAX),
target_count,
),
technique,
None,
OsDetection::default(),
ServiceDetection::default(),
)
}
fn build(
core: RawProbeScan<TcpToken>,
technique: TcpScanTechnique,
flags_override: Option<u8>,
os_detection: OsDetection,
service_detection: ServiceDetection,
) -> Self {
Self {
technique,
flags_override,
os_detection,
service_detection,
core,
}
}
fn core(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
tuning: &ProbeTuning,
src_port: u16,
target_count: usize,
) -> RawProbeScan<TcpToken> {
let retry = PORT_RETRY_POLICY.configured(tuning.retry);
let rate = super::super::raw::rate_within(
tuning.max_probe_rate,
tuning.min_probe_rate,
super::TCP_PORT_RATE_CEILING,
);
RawProbeScan::new(CoreParts {
resolver,
ctx,
transport,
tuning,
src_port,
target_count,
retry,
rate,
deadline: super::super::raw::DEADLINE_CONFIG,
window: super::TCP_PORT_WINDOW,
max_unresolved: super::TCP_PORT_UNRESOLVED,
})
}
fn handle_tcp_reply(&mut self, captured: &CapturedSegment, now: Instant) {
let (ip, bytes) = (captured.source, &captured.bytes);
let Ok(tcp_packet) = tcp::parse(bytes) else {
self.core.audit.record_off_target();
return;
};
if tcp_packet.source_port() == self.core.src_port
&& tcp_packet.destination_port() != self.core.src_port
{
self.witness_probe(captured, &tcp_packet);
return;
}
if tcp_packet.destination_port() != self.core.src_port {
self.core.audit.record_off_target();
return;
}
let Some(reply) = tcp::classify_probe_response(&tcp_packet) else {
self.core.audit.record_off_target();
return;
};
let state = if self.arbitrary_flags() {
PortState::Unfiltered
} else {
match self.technique.verdict(reply) {
Some(state) => state,
None => return,
}
};
let token = TcpToken {
nonce: tcp::echoed_nonce_with_flags(
self.effective_flags(),
&tcp_packet,
self.core.shaping.padding.unwrap_or(0),
),
};
let key = (ip, tcp_packet.source_port());
let resolved = self.resolve_probe(
key,
Some(token),
state,
Answer {
drawn_by: Some(reply),
sender: None,
ttl: captured.observation.map(IpObservation::remaining_hops),
},
now,
);
if resolved {
self.identify_stack(ip, state, captured);
}
}
fn witness_probe(&mut self, captured: &CapturedSegment, probe: &tcp::Segment<'_>) {
let Some(destination) = captured.destination else {
return;
};
let token = TcpToken {
nonce: tcp::sent_nonce_with_flags(self.effective_flags(), probe),
};
if self
.core
.ledger
.witness(&(destination, probe.destination_port()), &token)
{
self.core.audit.record_witnessed_send();
}
}
fn identify_stack(&self, ip: IpAddr, state: PortState, captured: &CapturedSegment) {
let Some(observation) = captured.observation else {
return;
};
self.core.ctx.update_host(ip, |host| {
host.record_hop_counter(observation.remaining_hops())
});
if !self.os_detection.is_enabled() || state != PortState::Open {
return;
}
let Some(stack) = os::classify_reply(observation, &captured.bytes) else {
return;
};
self.core.ctx.update_host(ip, |host| {
os::identify(host, [stack.as_evidence()]);
});
}
fn handle_icmp_error(&mut self, reply: &CapturedSegment, now: Instant) {
let Some(error) = icmp_error::parse(reply) else {
return;
};
if error.quoted.protocol != IpNextHeaderProtocols::Tcp {
return;
}
let Some(quoted) = tcp::quoted_probe(error.quoted.payload) else {
return;
};
if quoted.source != self.core.src_port {
return;
}
let key = (error.quoted.destination, quoted.destination);
let token = tcp::quoted_nonce_with_flags(self.effective_flags(), "ed)
.map(|nonce| TcpToken { nonce });
match error.reason {
Unreachable::Host => {
self.core.record_host_down(&key, token, reply.source);
}
Unreachable::Port | Unreachable::Prohibited | Unreachable::Protocol
if token.is_none() =>
{
self.core.audit.record_reply_without_rtt();
}
Unreachable::Port | Unreachable::Prohibited | Unreachable::Protocol => {
self.resolve_probe(
key,
token,
PortState::Filtered,
Answer {
drawn_by: None,
sender: Some(reply.source),
ttl: reply.observation.map(IpObservation::remaining_hops),
},
now,
);
}
}
}
fn resolve_probe(
&mut self,
key: ProbeTarget,
token: Option<TcpToken>,
state: PortState,
answer: Answer,
now: Instant,
) -> bool {
let Some(resolution) = self.core.ledger.resolve(&key, token, now) else {
self.core.audit.record_reply_without_rtt();
return false;
};
let rtt = resolution.rtt;
self.core.record_answer(&resolution);
self.record_port_answered_by(key.0, key.1, state, answer, rtt);
self.settle(Outcome::Answered {
position: resolution.payload,
});
true
}
const fn status_protocol(&self) -> StatusProtocol {
match self.technique {
TcpScanTechnique::Syn => StatusProtocol::TcpSyn,
_ => StatusProtocol::Tcp,
}
}
fn effective_flags(&self) -> u8 {
self.flags_override
.unwrap_or_else(|| tcp::probe_flags(self.technique))
}
const fn arbitrary_flags(&self) -> bool {
self.flags_override.is_some()
}
}
impl RawPortScan for TcpPortScanner {
type Token = TcpToken;
fn core(&self) -> &RawProbeScan<TcpToken> {
&self.core
}
fn core_mut(&mut self) -> &mut RawProbeScan<TcpToken> {
&mut self.core
}
fn protocol(&self) -> Protocol {
Protocol::Tcp
}
fn silence_means(&self) -> PortState {
if self.arbitrary_flags() {
PortState::OpenFiltered
} else {
self.technique.silence_means()
}
}
fn audit_labels(&self) -> AuditLabels {
AuditLabels {
tag: "tcp-port",
silence: "unanswered",
}
}
fn handle_reply(&mut self, reply: &CapturedSegment, now: Instant) {
match reply.protocol {
IpNextHeaderProtocols::Tcp => self.handle_tcp_reply(reply, now),
_ => self.handle_icmp_error(reply, now),
}
}
fn record_port(&mut self, ip: IpAddr, port_num: u16, state: PortState, sender: Option<IpAddr>) {
self.record_port_answered_by(
ip,
port_num,
state,
Answer {
sender,
..Answer::default()
},
None,
);
}
fn send(&mut self, ip: IpAddr, port: u16, position: Option<u64>, now: Instant) {
let Some(src_addr) = self.core.resolver.resolve(ip) else {
self.core.record_no_route(ip);
return;
};
let first_attempt = position.is_some();
let token = send_tcp_probe(
self.core.transport.tx.as_ref(),
self.technique,
self.effective_flags(),
self.core.src_port,
src_addr,
ip,
self.core.resolver.zone_of(ip),
port,
self.core.emission,
self.core.shaping,
&self.core.decoys,
);
self.core
.record_send((ip, port), token.as_ref().map(|_| ()), first_attempt);
if let Ok(token) = token {
match position {
Some(position) => self.core.ledger.arm(ip, (ip, port), token, position, now),
None => self.core.ledger.rearm(ip, (ip, port), token, now),
}
}
}
}
impl TcpPortScanner {
fn record_port_answered_by(
&mut self,
ip: IpAddr,
port_num: u16,
state: PortState,
answer: Answer,
rtt: Option<Duration>,
) {
let Answer {
drawn_by, sender, ..
} = answer;
let port = crate::fingerprint::baseline_port(port_num, Protocol::Tcp, state);
let port = match port_evidence(state, drawn_by, sender, ip) {
Some(reason) => {
let mut discovery = PortDiscovery::new(reason);
if let Some(rtt) = rtt {
discovery = discovery.with_rtt(rtt);
}
if let Some(ttl) = answer.ttl {
discovery = discovery.with_ttl(ttl);
}
port.with_discovery(discovery)
}
None => port,
};
let evidence = match (state, sender) {
(PortState::Open, _) => Some((
HostStatus::Up,
match drawn_by {
Some(TcpReply::Rst { .. }) => {
StatusReason::new(self.status_protocol(), rst_evidence(self.technique))
}
Some(TcpReply::ChallengeAck) => StatusReason::new(
StatusProtocol::TcpSyn,
"challenge ack from a probed port, so a listener holds it half-open",
),
_ => StatusReason::new(StatusProtocol::TcpSyn, "syn-ack from a probed port"),
},
)),
(PortState::Closed | PortState::Unfiltered, _) => Some((
HostStatus::Up,
StatusReason::new(self.status_protocol(), rst_evidence(self.technique)),
)),
(PortState::Filtered, Some(sender)) if sender == ip => Some((
HostStatus::Up,
StatusReason::new(
StatusProtocol::IcmpUnreachable,
"unreachable for a probed port, from the host",
),
)),
(PortState::Filtered, Some(sender)) => Some((
HostStatus::Filtered,
StatusReason::new(
StatusProtocol::IcmpUnreachable,
"unreachable for a probed port, from the path",
)
.from_source(sender),
)),
_ => None,
};
let timed = rtt.filter(|_| drawn_by.is_some());
let protocol = self.status_protocol();
self.core.ctx.update_host(ip, |host| {
host.add_port(port);
if let Some((status, reason)) = evidence {
host.record_evidence(status, reason);
}
if let Some(rtt) = timed {
host.add_rtt_from(rtt, protocol);
}
});
}
}
#[derive(Debug, Clone, Copy, Default)]
struct Answer {
drawn_by: Option<TcpReply>,
sender: Option<IpAddr>,
ttl: Option<u8>,
}
fn port_evidence(
state: PortState,
drawn_by: Option<TcpReply>,
sender: Option<IpAddr>,
target: IpAddr,
) -> Option<ScanResponse> {
match (state, drawn_by, sender) {
(PortState::Open, Some(TcpReply::Rst { .. }), _) => Some(ScanResponse::TcpRst),
(PortState::Open, _, _) => Some(ScanResponse::TcpSynAck),
(PortState::Closed | PortState::Unfiltered, _, _) => Some(ScanResponse::TcpRst),
(PortState::Filtered, _, Some(from)) => Some(match from == target {
true => ScanResponse::IcmpProhibited,
false => ScanResponse::IcmpUnreachable,
}),
(PortState::Filtered, None, None) => Some(ScanResponse::NoResponse),
_ => None,
}
}
const fn rst_evidence(technique: TcpScanTechnique) -> &'static str {
match technique {
TcpScanTechnique::Syn => "rst from a probed port",
TcpScanTechnique::Fin => "rst to a fin probe",
TcpScanTechnique::Null => "rst to a flagless probe",
TcpScanTechnique::Xmas => "rst to a fin-psh-urg probe",
TcpScanTechnique::Maimon => "rst to a fin-ack probe",
TcpScanTechnique::Ack => "rst to an ack probe",
TcpScanTechnique::Window => "rst to an ack probe, read for its window",
}
}
#[allow(clippy::too_many_arguments)]
fn send_tcp_probe(
sender: &dyn ProbeSender,
technique: TcpScanTechnique,
flags: u8,
src_port: u16,
src_addr: IpAddr,
dst_addr: IpAddr,
dst_zone: Option<u32>,
dst_port: u16,
emission: Emission,
shaping: SegmentShaping,
decoys: &[IpAddr],
) -> Result<TcpToken, SendError> {
let nonce: u32 = rand::random();
let packet = tcp::build_probe_with_flags(
flags,
src_addr,
dst_addr,
src_port,
dst_port,
nonce,
shaping.padding,
shaping.bad_tcp_checksum,
)
.map_err(|e| SendError::Refused(format!("the {technique} probe could not be built: {e}")))?;
let decoy_packets: Vec<(IpAddr, Vec<u8>)> = decoys
.iter()
.filter(|decoy| decoy.is_ipv4() == dst_addr.is_ipv4())
.filter_map(|&decoy| {
tcp::build_probe_with_flags(
flags,
decoy,
dst_addr,
rand::random_range(50_000..u16::MAX),
dst_port,
rand::random(),
shaping.padding,
shaping.bad_tcp_checksum,
)
.ok()
.map(|packet| (decoy, packet))
})
.collect();
super::super::raw::emit_among_decoys(
sender,
dst_addr,
dst_zone,
emission,
src_addr,
&packet,
&decoy_packets,
)?;
success!(
verbosity = 2,
"sent {technique} probe to {dst_addr}:{dst_port}"
);
Ok(TcpToken { nonce })
}
#[async_trait]
impl PortScanner for TcpPortScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::for_raw_tcp(self.technique)
}
fn supported_protocols(&self) -> Vec<Protocol> {
vec![Protocol::Tcp]
}
async fn scan(&mut self, targets: mpsc::Receiver<PlannedTarget>) -> Result<(), StrategyError> {
super::drive(self, targets).await;
Ok(())
}
async fn detect_services(&mut self, ctx: &ScanContext) {
service::detect(ctx, self.service_detection, Protocol::Tcp).await;
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::model::target::Target;
use std::net::Ipv4Addr;
use std::time::Duration;
use pnet_packet::icmp::destination_unreachable::{
DestinationUnreachablePacket, IcmpCodes, MutableDestinationUnreachablePacket,
};
use pnet_packet::icmp::{IcmpCode, IcmpTypes};
use pnet_packet::tcp::MutableTcpPacket;
use crate::protocols::ip;
use crate::scanner::session::ScanSession;
use crate::transport::probe::{MockSender, ProbeTransport};
const SYN: u8 = 1 << 1;
const RST: u8 = 1 << 2;
const PSH: u8 = 1 << 3;
const ACK: u8 = 1 << 4;
const TARGET: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 200));
const LOCAL: Ipv4Addr = Ipv4Addr::new(192, 0, 2, 50);
const LOCAL_IP: IpAddr = IpAddr::V4(LOCAL);
const ROUTER: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1));
fn on_link_interface() -> crate::system::interface::Link {
use crate::system::interface::{Link, LinkAddress};
use std::net::{Ipv4Addr, Ipv6Addr};
Link::new("test0", 0).with_addresses(vec![
LinkAddress::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 50)), 24),
LinkAddress::new(
IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 50)),
64,
),
])
}
fn segment_to(
from_port: u16,
to_port: u16,
technique: TcpScanTechnique,
token: TcpToken,
flags: u8,
) -> Vec<u8> {
let mut buf = vec![0u8; 20];
let mut tcp = MutableTcpPacket::new(&mut buf).unwrap();
tcp.set_source(from_port);
tcp.set_destination(to_port);
tcp.set_data_offset(5);
tcp.set_flags(flags);
match technique {
TcpScanTechnique::Maimon | TcpScanTechnique::Ack | TcpScanTechnique::Window => {
tcp.set_sequence(token.nonce)
}
TcpScanTechnique::Null => tcp.set_acknowledgement(token.nonce),
_ => tcp.set_acknowledgement(token.nonce.wrapping_add(1)),
}
buf
}
fn tcp_segment(
scanner: &TcpPortScanner,
from_port: u16,
token: TcpToken,
flags: u8,
) -> Vec<u8> {
segment_to(
from_port,
scanner.core.src_port,
scanner.technique,
token,
flags,
)
}
type SentProbes = std::sync::Arc<std::sync::Mutex<Vec<crate::transport::probe::SentProbe>>>;
struct RefusingSender;
impl crate::transport::probe::ProbeSender for RefusingSender {
fn send(
&self,
_segment: &[u8],
_src: IpAddr,
_dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), crate::transport::probe::SendError> {
Err(crate::transport::probe::SendError::Refused(
"no route to host".to_string(),
))
}
}
fn scanner_with_mock() -> (TcpPortScanner, ScanSession, SentProbes) {
scanner_for(TcpScanTechnique::Syn)
}
fn scanner_for(technique: TcpScanTechnique) -> (TcpPortScanner, ScanSession, SentProbes) {
let (session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let sender = MockSender::default();
let sent = sender.sent.clone();
let transport = ProbeTransport::from_parts(Box::new(sender), reply_rx);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let scanner = TcpPortScanner::with_transport(resolver, ctx, technique, transport, 8);
(scanner, session, sent)
}
fn probe(scanner: &mut TcpPortScanner, sent: &SentProbes, port: u16) -> TcpToken {
let before = sent.lock().unwrap().len();
scanner.send_probe(PlannedTarget::new(
u64::from(port),
Target {
ip: TARGET,
port,
protocol: Protocol::Tcp,
},
));
let sent = sent.lock().unwrap();
let (segment, _, _) = sent.get(before).expect("probe reached the wire");
token_of(scanner.technique, segment)
}
fn token_of(technique: TcpScanTechnique, segment: &[u8]) -> TcpToken {
let tcp = tcp::parse(segment).expect("probe is a TCP segment");
TcpToken {
nonce: match technique {
TcpScanTechnique::Maimon | TcpScanTechnique::Ack | TcpScanTechnique::Window => {
tcp.acknowledgement()
}
_ => tcp.sequence(),
},
}
}
fn last_probe(technique: TcpScanTechnique, sent: &SentProbes) -> TcpToken {
let sent = sent.lock().unwrap();
let (segment, _, _) = sent.last().expect("a probe reached the wire");
token_of(technique, segment)
}
fn port_state(session: &ScanSession, port: u16) -> Option<PortState> {
session
.hosts()
.get(TARGET)
.and_then(|h| h.ports().find(|p| p.number() == port).map(|p| p.state()))
}
#[test]
fn an_answered_port_records_the_packet_that_settled_it() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(&captured_with_ttl(reply, 58), Instant::now());
let discovery = port_discovery(&session, 80).expect("the port carries its evidence");
assert_eq!(discovery.reason(), &ScanResponse::TcpSynAck);
assert_eq!(
discovery.ttl(),
Some(58),
"the hop counter the reply arrived under was not kept"
);
}
#[test]
fn a_refused_port_records_the_reset_rather_than_a_silence() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 81);
let reply = tcp_segment(&scanner, 81, token, RST | ACK);
scanner.handle_tcp_reply(&captured_with_ttl(reply, 64), Instant::now());
let discovery = port_discovery(&session, 81).expect("the port carries its evidence");
assert_eq!(discovery.reason(), &ScanResponse::TcpRst);
assert_eq!(discovery.ttl(), Some(64));
}
#[test]
fn a_reply_with_no_header_behind_it_claims_no_hop_counter() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply),
Instant::now(),
);
let discovery = port_discovery(&session, 80).expect("the port carries its evidence");
assert_eq!(discovery.reason(), &ScanResponse::TcpSynAck);
assert_eq!(discovery.ttl(), None);
}
#[test]
fn a_probe_the_sender_refused_leaves_the_port_unasked() {
let (session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let transport = ProbeTransport::from_parts(Box::new(RefusingSender), reply_rx);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let mut scanner =
TcpPortScanner::with_transport(resolver, ctx, TcpScanTechnique::Syn, transport, 8);
scanner.send_probe(PlannedTarget::new(
80,
Target {
ip: TARGET,
port: 80,
protocol: Protocol::Tcp,
},
));
assert_eq!(
port_state(&session, 80),
Some(PortState::Unasked),
"a port whose probe never left this machine went missing from the host"
);
assert!(
!scanner.core.ledger.contains(&(TARGET, 80)),
"a probe that never went out must not be waiting for an answer"
);
}
#[test]
fn an_unanswered_port_records_the_silence() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
scanner.record_port(TARGET, 80, PortState::Filtered, None);
assert_eq!(port_state(&session, 80), Some(PortState::Filtered));
let discovery = port_discovery(&session, 80).expect("the silence is evidence too");
assert_eq!(discovery.reason(), &ScanResponse::NoResponse);
assert_eq!(discovery.rtt(), None, "nothing arrived to be timed");
assert_eq!(discovery.ttl(), None, "and nothing carried a hop count");
}
#[test]
fn a_refusal_is_not_recorded_as_a_silence() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 81);
scanner.record_port(TARGET, 81, PortState::Filtered, Some(TARGET));
let discovery = port_discovery(&session, 81).expect("the refusal is evidence");
assert_eq!(discovery.reason(), &ScanResponse::IcmpProhibited);
}
fn captured_with_ttl(bytes: Vec<u8>, ttl: u8) -> CapturedSegment {
CapturedSegment {
received_at: Instant::now(),
source: TARGET,
destination: None,
protocol: IpNextHeaderProtocols::Tcp,
bytes,
observation: Some(IpObservation::V4(crate::model::capture::Ipv4Observation {
ttl,
identification: 0,
dont_fragment: true,
more_fragments: false,
dscp: 0,
ecn: 0,
})),
source_mac: None,
}
}
#[test]
fn a_segment_answering_no_probe_of_this_scan_records_no_host() {
let (mut scanner, session, _sent) = scanner_with_mock();
let stray = tcp_segment(&scanner, 443, TcpToken { nonce: 0 }, SYN | ACK);
scanner.handle_tcp_reply(&captured_with_ttl(stray, 64), Instant::now());
assert_eq!(
session.hosts().len(),
0,
"a stray segment invented a host: {:?}",
session.hosts().get(TARGET)
);
}
fn own_probe_leaving(bytes: Vec<u8>) -> CapturedSegment {
CapturedSegment {
received_at: Instant::now(),
source: IpAddr::V4(Ipv4Addr::new(192, 0, 2, 2)),
destination: Some(TARGET),
protocol: IpNextHeaderProtocols::Tcp,
bytes,
observation: None,
source_mac: None,
}
}
fn last_sent(sent: &SentProbes) -> Vec<u8> {
sent.lock().unwrap().last().expect("a probe").0.clone()
}
#[test]
fn a_probe_seen_leaving_is_witnessed_against_its_own_attempt() {
let (mut scanner, _session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
assert!(
!scanner.core.audit.witnesses_its_sends(),
"nothing has been seen yet"
);
scanner.handle_reply(&own_probe_leaving(last_sent(&sent)), Instant::now());
assert_eq!(scanner.core.audit.sends_witnessed(), 1);
assert!(
scanner.core.ledger.contains(&(TARGET, 80)),
"a sighting is not an answer, and must not settle the port"
);
}
#[test]
fn the_same_probe_seen_twice_is_witnessed_once() {
let (mut scanner, _session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
let frame = last_sent(&sent);
scanner.handle_reply(&own_probe_leaving(frame.clone()), Instant::now());
scanner.handle_reply(&own_probe_leaving(frame), Instant::now());
assert_eq!(scanner.core.audit.sends_witnessed(), 1);
}
#[test]
fn a_stranger_on_the_scans_own_port_witnesses_nothing() {
let (mut scanner, _session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
let mut frame = last_sent(&sent);
frame[4] ^= 0xFF;
scanner.handle_reply(&own_probe_leaving(frame), Instant::now());
assert_eq!(scanner.core.audit.sends_witnessed(), 0);
assert_eq!(scanner.core.audit.segments_off_target, 0);
}
fn port_discovery(
session: &ScanSession,
port: u16,
) -> Option<crate::model::port::discovery::Discovery> {
session
.hosts()
.get(TARGET)?
.ports()
.find_map(|probed| (probed.number() == port).then(|| probed.discovery().cloned()))?
}
#[test]
fn syn_ack_matching_probe_is_open() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 80), Some(PortState::Open));
assert!(!scanner.core.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);
let reply = tcp_segment(&scanner, 81, token, RST | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 81), Some(PortState::Closed));
}
#[test]
fn an_arbitrary_flag_combination_reads_reachable_not_open_or_closed() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Syn);
scanner.flags_override = Some(SYN | PSH);
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, RST | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply),
Instant::now(),
);
assert_eq!(
port_state(&session, 80),
Some(PortState::Unfiltered),
"a reply to an arbitrary combination proves only reachability"
);
assert_eq!(
scanner.silence_means(),
PortState::OpenFiltered,
"and its silence is open-filtered, not a SYN's plain filtered"
);
}
#[test]
fn reply_carrying_the_wrong_nonce_is_ignored() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 82);
let stray = TcpToken {
nonce: token.nonce.wrapping_add(999),
};
let reply = tcp_segment(&scanner, 82, stray, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 82), None);
assert!(scanner.core.ledger.contains(&(TARGET, 82)));
}
#[test]
fn reply_addressed_to_another_port_on_this_host_is_ignored() {
let (mut scanner, session, sent) = scanner_with_mock();
let token = probe(&mut scanner, &sent, 83);
let elsewhere = scanner.core.src_port.wrapping_add(1);
let reply = segment_to(83, elsewhere, scanner.technique, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 83), None);
assert!(scanner.core.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);
let reply = tcp_segment(&scanner, 1234, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 1234), None);
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
}
#[test]
fn unanswered_probes_resolve_as_filtered() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 443);
super::super::run_out(&mut scanner);
assert_eq!(port_state(&session, 443), Some(PortState::Filtered));
assert!(scanner.core.ledger.is_empty());
}
#[test]
fn a_rst_is_read_according_to_the_probe_that_drew_it() {
for (technique, expected) in [
(TcpScanTechnique::Syn, PortState::Closed),
(TcpScanTechnique::Fin, PortState::Closed),
(TcpScanTechnique::Null, PortState::Closed),
(TcpScanTechnique::Xmas, PortState::Closed),
(TcpScanTechnique::Maimon, PortState::Closed),
(TcpScanTechnique::Ack, PortState::Unfiltered),
(TcpScanTechnique::Window, PortState::Closed),
] {
let (mut scanner, session, sent) = scanner_for(technique);
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, RST | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 80), Some(expected), "{technique}");
}
}
#[test]
fn a_rst_proves_the_host_is_up_whatever_it_says_about_the_port() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, RST | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
let host = session.hosts().get(TARGET).expect("host recorded");
assert!(host.status().is_up());
}
#[test]
fn a_window_scan_reads_an_open_port_out_of_a_reset() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Window);
let token = probe(&mut scanner, &sent, 80);
let mut reply = tcp_segment(&scanner, 80, token, RST | ACK);
MutableTcpPacket::new(&mut reply)
.expect("the reply is a TCP segment")
.set_window(8192);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply),
Instant::now(),
);
assert_eq!(port_state(&session, 80), Some(PortState::Open));
let host = session.hosts().get(TARGET).expect("host recorded");
assert!(host.status().is_up());
assert!(
host.reasons().iter().all(|reason| reason
.details
.as_deref()
.is_some_and(|details| details.contains("rst"))),
"an open port drawn by a reset was credited to a handshake"
);
}
#[test]
fn a_syn_ack_resolves_nothing_for_a_flag_probe() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
let token = probe(&mut scanner, &sent, 80);
let reply = tcp_segment(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 80), None);
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
}
#[test]
fn silence_is_filtered_or_open_filtered_by_technique() {
for (technique, expected) in [
(TcpScanTechnique::Syn, PortState::Filtered),
(TcpScanTechnique::Ack, PortState::Filtered),
(TcpScanTechnique::Window, PortState::Filtered),
(TcpScanTechnique::Fin, PortState::OpenFiltered),
(TcpScanTechnique::Null, PortState::OpenFiltered),
(TcpScanTechnique::Xmas, PortState::OpenFiltered),
(TcpScanTechnique::Maimon, PortState::OpenFiltered),
] {
let (mut scanner, session, sent) = scanner_for(technique);
probe(&mut scanner, &sent, 443);
super::super::run_out(&mut scanner);
assert_eq!(port_state(&session, 443), Some(expected), "{technique}");
}
}
#[test]
fn an_unanswered_probe_says_nothing_about_the_host() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Xmas);
probe(&mut scanner, &sent, 443);
super::super::run_out(&mut scanner);
let host = session.hosts().get(TARGET).expect("the port was recorded");
assert!(!host.status().is_up());
}
#[test]
fn the_reported_strategy_names_the_probe_that_was_sent() {
assert_eq!(
scanner_for(TcpScanTechnique::Syn).0.kind(),
ScannerKind::SynPort
);
assert_eq!(
scanner_for(TcpScanTechnique::Fin).0.kind(),
ScannerKind::TcpPort
);
}
fn icmp_error_quoting(code: IcmpCode, quoted: &[u8], from: IpAddr) -> CapturedSegment {
let quotation = quote(quoted);
let mut bytes =
vec![0u8; DestinationUnreachablePacket::minimum_packet_size() + quotation.len()];
let mut packet = MutableDestinationUnreachablePacket::new(&mut bytes).unwrap();
packet.set_icmp_type(IcmpTypes::DestinationUnreachable);
packet.set_icmp_code(code);
packet.set_payload("ation);
CapturedSegment::synthetic(from, IpNextHeaderProtocols::Icmp, bytes)
}
fn quote(probe: &[u8]) -> Vec<u8> {
let header = ip::build_ipv4_header(
LOCAL,
match TARGET {
IpAddr::V4(v4) => v4,
IpAddr::V6(_) => unreachable!("the fixture is v4"),
},
probe.len() as u16,
IpNextHeaderProtocols::Tcp,
ip::HOP_LIMIT_ROUTED,
)
.unwrap();
header.into_iter().chain(probe.iter().copied()).collect()
}
fn last_probe_bytes(sent: &SentProbes) -> Vec<u8> {
let sent = sent.lock().unwrap();
sent.last().expect("a probe reached the wire").0.clone()
}
#[test]
fn a_port_unreachable_about_a_tcp_probe_is_filtered_not_closed() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::DestinationPortUnreachable,
&last_probe_bytes(&sent),
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(port_state(&session, 80), Some(PortState::Filtered));
assert!(scanner.core.ledger.is_empty());
}
#[test]
fn an_administrative_rejection_beats_the_silence_verdict() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Xmas);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&last_probe_bytes(&sent),
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(port_state(&session, 80), Some(PortState::Filtered));
assert_ne!(port_state(&session, 80), Some(PortState::OpenFiltered));
}
#[test]
fn a_rejection_from_the_path_does_not_prove_the_host_is_up() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&last_probe_bytes(&sent),
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
let host = session.hosts().get(TARGET).expect("host recorded");
assert_eq!(host.status(), HostStatus::Filtered);
}
#[test]
fn a_rejection_from_the_host_proves_it_is_up() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&last_probe_bytes(&sent),
TARGET,
);
scanner.handle_reply(&error, Instant::now());
let host = session.hosts().get(TARGET).expect("host recorded");
assert!(host.status().is_up());
}
#[tokio::test]
async fn a_neighbour_the_kernel_never_resolves_is_asked_once_and_reported_unreached() {
use crate::transport::kernel_neighbors::{KernelNeighbors, NeighborState, NeighborTable};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
let reads = Arc::new(AtomicUsize::new(0));
let counted = Arc::clone(&reads);
let table = KernelNeighbors::with_reader(Box::new(move || {
let state = match counted.fetch_add(1, Ordering::SeqCst) {
0 | 1 => NeighborState::Resolving,
_ => NeighborState::Failed,
};
Ok(NeighborTable::from([(TARGET, state)]))
}));
let (session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let sender = MockSender::default();
let sent = sender.sent.clone();
let transport =
ProbeTransport::from_parts(Box::new(sender), reply_rx).with_kernel_neighbors(table);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let mut scanner = TcpPortScanner::with_transport(
resolver,
ctx.clone(),
TcpScanTechnique::Syn,
transport,
8,
);
let (targets, stream) = tokio::sync::mpsc::channel(32);
for port in 1..=20u16 {
targets
.send(PlannedTarget::new(
u64::from(port),
Target {
ip: TARGET,
port,
protocol: Protocol::Tcp,
},
))
.await
.expect("the stream is open");
}
drop(targets);
scanner.scan(stream).await.expect("the scan runs");
assert_eq!(
sent.lock().unwrap().len(),
1,
"one probe went to the kernel"
);
let host = session
.hosts()
.get(TARGET)
.expect("the address is recorded");
assert_eq!(host.ports().count(), 20, "every port is on the host");
assert!(
host.ports().all(|port| port.state() == PortState::Unasked),
"no probe left, so no port was asked"
);
assert_eq!(
ctx.take_unroutable(),
vec![TARGET],
"the address is unreached"
);
assert!(
ctx.failures_snapshot().is_empty(),
"and nothing failed here"
);
}
#[tokio::test]
async fn probes_held_on_a_resolution_spend_none_of_a_rate_ceiling() {
use crate::transport::kernel_neighbors::{KernelNeighbors, NeighborState, NeighborTable};
use std::sync::Arc;
const LIVE: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 60));
const LIVE_PORTS: u16 = 10;
let dead: Vec<IpAddr> = (101..106)
.map(|last| IpAddr::V4(Ipv4Addr::new(192, 0, 2, last)))
.collect();
let sender = MockSender::default();
let sent = sender.sent.clone();
let seen = Arc::clone(&sent);
let neighbours = dead.clone();
let table = KernelNeighbors::with_reader(Box::new(move || {
let live_asked = seen
.lock()
.unwrap()
.iter()
.filter(|(_, _, dst)| *dst == LIVE)
.count();
let state = if live_asked >= usize::from(LIVE_PORTS) {
NeighborState::Failed
} else {
NeighborState::Resolving
};
Ok(neighbours
.iter()
.map(|address| (*address, state))
.chain([(LIVE, NeighborState::Resolved)])
.collect::<NeighborTable>())
}));
let (session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let transport =
ProbeTransport::from_parts(Box::new(sender), reply_rx).with_kernel_neighbors(table);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let targets_total = dead.len() * 20 + usize::from(LIVE_PORTS);
let mut scanner = TcpPortScanner::with_transport(
resolver,
ctx.clone(),
TcpScanTechnique::Syn,
transport,
targets_total,
);
scanner.core_mut().send_tick = Duration::from_millis(10);
scanner.core_mut().batch = 1;
let (targets, stream) = tokio::sync::mpsc::channel(targets_total);
let plan = dead
.iter()
.flat_map(|address| (1..=20u16).map(move |port| (*address, port)))
.chain((1..=LIVE_PORTS).map(|port| (LIVE, port)));
for (position, (ip, port)) in plan.enumerate() {
targets
.send(PlannedTarget::new(
position as u64,
Target {
ip,
port,
protocol: Protocol::Tcp,
},
))
.await
.expect("the stream is open");
}
drop(targets);
scanner.scan(stream).await.expect("the scan runs");
let live = session
.hosts()
.get(LIVE)
.expect("the live host is recorded");
for port in live.ports() {
assert_ne!(
port.state(),
PortState::Unasked,
"the live host's port {} was never asked",
port.number()
);
}
let unreached = ctx.take_unroutable();
for address in &dead {
assert!(
unreached.contains(address),
"{address} is unreached: {unreached:?}"
);
}
let to_dead = sent
.lock()
.unwrap()
.iter()
.filter(|(_, _, dst)| dead.contains(dst))
.count();
assert_eq!(
to_dead,
dead.len(),
"one probe each started the resolutions"
);
}
#[tokio::test]
async fn the_deadline_allows_for_the_time_the_sender_spends_resolving() {
use std::sync::{Arc, Mutex};
struct Resolving {
asked: Arc<Mutex<Vec<IpAddr>>>,
}
impl crate::transport::probe::ProbeSender for Resolving {
fn send(
&self,
_segment: &[u8],
_src: IpAddr,
dst: IpAddr,
_zone: Option<u32>,
_emission: crate::transport::probe::Emission,
) -> Result<(), crate::transport::probe::SendError> {
let first = {
let mut asked = self.asked.lock().unwrap();
let first = !asked.contains(&dst);
asked.push(dst);
first
};
if first {
std::thread::sleep(Duration::from_millis(500));
}
Err(crate::transport::probe::SendError::Unresolved(format!(
"{dst} did not answer address resolution"
)))
}
}
let dead: Vec<IpAddr> = (101..111)
.map(|last| IpAddr::V4(Ipv4Addr::new(192, 0, 2, last)))
.collect();
let asked = Arc::new(Mutex::new(Vec::new()));
let (_session, ctx) = ScanSession::new();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let transport = ProbeTransport::from_parts(
Box::new(Resolving {
asked: Arc::clone(&asked),
}),
reply_rx,
);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let mut scanner = TcpPortScanner::with_transport(
resolver,
ctx.clone(),
TcpScanTechnique::Syn,
transport,
8,
);
let (targets, stream) = tokio::sync::mpsc::channel(256);
for (host, ip) in dead.iter().enumerate() {
for port in 1..=20u16 {
targets
.send(PlannedTarget::new(
(host * 20 + usize::from(port)) as u64,
Target {
ip: *ip,
port,
protocol: Protocol::Tcp,
},
))
.await
.expect("the stream is open");
}
}
drop(targets);
scanner.scan(stream).await.expect("the scan runs");
let asked = asked.lock().unwrap();
for ip in &dead {
assert!(asked.contains(ip), "{ip} was never asked");
}
assert_eq!(ctx.take_unroutable(), dead, "every address is unreached");
}
#[test]
fn a_host_unreachable_leaves_the_port_undecided() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::DestinationHostUnreachable,
&last_probe_bytes(&sent),
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(port_state(&session, 80), None);
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
assert_eq!(
session.hosts().get(TARGET).map(|host| host.status()),
Some(HostStatus::Down)
);
}
#[test]
fn an_error_quoting_somebody_elses_probe_is_ignored() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let theirs = tcp::build_probe(
TcpScanTechnique::Fin,
LOCAL_IP,
TARGET,
scanner.core.src_port.wrapping_add(1),
80,
0xABCD,
)
.unwrap();
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&theirs,
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(port_state(&session, 80), None);
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
}
#[test]
fn a_truncated_error_resolves_nothing() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
let mut error = icmp_error_quoting(
IcmpCodes::DestinationPortUnreachable,
&last_probe_bytes(&sent),
ROUTER,
);
error.bytes.truncate(12);
scanner.handle_reply(&error, Instant::now());
assert_eq!(port_state(&session, 80), None);
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
}
#[test]
fn non_tcp_targets_are_not_probed() {
let (mut scanner, _session, _sent) = scanner_with_mock();
scanner.send_probe(PlannedTarget::new(
0,
Target {
ip: TARGET,
port: 53,
protocol: Protocol::Udp,
},
));
assert!(scanner.core.ledger.is_empty());
}
#[test]
fn an_unanswered_probe_is_sent_again() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(1));
assert_eq!(sent.lock().unwrap().len(), 2, "the probe was not retried");
assert!(scanner.core.ledger.contains(&(TARGET, 80)));
assert_eq!(port_state(&session, 80), None, "no verdict has been earned");
}
#[test]
fn a_port_whose_probes_were_never_seen_leaving_is_unasked_not_filtered() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
scanner.handle_reply(&own_probe_leaving(last_sent(&sent)), Instant::now());
probe(&mut scanner, &sent, 443);
let mut now = Instant::now();
for _ in 0..PORT_RETRY_POLICY.max_attempts + 2 {
now += Duration::from_secs(4);
super::super::retry_due(&mut scanner, now);
}
assert_eq!(
port_state(&session, 443),
Some(PortState::Unasked),
"silence from a probe nobody saw leave is not a verdict"
);
assert_eq!(
port_state(&session, 80),
Some(PortState::Filtered),
"and a probe that was watched leaving still earns one"
);
}
#[test]
fn a_scan_that_witnesses_nothing_reads_silence_as_it_always_did() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 443);
assert!(!scanner.core.audit.witnesses_its_sends(), "test premise");
let mut now = Instant::now();
for _ in 0..PORT_RETRY_POLICY.max_attempts + 2 {
now += Duration::from_secs(4);
super::super::retry_due(&mut scanner, now);
}
assert_eq!(port_state(&session, 443), Some(PortState::Filtered));
}
#[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..PORT_RETRY_POLICY.max_attempts + 2 {
now += Duration::from_secs(4);
super::super::retry_due(&mut scanner, now);
}
assert_eq!(port_state(&session, 80), Some(PortState::Filtered));
assert_eq!(
sent.lock().unwrap().len(),
usize::from(PORT_RETRY_POLICY.max_attempts),
);
assert!(scanner.core.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);
let reply = tcp_segment(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(10));
assert_eq!(sent.lock().unwrap().len(), 1);
}
#[test]
fn a_retry_overtaken_by_a_late_answer_is_never_sent() {
let (session, ctx) = ScanSession::builder()
.host_probe_interval(Some(Duration::from_secs(3600)))
.build();
let (_reply_tx, reply_rx) = tokio::sync::mpsc::channel(1024);
let sender = MockSender::default();
let sent = sender.sent.clone();
let transport = ProbeTransport::from_parts(Box::new(sender), reply_rx);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let mut scanner =
TcpPortScanner::with_transport(resolver, ctx, TcpScanTechnique::Syn, transport, 8);
let first = probe(&mut scanner, &sent, 80);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(1));
assert_eq!(sent.lock().unwrap().len(), 1, "the retry waits for the gap");
let reply = tcp_segment(&scanner, 80, first, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply),
Instant::now(),
);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(7200));
assert_eq!(
sent.lock().unwrap().len(),
1,
"a retry went out for a port already answered"
);
assert_eq!(scanner.core.window.in_flight(), 0, "a window slot leaked");
assert_eq!(port_state(&session, 80), Some(PortState::Open));
}
#[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);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(1));
let second = last_probe(scanner.technique, &sent);
assert_ne!(
first.nonce, second.nonce,
"each attempt needs its own identity"
);
let reply = tcp_segment(&scanner, 80, first, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
assert_eq!(port_state(&session, 80), Some(PortState::Open));
}
#[test]
fn every_attempt_leaves_from_the_scans_own_port() {
let (mut scanner, _session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 80);
super::super::retry_due(&mut scanner, Instant::now() + Duration::from_secs(1));
let ports: Vec<u16> = sent
.lock()
.unwrap()
.iter()
.map(|(segment, _, _)| tcp::parse(segment).unwrap().source_port())
.collect();
assert_eq!(ports.len(), 2, "the probe was not retried");
assert!(
ports.iter().all(|port| *port == scanner.core.src_port),
"probes left from {ports:?}, not from {}",
scanner.core.src_port
);
}
#[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(&scanner, 80, token, SYN | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, reply.clone()),
Instant::now(),
);
let host = session.hosts().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 = PORT_RETRY_POLICY.worst_case_probe_lifetime();
let budget = crate::scanner::strategy::raw::DEADLINE_CONFIG
.allowing_for(lifetime)
.max_budget
.for_target_count(1);
assert!(
budget > lifetime,
"a {budget:?} scan cannot finish a {lifetime:?} probe"
);
}
struct Path {
answer_after: Option<Duration>,
live: Vec<IpAddr>,
replies: mpsc::Sender<CapturedSegment>,
sent: std::sync::Arc<std::sync::Mutex<Vec<(u16, Instant)>>>,
}
impl ProbeSender for Path {
fn send(
&self,
segment: &[u8],
_src: IpAddr,
dst: IpAddr,
_zone: Option<u32>,
_emission: Emission,
) -> Result<(), SendError> {
let probe = tcp::parse(segment).expect("the scan sends whole segments");
self.sent
.lock()
.unwrap()
.push((probe.destination_port(), Instant::now()));
let Some(delay) = self.answer_after else {
return Ok(());
};
if !self.live.is_empty() && !self.live.contains(&dst) {
return Ok(());
}
let reply = segment_to(
probe.destination_port(),
probe.source_port(),
TcpScanTechnique::Syn,
TcpToken {
nonce: probe.sequence(),
},
SYN | ACK,
);
let replies = self.replies.clone();
tokio::spawn(async move {
tokio::time::sleep(delay).await;
let arrived = CapturedSegment::synthetic(dst, IpNextHeaderProtocols::Tcp, reply);
let _ = replies.send(arrived).await;
});
Ok(())
}
}
type Departures = std::sync::Arc<std::sync::Mutex<Vec<(u16, Instant)>>>;
async fn scan_over_path(
tuning: &ProbeTuning,
answer_after: Option<Duration>,
ports: u16,
) -> (ScanSession, Departures) {
let targets = (1..=ports).map(|port| (TARGET, port)).collect();
scan_targets_over_path(tuning, answer_after, Vec::new(), targets).await
}
async fn scan_targets_over_path(
tuning: &ProbeTuning,
answer_after: Option<Duration>,
live: Vec<IpAddr>,
targets: Vec<(IpAddr, u16)>,
) -> (ScanSession, Departures) {
let (session, ctx) = ScanSession::new();
let (replies, reply_rx) = mpsc::channel(4096);
let sent = Departures::default();
let path = Path {
answer_after,
live,
replies,
sent: std::sync::Arc::clone(&sent),
};
let transport = ProbeTransport::from_parts(Box::new(path), reply_rx);
let resolver = SourceResolver::from_links(&[on_link_interface()]);
let core = TcpPortScanner::core(resolver, ctx, transport, tuning, 54_321, targets.len());
let mut scanner = TcpPortScanner::build(
core,
TcpScanTechnique::Syn,
None,
OsDetection::default(),
ServiceDetection::default(),
);
let (queue, stream) = mpsc::channel(targets.len().max(1));
for (position, (ip, port)) in targets.into_iter().enumerate() {
queue
.send(PlannedTarget::new(
position as u64,
Target {
ip,
port,
protocol: Protocol::Tcp,
},
))
.await
.expect("the stream is open");
}
drop(queue);
scanner.scan(stream).await.expect("the scan runs");
(session, sent)
}
fn busiest_second(sent: &Departures) -> usize {
let departures: Vec<Instant> = sent.lock().unwrap().iter().map(|(_, at)| *at).collect();
departures
.iter()
.map(|start| {
departures
.iter()
.filter(|at| **at >= *start && **at < *start + Duration::from_secs(1))
.count()
})
.max()
.unwrap_or(0)
}
#[tokio::test]
async fn a_rate_limited_scan_asks_every_port_however_long_the_ceiling_makes_it() {
const PORTS: u16 = 300;
let tuning = ProbeTuning {
max_probe_rate: std::num::NonZeroU32::new(100),
retry: crate::config::RetryConfig {
max_attempts: std::num::NonZeroU8::new(1),
..crate::config::RetryConfig::default()
},
..ProbeTuning::default()
};
let (session, _sent) = scan_over_path(&tuning, Some(Duration::from_millis(5)), PORTS).await;
let host = session.hosts().get(TARGET).expect("the target answered");
let unasked: Vec<u16> = host
.ports()
.filter(|port| port.state() == PortState::Unasked)
.map(|port| port.number())
.collect();
assert!(
unasked.is_empty(),
"{} of {PORTS} ports never asked, first {:?}",
unasked.len(),
unasked.first()
);
assert_eq!(host.ports().count(), usize::from(PORTS));
assert!(
host.ports().any(|port| port.state() == PortState::Open),
"the path answered nothing, so the scan proved nothing"
);
}
#[tokio::test]
async fn a_rate_limited_scan_of_a_range_finds_its_hosts_and_asks_every_address() {
const RATE: u32 = 40;
let addresses: Vec<IpAddr> = (100..140)
.map(|last| IpAddr::V4(Ipv4Addr::new(192, 0, 2, last)))
.collect();
let live = vec![addresses[7], addresses[31]];
let targets: Vec<(IpAddr, u16)> = addresses
.iter()
.flat_map(|ip| [(*ip, 22), (*ip, 80)])
.collect();
let tuning = ProbeTuning {
max_probe_rate: std::num::NonZeroU32::new(RATE),
..ProbeTuning::default()
};
let (session, sent) = scan_targets_over_path(
&tuning,
Some(Duration::from_millis(5)),
live.clone(),
targets,
)
.await;
for ip in &addresses {
let host = session.hosts().get(*ip).expect("every address was asked");
let expected = if live.contains(ip) {
PortState::Open
} else {
PortState::Filtered
};
for port in host.ports() {
assert_eq!(port.state(), expected, "{ip}:{}", port.number());
}
assert_eq!(host.ports().count(), 2, "{ip}");
assert_eq!(host.status().is_up(), live.contains(ip), "{ip}");
}
let busiest = busiest_second(&sent);
assert!(
busiest <= RATE as usize + 2,
"{busiest} probes left in one second under a ceiling of {RATE}"
);
}
#[tokio::test]
async fn a_scan_built_from_the_largest_accepted_retry_settings_runs() {
let tuning = ProbeTuning {
retry: crate::config::RetryConfig {
max_attempts: std::num::NonZeroU8::new(u8::MAX),
timeout_scale: crate::config::TimeoutScale::new(f64::MAX),
..crate::config::RetryConfig::default()
},
..ProbeTuning::default()
};
let (session, _sent) = scan_over_path(&tuning, Some(Duration::from_millis(1)), 3).await;
let host = session.hosts().get(TARGET).expect("the target answered");
assert!(host.ports().all(|port| port.state() == PortState::Open));
}
#[tokio::test]
async fn a_host_that_answered_is_credited_its_round_trip() {
let (session, _sent) =
scan_over_path(&ProbeTuning::default(), Some(Duration::from_millis(5)), 3).await;
let host = session.hosts().get(TARGET).expect("the target answered");
assert_eq!(host.rtt_protocol(), Some(StatusProtocol::TcpSyn));
assert!(
host.median_rtt()
.is_some_and(|rtt| rtt >= Duration::from_millis(5)),
"{:?}",
host.median_rtt()
);
}
#[tokio::test]
async fn a_rate_ceiling_holds_retries_to_it_as_well() {
const PORTS: u16 = 100;
const RATE: u32 = 100;
let tuning = ProbeTuning {
max_probe_rate: std::num::NonZeroU32::new(RATE),
retry: crate::config::RetryConfig {
dampen_silent_hosts: false,
..crate::config::RetryConfig::default()
},
..ProbeTuning::default()
};
let (session, sent) = scan_over_path(&tuning, None, PORTS).await;
let attempts = usize::from(PORT_RETRY_POLICY.max_attempts);
assert_eq!(
sent.lock().unwrap().len(),
usize::from(PORTS) * attempts,
"every port asked as often as its budget allows"
);
let busiest = busiest_second(&sent);
assert!(
busiest <= RATE as usize + 2,
"{busiest} probes left in one second under a ceiling of {RATE}"
);
let host = session.hosts().get(TARGET).expect("the ports are recorded");
assert!(host.ports().all(|port| port.state() == PortState::Filtered));
}
fn forged_host_unreachable(
dst: Ipv4Addr,
src_port: u16,
dst_port: u16,
header_bytes: usize,
) -> CapturedSegment {
let mut tcp_header = vec![0u8; 20];
tcp_header[0..2].copy_from_slice(&src_port.to_be_bytes());
tcp_header[2..4].copy_from_slice(&dst_port.to_be_bytes());
tcp_header[4..8].copy_from_slice(&0xDEAD_BEEFu32.to_be_bytes());
tcp_header.truncate(header_bytes);
let ip_header = ip::build_ipv4_header(
LOCAL,
dst,
tcp_header.len() as u16,
IpNextHeaderProtocols::Tcp,
ip::HOP_LIMIT_ROUTED,
)
.expect("an IPv4 header");
let quotation: Vec<u8> = ip_header.into_iter().chain(tcp_header).collect();
let mut bytes =
vec![0u8; DestinationUnreachablePacket::minimum_packet_size() + quotation.len()];
let mut packet =
MutableDestinationUnreachablePacket::new(&mut bytes).expect("an ICMP buffer");
packet.set_icmp_type(IcmpTypes::DestinationUnreachable);
packet.set_icmp_code(IcmpCodes::DestinationHostUnreachable);
packet.set_payload("ation);
CapturedSegment::synthetic(ROUTER, IpNextHeaderProtocols::Icmp, bytes)
}
const TARGET_V4: Ipv4Addr = Ipv4Addr::new(192, 0, 2, 200);
#[test]
fn an_unreachable_naming_an_unprobed_address_records_no_host() {
let (mut scanner, session, _sent) = scanner_for(TcpScanTechnique::Fin);
let never = Ipv4Addr::new(203, 0, 113, 77);
let src = scanner.core.src_port;
scanner.handle_reply(&forged_host_unreachable(never, src, 443, 8), Instant::now());
assert_eq!(session.hosts().len(), 0, "no host may be invented");
assert!(session.hosts().get(IpAddr::V4(never)).is_none());
}
#[test]
fn an_unreachable_quoting_an_unprobed_port_does_not_file_the_host_down() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let src = scanner.core.src_port;
scanner.handle_reply(
&forged_host_unreachable(TARGET_V4, src, 9999, 8),
Instant::now(),
);
assert_ne!(
session.hosts().get(TARGET).map(|host| host.status()),
Some(HostStatus::Down),
"port 9999 was never probed, so this error is about nothing this scan sent"
);
}
#[test]
fn a_live_host_does_not_collect_a_forged_unreachable_as_a_reason() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
let token = probe(&mut scanner, &sent, 80);
let rst = tcp_segment(&scanner, 80, token, RST | ACK);
scanner.handle_tcp_reply(
&CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Tcp, rst),
Instant::now(),
);
let before = session
.hosts()
.get(TARGET)
.map(|host| host.reasons().len())
.expect("the host answered");
let src = scanner.core.src_port;
scanner.handle_reply(
&forged_host_unreachable(TARGET_V4, src, 80, 8),
Instant::now(),
);
let host = session.hosts().get(TARGET).expect("still recorded");
assert!(host.status().is_up(), "the promotion rule holds");
assert_eq!(
host.reasons().len(),
before,
"an unreachable this scan cannot attribute adds no evidence"
);
}
#[test]
fn an_unreachable_quoting_a_real_probe_still_files_the_host_down() {
let (mut scanner, session, sent) = scanner_for(TcpScanTechnique::Fin);
probe(&mut scanner, &sent, 80);
let error = icmp_error_quoting(
IcmpCodes::DestinationHostUnreachable,
&last_probe_bytes(&sent),
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(
session.hosts().get(TARGET).map(|host| host.status()),
Some(HostStatus::Down)
);
assert!(
scanner.core.ledger.contains(&(TARGET, 80)),
"and the port keeps its remaining attempts"
);
}
#[test]
fn a_refusal_quoting_too_little_to_name_the_attempt_resolves_no_port() {
for technique in [
TcpScanTechnique::Ack,
TcpScanTechnique::Window,
TcpScanTechnique::Maimon,
] {
let (mut scanner, session, sent) = scanner_for(technique);
probe(&mut scanner, &sent, 80);
let whole = last_probe_bytes(&sent);
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&whole[..8],
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(
port_state(&session, 80),
None,
"{technique:?}: an eight-byte quotation named no attempt"
);
assert!(
scanner.core.ledger.contains(&(TARGET, 80)),
"{technique:?}: and the probe keeps its remaining attempts"
);
}
}
#[test]
fn a_sequence_nonce_technique_still_resolves_on_the_guaranteed_eight() {
for technique in [
TcpScanTechnique::Syn,
TcpScanTechnique::Fin,
TcpScanTechnique::Null,
TcpScanTechnique::Xmas,
] {
let (mut scanner, session, sent) = scanner_for(technique);
probe(&mut scanner, &sent, 80);
let whole = last_probe_bytes(&sent);
let error = icmp_error_quoting(
IcmpCodes::CommunicationAdministrativelyProhibited,
&whole[..8],
ROUTER,
);
scanner.handle_reply(&error, Instant::now());
assert_eq!(
port_state(&session, 80),
Some(PortState::Filtered),
"{technique:?}: the sequence number is inside the guaranteed eight"
);
}
}
}