use std::net::IpAddr;
use crate::model::mac::MacAddr;
use crate::protocols::ip::SMALLEST_FRAGMENT_MTU;
use crate::protocols::sizes::{IP_V4_HDR_LEN, TCP_HDR_LEN};
use crate::transport::probe::Emission;
use crate::transport::probe::SendMode;
#[must_use]
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EvasionProfile {
pub source_port: Option<u16>,
pub ttl: Option<u8>,
pub padding: Option<u16>,
pub bad_tcp_checksum: bool,
pub spoof_mac: Option<MacAddr>,
pub fragment: Option<u16>,
pub decoys: Vec<IpAddr>,
pub flags: Option<u8>,
}
const LARGEST_PAYLOAD: u16 = u16::MAX - (IP_V4_HDR_LEN + TCP_HDR_LEN) as u16;
#[non_exhaustive]
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum EvasionError {
#[error(
"a fragment size of {mtu} cannot carry a header and one eight-byte unit; {minimum} is the smallest that can"
)]
FragmentTooSmall {
mtu: u16,
minimum: u16,
},
#[error("a source port of zero is not one a probe can leave from")]
SourcePortZero,
#[error(
"{padding} bytes of padding is more than a probe's length field can describe; {limit} is the most"
)]
PaddingTooLarge {
padding: u16,
limit: u16,
},
#[error(
"a hop limit of zero expires every probe before it leaves; 1 is the least that travels"
)]
HopLimitZero,
}
impl EvasionProfile {
pub fn validate(&self) -> Result<(), EvasionError> {
if let Some(mtu) = self.fragment
&& mtu < SMALLEST_FRAGMENT_MTU
{
return Err(EvasionError::FragmentTooSmall {
mtu,
minimum: SMALLEST_FRAGMENT_MTU,
});
}
if self.source_port == Some(0) {
return Err(EvasionError::SourcePortZero);
}
if let Some(padding) = self.padding
&& padding > LARGEST_PAYLOAD
{
return Err(EvasionError::PaddingTooLarge {
padding,
limit: LARGEST_PAYLOAD,
});
}
if self.ttl == Some(0) {
return Err(EvasionError::HopLimitZero);
}
Ok(())
}
#[must_use]
pub fn is_active(&self) -> bool {
*self != Self::default()
}
#[must_use]
pub fn requires_link_layer(&self) -> bool {
self.spoof_mac.is_some() || self.fragment.is_some() || !self.decoys.is_empty()
}
#[must_use]
pub fn effective_send_mode(&self, requested: SendMode) -> SendMode {
if self.requires_link_layer() && matches!(requested, SendMode::Auto) {
SendMode::Ethernet
} else {
requested
}
}
#[must_use]
pub fn source_port_or(&self, default: u16) -> u16 {
self.source_port.unwrap_or(default)
}
#[must_use]
pub fn emission(&self) -> Emission {
let mut emission = self.hop_limited_emission();
emission.source_mac = self.spoof_mac;
emission.fragment = self.fragment;
emission
}
#[must_use]
pub fn hop_limited_emission(&self) -> Emission {
match self.ttl {
Some(hop_limit) => Emission::routed().with_hop_limit(hop_limit),
None => Emission::routed(),
}
}
#[must_use]
pub fn segment_shaping(&self) -> SegmentShaping {
SegmentShaping {
padding: self.padding,
bad_tcp_checksum: self.bad_tcp_checksum,
}
}
pub fn with_source_port(mut self, port: u16) -> Self {
self.source_port = Some(port);
self
}
pub fn with_ttl(mut self, ttl: u8) -> Self {
self.ttl = Some(ttl);
self
}
pub fn with_padding(mut self, padding: u16) -> Self {
self.padding = Some(padding);
self
}
pub fn with_bad_tcp_checksum(mut self, corrupt: bool) -> Self {
self.bad_tcp_checksum = corrupt;
self
}
pub fn with_spoof_mac(mut self, mac: MacAddr) -> Self {
self.spoof_mac = Some(mac);
self
}
pub fn with_fragment(mut self, mtu: u16) -> Self {
self.fragment = Some(mtu);
self
}
pub fn with_decoys(mut self, decoys: Vec<IpAddr>) -> Self {
self.decoys = decoys;
self
}
pub fn with_flags(mut self, flags: u8) -> Self {
self.flags = Some(flags);
self
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct SegmentShaping {
pub padding: Option<u16>,
pub bad_tcp_checksum: bool,
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_default_profile_is_inert() {
assert!(!EvasionProfile::default().is_active());
}
#[test]
fn setting_any_field_makes_the_profile_active() {
assert!(EvasionProfile::default().with_source_port(53).is_active());
assert!(EvasionProfile::default().with_ttl(32).is_active());
assert!(EvasionProfile::default().with_padding(16).is_active());
assert!(
EvasionProfile::default()
.with_bad_tcp_checksum(true)
.is_active()
);
assert!(
EvasionProfile::default()
.with_spoof_mac(MacAddr::new(2, 0, 0, 0, 0, 1))
.is_active()
);
assert!(EvasionProfile::default().with_fragment(28).is_active());
assert!(
EvasionProfile::default()
.with_decoys(vec!["10.0.0.9".parse().unwrap()])
.is_active()
);
}
#[test]
fn a_builder_records_exactly_what_it_was_given() {
let mac = MacAddr::new(0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01);
let profile = EvasionProfile::default()
.with_source_port(53)
.with_ttl(32)
.with_padding(16)
.with_bad_tcp_checksum(true)
.with_spoof_mac(mac)
.with_fragment(28)
.with_decoys(vec!["10.0.0.9".parse().unwrap()]);
assert_eq!(profile.source_port, Some(53));
assert_eq!(profile.ttl, Some(32));
assert_eq!(profile.padding, Some(16));
assert!(profile.bad_tcp_checksum);
assert_eq!(profile.spoof_mac, Some(mac));
assert_eq!(profile.fragment, Some(28));
assert_eq!(profile.decoys, vec!["10.0.0.9".parse::<IpAddr>().unwrap()]);
}
#[test]
fn source_port_resolves_to_the_override_when_set_and_the_default_otherwise() {
assert_eq!(EvasionProfile::default().source_port_or(50_000), 50_000);
assert_eq!(
EvasionProfile::default()
.with_source_port(53)
.source_port_or(50_000),
53
);
}
#[test]
fn emission_carries_the_ttl_override_and_the_routed_default_otherwise() {
assert_eq!(EvasionProfile::default().emission(), Emission::routed());
assert_eq!(
EvasionProfile::default().with_ttl(7).emission().hop_limit,
7
);
}
#[test]
fn emission_carries_the_spoofed_hardware_address() {
let mac = MacAddr::new(0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01);
let emission = EvasionProfile::default().with_spoof_mac(mac).emission();
assert_eq!(emission.source_mac, Some(mac));
assert!(emission.requires_link_layer());
let emission = EvasionProfile::default().with_fragment(28).emission();
assert_eq!(emission.fragment, Some(28));
assert!(emission.requires_link_layer());
assert_eq!(EvasionProfile::default().emission().source_mac, None);
assert_eq!(EvasionProfile::default().emission().fragment, None);
assert!(!EvasionProfile::default().emission().requires_link_layer());
}
#[test]
fn a_hop_limited_emission_carries_the_hop_limit_but_never_reshapes() {
assert_eq!(
EvasionProfile::default().hop_limited_emission(),
Emission::routed(),
);
let profile = EvasionProfile::default()
.with_ttl(7)
.with_spoof_mac(MacAddr::new(0xDE, 0xAD, 0xBE, 0xEF, 0x00, 0x01))
.with_fragment(28);
let emission = profile.hop_limited_emission();
assert_eq!(emission.hop_limit, 7, "the chosen hop limit is carried");
assert_eq!(emission.source_mac, None, "no spoofed address reshapes it");
assert_eq!(emission.fragment, None, "no fragmentation reshapes it");
assert!(
!emission.requires_link_layer(),
"so a measurement probe stays on whatever path its phase opened"
);
}
#[test]
fn validate_refuses_what_a_profile_alone_can_be_wrong_about() {
let refused = |profile: EvasionProfile| profile.validate().expect_err("refused");
assert_eq!(
refused(EvasionProfile::default().with_fragment(SMALLEST_FRAGMENT_MTU - 1)),
EvasionError::FragmentTooSmall {
mtu: SMALLEST_FRAGMENT_MTU - 1,
minimum: SMALLEST_FRAGMENT_MTU,
}
);
assert_eq!(
refused(EvasionProfile::default().with_source_port(0)),
EvasionError::SourcePortZero
);
assert_eq!(
refused(EvasionProfile::default().with_padding(u16::MAX)),
EvasionError::PaddingTooLarge {
padding: u16::MAX,
limit: LARGEST_PAYLOAD,
}
);
for allowed in [
EvasionProfile::default().with_fragment(SMALLEST_FRAGMENT_MTU),
EvasionProfile::default().with_source_port(1),
EvasionProfile::default().with_padding(LARGEST_PAYLOAD),
] {
assert_eq!(allowed.validate(), Ok(()), "{allowed:?}");
}
assert_eq!(
refused(EvasionProfile::default().with_ttl(0)),
EvasionError::HopLimitZero
);
assert!(
EvasionProfile::default().with_ttl(1).validate().is_ok(),
"one hop still travels, and expiring at a chosen distance is the point"
);
}
#[test]
fn the_fragment_bound_is_the_one_the_fragmenter_refuses_at() {
use crate::protocols::craft;
use crate::protocols::error::PacketError;
let header = craft::Ipv4::new(
"192.0.2.1".parse().expect("literal"),
"192.0.2.2".parse().expect("literal"),
);
let payload = vec![0u8; 40];
assert!(
matches!(
crate::protocols::ip::fragment_ipv4(&header, &payload, SMALLEST_FRAGMENT_MTU - 1),
Err(PacketError::MtuTooSmall { .. })
),
"one below the published bound is refused"
);
assert!(
crate::protocols::ip::fragment_ipv4(&header, &payload, SMALLEST_FRAGMENT_MTU).is_ok(),
"and the bound itself is not"
);
}
#[test]
fn every_builder_setting_validates_or_refuses_without_panicking() {
let mac = MacAddr::new(0x02, 0, 0, 0, 0, 1);
let decoy: IpAddr = "192.0.2.9".parse().expect("literal");
for profile in [
EvasionProfile::default(),
EvasionProfile::default().with_source_port(u16::MAX),
EvasionProfile::default().with_ttl(0),
EvasionProfile::default().with_ttl(u8::MAX),
EvasionProfile::default().with_padding(0),
EvasionProfile::default().with_bad_tcp_checksum(true),
EvasionProfile::default().with_spoof_mac(mac),
EvasionProfile::default().with_fragment(u16::MAX),
EvasionProfile::default().with_decoys(vec![decoy]),
EvasionProfile::default().with_flags(0),
EvasionProfile::default().with_flags(u8::MAX),
] {
let _ = profile.validate();
}
}
#[test]
fn auto_becomes_ethernet_only_when_a_framing_technique_is_set() {
let plain = EvasionProfile::default();
let framing = EvasionProfile::default().with_spoof_mac(MacAddr::new(2, 0, 0, 0, 0, 1));
assert_eq!(
framing.effective_send_mode(SendMode::Auto),
SendMode::Ethernet
);
assert_eq!(plain.effective_send_mode(SendMode::Auto), SendMode::Auto);
assert_eq!(
framing.effective_send_mode(SendMode::RawSocket),
SendMode::RawSocket
);
assert_eq!(
plain.effective_send_mode(SendMode::Ethernet),
SendMode::Ethernet
);
assert_eq!(
EvasionProfile::default()
.with_fragment(28)
.effective_send_mode(SendMode::Auto),
SendMode::Ethernet
);
assert_eq!(
EvasionProfile::default()
.with_decoys(vec!["10.0.0.9".parse().unwrap()])
.effective_send_mode(SendMode::Auto),
SendMode::Ethernet
);
}
#[test]
fn segment_shaping_carries_the_overrides_and_nothing_by_default() {
assert_eq!(
EvasionProfile::default().segment_shaping(),
SegmentShaping::default()
);
let shaping = EvasionProfile::default()
.with_padding(16)
.with_bad_tcp_checksum(true)
.segment_shaping();
assert_eq!(shaping.padding, Some(16));
assert!(shaping.bad_tcp_checksum);
}
}