use std::collections::{BTreeMap, BTreeSet};
use std::net::IpAddr;
use std::time::{Duration, Instant};
use pnet_packet::ip::IpNextHeaderProtocols;
use crate::model::host::IpProtocolState;
use crate::protocols::{icmp, sctp, tcp, udp};
use crate::report::ScannerKind;
use crate::scanner::session::ScanContext;
use crate::scanner::strategy::icmp_error::{self, Unreachable};
use crate::system::interface::SourceResolver;
use crate::transport::frame::IpSegment;
use crate::transport::probe::{Emission, ProbeKind, ProbeTransport};
use crate::transport::raw::{self, TransportSenderHandle};
use crate::{counted, info};
const REPLY_WINDOW: Duration = Duration::from_secs(2);
pub const DEFAULT_PROTOCOLS: [u8; 13] = [1, 2, 4, 6, 17, 41, 47, 50, 51, 89, 103, 112, 132];
fn draw_source_port() -> u16 {
rand::random_range(50_000..u16::MAX)
}
const CLOSED_PORT: u16 = 54_321;
fn draw_echo_identifier() -> u16 {
rand::random()
}
#[derive(Debug, Clone)]
struct Correlation {
source_port: u16,
echo_identifier: u16,
sources: BTreeSet<IpAddr>,
}
impl Correlation {
fn admits(&self, quoted: &IpSegment<'_>, number: u8) -> bool {
if !self.sources.contains("ed.source) {
return false;
}
match Header::of(number, quoted.destination) {
Header::Echo => icmp::echo_token(quoted.payload)
.is_ok_and(|(identifier, _)| identifier == self.echo_identifier),
Header::Tcp => tcp::quoted_probe(quoted.payload)
.is_some_and(|probe| probe.source == self.source_port),
Header::Udp => {
udp_quoted_source(quoted.payload).is_some_and(|port| port == self.source_port)
}
Header::Sctp => sctp::quoted_probe(quoted.payload)
.is_some_and(|probe| probe.source == self.source_port),
Header::Bare => true,
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Header {
Echo,
Tcp,
Udp,
Sctp,
Bare,
}
impl Header {
fn of(number: u8, host: IpAddr) -> Self {
match (number, host) {
(1, IpAddr::V4(_)) | (58, IpAddr::V6(_)) => Self::Echo,
(6, _) => Self::Tcp,
(17, _) => Self::Udp,
(132, _) => Self::Sctp,
_ => Self::Bare,
}
}
}
fn udp_quoted_source(quoted: &[u8]) -> Option<u16> {
let head: &[u8; 2] = quoted.first_chunk()?;
Some(u16::from_be_bytes(*head))
}
pub async fn probe(ctx: &ScanContext, targets: &[IpAddr], protocols: &BTreeSet<u8>) {
if targets.is_empty() || protocols.is_empty() {
return;
}
let Some((mut transport, senders)) = open(ctx, protocols) else {
return;
};
let mut resolver = SourceResolver::from_system();
info!(
"asking {} about {}",
counted(targets.len() as u128, "host", "hosts"),
counted(senders.len() as u128, "IP protocol", "IP protocols")
);
let mut keys = Correlation {
source_port: draw_source_port(),
echo_identifier: draw_echo_identifier(),
sources: BTreeSet::new(),
};
send_probes(ctx, targets, &senders, &mut resolver, &mut keys);
let probed: BTreeSet<IpAddr> = targets.iter().copied().collect();
let asked: BTreeSet<u8> = senders.keys().copied().collect();
collect_replies(ctx, &mut transport, &probed, &asked, &keys).await;
}
fn open(
ctx: &ScanContext,
protocols: &BTreeSet<u8>,
) -> Option<(ProbeTransport, BTreeMap<u8, TransportSenderHandle>)> {
let first = protocols.iter().copied().next()?;
let transport = match ProbeTransport::open_receiver(ProbeKind::IpProtocol { number: first }) {
Ok(transport) => transport,
Err(failure) => {
ctx.record_failure(
ScannerKind::Routed,
format!("no capture to hear IP protocol answers on: {failure}"),
);
return None;
}
};
let mut senders = BTreeMap::new();
for number in protocols.iter().copied() {
match raw::open_sender(raw::TransportType::IpProtocol(number)) {
Ok(handle) => {
senders.insert(number, handle);
}
Err(failure) => ctx.record_failure(
ScannerKind::Routed,
format!("no socket for IP protocol {number}, so it goes unasked: {failure:#}"),
),
}
}
if senders.is_empty() {
ctx.record_failure(
ScannerKind::Routed,
"no raw socket for any IP protocol asked about".to_string(),
);
return None;
}
Some((transport, senders))
}
fn send_probes(
ctx: &ScanContext,
targets: &[IpAddr],
senders: &BTreeMap<u8, TransportSenderHandle>,
resolver: &mut SourceResolver,
keys: &mut Correlation,
) {
for &host in targets {
let Some(source) = resolver.resolve(host) else {
continue;
};
keys.sources.insert(source);
for (&number, sender) in senders {
let payload = probe_payload(number, source, host, keys);
let sent = sender
.send_to(Datagram(&payload), host, None, Emission::routed().hop_limit)
.is_ok();
let state = match sent {
true => IpProtocolState::OpenFiltered,
false => IpProtocolState::Unasked,
};
ctx.update_host(host, |host| {
host.record_ip_protocol(number, state);
});
}
}
}
fn probe_payload(number: u8, source: IpAddr, host: IpAddr, keys: &Correlation) -> Vec<u8> {
let built = match Header::of(number, host) {
Header::Echo => {
icmp::build_echo_request_message(source, host, 0, keys.echo_identifier, 0, &[])
}
Header::Tcp => tcp::build_probe(
crate::model::technique::TcpScanTechnique::Syn,
source,
host,
keys.source_port,
CLOSED_PORT,
rand::random(),
),
Header::Udp => udp::build_packet(source, host, keys.source_port, CLOSED_PORT, Vec::new()),
Header::Sctp => Ok(sctp::build_init_probe(
keys.source_port,
CLOSED_PORT,
rand::random(),
)),
Header::Bare => return Vec::new(),
};
built.unwrap_or_default()
}
async fn collect_replies(
ctx: &ScanContext,
transport: &mut ProbeTransport,
probed: &BTreeSet<IpAddr>,
asked: &BTreeSet<u8>,
keys: &Correlation,
) {
let deadline = Instant::now() + REPLY_WINDOW;
loop {
if ctx.handle.should_stop() {
return;
}
let remaining = deadline.saturating_duration_since(Instant::now());
if remaining.is_zero() {
return;
}
match tokio::time::timeout(remaining, transport.rx.recv()).await {
Ok(Some(reply)) => {
if let Some((host, number, state)) = matched(&reply, probed, asked, keys) {
ctx.update_host(host, |host| {
host.record_ip_protocol(number, state);
});
}
}
Ok(None) | Err(_) => return,
}
}
}
fn matched(
reply: &crate::transport::capture::CapturedSegment,
probed: &BTreeSet<IpAddr>,
asked: &BTreeSet<u8>,
keys: &Correlation,
) -> Option<(IpAddr, u8, IpProtocolState)> {
if let Some(error) = icmp_error::parse(reply) {
let host = error.quoted.destination;
let number = error.quoted.protocol.0;
if !probed.contains(&host) || !asked.contains(&number) {
return None;
}
if !keys.admits(&error.quoted, number) {
return None;
}
let state = match error.reason {
Unreachable::Protocol => IpProtocolState::Closed,
Unreachable::Port => IpProtocolState::Open,
Unreachable::Prohibited => IpProtocolState::Filtered,
Unreachable::Host => return None,
};
return Some((host, number, state));
}
let number = match reply.protocol {
IpNextHeaderProtocols::Icmp => 1,
IpNextHeaderProtocols::Icmpv6 => 58,
_ => return None,
};
if !probed.contains(&reply.source) || !asked.contains(&number) {
return None;
}
let over_ipv6 = number == 58;
match icmp::classify_echo_reply(&reply.bytes, keys.echo_identifier, over_ipv6) {
icmp::EchoReply::Ours { .. } => Some((reply.source, number, IpProtocolState::Open)),
_ => None,
}
}
struct Datagram<'a>(&'a [u8]);
impl pnet_packet::Packet for Datagram<'_> {
fn packet(&self) -> &[u8] {
self.0
}
fn payload(&self) -> &[u8] {
&[]
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::{Ipv4Addr, Ipv6Addr};
use pnet_packet::icmp::destination_unreachable::IcmpCodes;
use pnet_packet::icmp::destination_unreachable::MutableDestinationUnreachablePacket;
use pnet_packet::icmp::{IcmpCode, IcmpTypes};
use pnet_packet::icmpv6::{Icmpv6Packet, Icmpv6Types, MutableIcmpv6Packet};
use pnet_packet::ip::IpNextHeaderProtocol;
use crate::protocols::ip;
use crate::scanner::strategy::icmp_error::ICMPV6_UNRECOGNISED_NEXT_HEADER;
use crate::transport::capture::CapturedSegment;
const LOCAL: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 50));
const TARGET: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 200));
const STRANGER: IpAddr = IpAddr::V4(Ipv4Addr::new(198, 51, 100, 9));
const LOCAL_V6: IpAddr = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0x50));
const TARGET_V6: IpAddr = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0x200));
fn asked(numbers: &[u8]) -> BTreeSet<u8> {
numbers.iter().copied().collect()
}
const TEST_SOURCE_PORT: u16 = 51_111;
const TEST_ECHO_IDENTIFIER: u16 = 0x5A4F;
fn keys() -> Correlation {
Correlation {
source_port: TEST_SOURCE_PORT,
echo_identifier: TEST_ECHO_IDENTIFIER,
sources: [LOCAL, LOCAL_V6].into_iter().collect(),
}
}
fn refusal(code: IcmpCode, host: IpAddr, number: u8) -> CapturedSegment {
refusal_quoting(
code,
LOCAL,
host,
number,
&probe_payload(number, LOCAL, host, &keys()),
)
}
fn refusal_quoting(
code: IcmpCode,
quoted_source: IpAddr,
host: IpAddr,
number: u8,
payload: &[u8],
) -> CapturedSegment {
let (IpAddr::V4(src), IpAddr::V4(dst)) = (quoted_source, host) else {
panic!("the fixture is IPv4");
};
let header = ip::build_ipv4_header(
src,
dst,
payload.len() as u16,
IpNextHeaderProtocol(number),
ip::HOP_LIMIT_ROUTED,
)
.expect("a header");
let quoted: Vec<u8> = header.into_iter().chain(payload.iter().copied()).collect();
let mut bytes =
vec![0u8; MutableDestinationUnreachablePacket::minimum_packet_size() + quoted.len()];
let mut message = MutableDestinationUnreachablePacket::new(&mut bytes).expect("a packet");
message.set_icmp_type(IcmpTypes::DestinationUnreachable);
message.set_icmp_code(code);
message.set_payload("ed);
CapturedSegment::synthetic(host, IpNextHeaderProtocols::Icmp, bytes)
}
fn next_header_refusal(host: IpAddr, number: u8) -> CapturedSegment {
let (IpAddr::V6(src), IpAddr::V6(dst)) = (LOCAL_V6, host) else {
panic!("the fixture is IPv6");
};
let payload = probe_payload(number, LOCAL_V6, host, &keys());
let header = ip::build_ipv6_header(
src,
dst,
payload.len() as u16,
IpNextHeaderProtocol(number),
ip::HOP_LIMIT_ROUTED,
);
let mut body = 6u32.to_be_bytes().to_vec();
body.extend(header);
body.extend(payload);
let mut bytes = vec![0u8; Icmpv6Packet::minimum_packet_size() + body.len()];
let mut message = MutableIcmpv6Packet::new(&mut bytes).expect("a packet");
message.set_icmpv6_type(Icmpv6Types::ParameterProblem);
message.set_icmpv6_code(ICMPV6_UNRECOGNISED_NEXT_HEADER);
message.set_payload(&body);
CapturedSegment::synthetic(host, IpNextHeaderProtocols::Icmpv6, bytes)
}
fn verdict(reply: &CapturedSegment, named: &[u8]) -> Option<(IpAddr, u8, IpProtocolState)> {
matched(
reply,
&[TARGET, TARGET_V6].into_iter().collect(),
&asked(named),
&keys(),
)
}
#[test]
fn each_message_settles_the_verdict_it_proves() {
let cases = [
(
IcmpCodes::DestinationProtocolUnreachable,
IpProtocolState::Closed,
),
(IcmpCodes::DestinationPortUnreachable, IpProtocolState::Open),
(
IcmpCodes::CommunicationAdministrativelyProhibited,
IpProtocolState::Filtered,
),
];
for (code, expected) in cases {
assert_eq!(
verdict(&refusal(code, TARGET, 47), &[47]),
Some((TARGET, 47, expected)),
"{code:?}"
);
}
}
#[test]
fn an_unreachable_address_settles_nothing_about_its_protocols() {
assert_eq!(
verdict(
&refusal(IcmpCodes::DestinationHostUnreachable, TARGET, 47),
&[47]
),
None
);
}
#[test]
fn a_message_this_pass_did_not_provoke_settles_nothing() {
assert_eq!(
verdict(
&refusal(IcmpCodes::DestinationProtocolUnreachable, STRANGER, 47),
&[47]
),
None,
"a host this pass never probed"
);
assert_eq!(
verdict(
&refusal(IcmpCodes::DestinationProtocolUnreachable, TARGET, 89),
&[47]
),
None,
"a protocol this pass never asked about"
);
}
#[test]
fn an_echo_reply_proves_icmp_only_when_it_is_this_passs_own() {
let ours = icmp::build_echo_request_message(TARGET, LOCAL, 0, TEST_ECHO_IDENTIFIER, 0, &[])
.expect("an echo message");
let mut ours = CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Icmp, ours);
ours.bytes[0] = IcmpTypes::EchoReply.0;
assert_eq!(
verdict(&ours, &[1]),
Some((TARGET, 1, IpProtocolState::Open))
);
let theirs =
icmp::build_echo_request_message(TARGET, LOCAL, 0, TEST_ECHO_IDENTIFIER ^ 1, 0, &[])
.expect("an echo message");
let mut theirs = CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Icmp, theirs);
theirs.bytes[0] = IcmpTypes::EchoReply.0;
assert_eq!(verdict(&theirs, &[1]), None, "somebody else's ping");
}
#[test]
fn a_header_is_built_only_where_it_could_change_the_answer() {
for number in [1, 6, 17, 132] {
assert!(
!probe_payload(number, LOCAL, TARGET, &keys()).is_empty(),
"protocol {number} went out bare"
);
}
for number in [2, 4, 41, 47, 50, 51, 89, 103, 112] {
assert!(
probe_payload(number, LOCAL, TARGET, &keys()).is_empty(),
"protocol {number} carried a header it has no use for"
);
}
}
#[test]
fn an_icmp_header_follows_its_own_family() {
assert!(
!probe_payload(1, LOCAL, TARGET, &keys()).is_empty(),
"icmp over v4"
);
assert!(
probe_payload(58, LOCAL, TARGET, &keys()).is_empty(),
"icmpv6 has no business in an IPv4 datagram"
);
}
#[test]
fn an_icmp_number_sent_bare_is_refused_like_any_bare_header() {
assert_eq!(
verdict(&next_header_refusal(TARGET_V6, 1), &[1]),
Some((TARGET_V6, 1, IpProtocolState::Closed)),
"ICMP asked of an IPv6 host"
);
assert_eq!(
verdict(
&refusal(IcmpCodes::DestinationProtocolUnreachable, TARGET, 58),
&[58]
),
Some((TARGET, 58, IpProtocolState::Closed)),
"ICMPv6 asked of an IPv4 host"
);
}
#[test]
fn every_default_protocol_is_one_the_registry_names() {
for number in DEFAULT_PROTOCOLS {
assert!(
crate::model::host::ip_protocol_name(number).is_some(),
"protocol {number} is in the default set and has no name to print"
);
}
}
#[test]
fn a_refusal_quoting_a_datagram_this_pass_did_not_send_settles_nothing() {
for number in [1u8, 6, 17, 47, 132] {
let forged = refusal_quoting(
IcmpCodes::DestinationPortUnreachable,
STRANGER,
TARGET,
number,
&probe_payload(number, LOCAL, TARGET, &keys()),
);
assert_eq!(
verdict(&forged, &[number]),
None,
"protocol {number}: a quotation naming a source this pass never used"
);
}
}
#[test]
fn a_refusal_quoting_another_ports_datagram_settles_nothing() {
for number in [6u8, 17, 132] {
let mut payload = probe_payload(number, LOCAL, TARGET, &keys());
payload[0..2].copy_from_slice(&1234u16.to_be_bytes());
let forged = refusal_quoting(
IcmpCodes::DestinationPortUnreachable,
LOCAL,
TARGET,
number,
&payload,
);
assert_eq!(
verdict(&forged, &[number]),
None,
"protocol {number}: a quotation carrying a port this pass never sent from"
);
}
}
#[test]
fn a_refusal_quoting_another_pings_identifier_settles_nothing() {
let mut payload = probe_payload(1, LOCAL, TARGET, &keys());
payload[4..6].copy_from_slice(&(TEST_ECHO_IDENTIFIER ^ 1).to_be_bytes());
let forged = refusal_quoting(
IcmpCodes::DestinationPortUnreachable,
LOCAL,
TARGET,
1,
&payload,
);
assert_eq!(verdict(&forged, &[1]), None);
}
#[test]
fn a_bare_protocol_is_admitted_on_its_source_address_alone() {
let sent = refusal_quoting(
IcmpCodes::DestinationProtocolUnreachable,
LOCAL,
TARGET,
47,
&[],
);
assert_eq!(
verdict(&sent, &[47]),
Some((TARGET, 47, IpProtocolState::Closed)),
"a quotation from an address this pass sent from is admitted"
);
let forged = refusal_quoting(
IcmpCodes::DestinationProtocolUnreachable,
STRANGER,
TARGET,
47,
&[],
);
assert_eq!(
verdict(&forged, &[47]),
None,
"and one from anywhere else is not"
);
}
#[test]
fn each_pass_draws_its_own_identity() {
let ports: BTreeSet<u16> = (0..64).map(|_| draw_source_port()).collect();
assert!(
ports.len() > 1,
"a drawn port that never varies is a constant"
);
assert!(
ports.iter().all(|port| *port >= 50_000),
"the range is the ephemeral one the raw sender uses"
);
let identifiers: BTreeSet<u16> = (0..64).map(|_| draw_echo_identifier()).collect();
assert!(identifiers.len() > 1);
}
}