use std::fmt;
use std::net::IpAddr;
use pnet::datalink;
use pnet::packet::Packet;
use pnet::packet::ip::{IpNextHeaderProtocol, IpNextHeaderProtocols};
use crate::config::SendMode;
use crate::model::capture::CaptureCounts;
use crate::transport::capture::{self, CaptureGuard, CaptureStream};
use crate::transport::link::EthernetSender;
use crate::transport::raw::{self, TransportSenderHandle, TransportType};
#[derive(Debug, Clone, Copy)]
pub enum ProbeKind {
TcpSyn,
TcpProbe {
reply_port: u16,
icmp_errors: bool,
},
UdpResolve,
IcmpEcho {
identifier: u16,
},
UdpProbe {
reply_port: u16,
},
}
impl ProbeKind {
fn transport_type(self) -> TransportType {
match self {
ProbeKind::TcpSyn | ProbeKind::TcpProbe { .. } => TransportType::TcpLayer4,
ProbeKind::UdpResolve | ProbeKind::UdpProbe { .. } => TransportType::UdpLayer4,
ProbeKind::IcmpEcho { .. } => TransportType::IcmpLayer4,
}
}
fn ip_protocols(self) -> IpProtocols {
match self {
ProbeKind::TcpSyn | ProbeKind::TcpProbe { .. } => {
IpProtocols::same(IpNextHeaderProtocols::Tcp)
}
ProbeKind::UdpResolve | ProbeKind::UdpProbe { .. } => {
IpProtocols::same(IpNextHeaderProtocols::Udp)
}
ProbeKind::IcmpEcho { .. } => IpProtocols {
v4: IpNextHeaderProtocols::Icmp,
v6: IpNextHeaderProtocols::Icmpv6,
},
}
}
fn filter(self) -> String {
match self {
ProbeKind::TcpSyn => {
"(ip and tcp and (tcp[tcpflags] & (tcp-syn|tcp-rst)) != 0) or (ip6 and tcp)"
.to_string()
}
ProbeKind::TcpProbe {
reply_port,
icmp_errors,
} => {
let tcp = format!("tcp and dst port {reply_port}");
if icmp_errors {
format!("icmp or icmp6 or ({tcp})")
} else {
tcp
}
}
ProbeKind::UdpResolve => "udp and (src port 53 or src port 5353)".to_string(),
ProbeKind::UdpProbe { reply_port } => {
format!("icmp or icmp6 or (udp and dst port {reply_port})")
}
ProbeKind::IcmpEcho { .. } => "icmp or icmp6".to_string(),
}
}
}
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum SendError {
#[error("{0}")]
Refused(String),
#[error("this transport cannot send that probe: {0}")]
Unsupported(&'static str),
}
impl SendError {
pub(crate) fn refused(error: impl fmt::Display) -> Self {
Self::Refused(format!("{error:#}"))
}
}
pub trait ProbeSender: Send + Sync {
fn send(&self, segment: &[u8], src: IpAddr, dst: IpAddr) -> Result<(), SendError>;
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct IpProtocols {
pub v4: IpNextHeaderProtocol,
pub v6: IpNextHeaderProtocol,
}
impl IpProtocols {
pub const fn same(protocol: IpNextHeaderProtocol) -> Self {
Self {
v4: protocol,
v6: protocol,
}
}
pub const fn for_destination(self, destination: IpAddr) -> IpNextHeaderProtocol {
match destination {
IpAddr::V4(_) => self.v4,
IpAddr::V6(_) => self.v6,
}
}
}
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum TransportError {
#[error("the reply capture could not be started: {0}")]
Capture(#[from] capture::CaptureError),
#[error("the raw send socket could not be opened: {0}")]
RawSocket(String),
#[error("no Ethernet-capable interface for Layer-2 send: {0}")]
NoEthernetInterface(String),
}
struct RawSegment<'a>(&'a [u8]);
impl Packet for RawSegment<'_> {
fn packet(&self) -> &[u8] {
self.0
}
fn payload(&self) -> &[u8] {
&[]
}
}
pub struct RawIpSender {
handle: TransportSenderHandle,
}
impl RawIpSender {
fn open(kind: ProbeKind) -> Result<Self, TransportError> {
raw::open_sender(kind.transport_type())
.map(|handle| Self { handle })
.map_err(|e| TransportError::RawSocket(format!("{e:#}")))
}
}
impl ProbeSender for RawIpSender {
fn send(&self, segment: &[u8], _src: IpAddr, dst: IpAddr) -> Result<(), SendError> {
self.handle
.send_to(RawSegment(segment), dst)
.map(|_| ())
.map_err(SendError::refused)
}
}
struct NoopSender;
impl ProbeSender for NoopSender {
fn send(&self, _segment: &[u8], _src: IpAddr, _dst: IpAddr) -> Result<(), SendError> {
Err(SendError::Unsupported("it is receive-only"))
}
}
pub struct ProbeTransport {
pub tx: Box<dyn ProbeSender>,
pub rx: CaptureStream,
capture: CaptureGuard,
}
impl ProbeTransport {
pub fn capture_counts(&self) -> Option<CaptureCounts> {
self.capture.counts()
}
pub fn open(kind: ProbeKind) -> Result<Self, TransportError> {
Self::open_with(kind, SendMode::Auto)
}
pub fn open_with(kind: ProbeKind, mode: SendMode) -> Result<Self, TransportError> {
match mode {
SendMode::Ethernet => Self::open_ethernet(kind),
SendMode::RawSocket => Self::open_on(kind, &capturable_interfaces()),
SendMode::Auto => {
#[cfg(windows)]
{
Self::open_ethernet(kind)
}
#[cfg(not(windows))]
{
Self::open_on(kind, &capturable_interfaces())
}
}
}
}
pub fn open_on(kind: ProbeKind, interfaces: &[String]) -> Result<Self, TransportError> {
let (rx, capture) = capture::start(interfaces, &kind.filter())?;
let tx: Box<dyn ProbeSender> = Box::new(RawIpSender::open(kind)?);
Ok(Self { tx, rx, capture })
}
pub fn open_ethernet(kind: ProbeKind) -> Result<Self, TransportError> {
let sender = EthernetSender::from_system(kind.ip_protocols()).ok_or_else(|| {
TransportError::NoEthernetInterface(
"the host has only tunnel or loopback interfaces".to_string(),
)
})?;
let (rx, capture) = capture::start(&capturable_interfaces(), &kind.filter())?;
Ok(Self {
tx: Box::new(sender),
rx,
capture,
})
}
pub fn open_receiver(kind: ProbeKind) -> Result<Self, TransportError> {
let (rx, capture) = capture::start(&capturable_interfaces(), &kind.filter())?;
Ok(Self {
tx: Box::new(NoopSender),
rx,
capture,
})
}
#[cfg(any(test, feature = "test-support"))]
pub fn from_parts(tx: Box<dyn ProbeSender>, rx: CaptureStream) -> Self {
Self {
tx,
rx,
capture: CaptureGuard::noop(),
}
}
}
fn capturable_interfaces() -> Vec<String> {
datalink::interfaces()
.into_iter()
.filter(|iface| iface.is_up())
.map(|iface| iface.name)
.collect()
}
#[cfg(test)]
pub type SentProbe = (Vec<u8>, IpAddr, IpAddr);
#[cfg(test)]
#[derive(Clone, Default)]
pub struct MockSender {
pub sent: std::sync::Arc<std::sync::Mutex<Vec<SentProbe>>>,
}
#[cfg(test)]
impl ProbeSender for MockSender {
fn send(&self, segment: &[u8], src: IpAddr, dst: IpAddr) -> Result<(), SendError> {
self.sent.lock().unwrap().push((segment.to_vec(), src, dst));
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn transport_forwards_sends_and_delivers_replies() {
use crate::transport::capture::CapturedSegment;
use std::net::Ipv4Addr;
let mock = MockSender::default();
let recorded = mock.sent.clone();
let (reply_tx, reply_rx) = tokio::sync::mpsc::unbounded_channel();
let mut transport = ProbeTransport::from_parts(Box::new(mock), reply_rx);
let src = IpAddr::V4(Ipv4Addr::new(10, 0, 0, 2));
let dst = IpAddr::V4(Ipv4Addr::new(1, 1, 1, 1));
transport.tx.send(&[0xAA, 0xBB], src, dst).unwrap();
let sent = recorded.lock().unwrap().clone();
assert_eq!(sent, vec![(vec![0xAA, 0xBB], src, dst)]);
let reply = CapturedSegment::synthetic(
dst,
pnet::packet::ip::IpNextHeaderProtocols::Udp,
vec![1, 2, 3],
);
reply_tx.send(reply.clone()).unwrap();
assert_eq!(transport.rx.recv().await, Some(reply));
}
#[test]
fn every_probe_kind_carries_its_own_ip_protocol() {
assert_eq!(
ProbeKind::TcpSyn.ip_protocols(),
IpProtocols::same(IpNextHeaderProtocols::Tcp)
);
assert_eq!(
ProbeKind::TcpProbe {
reply_port: 50_000,
icmp_errors: true,
}
.ip_protocols(),
IpProtocols::same(IpNextHeaderProtocols::Tcp)
);
assert_eq!(
ProbeKind::UdpResolve.ip_protocols(),
IpProtocols::same(IpNextHeaderProtocols::Udp)
);
assert_eq!(
ProbeKind::UdpProbe { reply_port: 40_000 }.ip_protocols(),
IpProtocols::same(IpNextHeaderProtocols::Udp)
);
}
#[test]
fn an_icmp_probe_names_a_different_protocol_per_family() {
let protocols = ProbeKind::IcmpEcho { identifier: 1 }.ip_protocols();
assert_eq!(protocols.v4, IpNextHeaderProtocols::Icmp);
assert_eq!(protocols.v6, IpNextHeaderProtocols::Icmpv6);
assert_eq!(
protocols.for_destination(IpAddr::from([192, 0, 2, 1])),
IpNextHeaderProtocols::Icmp
);
assert_eq!(
protocols.for_destination("2001:db8::1".parse().unwrap()),
IpNextHeaderProtocols::Icmpv6
);
}
#[test]
fn the_icmp_filter_admits_both_families() {
assert_eq!(
ProbeKind::IcmpEcho { identifier: 4242 }.filter(),
"icmp or icmp6"
);
}
#[test]
fn udp_probe_filter_narrows_replies_to_the_scan_source_port() {
let filter = ProbeKind::UdpProbe { reply_port: 54_321 }.filter();
assert_eq!(filter, "icmp or icmp6 or (udp and dst port 54321)");
}
}
#[cfg(test)]
mod filter_conformance {
use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
use pnet::packet::icmpv6::{Icmpv6Code, Icmpv6Types, MutableIcmpv6Packet};
use pnet::packet::ip::IpNextHeaderProtocols;
use pnet::packet::tcp::MutableTcpPacket;
use pnet::util::MacAddr;
use super::ProbeKind;
use crate::protocols::udp;
use crate::transport::frame::build_ethernet_frame;
const SRC_V4: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 10));
const DST_V4: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 20));
const SRC_V6: IpAddr = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0x10));
const DST_V6: IpAddr = IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0x20));
const SYN: u8 = 1 << 1;
const RST: u8 = 1 << 2;
const ACK: u8 = 1 << 4;
const TCP_HDR_LEN: usize = 20;
const ICMPV6_UNUSED_LEN: usize = 4;
const SCAN_PORT: u16 = 50_000;
fn admits(filter: &str, frame: &[u8]) -> bool {
let capture = pcap::Capture::dead(pcap::Linktype::ETHERNET)
.expect("opening a dead capture for the Ethernet link type");
let program = capture
.compile(filter, true)
.unwrap_or_else(|e| panic!("compiling `{filter}`: {e}"));
program.filter(frame)
}
fn tcp_frame(src: IpAddr, dst: IpAddr, flags: u8) -> Vec<u8> {
tcp_frame_to(src, dst, flags, SCAN_PORT)
}
fn tcp_frame_to(src: IpAddr, dst: IpAddr, flags: u8, dst_port: u16) -> Vec<u8> {
let mut segment = vec![0u8; TCP_HDR_LEN];
{
let mut tcp = MutableTcpPacket::new(&mut segment).expect("TCP header buffer");
tcp.set_source(443);
tcp.set_destination(dst_port);
tcp.set_data_offset((TCP_HDR_LEN / 4) as u8);
tcp.set_flags(flags);
tcp.set_window(1024);
}
frame(src, dst, IpNextHeaderProtocols::Tcp, &segment)
}
fn udp_frame(src: IpAddr, dst: IpAddr, src_port: u16, dst_port: u16) -> Vec<u8> {
let segment = udp::create_packet(&src, &dst, src_port, dst_port, vec![0u8; 4])
.expect("building a UDP datagram");
frame(src, dst, IpNextHeaderProtocols::Udp, &segment)
}
fn icmpv6_error_frame(src: IpAddr, dst: IpAddr) -> Vec<u8> {
let mut segment = vec![0u8; MutableIcmpv6Packet::minimum_packet_size() + ICMPV6_UNUSED_LEN];
{
let mut icmp = MutableIcmpv6Packet::new(&mut segment).expect("ICMPv6 header buffer");
icmp.set_icmpv6_type(Icmpv6Types::DestinationUnreachable);
icmp.set_icmpv6_code(Icmpv6Code(4));
}
frame(src, dst, IpNextHeaderProtocols::Icmpv6, &segment)
}
fn frame(
src: IpAddr,
dst: IpAddr,
protocol: pnet::packet::ip::IpNextHeaderProtocol,
segment: &[u8],
) -> Vec<u8> {
build_ethernet_frame(
MacAddr::new(0x02, 0, 0, 0, 0, 0x02),
MacAddr::new(0x02, 0, 0, 0, 0, 0x01),
src,
dst,
protocol,
segment,
)
.expect("building an Ethernet frame")
}
#[test]
fn the_syn_filter_admits_the_two_answers_a_syn_probe_draws_over_ipv4() {
let filter = ProbeKind::TcpSyn.filter();
assert!(
admits(&filter, &tcp_frame(SRC_V4, DST_V4, SYN | ACK)),
"a SYN+ACK is an open port and must reach the scanner"
);
assert!(
admits(&filter, &tcp_frame(SRC_V4, DST_V4, RST | ACK)),
"a RST is a closed port and must reach the scanner"
);
}
#[test]
fn the_syn_filter_rejects_established_traffic_over_ipv4() {
assert!(!admits(
&ProbeKind::TcpSyn.filter(),
&tcp_frame(SRC_V4, DST_V4, ACK)
));
}
#[test]
fn the_syn_filter_admits_the_same_answers_over_ipv6() {
let filter = ProbeKind::TcpSyn.filter();
assert!(admits(&filter, &tcp_frame(SRC_V6, DST_V6, SYN | ACK)));
assert!(admits(&filter, &tcp_frame(SRC_V6, DST_V6, RST | ACK)));
}
#[test]
fn the_ipv6_half_of_the_syn_filter_is_not_narrowed_to_probe_replies() {
let filter = ProbeKind::TcpSyn.filter();
assert!(
!admits(&filter, &tcp_frame(SRC_V4, DST_V4, ACK)),
"the IPv4 half is narrowed by the kernel"
);
assert!(
admits(&filter, &tcp_frame(SRC_V6, DST_V6, ACK)),
"the IPv6 half cannot be, so userspace has to do it"
);
}
#[test]
fn libpcap_cannot_narrow_tcp_flags_over_ipv6() {
let narrowed = "ip6 and tcp and (tcp[tcpflags] & (tcp-syn|tcp-rst)) != 0";
let capture = pcap::Capture::dead(pcap::Linktype::ETHERNET).expect("dead capture");
let admits_a_syn_ack = capture
.compile(narrowed, true)
.map(|program| program.filter(&tcp_frame(SRC_V6, DST_V6, SYN | ACK)))
.unwrap_or(false);
assert!(
!admits_a_syn_ack,
"libpcap now narrows TCP flags over IPv6; the split filter is no longer needed"
);
}
fn tcp_probe_filter(icmp_errors: bool) -> String {
ProbeKind::TcpProbe {
reply_port: SCAN_PORT,
icmp_errors,
}
.filter()
}
#[test]
fn the_tcp_probe_filter_admits_answers_addressed_to_the_scan() {
let filter = tcp_probe_filter(false);
for (src, dst) in [(SRC_V4, DST_V4), (SRC_V6, DST_V6)] {
assert!(
admits(&filter, &tcp_frame(src, dst, SYN | ACK)),
"a SYN+ACK is an open port and must reach the scanner"
);
assert!(
admits(&filter, &tcp_frame(src, dst, RST | ACK)),
"a RST is an answer and must reach the scanner"
);
}
}
#[test]
fn the_tcp_probe_filter_rejects_traffic_addressed_elsewhere_over_both_families() {
let filter = tcp_probe_filter(false);
let elsewhere = SCAN_PORT + 1;
for (src, dst) in [(SRC_V4, DST_V4), (SRC_V6, DST_V6)] {
assert!(
!admits(&filter, &tcp_frame_to(src, dst, RST | ACK, elsewhere)),
"a segment to a port this scan never sent from is somebody else's"
);
}
}
#[test]
fn the_tcp_probe_filter_narrows_on_the_conversation_rather_than_the_flags() {
let filter = tcp_probe_filter(false);
assert!(admits(&filter, &tcp_frame(SRC_V4, DST_V4, ACK)));
assert!(admits(&filter, &tcp_frame(SRC_V6, DST_V6, ACK)));
}
#[test]
fn the_tcp_probe_filter_admits_icmp_errors_only_when_asked() {
let error = icmpv6_error_frame(SRC_V6, DST_V6);
assert!(!admits(&tcp_probe_filter(false), &error));
assert!(admits(&tcp_probe_filter(true), &error));
}
#[test]
fn asking_for_icmp_changes_nothing_about_the_tcp_half() {
let filter = tcp_probe_filter(true);
assert!(admits(&filter, &tcp_frame(SRC_V6, DST_V6, RST | ACK)));
assert!(!admits(
&filter,
&tcp_frame_to(SRC_V6, DST_V6, RST | ACK, SCAN_PORT + 1)
));
}
#[test]
fn the_resolve_filter_admits_dns_answers_over_both_families() {
let filter = ProbeKind::UdpResolve.filter();
assert!(admits(&filter, &udp_frame(SRC_V4, DST_V4, 53, 40_000)));
assert!(admits(&filter, &udp_frame(SRC_V6, DST_V6, 53, 40_000)));
assert!(admits(&filter, &udp_frame(SRC_V6, DST_V6, 5353, 5353)));
assert!(
!admits(&filter, &udp_frame(SRC_V6, DST_V6, 12_345, 40_000)),
"traffic from an unrelated source port is not an answer to anything"
);
}
#[test]
fn the_udp_probe_filter_admits_direct_replies_and_icmp_errors_over_both_families() {
const REPLY_PORT: u16 = 40_000;
let filter = ProbeKind::UdpProbe {
reply_port: REPLY_PORT,
}
.filter();
assert!(admits(&filter, &udp_frame(SRC_V4, DST_V4, 53, REPLY_PORT)));
assert!(admits(&filter, &udp_frame(SRC_V6, DST_V6, 53, REPLY_PORT)));
assert!(admits(&filter, &icmpv6_error_frame(SRC_V6, DST_V6)));
assert!(
!admits(&filter, &udp_frame(SRC_V6, DST_V6, 53, REPLY_PORT + 1)),
"a datagram to a port this scan never sent from is somebody else's"
);
}
}