use std::net::IpAddr;
use std::time::{Duration, Instant};
use async_trait::async_trait;
use pnet_packet::ip::{IpNextHeaderProtocol, IpNextHeaderProtocols};
use tokio::sync::mpsc;
use crate::config::ProbeTuning;
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::{SctpReply, SctpScanTechnique};
use crate::protocols::sctp;
use crate::report::ScannerKind;
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::{AuditLabels, CoreParts, ProbeTarget, RawPortScan, RawProbeScan};
use crate::scanner::strategy::icmp_error::{self, Unreachable};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct SctpToken {
tag: u32,
}
pub struct SctpPortScanner {
core: RawProbeScan<SctpToken>,
technique: SctpScanTechnique,
}
impl SctpPortScanner {
pub fn new(
resolver: SourceResolver,
ctx: ScanContext,
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 transport = ProbeTransport::open_capturing(
ProbeKind::Sctp {
reply_port: src_port,
},
tuning.evasion.effective_send_mode(tuning.send_mode),
&ctx.capture_links(),
)?;
Ok(Self {
core: Self::core(resolver, ctx, transport, &tuning, src_port, target_count),
technique: tuning.sctp_technique,
})
}
pub fn with_transport(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
target_count: usize,
src_port: u16,
) -> Self {
Self::with_transport_tuned(
resolver,
ctx,
transport,
target_count,
src_port,
ProbeTuning::default(),
)
}
pub fn with_transport_tuned(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
target_count: usize,
src_port: u16,
tuning: ProbeTuning,
) -> Self {
Self {
core: Self::core(resolver, ctx, transport, &tuning, src_port, target_count),
technique: tuning.sctp_technique,
}
}
#[must_use]
pub fn probing_with(mut self, technique: SctpScanTechnique) -> Self {
self.technique = technique;
self
}
fn core(
resolver: SourceResolver,
ctx: ScanContext,
transport: ProbeTransport,
tuning: &ProbeTuning,
src_port: u16,
target_count: usize,
) -> RawProbeScan<SctpToken> {
let retry = super::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_sctp_reply(&mut self, captured: &CapturedSegment, now: Instant) {
let (ip, bytes) = (captured.source, &captured.bytes);
let Ok(packet) = sctp::parse(bytes) else {
self.core.audit.record_off_target();
return;
};
if packet.destination_port() != self.core.src_port {
self.core.audit.record_off_target();
return;
}
let Some(reply) = sctp::classify_probe_response(&packet) else {
self.core.audit.record_off_target();
return;
};
let Some(state) = self.technique.verdict(reply) else {
self.core.audit.record_off_target();
return;
};
self.resolve_probe(
(ip, packet.source_port()),
Some(SctpToken {
tag: sctp::echoed_nonce(&packet),
}),
state,
Answer {
drawn_by: Some(reply),
sender: Some(ip),
ttl: captured.observation.map(IpObservation::remaining_hops),
},
now,
);
}
fn handle_icmp_error(&mut self, reply: &CapturedSegment, now: Instant) {
let Some(error) = icmp_error::parse(reply) else {
return;
};
if error.quoted.protocol != IpNextHeaderProtocols::Sctp.0 {
return;
}
let Some(quoted) = sctp::quoted_probe(error.quoted.payload) else {
return;
};
if quoted.source != self.core.src_port {
return;
}
let key = (error.quoted.destination, quoted.destination);
let nonce = match self.technique {
SctpScanTechnique::Init => sctp::quoted_init_tag(error.quoted.payload),
SctpScanTechnique::CookieEcho => Some(quoted.verification_tag).filter(|tag| *tag != 0),
};
let Some(nonce) = nonce else {
self.core.audit.record_reply_without_rtt();
return;
};
let token = Some(SctpToken { tag: nonce });
match error.reason {
Unreachable::Host => {
self.core.record_host_down(&key, token, 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<SctpToken>,
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,
});
}
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::Sctp, 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 | PortState::Closed, _) => Some((
HostStatus::Up,
StatusReason::new(
StatusProtocol::Sctp,
match drawn_by {
Some(SctpReply::Abort) => "abort to an sctp probe",
_ => "init-ack from a probed port",
},
),
)),
(PortState::Filtered, Some(sender)) if sender == ip => Some((
HostStatus::Up,
StatusReason::new(
StatusProtocol::IcmpUnreachable,
"unreachable for a probed sctp port, from the host",
),
)),
(PortState::Filtered, Some(sender)) => Some((
HostStatus::Filtered,
StatusReason::new(
StatusProtocol::IcmpUnreachable,
"unreachable for a probed sctp 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)]
struct Answer {
drawn_by: Option<SctpReply>,
sender: Option<IpAddr>,
ttl: Option<u8>,
}
fn port_evidence(
state: PortState,
drawn_by: Option<SctpReply>,
sender: Option<IpAddr>,
target: IpAddr,
) -> Option<ScanResponse> {
match (state, drawn_by, sender) {
(_, Some(SctpReply::InitAck), _) => Some(ScanResponse::SctpInitAck),
(_, Some(SctpReply::Abort), _) => Some(ScanResponse::SctpAbort),
(PortState::Filtered, None, Some(from)) => Some(match from == target {
true => ScanResponse::IcmpProhibited,
false => ScanResponse::IcmpUnreachable,
}),
(PortState::Filtered, None, None) => Some(ScanResponse::NoResponse),
_ => None,
}
}
impl RawPortScan for SctpPortScanner {
type Token = SctpToken;
fn core(&self) -> &RawProbeScan<SctpToken> {
&self.core
}
fn core_mut(&mut self) -> &mut RawProbeScan<SctpToken> {
&mut self.core
}
fn protocol(&self) -> Protocol {
Protocol::Sctp
}
fn silence_means(&self) -> PortState {
self.technique.silence_means()
}
fn audit_labels(&self) -> AuditLabels {
AuditLabels {
tag: "sctp-port",
silence: self.technique.silence_label(),
}
}
fn handle_reply(&mut self, reply: &CapturedSegment, now: Instant) {
match IpNextHeaderProtocol(reply.protocol) {
IpNextHeaderProtocols::Sctp => self.handle_sctp_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 {
drawn_by: None,
sender,
ttl: None,
},
None,
);
}
fn send(&mut self, ip: IpAddr, port: u16, position: Option<u64>, now: Instant) {
let first_attempt = position.is_some();
let Some(src_addr) = self.core.source_for((ip, port), first_attempt) else {
return;
};
let sent = send_probe(
self.core.transport.tx.as_ref(),
self.technique,
self.core.src_port,
src_addr,
ip,
self.core.resolver.zone_of(ip),
port,
self.core.emission,
&self.core.decoys,
);
self.core
.record_send((ip, port), sent.as_ref().map(|_| ()), first_attempt);
if let Ok(token) = sent {
match position {
Some(position) => self.core.ledger.arm(ip, (ip, port), token, position, now),
None => self.core.ledger.rearm(ip, (ip, port), token, now),
}
}
}
}
#[allow(clippy::too_many_arguments)]
fn send_probe(
sender: &dyn ProbeSender,
technique: SctpScanTechnique,
src_port: u16,
src_addr: IpAddr,
dst_addr: IpAddr,
dst_zone: Option<u32>,
dst_port: u16,
emission: Emission,
decoys: &[IpAddr],
) -> Result<SctpToken, SendError> {
let tag: u32 = rand::random_range(1..=u32::MAX);
let packet = build(technique, src_port, dst_port, tag);
let decoy_packets: Vec<(IpAddr, Vec<u8>)> = decoys
.iter()
.filter(|decoy| decoy.is_ipv4() == dst_addr.is_ipv4())
.map(|&decoy| {
let packet = build(
technique,
rand::random_range(50_000..u16::MAX),
dst_port,
rand::random_range(1..=u32::MAX),
);
(decoy, packet)
})
.collect();
super::super::raw::emit_among_decoys(
sender,
dst_addr,
dst_zone,
emission,
src_addr,
&packet,
&decoy_packets,
)?;
success!(
verbosity = 2,
"sent SCTP {technique} probe to {dst_addr}:{dst_port}"
);
Ok(SctpToken { tag })
}
fn build(technique: SctpScanTechnique, src_port: u16, dst_port: u16, tag: u32) -> Vec<u8> {
match technique {
SctpScanTechnique::Init => sctp::build_init_probe(src_port, dst_port, tag),
SctpScanTechnique::CookieEcho => sctp::build_cookie_echo_probe(src_port, dst_port, tag),
}
}
#[async_trait]
impl PortScanner for SctpPortScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::SctpPort
}
fn supported_protocols(&self) -> Vec<Protocol> {
vec![Protocol::Sctp]
}
async fn scan(&mut self, targets: mpsc::Receiver<PlannedTarget>) -> Result<(), StrategyError> {
super::drive(self, targets).await
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::Ipv4Addr;
use pnet_packet::icmp::destination_unreachable::MutableDestinationUnreachablePacket;
use pnet_packet::icmp::{IcmpCode, IcmpTypes};
use crate::model::target::Target;
use crate::scanner::session::ScanSession;
use crate::transport::probe::{MockSender, SentProbe};
const TARGET: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 200));
const LOCAL: Ipv4Addr = Ipv4Addr::new(192, 0, 2, 50);
const ROUTER: IpAddr = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1));
const INIT_ACK: u8 = 2;
const ABORT: u8 = 6;
type SentProbes = std::sync::Arc<std::sync::Mutex<Vec<SentProbe>>>;
fn on_link_interface() -> crate::system::interface::Link {
use crate::system::interface::{Link, LinkAddress};
Link::new("test0", 0).with_addresses(vec![LinkAddress::new(IpAddr::V4(LOCAL), 24)])
}
fn scanner_with_mock() -> (SctpPortScanner, ScanSession, SentProbes) {
scanner_probing(SctpScanTechnique::Init)
}
fn scanner_probing(technique: SctpScanTechnique) -> (SctpPortScanner, 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 = SctpPortScanner::with_transport(resolver, ctx, transport, 8, SCAN_PORT)
.probing_with(technique);
(scanner, session, sent)
}
const SCAN_PORT: u16 = 50_000;
fn probe(scanner: &mut SctpPortScanner, sent: &SentProbes, port: u16) -> u32 {
let before = sent.lock().unwrap().len();
scanner.send_probe(PlannedTarget::new(
u64::from(port),
Target {
ip: TARGET,
port,
protocol: Protocol::Sctp,
},
));
let sent = sent.lock().unwrap();
let (packet, _, _) = sent.get(before).expect("the probe reached the wire");
u32::from_be_bytes([packet[16], packet[17], packet[18], packet[19]])
}
fn cookie_probe(scanner: &mut SctpPortScanner, sent: &SentProbes, port: u16) -> u32 {
let before = sent.lock().unwrap().len();
scanner.send_probe(PlannedTarget::new(
u64::from(port),
Target {
ip: TARGET,
port,
protocol: Protocol::Sctp,
},
));
let sent = sent.lock().unwrap();
let (packet, _, _) = sent.get(before).expect("the probe reached the wire");
assert_eq!(
packet[12],
sctp::chunk_type::COOKIE_ECHO,
"a cookie-echo scan must not send an init"
);
u32::from_be_bytes([packet[4], packet[5], packet[6], packet[7]])
}
fn reply(from_port: u16, to_port: u16, tag: u32, kind: u8) -> Vec<u8> {
let mut packet = Vec::with_capacity(20);
packet.extend_from_slice(&from_port.to_be_bytes());
packet.extend_from_slice(&to_port.to_be_bytes());
packet.extend_from_slice(&tag.to_be_bytes());
packet.extend_from_slice(&0u32.to_be_bytes());
packet.push(kind);
packet.push(0);
packet.extend_from_slice(&4u16.to_be_bytes());
packet
}
fn captured(bytes: Vec<u8>) -> CapturedSegment {
CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Sctp.0, bytes)
}
fn icmp_error(from: IpAddr, code: IcmpCode, port: u16, tag: u32) -> CapturedSegment {
icmp_error_quoting(from, code, SctpScanTechnique::Init, port, tag)
}
fn icmp_error_quoting(
from: IpAddr,
code: IcmpCode,
technique: SctpScanTechnique,
port: u16,
tag: u32,
) -> CapturedSegment {
let probe = build(technique, SCAN_PORT, port, tag);
let quoted_ip = crate::protocols::ip::build_ipv4_header(
LOCAL,
match TARGET {
IpAddr::V4(v4) => v4,
IpAddr::V6(_) => unreachable!("the target is v4"),
},
probe.len() as u16,
IpNextHeaderProtocols::Sctp.0,
crate::protocols::ip::HOP_LIMIT_ROUTED,
)
.expect("an IPv4 header");
let quoted = [quoted_ip, probe].concat();
let mut bytes = vec![0u8; 8 + quoted.len()];
{
let mut icmp =
MutableDestinationUnreachablePacket::new(&mut bytes).expect("an ICMP buffer");
icmp.set_icmp_type(IcmpTypes::DestinationUnreachable);
icmp.set_icmp_code(code);
icmp.set_payload("ed);
}
CapturedSegment::synthetic(from, IpNextHeaderProtocols::Icmp.0, bytes)
}
fn port_state(session: &ScanSession, port: u16) -> Option<PortState> {
session.hosts().get(TARGET).and_then(|host| {
host.ports()
.find(|p| p.number() == port && p.protocol() == Protocol::Sctp)
.map(|p| p.state())
})
}
#[test]
fn an_init_ack_is_an_open_port_and_an_abort_is_a_closed_one() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 2905);
scanner.handle_reply(
&captured(reply(2905, SCAN_PORT, tag, INIT_ACK)),
Instant::now(),
);
let tag = probe(&mut scanner, &sent, 3868);
scanner.handle_reply(
&captured(reply(3868, SCAN_PORT, tag, ABORT)),
Instant::now(),
);
assert_eq!(port_state(&session, 2905), Some(PortState::Open));
assert_eq!(port_state(&session, 3868), Some(PortState::Closed));
}
#[test]
fn either_chunk_proves_the_host_and_says_which_it_was() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 3868);
scanner.handle_reply(
&captured(reply(3868, SCAN_PORT, tag, ABORT)),
Instant::now(),
);
let host = session.hosts().get(TARGET).expect("the host is recorded");
assert!(host.status().is_up());
assert!(
host.reasons()
.iter()
.any(|reason| reason.protocol == StatusProtocol::Sctp
&& reason.details.as_deref() == Some("abort to an sctp probe")),
"the abort was not recorded as the chunk it was"
);
let port = host
.ports()
.find(|port| port.number() == 3868)
.expect("the port is recorded");
assert_eq!(
port.discovery().map(|d| d.reason()),
Some(&ScanResponse::SctpAbort)
);
}
#[test]
fn a_reply_carrying_another_tag_resolves_nothing() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 2905);
scanner.handle_reply(
&captured(reply(2905, SCAN_PORT, tag.wrapping_add(1), INIT_ACK)),
Instant::now(),
);
assert_eq!(port_state(&session, 2905), None);
assert!(scanner.core.ledger.contains(&(TARGET, 2905)));
}
#[test]
fn a_packet_addressed_elsewhere_is_not_this_scans_answer() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 2905);
scanner.handle_reply(
&captured(reply(2905, SCAN_PORT + 1, tag, INIT_ACK)),
Instant::now(),
);
assert_eq!(port_state(&session, 2905), None);
}
#[test]
fn an_unanswered_probe_is_filtered_rather_than_open_filtered() {
let (mut scanner, session, sent) = scanner_with_mock();
probe(&mut scanner, &sent, 2905);
super::super::run_out(&mut scanner);
assert_eq!(port_state(&session, 2905), Some(PortState::Filtered));
assert_eq!(scanner.silence_means(), PortState::Filtered);
}
#[test]
fn an_icmp_refusal_is_a_filter_and_not_a_closed_port() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 2905);
scanner.handle_reply(&icmp_error(TARGET, IcmpCode(2), 2905, tag), Instant::now());
assert_eq!(port_state(&session, 2905), Some(PortState::Filtered));
let host = session.hosts().get(TARGET).expect("the host is recorded");
assert!(
host.status().is_up(),
"a host refusing a probe under its own address is a host that is there"
);
}
#[test]
fn a_refusal_from_the_path_is_filtered_without_promoting_the_host() {
let (mut scanner, session, sent) = scanner_with_mock();
let tag = probe(&mut scanner, &sent, 2905);
scanner.handle_reply(&icmp_error(ROUTER, IcmpCode(13), 2905, tag), Instant::now());
assert_eq!(port_state(&session, 2905), Some(PortState::Filtered));
let host = session.hosts().get(TARGET).expect("the host is recorded");
assert!(!host.status().is_up());
}
#[test]
fn a_cookie_echo_reads_an_abort_as_a_closed_port() {
let (mut scanner, session, sent) = scanner_probing(SctpScanTechnique::CookieEcho);
let tag = cookie_probe(&mut scanner, &sent, 3868);
scanner.handle_reply(
&captured(reply(3868, SCAN_PORT, tag, ABORT)),
Instant::now(),
);
assert_eq!(port_state(&session, 3868), Some(PortState::Closed));
}
#[test]
fn a_cookie_echo_does_not_read_an_init_ack_as_an_open_port() {
let (mut scanner, session, sent) = scanner_probing(SctpScanTechnique::CookieEcho);
let tag = cookie_probe(&mut scanner, &sent, 2905);
scanner.handle_reply(
&captured(reply(2905, SCAN_PORT, tag, INIT_ACK)),
Instant::now(),
);
assert_eq!(
port_state(&session, 2905),
None,
"an init-ack settled a port for a scan that could not have drawn one"
);
}
#[test]
fn a_cookie_echo_reads_silence_as_open_or_filtered() {
let (mut scanner, session, sent) = scanner_probing(SctpScanTechnique::CookieEcho);
let _ = cookie_probe(&mut scanner, &sent, 2905);
super::super::run_out(&mut scanner);
assert_eq!(port_state(&session, 2905), Some(PortState::OpenFiltered));
}
#[test]
fn a_cookie_echo_resolves_an_icmp_error_by_the_attempt_it_quotes() {
let (mut scanner, session, sent) = scanner_probing(SctpScanTechnique::CookieEcho);
let tag = cookie_probe(&mut scanner, &sent, 3868);
scanner.handle_reply(
&icmp_error_quoting(
TARGET,
IcmpCode(2),
SctpScanTechnique::CookieEcho,
3868,
tag,
),
Instant::now(),
);
assert_eq!(port_state(&session, 3868), Some(PortState::Filtered));
}
#[test]
fn a_quotation_too_short_to_name_the_attempt_resolves_no_port() {
for keep in [8usize, 12, 16] {
let (mut scanner, session, sent) = scanner_with_mock();
let real = probe(&mut scanner, &sent, 4000);
let full = icmp_error(TARGET, IcmpCode(2), 4000, real ^ 0xFFFF_FFFF);
let mut bytes = full.bytes.clone();
bytes.truncate(8 + 20 + keep);
let cut = CapturedSegment::synthetic(TARGET, IpNextHeaderProtocols::Icmp.0, bytes);
scanner.handle_reply(&cut, Instant::now());
assert_eq!(
port_state(&session, 4000),
None,
"a quotation of {keep} SCTP bytes named no attempt and must retire none"
);
}
}
#[test]
fn a_full_quotation_carrying_another_tag_resolves_no_port() {
let (mut scanner, session, sent) = scanner_with_mock();
let real = probe(&mut scanner, &sent, 4001);
scanner.handle_reply(
&icmp_error(TARGET, IcmpCode(2), 4001, real ^ 0xFFFF_FFFF),
Instant::now(),
);
assert_eq!(port_state(&session, 4001), None);
scanner.handle_reply(&icmp_error(TARGET, IcmpCode(2), 4001, real), Instant::now());
assert_eq!(port_state(&session, 4001), Some(PortState::Filtered));
}
}