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::error;
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};
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,
pace: retry.min_rto / super::TCP_PORT_WINDOW.floor,
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());
self.resolve_probe(
key,
Some(token),
state,
Answer {
drawn_by: Some(reply),
sender: None,
ttl: captured.observation.map(IpObservation::remaining_hops),
},
now,
);
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.0, reply.source),
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,
) {
let Some(resolution) = self.core.ledger.resolve(&key, token, now) else {
self.core.audit.record_reply_without_rtt();
return;
};
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,
});
}
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 {
error!(verbosity = 2, "no route to {ip}; skipping {ip}:{port}");
return;
};
let first_attempt = !self.core.ledger.contains(&(ip, port));
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,
&mut self.core.send_failure,
);
self.core.record_send(ip, token.is_some(), first_attempt);
if let Some(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,
};
self.core.ctx.update_host(ip, |host| {
host.add_port(port);
if let Some((status, reason)) = evidence {
host.record_evidence(status, reason);
}
});
}
}
#[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],
reason: &mut Option<String>,
) -> Option<TcpToken> {
let nonce: u32 = rand::random();
let packet = match tcp::build_probe_with_flags(
flags,
src_addr,
dst_addr,
src_port,
dst_port,
nonce,
shaping.padding,
shaping.bad_tcp_checksum,
) {
Ok(packet) => packet,
Err(e) => {
error!(
verbosity = 2,
"failed to create {technique} probe for {dst_addr}:{dst_port}: {e}"
);
return None;
}
};
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();
match super::super::raw::emit_among_decoys(
sender,
dst_addr,
dst_zone,
emission,
src_addr,
&packet,
&decoy_packets,
) {
Ok(()) => {
success!(
verbosity = 2,
"sent {technique} probe to {dst_addr}:{dst_port}"
);
Some(TcpToken { nonce })
}
Err(e) => {
if reason.is_none() {
error!(
verbosity = 2,
"failed to send {technique} probe to {dst_addr}:{dst_port}: {e:#}"
);
*reason = Some(format!("{e:#}"));
}
None
}
}
}
#[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, 168, 1, 200));
const LOCAL: Ipv4Addr = Ipv4Addr::new(192, 168, 1, 50);
const LOCAL_IP: IpAddr = IpAddr::V4(LOCAL);
const ROUTER: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 168, 1, 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, 168, 1, 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,
}
}
fn own_probe_leaving(bytes: Vec<u8>) -> CapturedSegment {
CapturedSegment {
received_at: Instant::now(),
source: IpAddr::V4(Ipv4Addr::new(192, 168, 1, 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);
scanner.resolve_remaining();
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);
scanner.resolve_remaining();
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);
scanner.resolve_remaining();
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());
}
#[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);
scanner.service_retries(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);
scanner.service_retries(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);
scanner.service_retries(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);
scanner.service_retries(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(),
);
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 = 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);
scanner.service_retries(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"
);
}
}