use crate::model::host::OsEvidence;
use crate::system::privilege::{self, Privilege};
use std::net::IpAddr;
use std::sync::Arc;
use tokio::sync::mpsc::{self, UnboundedReceiver, UnboundedSender};
use tokio::task::JoinHandle;
use crate::config::DetectionEnvelope;
use crate::config::limits::CONNECT_CONCURRENCY;
use crate::config::{OsDetection, ProbeTuning, ServiceDetection, ZondConfig};
use crate::evasion::EvasionProfile;
use crate::fingerprint::os;
use crate::journal::cursor::Checkpoint;
use crate::logging::error;
use crate::model::ip::range::{IpRange, Ipv4Range, Ipv6Range};
use crate::model::ip::scoped::{Zone, ZoneMap};
use crate::model::{
ip::set::IpSet,
port::{Discovery as PortDiscovery, Port, PortState, Protocol, ScanResponse},
target::{PlannedTarget, TargetIndex, TargetMap, TargetSet},
technique::{SctpScanTechnique, TcpScanTechnique},
};
use crate::report::{ScannerKind, TargetScope};
use crate::scanner::pool::ProbePool;
use crate::scanner::rdns::HostnameResolver;
use crate::scanner::session::{ScanContext, Stage};
use crate::scanner::strategy::composite::Reach;
use crate::scanner::strategy::{HostScanner, PortScanner, StrategyError};
use crate::scanner::{plan, rdns, strategy};
use crate::system::interface;
use crate::transport::probe::SendMode;
use crate::{counted, info, success, warn};
pub(super) fn walkable(targets: IpSet, ctx: &ScanContext) -> IpSet {
let refused: Vec<_> = targets
.v6()
.iter()
.filter(|range| !interface::is_enumerable(range))
.copied()
.collect();
if refused.is_empty() {
return targets;
}
let mut kept = IpSet::new();
for range in targets.v4() {
kept.push_v4_range(*range);
}
for range in targets.v6() {
if interface::is_enumerable(range) {
kept.push_v6_range(*range);
}
}
kept.canonicalize();
for range in &refused {
ctx.record_refusal(plan::RefusedStep::unprivileged_range_not_enumerable(range).into());
}
kept
}
#[derive(Clone, Copy)]
pub(super) struct ScanCapabilities {
pub(super) privilege: Privilege,
pub(super) frames_only: bool,
dns: bool,
}
impl ScanCapabilities {
pub(super) fn resolve(cfg: &ZondConfig, probing: Probing) -> Self {
let privilege = Privilege::current();
let mode = cfg.evasion.effective_send_mode(cfg.send_mode);
let frames_only =
privilege.is_raw() && mode == SendMode::Auto && !mode.reaches_past_frames();
let caps = Self {
privilege,
frames_only,
dns: !cfg.no_dns,
};
caps.announce(probing, privilege::can_send_raw());
caps
}
fn announce(self, probing: Probing, raw_sockets: bool) {
if self.privilege.is_raw() {
let route = if raw_sockets {
"raw sockets"
} else {
"link-layer frames"
};
success!("probing with {} ({route})", probing.raw_probes());
} else if probing.udp {
warn!("no raw sockets: probing with TCP connect and plain UDP datagrams");
} else {
warn!("no raw sockets: probing with TCP connect only");
}
}
pub(super) fn beyond_frames(
self,
targets: &IpSet,
forced: &[IpAddr],
sender: interface::FrameSender,
) -> interface::BeyondFrames {
if !self.frames_only || targets.is_empty() {
return interface::BeyondFrames::default();
}
interface::beyond_frames(targets.clone(), forced, sender)
}
}
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(super) struct Probing {
tcp: Option<TcpScanTechnique>,
udp: bool,
sctp: Option<SctpScanTechnique>,
}
impl Probing {
pub(super) fn sweep() -> Self {
Self::default()
}
pub(super) fn ports(cfg: &ZondConfig, map: &TargetMap) -> Self {
Self {
tcp: map.names(Protocol::Tcp).then_some(cfg.tcp_technique),
udp: map.names(Protocol::Udp),
sctp: map.names(Protocol::Sctp).then_some(cfg.sctp_technique),
}
}
fn raw_probes(self) -> String {
let mut probes = vec!["ARP".to_owned(), "ICMPv6".to_owned(), "SYN".to_owned()];
if let Some(tcp) = self.tcp
&& tcp != TcpScanTechnique::Syn
{
probes.push(tcp.name().to_uppercase());
}
if self.udp {
probes.push("UDP".to_owned());
}
if let Some(sctp) = self.sctp {
probes.push(format!("SCTP {}", sctp.name().to_uppercase()));
}
let last = probes.pop().expect("SYN is always listed");
format!("{} and {last}", probes.join(", "))
}
}
fn within_frames<T>(
hosts: Vec<T>,
address: impl Fn(&T) -> IpAddr,
caps: ScanCapabilities,
forced: &[IpAddr],
ctx: &ScanContext,
scanner: ScannerKind,
pass: &str,
) -> Vec<T> {
if !caps.frames_only || hosts.is_empty() {
return hosts;
}
let mut addresses = IpSet::new();
for host in &hosts {
addresses.insert(address(host));
}
let beyond = caps.beyond_frames(&addresses, forced, interface::FrameSender::Probe);
if beyond.is_empty() {
return hosts;
}
ctx.record_refusal(
plan::RefusedStep::pass_beyond_frames(scanner, pass, beyond.targets.len()).into(),
);
hosts
.into_iter()
.filter(|host| !beyond.targets.contains(&address(host)))
.collect()
}
fn announce_beyond_frames(beyond: &interface::BeyondFrames) {
if beyond.is_empty() {
return;
}
let reasons: Vec<String> = beyond
.summary()
.into_iter()
.map(|(reason, first, count)| match count {
1 => format!("{first} ({reason})"),
more => format!("{first} +{} ({reason})", more - 1),
})
.collect();
info!(
verbosity = 1,
"port scan by connect: {}",
reasons.join(", ")
);
}
pub(super) struct Enrichment {
scanners: Vec<(ScannerKind, JoinHandle<Result<(), StrategyError>>)>,
resolver: Option<JoinHandle<Option<HostnameResolver>>>,
}
impl Enrichment {
pub(super) async fn spawn(
plan: plan::DiscoveryPlan,
ctx: &ScanContext,
caps: ScanCapabilities,
tuning: ProbeTuning,
) -> Self {
let (dns_tx, resolver) = if caps.dns {
let (tx, rx) = mpsc::unbounded_channel();
(Some(tx), Some(spawn_resolver(rx).await))
} else {
info!("DNS resolution skipped by user flag");
(None, None)
};
let scanners = spawn_explorers(plan, ctx, dns_tx, tuning).await;
Self { scanners, resolver }
}
async fn finish(self, ctx: &ScanContext) {
for (kind, handle) in self.scanners {
match handle.await {
Ok(Ok(())) => {}
Ok(Err(e)) => ctx.record_failure(kind, e.to_string()),
Err(e) => ctx.record_failure(kind, format!("panicked: {e}")),
}
}
if let Some(task) = self.resolver
&& let Ok(Some(mut resolver)) = task.await
{
resolver.resolve_hosts(ctx);
}
}
}
fn record_our_own_addresses(ours: &crate::model::ip::set::IpSet, ctx: &ScanContext) {
let addresses: Vec<IpAddr> = ours.iter().collect();
if addresses.is_empty() {
return;
}
info!(
verbosity = 2,
"{} named is this host's own and is up without asking",
counted(addresses.len() as u128, "address", "addresses")
);
for address in addresses {
ctx.update_host(crate::model::ip::scoped::ScopedIp::from(address), |host| {
host.record_evidence(
crate::model::host::HostStatus::Up,
crate::model::host::StatusReason::new(
crate::model::host::StatusProtocol::Custom("local-interface".into()),
"an address this host holds",
),
);
});
ctx.settle_address(address, crate::journal::settle::Settled::Answered);
}
}
pub(super) async fn spawn_explorers(
plan: plan::DiscoveryPlan,
ctx: &ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
) -> Vec<(ScannerKind, JoinHandle<Result<(), StrategyError>>)> {
for refusal in plan.refusals() {
ctx.record_refusal(refusal.clone().into());
}
record_our_own_addresses(plan.ours(), ctx);
let mut explorers: Vec<Box<dyn HostScanner>> = Vec::new();
for step in plan.into_steps() {
let kind = step.kind();
info!(
verbosity = 3,
"spawning {kind:?} scanner for {}",
counted(step.target_count(), "target", "targets")
);
match step.into_scanner(ctx.clone(), dns_tx.clone(), tuning.clone()) {
Ok(scanner) => explorers.push(scanner),
Err(e) => ctx.record_failure(kind, e.to_string()),
}
}
explorers
.into_iter()
.map(|mut explorer| {
let kind = explorer.kind();
(
kind,
tokio::spawn(async move { explorer.discover_hosts().await }),
)
})
.collect()
}
pub(super) enum RawReach {
Everything,
AllBut(IpSet),
Nothing(IpSet),
}
impl RawReach {
pub(super) fn of(probed: &IpSet, beyond: IpSet) -> Self {
if beyond.is_empty() {
return Self::Everything;
}
let mut within = probed.clone();
within.subtract(&beyond);
match within.is_empty() {
true => Self::Nothing(beyond),
false => Self::AllBut(beyond),
}
}
fn beyond(&self) -> IpSet {
match self {
Self::Everything => IpSet::new(),
Self::AllBut(beyond) | Self::Nothing(beyond) => beyond.clone(),
}
}
}
pub(super) fn build_port_scanner(
plan: plan::PortScanPlan,
named: &[Protocol],
ctx: &ScanContext,
target_count: usize,
tuning: ProbeTuning,
zones: &ZoneMap,
raw: &RawReach,
) -> BuiltPortScan {
for refusal in plan.refusals() {
ctx.record_refusal(refusal.clone().into());
}
let technique = plan.technique();
let intended: Vec<Protocol> = Protocol::ALL
.into_iter()
.filter(|protocol| plan.covers(*protocol) && named.contains(protocol))
.collect();
let mut refused: Vec<(Protocol, Reach)> = Protocol::ALL
.into_iter()
.filter(|protocol| plan.refuses(*protocol))
.map(|protocol| (protocol, Reach::Any))
.collect();
let beyond = Arc::new(raw.beyond());
let mut routes: Vec<(Box<dyn PortScanner>, Reach)> = Vec::new();
for step in plan.into_steps() {
if step.is_raw() && matches!(raw, RawReach::Nothing(_)) {
continue;
}
match step.into_scanner(ctx.clone(), target_count, tuning.clone(), zones.clone()) {
Ok(scanner) => {
let reach = match step.is_raw() && !beyond.is_empty() {
true => Reach::Except(Arc::clone(&beyond)),
false => Reach::Any,
};
routes.push((scanner, reach));
}
Err(e) => ctx.record_failure(step.kind(), e.to_string()),
}
}
let coverage = ensure_coverage(
routes,
ctx,
technique,
&intended,
tuning.service_detection,
&tuning.evasion,
raw,
);
refused.extend(coverage.refused);
BuiltPortScan {
scanner: Box::new(
strategy::composite::CompositePortScanner::with_reach(coverage.routes, ctx.clone())
.refusing(refused),
),
reached_by_connect: coverage.reached_by_connect,
}
}
pub(super) struct Coverage {
pub(super) routes: Vec<(Box<dyn PortScanner>, Reach)>,
pub(super) refused: Vec<(Protocol, Reach)>,
pub(super) reached_by_connect: bool,
}
pub(super) fn ensure_coverage(
mut routes: Vec<(Box<dyn PortScanner>, Reach)>,
ctx: &ScanContext,
technique: TcpScanTechnique,
intended: &[Protocol],
detection: ServiceDetection,
evasion: &EvasionProfile,
raw: &RawReach,
) -> Coverage {
let beyond = &Arc::new(raw.beyond());
let withheld = matches!(raw, RawReach::Nothing(_));
let mut refused: Vec<(Protocol, Reach)> = Vec::new();
let covered: Vec<Protocol> = routes
.iter()
.flat_map(|(scanner, _)| scanner.supported_protocols())
.collect();
let beyond_uncovered: Vec<Protocol> = match beyond.is_empty() {
true => Vec::new(),
false => covered
.iter()
.copied()
.filter(|protocol| intended.contains(protocol))
.filter(|protocol| {
!routes.iter().any(|(scanner, reach)| {
!matches!(reach, Reach::Except(_))
&& scanner.supported_protocols().contains(protocol)
})
})
.collect(),
};
let missing = |protocol: Protocol| intended.contains(&protocol) && !covered.contains(&protocol);
let mut connected = false;
if missing(Protocol::Tcp) {
if technique.has_connect_fallback() {
routes.push((connect_tcp(ctx, detection, evasion), Reach::Any));
connected = true;
} else {
let refusal = match withheld {
true => plan::RefusedStep::technique_beyond_frames(technique, beyond.len()),
false => plan::RefusedStep::technique_needs_raw_sockets(technique),
};
ctx.record_refusal(refusal.into());
refused.push((Protocol::Tcp, Reach::Any));
}
}
if missing(Protocol::Udp) {
routes.push((connect_udp(ctx, detection, evasion), Reach::Any));
connected = true;
}
if missing(Protocol::Sctp) {
let refusal = match withheld {
true => plan::RefusedStep::sctp_beyond_frames(beyond.len()),
false => plan::RefusedStep::sctp_needs_raw_sockets(),
};
ctx.record_refusal(refusal.into());
refused.push((Protocol::Sctp, Reach::Any));
}
let beyond_count = beyond.len();
for protocol in beyond_uncovered {
match protocol {
Protocol::Tcp if technique.has_connect_fallback() => {
routes.push((
connect_tcp(ctx, detection, evasion),
Reach::Only(Arc::clone(beyond)),
));
connected = true;
}
Protocol::Tcp => {
ctx.record_refusal(
plan::RefusedStep::technique_beyond_frames(technique, beyond_count).into(),
);
refused.push((Protocol::Tcp, Reach::Only(Arc::clone(beyond))));
}
Protocol::Udp => {
routes.push((
connect_udp(ctx, detection, evasion),
Reach::Only(Arc::clone(beyond)),
));
connected = true;
}
Protocol::Sctp => {
ctx.record_refusal(plan::RefusedStep::sctp_beyond_frames(beyond_count).into());
refused.push((Protocol::Sctp, Reach::Only(Arc::clone(beyond))));
}
}
}
let reached_by_connect = connected && !beyond.is_empty();
if reached_by_connect {
ctx.record_reached_by_connect(beyond);
}
Coverage {
routes,
refused,
reached_by_connect,
}
}
fn connect_tcp(
ctx: &ScanContext,
detection: ServiceDetection,
evasion: &EvasionProfile,
) -> Box<dyn PortScanner> {
Box::new(strategy::connect::ConnectPortScanner::new(
ctx.clone(),
crate::config::limits::CONNECT_CONCURRENCY,
detection,
evasion,
))
}
fn connect_udp(
ctx: &ScanContext,
detection: ServiceDetection,
evasion: &EvasionProfile,
) -> Box<dyn PortScanner> {
Box::new(strategy::connect::ConnectUdpPortScanner::with_detection(
ctx.clone(),
crate::config::limits::CONNECT_CONCURRENCY,
evasion,
detection,
))
}
pub(super) struct BuiltPortScan {
pub(super) scanner: Box<dyn PortScanner>,
reached_by_connect: bool,
}
pub(super) async fn run_port_scan(
mut scanner: Box<dyn PortScanner>,
rx: mpsc::Receiver<PlannedTarget>,
ctx: &ScanContext,
service_detection: ServiceDetection,
detection: DetectionEnvelope,
) {
let kind = scanner.kind();
match scanner.scan(rx).await {
Ok(()) => {
if !ctx.handle.should_stop() {
scanner.detect_services(ctx).await;
}
if !ctx.handle.should_stop() {
super::detection::detect(ctx, service_detection, detection).await;
}
}
Err(e) => ctx.record_failure(kind, e.to_string()),
}
}
pub(super) async fn finish_enrichment(
enrichment: Option<Enrichment>,
caps: ScanCapabilities,
ctx: &ScanContext,
unheard: rdns::Unheard,
) {
match enrichment {
Some(enrichment) => enrichment.finish(ctx).await,
None if caps.dns => rdns::resolve(ctx, unheard).await,
None => {}
}
}
pub(super) fn run_passive_os_identification(ctx: &ScanContext, os_detection: OsDetection) {
if matches!(os_detection, OsDetection::Off) {
return;
}
let mut named = 0usize;
for ip in ctx.host_addresses() {
let mut identified = false;
ctx.write_host(ip, |host| {
identified = os::identify(host, []);
identified
});
if identified {
named += 1;
}
}
if named > 0 {
info!(
verbosity = 1,
"named {} from what the sweep already knew",
counted(named as u128, "host", "hosts")
);
}
}
pub(super) async fn run_active_os_series(
ctx: &ScanContext,
os_detection: OsDetection,
tuning: ProbeTuning,
caps: ScanCapabilities,
) {
if !os_detection.is_active() {
return;
}
ctx.enter_stage(Stage::Os, None);
let thorough = matches!(os_detection, OsDetection::Aggressive);
let targets: Vec<strategy::identify::series::SeriesTarget> = ctx
.host_addresses()
.into_iter()
.filter(|key| !ctx.host_expired(key.addr()))
.filter_map(|key| {
ctx.read_host(&key, |host| {
if !host.status().is_up() {
return None;
}
let settled = host.os().is_some_and(|os| os.is_highly_confident());
if settled && !thorough {
return None;
}
strategy::identify::series::SeriesTarget::for_host(key.clone(), host)
})
.flatten()
})
.collect();
let targets = within_frames(
targets,
|target| target.address.addr(),
caps,
&tuning.send_source,
ctx,
ScannerKind::OsSeries,
"the OS series probe",
);
if targets.is_empty() {
return;
}
let samples = if thorough {
strategy::identify::series::AGGRESSIVE_SAMPLES
} else {
strategy::identify::series::ACTIVE_SAMPLES
};
info!(
"following {} over {}",
counted(targets.len() as u128, "host", "hosts"),
counted(samples as u128, "sample", "samples")
);
match strategy::identify::series::OsSeriesScanner::new(ctx.clone(), targets, samples, tuning) {
Ok(mut scanner) => {
if let Err(e) = scanner.probe().await {
ctx.record_failure(ScannerKind::OsSeries, e.to_string());
}
}
Err(e) => ctx.record_failure(
ScannerKind::OsSeries,
format!("the active series probe could not open its transport: {e}"),
),
}
}
pub(super) async fn run_active_os_snmp(ctx: &ScanContext, os_detection: OsDetection) {
if !os_detection.is_active() {
return;
}
ctx.enter_stage(Stage::Os, None);
let targets: Vec<crate::model::ip::scoped::ScopedIp> = ctx
.host_addresses()
.into_iter()
.filter(|ip| !ctx.host_expired(ip.addr()))
.filter_map(|ip| {
ctx.read_host(&ip, |host| {
let known = host.os().is_some_and(|os| os.kernel().is_some());
(host.status().is_up() && !known).then(|| host.scoped_ip())
})
.flatten()
})
.collect();
if targets.is_empty() {
return;
}
info!(
"asking {} for their kernel",
counted(targets.len() as u128, "host", "hosts")
);
let mut named = 0usize;
let mut pool = ProbePool::new(
CONNECT_CONCURRENCY,
ctx.clone(),
ScannerKind::OsSnmp,
|found: Option<(
crate::model::ip::scoped::ScopedIp,
Port,
crate::fingerprint::AboutTheHost,
)>,
_audit| {
if let Some((key, port, about)) = found {
ctx.update_host(key, |host| {
host.add_port(port);
if about.apply(host) {
named += 1;
}
});
}
},
);
for target in targets {
if ctx.handle.should_stop() {
break;
}
let egress = ctx.egress_toward(target.addr());
pool.admit(ask_for_kernel(target, egress)).await;
}
pool.drain().await;
if named > 0 {
info!(
verbosity = 1,
"named {} by SNMP",
counted(named as u128, "host", "hosts")
);
}
}
pub(super) async fn run_active_os_mdns(ctx: &ScanContext, os_detection: OsDetection) {
if !os_detection.is_active() {
return;
}
ctx.enter_stage(Stage::Os, None);
let targets: Vec<(crate::model::ip::scoped::ScopedIp, Option<String>)> = ctx
.host_addresses()
.into_iter()
.filter(|ip| !ctx.host_expired(ip.addr()))
.filter_map(|ip| {
ctx.read_host(&ip, |host| {
let name = host.hostname().map(str::to_string);
host.status().is_up().then(|| (host.scoped_ip(), name))
})
.flatten()
})
.collect();
if targets.is_empty() {
return;
}
info!(
"asking {} what hardware they are",
counted(targets.len() as u128, "host", "hosts")
);
let mut named = 0usize;
let mut pool = ProbePool::new(
CONNECT_CONCURRENCY,
ctx.clone(),
ScannerKind::OsSnmp,
|found: Option<(crate::model::ip::scoped::ScopedIp, Vec<OsEvidence>)>, _audit| {
if let Some((key, evidence)) = found {
ctx.update_host(key, |host| {
if os::identify(host, evidence) {
named += 1;
}
});
}
},
);
for (target, hostname) in targets {
if ctx.handle.should_stop() {
break;
}
let egress = ctx.egress_toward(target.addr());
pool.admit(ask_what_hardware(target, hostname, egress))
.await;
}
pool.drain().await;
if named > 0 {
info!(
verbosity = 1,
"named {} by mDNS",
counted(named as u128, "host", "hosts")
);
}
}
const MDNS_PORT: u16 = 5353;
async fn own_name(
addr: std::net::SocketAddr,
ip: IpAddr,
egress: crate::transport::dial::Egress,
) -> Option<String> {
let query = crate::protocols::mdns::build_reverse_query(ip).ok()?;
let reply = crate::fingerprint::probe_udp_raw_via(addr, &query, egress).await?;
crate::protocols::mdns::extract_hosts(&reply)
.ok()?
.into_iter()
.map(|host| host.hostname)
.find(|name| !name.is_empty())
}
async fn ask_what_hardware(
target: crate::model::ip::scoped::ScopedIp,
hostname: Option<String>,
egress: crate::transport::dial::Egress,
) -> Option<(crate::model::ip::scoped::ScopedIp, Vec<OsEvidence>)> {
let addr = target.to_socket_addr(MDNS_PORT)?;
let question = |name: &str| crate::protocols::mdns::build_device_info_query(name)?.ok();
let query = match hostname.as_deref().and_then(question) {
Some(query) => query,
None => question(&own_name(addr, target.addr(), egress).await?)?,
};
let evidence: Vec<OsEvidence> = crate::fingerprint::probe_udp_with_via(addr, &query, egress)
.await
.iter()
.filter_map(|text| {
crate::fingerprint::SignatureDb::global()
.identify(MDNS_PORT, Protocol::Udp, text)?
.os
})
.collect();
(!evidence.is_empty()).then_some((target, evidence))
}
const SNMP_PORT: u16 = 161;
async fn ask_for_kernel(
target: crate::model::ip::scoped::ScopedIp,
egress: crate::transport::dial::Egress,
) -> Option<(
crate::model::ip::scoped::ScopedIp,
Port,
crate::fingerprint::AboutTheHost,
)> {
let addr = target.to_socket_addr(SNMP_PORT)?;
let port = crate::fingerprint::baseline_port(SNMP_PORT, Protocol::Udp, PortState::Open);
let (port, evidence, _) = crate::fingerprint::fingerprint_udp_via(addr, port, egress).await?;
let port = port.with_discovery(PortDiscovery::new(ScanResponse::UdpResponse));
Some((target, port, evidence))
}
pub(super) async fn run_traceroute(
ctx: &ScanContext,
cfg: &crate::config::ZondConfig,
caps: ScanCapabilities,
) {
if !cfg.traceroute {
return;
}
ctx.enter_stage(Stage::Traceroute, None);
let mut alive: Vec<IpAddr> = ctx
.host_addresses()
.into_iter()
.filter(|key| {
ctx.read_host(key, |host| host.status().is_up())
.unwrap_or(false)
})
.filter_map(routable)
.collect();
alive.sort_unstable();
alive.dedup();
let alive = within_frames(
alive,
|ip| *ip,
caps,
&cfg.send_source,
ctx,
ScannerKind::Routed,
"the route trace",
);
if alive.is_empty() {
return;
}
info!(
"measuring the route to {}",
counted(alive.len() as u128, "host", "hosts")
);
strategy::topology::traceroute::trace(ctx, alive).await;
}
pub(super) fn run_correlation(ctx: &ScanContext, detection: ServiceDetection) {
if detection == ServiceDetection::Off {
return;
}
for key in ctx.host_addresses() {
ctx.update_host(key, crate::cve::correlate);
}
}
pub(super) fn run_cert_posture(ctx: &ScanContext) {
let now = std::time::SystemTime::now();
for key in ctx.host_addresses() {
ctx.update_host(key, |host| {
let hits: Vec<(u16, Protocol, crate::model::finding::Finding)> = host
.ports()
.flat_map(|port| {
let number = port.number();
let protocol = port.protocol();
port.security()
.and_then(|security| security.certificate())
.map(|cert| cert.findings(now))
.unwrap_or_default()
.into_iter()
.map(move |finding| (number, protocol, finding))
.collect::<Vec<_>>()
})
.collect();
for (number, protocol, finding) in hits {
host.add_port_finding(number, protocol, finding);
}
});
}
}
pub(super) async fn run_characterise(
ctx: &ScanContext,
cfg: &crate::config::ZondConfig,
caps: ScanCapabilities,
) {
if !cfg.characterise {
return;
}
let mut subjects: Vec<strategy::topology::characterise::Subject> = Vec::new();
for key in ctx.host_addresses() {
if ctx.host_expired(key.addr()) {
continue;
}
let ports = ctx.read_host(&key, |host| {
host.status().is_up().then(|| {
let tcp = |state| {
host.ports()
.find(|port| port.protocol() == Protocol::Tcp && port.state() == state)
.map(|port| port.number())
};
(tcp(PortState::Open), tcp(PortState::Filtered))
})
});
let Some(Some((open_port, filtered_port))) = ports else {
continue;
};
if open_port.is_none() && filtered_port.is_none() {
continue;
}
if let Some(host) = routable(key) {
subjects.push(strategy::topology::characterise::Subject {
host,
open_port,
filtered_port,
});
}
}
let subjects = within_frames(
subjects,
|subject| subject.host,
caps,
&cfg.send_source,
ctx,
ScannerKind::Routed,
"the filter characterisation",
);
if subjects.is_empty() {
return;
}
strategy::topology::characterise::characterise(ctx, subjects).await;
}
pub(super) async fn run_ip_protocols(ctx: &ScanContext, cfg: &crate::config::ZondConfig) {
if cfg.ip_protocols.is_empty() {
return;
}
let mut targets = Vec::new();
for key in ctx.host_addresses() {
if ctx.host_expired(key.addr()) {
continue;
}
if ctx.read_host(&key, |host| host.status().is_up()) != Some(true) {
continue;
}
if let Some(host) = routable(key) {
targets.push(host);
}
}
strategy::protocols::probe(ctx, &targets, &cfg.ip_protocols).await;
}
pub(super) async fn run_tls_enumeration(ctx: &ScanContext, cfg: &crate::config::ZondConfig) {
if !cfg.tls_enumeration {
return;
}
let targets = tls_ports(ctx);
if targets.is_empty() {
return;
}
ctx.enter_stage(Stage::Tls, Some(targets.len() as u64));
let ports = targets.len() as u128;
let accept = if ports == 1 { "accepts" } else { "accept" };
info!(
"enumerating what {} {accept}",
counted(ports, "TLS port", "TLS ports")
);
let mut pool = ProbePool::new(
CONNECT_CONCURRENCY,
ctx.clone(),
ScannerKind::Service,
|found: Option<(
crate::model::ip::scoped::ScopedIp,
u16,
crate::model::tls::TlsSupport,
)>,
_audit| {
ctx.stage_advanced();
if let Some((key, number, support)) = found {
record_tls_support(ctx, key, number, support);
}
},
);
for (address, number) in targets {
if ctx.handle.should_stop() {
break;
}
if ctx.host_expired(address.addr()) {
continue;
}
pool.admit(enumerate_one(ctx.clone(), address, number))
.await;
}
pool.drain().await;
}
fn tls_ports(ctx: &ScanContext) -> Vec<(crate::model::ip::scoped::ScopedIp, u16)> {
let mut targets = Vec::new();
for host in ctx.store.iter() {
let address = host.value().scoped_ip();
for port in host.value().ports() {
if port.protocol() == Protocol::Tcp
&& port.state() == PortState::Open
&& port.security().is_some()
&& !ctx.listens_only(port.number(), port.protocol())
{
targets.push((address.clone(), port.number()));
}
}
}
targets
}
async fn enumerate_one(
ctx: ScanContext,
address: crate::model::ip::scoped::ScopedIp,
number: u16,
) -> Option<(
crate::model::ip::scoped::ScopedIp,
u16,
crate::model::tls::TlsSupport,
)> {
let socket = address.to_socket_addr(number)?;
let ip = address.addr();
let support = crate::fingerprint::enumerate_tls_while(socket, ctx.egress_toward(ip), || {
!ctx.handle.should_stop() && !ctx.host_expired(ip)
})
.await;
(!support.is_empty()).then_some((address, number, support))
}
fn record_tls_support(
ctx: &ScanContext,
key: crate::model::ip::scoped::ScopedIp,
number: u16,
support: crate::model::tls::TlsSupport,
) {
let findings = support.findings();
let mut carrier = crate::model::port::Port::new(number, Protocol::Tcp, PortState::Open)
.with_security(crate::model::port::Security::new().with_support(support));
for finding in findings {
carrier.add_finding(finding);
}
ctx.update_host(key, |host| {
host.add_port(carrier);
});
}
pub(super) async fn run_active_os_probe(
ctx: &ScanContext,
os_detection: crate::config::OsDetection,
tuning: ProbeTuning,
caps: ScanCapabilities,
) {
if !os_detection.is_active() {
return;
}
ctx.enter_stage(Stage::Os, None);
let mut unnamed: Vec<IpAddr> = ctx
.host_addresses()
.into_iter()
.filter(|key| !ctx.host_expired(key.addr()))
.filter(|key| {
ctx.read_host(key, |host| {
host.status().is_up() && host.os().is_none_or(|os| !os.is_highly_confident())
})
.unwrap_or(false)
})
.filter_map(routable)
.collect();
unnamed.sort_unstable();
unnamed.dedup();
let unnamed = within_frames(
unnamed,
|ip| *ip,
caps,
&tuning.send_source,
ctx,
ScannerKind::OsEcho,
"the OS echo probe",
);
if unnamed.is_empty() {
return;
}
info!(
"probing {} the passive sources could not name, by echo",
counted(unnamed.len() as u128, "host", "hosts")
);
match strategy::identify::echo::OsEchoScanner::new(ctx.clone(), unnamed, tuning) {
Ok(mut scanner) => {
if let Err(e) = scanner.probe().await {
ctx.record_failure(ScannerKind::OsEcho, e.to_string());
}
}
Err(e) => ctx.record_failure(
ScannerKind::OsEcho,
format!("the active echo probe could not open its transport: {e}"),
),
}
}
pub(super) fn unsettled_ips(target_map: &TargetMap, settled: &Checkpoint) -> IpSet {
settled.remaining_hosts(&TargetIndex::of(target_map))
}
pub(super) async fn spawn_resolver(
dns_rx: UnboundedReceiver<IpAddr>,
) -> JoinHandle<Option<HostnameResolver>> {
tokio::spawn(async move {
match HostnameResolver::new(dns_rx) {
Ok(resolver) => {
success!(verbosity = 3, "successfully initialized hostname resolver");
Some(resolver.run().await)
}
Err(e) => {
error!("resolver failed to start: {e}");
None
}
}
})
}
fn withhold_ambiguous_targets(target_map: &mut TargetMap, ctx: &ScanContext) -> ZoneMap {
let mut refused: Vec<Ipv6Range> = Vec::new();
let mut contested: Vec<Ipv6Range> = Vec::new();
let mut zones = ZoneMap::new();
let named_a_zone = target_map
.units
.iter()
.flat_map(|unit| unit.ips().v6())
.any(|range| range.zone().is_some());
let links = match named_a_zone {
true => crate::system::interface::interfaces(),
false => Vec::new(),
};
let names: Vec<(u32, &str)> = links
.iter()
.map(|link| (link.index(), link.name()))
.collect();
for range in target_map.units.iter().flat_map(|unit| unit.ips().v6()) {
if range.is_ambiguous() {
refused.push(*range);
} else if zones.contests(range) {
contested.push(*range);
} else {
zones.insert(*range, &names);
}
}
let mut kept = Vec::with_capacity(target_map.units.len());
for unit in std::mem::take(&mut target_map.units) {
let (ips, ports) = unit.into_parts();
let mut walkable = IpSet::new();
for range in ips.v4() {
walkable.push_v4_range(*range);
}
for range in ips.v6() {
if !refused.contains(range) && !contested.contains(range) {
walkable.push_v6_range(*range);
}
}
walkable.canonicalize();
if !walkable.is_empty() {
kept.push(TargetSet::new(walkable, ports));
}
}
target_map.units = kept;
refused.sort_unstable_by_key(|range| range.start_addr());
refused.dedup();
for range in refused {
ctx.record_refusal(
plan::RefusedStep::link_local_port_target_needs_an_interface(&range).into(),
);
}
for range in contested {
ctx.record_refusal(
plan::RefusedStep::link_local_port_target_names_two_segments(&range).into(),
);
}
zones
}
pub(super) async fn run_port_phase(
mut target_map: TargetMap,
liveness: Option<Liveness>,
ctx: &ScanContext,
caps: ScanCapabilities,
cfg: &ZondConfig,
settled: Checkpoint,
stands_in: bool,
) {
if target_map.is_empty() {
return;
}
let zones = withhold_ambiguous_targets(&mut target_map, ctx);
if target_map.is_empty() {
return;
}
ctx.learn_zones(zones.clone());
let target_count = target_map.gross_targets().unwrap_or(0) as usize;
let mut plan = super::plan::PortScanPlan::build(cfg, caps.privilege);
if target_map.names(Protocol::Sctp) {
plan.cover_sctp(caps.privilege);
}
if target_map.names(Protocol::Udp) {
plan.cover_udp(caps.privilege);
}
let mut probed = unsettled_ips(&target_map, &settled);
if let Some(liveness) = &liveness {
probed = within(&probed, &liveness.live);
}
let beyond = caps.beyond_frames(&probed, &cfg.send_source, interface::FrameSender::Probe);
let raw = RawReach::of(&probed, beyond.targets.clone());
let named: Vec<Protocol> = Protocol::ALL
.into_iter()
.filter(|protocol| target_map.names(*protocol))
.collect();
let built = build_port_scanner(
plan,
&named,
ctx,
target_count,
cfg.probe_tuning(),
&zones,
&raw,
);
if built.reached_by_connect {
announce_beyond_frames(&beyond);
}
let mut dispatcher = super::dispatcher::Dispatcher::new(target_map).resuming(settled);
if let Some(Liveness { live, silent }) = liveness {
dispatcher = dispatcher.screened(live, silent);
}
let (rx, walk) = dispatcher.spawn(ctx);
run_port_scan(built.scanner, rx, ctx, cfg.service_detection, cfg.detection).await;
if let Err(error) = walk.await {
error!("the target walk ended abnormally: {error}");
}
if stands_in {
forget_the_silent(ctx, &probed);
}
let unheard = match cfg.assume_up {
true => rdns::Unheard::Named,
false => rdns::Unheard::Skipped,
};
finish_enrichment(None, caps, ctx, unheard).await;
run_passive_os_identification(ctx, cfg.os_detection);
}
fn forget_the_silent(ctx: &ScanContext, probed: &IpSet) {
let mut silent = Vec::new();
let mut undecided = Vec::new();
for entry in ctx.store.iter() {
let host = entry.value();
let address = entry.key().addr();
if host.status() != crate::model::host::HostStatus::Unknown
|| !probed.contains(&address)
|| ctx.is_unroutable(address)
{
continue;
}
let finished =
host.ports().all(|port| port.state() != PortState::Unasked) && !ctx.left_early(address);
match finished {
true => silent.push(entry.key().clone()),
false => undecided.push(entry.key().clone()),
}
}
ctx.forget_silent(silent);
ctx.forget_undecided(undecided);
}
pub(super) fn probed_subset(target_map: &TargetMap, live: &IpSet) -> TargetMap {
let live: Vec<IpAddr> = live.iter().collect();
let mut kept = TargetMap::new();
for unit in &target_map.units {
let mut ips = IpSet::new();
for ip in &live {
if unit.ips().contains(ip) {
push_single(&mut ips, *ip, None);
}
}
ips.canonicalize();
if !ips.is_empty() {
kept.add_unit(TargetSet::new(ips, unit.ports().clone()));
}
}
kept
}
pub(super) fn sctp_discovery_port(map: &TargetMap) -> Option<u16> {
let named: Vec<u16> = map
.units
.iter()
.flat_map(|unit| unit.ports().ranges(Protocol::Sctp))
.flat_map(|range| range.clone())
.collect();
named.iter().copied().min_by_key(|port| {
let rank = crate::model::port::catalog::SCTP_BY_PREVALENCE
.iter()
.position(|known| known == port)
.unwrap_or(usize::MAX);
(rank, *port)
})
}
pub(super) struct Liveness {
pub(super) live: IpSet,
pub(super) silent: IpSet,
}
impl Liveness {
pub(super) fn found(ctx: &ScanContext, silent: IpSet) -> Self {
Self {
live: live_addresses(ctx),
silent,
}
}
pub(super) fn undecided(&self, scope: &TargetScope, unroutable: &[IpAddr]) -> Vec<IpRange> {
let mut undecided = IpSet::new();
for range in scope.ranges() {
undecided.insert_range(*range);
}
undecided.subtract(&self.live);
undecided.subtract(&self.silent);
let mut unreachable = IpSet::new();
for address in unroutable {
unreachable.insert(*address);
}
undecided.subtract(&unreachable);
undecided.canonicalize();
let v4 = undecided.v4().iter().copied().map(IpRange::V4);
let v6 = undecided.v6().iter().copied().map(IpRange::V6);
v4.chain(v6).collect()
}
}
pub(super) fn live_addresses(ctx: &ScanContext) -> IpSet {
let mut live = IpSet::new();
for entry in ctx.store.iter() {
let host = entry.value();
if !host.is_alive() {
continue;
}
for ip in host.ips() {
push_single(&mut live, *ip, host.zone().and_then(Zone::index));
}
}
live.canonicalize();
live
}
fn routable(key: crate::model::ip::scoped::ScopedIp) -> Option<IpAddr> {
(!crate::model::ip::scoped::ScopedIp::needs_zone(&key.addr())).then(|| key.addr())
}
fn within(set: &IpSet, of: &IpSet) -> IpSet {
let mut outside = set.clone();
outside.subtract(of);
let mut inside = set.clone();
inside.subtract(&outside);
inside
}
fn push_single(set: &mut IpSet, ip: IpAddr, zone: Option<u32>) {
match ip {
IpAddr::V4(v4) => {
if let Ok(range) = Ipv4Range::new(v4, v4) {
set.push_v4_range(range);
}
}
IpAddr::V6(v6) => {
let zone = v6.is_unicast_link_local().then_some(zone).flatten();
if let Ok(range) = Ipv6Range::scoped(v6, v6, zone) {
set.push_v6_range(range);
}
}
}
}
#[cfg(test)]
mod tests {
#[test]
fn the_sweep_asks_on_the_likeliest_of_the_ports_the_scan_named() {
use crate::model::target::TargetSet;
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
"192.0.2.1".parse().expect("an address"),
"s:9999, s:3868, s:2905".parse().expect("a specification"),
));
assert_eq!(sctp_discovery_port(&map), Some(3868));
}
#[test]
fn a_sweep_over_unknown_ports_still_picks_one_deterministically() {
use crate::model::target::TargetSet;
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
"192.0.2.1".parse().expect("an address"),
"s:9999, s:9001".parse().expect("a specification"),
));
assert_eq!(sctp_discovery_port(&map), Some(9001));
}
#[test]
fn a_scan_naming_no_sctp_port_sweeps_none() {
use crate::model::target::TargetSet;
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
"192.0.2.1".parse().expect("an address"),
"80, u:53".parse().expect("a specification"),
));
assert_eq!(sctp_discovery_port(&map), None);
}
fn scoped_set(addr: &str, zone: u32) -> IpSet {
use crate::model::ip::range::IpRange;
let addr: std::net::Ipv6Addr = addr.parse().expect("an address");
let mut set = IpSet::new();
set.insert_range(IpRange::V6(
Ipv6Range::scoped(addr, addr, Some(zone)).expect("a scoped range"),
));
set.canonicalize();
set
}
#[test]
fn a_bare_link_local_port_target_is_refused_rather_than_probed() {
use crate::model::target::TargetSet;
use crate::scanner::session::ScanSession;
let (_session, ctx) = ScanSession::new();
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
ip_set(&["fe80::1"]),
"80".parse().expect("a port set"),
));
withhold_ambiguous_targets(&mut map, &ctx);
assert!(map.is_empty(), "nothing is left for a scanner to probe");
let refusals = ctx.refusals_snapshot();
assert_eq!(refusals.len(), 1);
assert!(
refusals[0].reason().contains("fe80::1%en0"),
"the refusal says what the caller could write instead: {}",
refusals[0].reason()
);
assert!(
ctx.failures_snapshot().is_empty(),
"nothing went wrong; the engine declined"
);
}
#[test]
fn a_link_local_target_that_names_an_interface_is_kept_with_its_zone() {
use crate::model::target::TargetSet;
use crate::scanner::session::ScanSession;
let (_session, ctx) = ScanSession::new();
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
scoped_set("fe80::1", 15),
"80".parse().expect("a port set"),
));
let zones = withhold_ambiguous_targets(&mut map, &ctx);
assert_eq!(map.units.len(), 1, "the target is still there to probe");
assert_eq!(
zones.zone_of(&"fe80::1".parse().expect("an address")),
Some(15),
"and the send knows which interface to leave by"
);
assert!(ctx.refusals_snapshot().is_empty());
}
#[test]
fn one_link_local_address_on_two_interfaces_is_refused() {
use crate::model::target::TargetSet;
use crate::scanner::session::ScanSession;
let (_session, ctx) = ScanSession::new();
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
scoped_set("fe80::1", 15),
"80".parse().expect("a port set"),
));
map.add_unit(TargetSet::new(
scoped_set("fe80::1", 16),
"80".parse().expect("a port set"),
));
let zones = withhold_ambiguous_targets(&mut map, &ctx);
assert_eq!(map.units.len(), 1, "the first one named is still probed");
assert_eq!(
zones.zone_of(&"fe80::1".parse().expect("an address")),
Some(15)
);
let refusals = ctx.refusals_snapshot();
assert_eq!(refusals.len(), 1);
assert!(
refusals[0].reason().contains("two interfaces"),
"the refusal says which question could not be answered: {}",
refusals[0].reason()
);
}
#[test]
fn the_addressable_targets_beside_it_survive() {
use crate::model::target::TargetSet;
use crate::scanner::session::ScanSession;
let (_session, ctx) = ScanSession::new();
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
ip_set(&["fe80::1", "192.0.2.7", "2001:db8::1"]),
"80".parse().expect("a port set"),
));
withhold_ambiguous_targets(&mut map, &ctx);
assert_eq!(map.units.len(), 1);
assert_eq!(map.units[0].ips().len(), 2, "the two addressable ones");
assert_eq!(ctx.refusals_snapshot().len(), 1);
}
#[test]
fn an_ordinary_target_map_is_left_alone() {
use crate::model::target::TargetSet;
use crate::scanner::session::ScanSession;
let (_session, ctx) = ScanSession::new();
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
ip_set(&["192.0.2.0/30"]),
"80".parse().expect("a port set"),
));
withhold_ambiguous_targets(&mut map, &ctx);
assert_eq!(map.units[0].ips().len(), 4);
assert!(ctx.refusals_snapshot().is_empty());
}
use super::*;
use crate::model::host::{Host, HostStatus};
use crate::report::Refusal;
use crate::scanner::session::ScanSession;
use tokio::sync::mpsc;
#[test]
fn this_hosts_own_address_is_settled_with_the_rest_of_a_sweep() {
let plan: IpSet = "192.0.2.1-192.0.2.3".parse().expect("a range");
let (_session, ctx) = ScanSession::builder().counting(plan.positions()).build();
ctx.settle_address(
"192.0.2.1".parse().expect("an address"),
crate::journal::settle::Settled::Answered,
);
ctx.settle_address(
"192.0.2.3".parse().expect("an address"),
crate::journal::settle::Settled::Answered,
);
record_our_own_addresses(&"192.0.2.2".parse().expect("an address"), &ctx);
assert_eq!(ctx.settlements().checkpoint().watermark, 3);
}
struct StubScanner(Vec<Protocol>);
#[async_trait::async_trait]
impl PortScanner for StubScanner {
fn kind(&self) -> ScannerKind {
ScannerKind::SynPort
}
fn supported_protocols(&self) -> Vec<Protocol> {
self.0.clone()
}
async fn scan(
&mut self,
_targets: mpsc::Receiver<PlannedTarget>,
) -> Result<(), StrategyError> {
Ok(())
}
}
const BOTH: &[Protocol] = &[Protocol::Tcp, Protocol::Udp];
fn ip_set(exprs: &[&str]) -> IpSet {
crate::model::parse::ip::to_set(exprs, None, None).expect("hand-written targets parse")
}
#[test]
fn a_range_too_large_to_walk_is_refused_rather_than_started() {
let (_session, ctx) = ScanSession::new();
let kept = walkable(ip_set(&["2001:db8::/64"]), &ctx);
assert!(kept.is_empty(), "nothing here can be walked");
assert!(ctx.failures_snapshot().is_empty(), "nothing went wrong");
let refusals = ctx.refusals_snapshot();
assert_eq!(refusals.len(), 1);
assert_eq!(refusals[0].scanner(), ScannerKind::Connect);
assert!(
refusals[0].reason().contains("18446744073709551616"),
"the refusal quotes the size it is refusing: {}",
refusals[0].reason()
);
}
#[test]
fn the_walkable_part_of_a_mixed_set_survives() {
let (_session, ctx) = ScanSession::new();
let kept = walkable(
ip_set(&["2001:db8::/64", "192.0.2.0/30", "2001:db8:1::/126"]),
&ctx,
);
assert_eq!(kept.len(), 8);
assert_eq!(ctx.refusals_snapshot().len(), 1);
assert!(ctx.failures_snapshot().is_empty());
}
#[test]
fn a_set_that_can_be_walked_is_left_alone_and_files_nothing() {
let (_session, ctx) = ScanSession::new();
let kept = walkable(ip_set(&["192.0.2.0/24", "2001:db8::/120"]), &ctx);
assert_eq!(kept.len(), 512);
assert!(ctx.failures_snapshot().is_empty());
}
#[test]
fn a_large_ipv4_range_is_not_this_functions_business() {
let (_session, ctx) = ScanSession::new();
let kept = walkable(ip_set(&["10.0.0.0/8"]), &ctx);
assert_eq!(kept.len(), 1 << 24);
assert!(ctx.failures_snapshot().is_empty());
}
fn covered(scanners: Vec<Box<dyn PortScanner>>) -> Vec<Protocol> {
let (_session, ctx) = ScanSession::new();
ensure_coverage(
reaching_everything(scanners),
&ctx,
TcpScanTechnique::Syn,
BOTH,
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::Everything,
)
.routes
.iter()
.flat_map(|(scanner, _)| scanner.supported_protocols())
.collect()
}
fn reaching_everything(
scanners: Vec<Box<dyn PortScanner>>,
) -> Vec<(Box<dyn PortScanner>, Reach)> {
scanners
.into_iter()
.map(|scanner| (scanner, Reach::Any))
.collect()
}
fn raw_everywhere() -> ScanCapabilities {
ScanCapabilities {
privilege: Privilege::Raw,
frames_only: false,
dns: false,
}
}
#[test]
fn a_refusal_the_plan_already_made_is_not_recorded_again() {
let cfg = ZondConfig {
tcp_technique: TcpScanTechnique::Fin,
..ZondConfig::default()
};
let (_session, ctx) = ScanSession::new();
let _built = build_port_scanner(
plan::PortScanPlan::build(&cfg, Privilege::Connect),
BOTH,
&ctx,
0,
cfg.probe_tuning(),
&ZoneMap::new(),
&RawReach::Everything,
);
let refusals = ctx.take_refusals();
assert_eq!(
refusals.len(),
1,
"one cause, one entry: {:?}",
refusals.iter().map(Refusal::reason).collect::<Vec<_>>()
);
assert_eq!(refusals[0].scanner(), ScannerKind::TcpPort);
assert!(refusals[0].reason().contains("fin"));
}
#[tokio::test]
async fn an_idle_scans_udp_ports_are_refused_rather_than_lost() {
use crate::journal::cursor::Checkpoint;
use crate::model::exclusion::Exclusions;
use crate::model::target::TargetSet;
let cfg = ZondConfig {
idle_scan: Some(crate::config::IdleScan::new(
"192.0.2.9".parse().expect("an address"),
)),
exclusions: Exclusions::new(ip_set(&["192.0.2.9"])),
..ZondConfig::default()
};
let mut map = TargetMap::new();
map.add_unit(TargetSet::new(
ip_set(&["192.0.2.1"]),
"80, u:53".parse().expect("a port set"),
));
let (_session, ctx) = ScanSession::new();
let caps = ScanCapabilities {
privilege: Privilege::Connect,
frames_only: false,
dns: false,
};
run_port_phase(map, None, &ctx, caps, &cfg, Checkpoint::default(), false).await;
let failures = ctx.take_failures();
assert!(
failures.is_empty(),
"a port the plan chose not to probe is not one the scan lost: {failures:?}"
);
let refusals = ctx.take_refusals();
let reasons: Vec<&str> = refusals.iter().map(Refusal::reason).collect();
assert!(
reasons
.iter()
.any(|reason| reason.contains("udp") && reason.contains("idle scan")),
"the refusal names UDP under an idle scan: {reasons:?}"
);
}
#[test]
fn raw_reach_is_everything_part_or_nothing() {
let probed = ip_set(&["127.0.0.1", "192.0.2.8"]);
assert!(matches!(
RawReach::of(&probed, IpSet::new()),
RawReach::Everything
));
assert!(matches!(
RawReach::of(&probed, ip_set(&["127.0.0.1"])),
RawReach::AllBut(_)
));
assert!(matches!(
RawReach::of(&probed, ip_set(&["127.0.0.1", "192.0.2.8"])),
RawReach::Nothing(_)
));
}
#[test]
fn nothing_within_a_frames_reach_opens_no_raw_strategy() {
let cfg = ZondConfig::default();
let (_session, ctx) = ScanSession::new();
let mut plan = plan::PortScanPlan::build(&cfg, Privilege::Raw);
plan.cover_udp(Privilege::Raw);
let built = build_port_scanner(
plan,
BOTH,
&ctx,
1,
cfg.probe_tuning(),
&ZoneMap::new(),
&RawReach::Nothing(ip_set(&["127.0.0.1"])),
);
assert_eq!(
built.scanner.supported_protocols(),
vec![Protocol::Tcp, Protocol::Udp],
"and the connect strategies cover both protocols"
);
assert!(ctx.take_failures().is_empty(), "declining is not failing");
assert!(ctx.take_refusals().is_empty());
assert_eq!(ctx.take_reached_by_connect().len(), 1);
}
#[tokio::test]
async fn a_refused_technique_is_reported_once_and_not_as_a_failure() {
let cfg = ZondConfig {
tcp_technique: TcpScanTechnique::Fin,
..ZondConfig::default()
};
let loopback = crate::model::target::Target {
ip: IpAddr::V4(std::net::Ipv4Addr::LOCALHOST),
port: 80,
protocol: Protocol::Tcp,
};
let paths = [
("connect", Privilege::Connect, RawReach::Everything),
(
"frames",
Privilege::Raw,
RawReach::Nothing(ip_set(&["127.0.0.1"])),
),
];
for (path, privilege, raw) in paths {
let (_session, ctx) = ScanSession::new();
let mut built = build_port_scanner(
plan::PortScanPlan::build(&cfg, privilege),
&[Protocol::Tcp],
&ctx,
1,
cfg.probe_tuning(),
&ZoneMap::new(),
&raw,
);
let (tx, rx) = mpsc::channel(1);
tx.send(PlannedTarget::new(0, loopback))
.await
.expect("the router is listening");
drop(tx);
built
.scanner
.scan(rx)
.await
.expect("a refusal is not an error");
let refusals = ctx.take_refusals();
assert_eq!(refusals.len(), 1, "{path}: {refusals:?}");
assert!(refusals[0].reason().contains("fin"), "{path}: {refusals:?}");
let failures = ctx.take_failures();
assert!(failures.is_empty(), "{path}: {failures:?}");
assert!(
ctx.take_reached_by_connect().is_empty(),
"{path}: nothing was reached by connect"
);
assert_eq!(
ctx.settlements()
.count(crate::journal::settle::Outcome::Unroutable),
1,
"{path}: the refused target is still owed a probe"
);
}
}
#[derive(Clone, Default)]
struct Heard(Arc<std::sync::Mutex<Vec<String>>>);
impl tracing::Subscriber for Heard {
fn enabled(&self, _: &tracing::Metadata<'_>) -> bool {
true
}
fn new_span(&self, _: &tracing::span::Attributes<'_>) -> tracing::span::Id {
tracing::span::Id::from_u64(1)
}
fn record(&self, _: &tracing::span::Id, _: &tracing::span::Record<'_>) {}
fn record_follows_from(&self, _: &tracing::span::Id, _: &tracing::span::Id) {}
fn event(&self, event: &tracing::Event<'_>) {
struct Message<'a>(&'a mut String);
impl tracing::field::Visit for Message<'_> {
fn record_debug(
&mut self,
field: &tracing::field::Field,
value: &dyn std::fmt::Debug,
) {
if field.name() == "message" {
*self.0 = format!("{value:?}");
}
}
}
let mut message = String::new();
event.record(&mut Message(&mut message));
self.0.lock().expect("an unpoisoned log").push(message);
}
fn enter(&self, _: &tracing::span::Id) {}
fn exit(&self, _: &tracing::span::Id) {}
}
#[test]
fn an_unprivileged_run_says_it_probes_udp_when_it_does() {
let unprivileged = ScanCapabilities {
privilege: Privilege::Connect,
frames_only: false,
dns: false,
};
for (udp, expected) in [
(
true,
"no raw sockets: probing with TCP connect and plain UDP datagrams",
),
(false, "no raw sockets: probing with TCP connect only"),
] {
let probing = Probing {
udp,
..Probing::sweep()
};
let heard = Heard::default();
tracing::subscriber::with_default(heard.clone(), || {
unprivileged.announce(probing, false);
});
let said = heard.0.lock().expect("an unpoisoned log").clone();
assert_eq!(said, [expected], "probing udp: {udp}");
}
}
#[test]
fn a_raw_run_names_the_technique_and_every_protocol_it_probes() {
let raw = ScanCapabilities {
privilege: Privilege::Raw,
frames_only: false,
dns: false,
};
let unit = |ports: &str| {
let mut map = TargetMap::new();
map.add_unit(crate::model::target::TargetSet::new(
"192.0.2.1".parse().expect("an address"),
ports.parse().expect("a specification"),
));
map
};
let map = unit("22, u:53, s:2905");
let fin = ZondConfig {
tcp_technique: TcpScanTechnique::Fin,
..ZondConfig::default()
};
let udp_only = unit("u:53");
for (probing, raw_sockets, expected) in [
(
Probing::sweep(),
true,
"probing with ARP, ICMPv6 and SYN (raw sockets)",
),
(
Probing::ports(&ZondConfig::default(), &map),
true,
"probing with ARP, ICMPv6, SYN, UDP and SCTP INIT (raw sockets)",
),
(
Probing::ports(&fin, &map),
false,
"probing with ARP, ICMPv6, SYN, FIN, UDP and SCTP INIT (link-layer frames)",
),
(
Probing::ports(&fin, &udp_only),
true,
"probing with ARP, ICMPv6, SYN and UDP (raw sockets)",
),
] {
let heard = Heard::default();
tracing::subscriber::with_default(heard.clone(), || {
raw.announce(probing, raw_sockets);
});
let said = heard.0.lock().expect("an unpoisoned log").clone();
assert_eq!(said, [expected], "{probing:?}");
}
}
#[test]
fn a_frames_only_refusal_names_the_frames_reach_rather_than_privilege() {
let cfg = ZondConfig {
tcp_technique: TcpScanTechnique::Fin,
..ZondConfig::default()
};
let (_session, ctx) = ScanSession::new();
let mut plan = plan::PortScanPlan::build(&cfg, Privilege::Raw);
plan.cover_sctp(Privilege::Raw);
let _built = build_port_scanner(
plan,
&[Protocol::Tcp, Protocol::Sctp],
&ctx,
2,
cfg.probe_tuning(),
&ZoneMap::new(),
&RawReach::Nothing(ip_set(&["127.0.0.1"])),
);
let refusals = ctx.take_refusals();
let reasons: Vec<&str> = refusals.iter().map(Refusal::reason).collect();
assert_eq!(reasons.len(), 2, "one for each protocol: {reasons:?}");
for reason in reasons {
assert!(
reason.contains("needs a raw socket"),
"the frames path's reason: {reason}"
);
assert!(
!reason.contains("needs raw sockets"),
"not the connect path's: {reason}"
);
assert!(
reason.contains("on 1 target:"),
"and it counts the one target it names: {reason}"
);
}
}
#[test]
fn an_unprivileged_scan_covers_both_protocols() {
let protocols = covered(Vec::new());
assert!(protocols.contains(&Protocol::Tcp));
assert!(protocols.contains(&Protocol::Udp));
}
#[test]
fn a_protocol_without_a_privileged_scanner_still_gets_a_fallback() {
let protocols = covered(vec![Box::new(StubScanner(vec![Protocol::Udp]))]);
assert!(
protocols.contains(&Protocol::Tcp),
"TCP targets would be silently dropped"
);
assert!(protocols.contains(&Protocol::Udp));
}
#[test]
fn a_technique_the_fallback_cannot_express_is_reported_rather_than_substituted() {
let (_session, ctx) = ScanSession::new();
let scanners = ensure_coverage(
Vec::new(),
&ctx,
TcpScanTechnique::Fin,
BOTH,
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::Everything,
)
.routes;
let protocols: Vec<Protocol> = scanners
.iter()
.flat_map(|(scanner, _)| scanner.supported_protocols())
.collect();
assert!(
!protocols.contains(&Protocol::Tcp),
"a connect scan cannot send a FIN and must not pretend to"
);
let refusals = ctx.take_refusals();
assert_eq!(refusals.len(), 1, "the caller has to be told");
assert_eq!(refusals[0].scanner(), ScannerKind::TcpPort);
assert!(
refusals[0].reason().contains("fin"),
"the refusal has to name the technique: {}",
refusals[0].reason()
);
}
#[test]
fn a_privileged_tcp_only_scan_falls_back_for_udp() {
let protocols = covered(vec![Box::new(StubScanner(vec![Protocol::Tcp]))]);
assert!(protocols.contains(&Protocol::Tcp));
assert!(
protocols.contains(&Protocol::Udp),
"UDP targets would be silently dropped"
);
}
#[test]
fn fully_covered_protocols_gain_no_fallback() {
let (_session, ctx) = ScanSession::new();
let scanners = ensure_coverage(
reaching_everything(vec![
Box::new(StubScanner(vec![Protocol::Tcp])),
Box::new(StubScanner(vec![Protocol::Udp])),
]),
&ctx,
TcpScanTechnique::Syn,
BOTH,
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::Everything,
)
.routes;
assert_eq!(scanners.len(), 2);
}
fn loopback_beyond() -> Arc<IpSet> {
let mut set = IpSet::new();
set.insert(IpAddr::V4(std::net::Ipv4Addr::LOCALHOST));
Arc::new(set)
}
fn raw_routes(
beyond: &Arc<IpSet>,
protocols: &[Protocol],
) -> Vec<(Box<dyn PortScanner>, Reach)> {
protocols
.iter()
.map(|protocol| {
let scanner: Box<dyn PortScanner> = Box::new(StubScanner(vec![*protocol]));
(scanner, Reach::Except(Arc::clone(beyond)))
})
.collect()
}
fn covered_beyond(routes: &[(Box<dyn PortScanner>, Reach)]) -> Vec<Protocol> {
routes
.iter()
.filter(|(_, reach)| matches!(reach, Reach::Only(_)))
.flat_map(|(scanner, _)| scanner.supported_protocols())
.collect()
}
#[test]
fn what_frames_cannot_reach_gets_the_connect_strategies_for_itself_alone() {
let (_session, ctx) = ScanSession::new();
let beyond = loopback_beyond();
let routes = ensure_coverage(
raw_routes(&beyond, BOTH),
&ctx,
TcpScanTechnique::Syn,
BOTH,
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::AllBut(IpSet::clone(&beyond)),
)
.routes;
assert_eq!(covered_beyond(&routes), vec![Protocol::Tcp, Protocol::Udp]);
assert_eq!(routes.len(), 4, "the raw routes are kept beside them");
assert!(ctx.take_refusals().is_empty());
assert_eq!(
ctx.take_reached_by_connect().len(),
1,
"the phase has to say its loopback evidence is connect evidence"
);
}
#[test]
fn a_technique_connect_cannot_express_is_refused_for_those_targets_alone() {
let (_session, ctx) = ScanSession::new();
let beyond = loopback_beyond();
let routes = ensure_coverage(
raw_routes(&beyond, BOTH),
&ctx,
TcpScanTechnique::Fin,
BOTH,
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::AllBut(IpSet::clone(&beyond)),
)
.routes;
assert_eq!(covered_beyond(&routes), vec![Protocol::Udp]);
let refusals = ctx.take_refusals();
assert_eq!(refusals.len(), 1);
assert_eq!(refusals[0].scanner(), ScannerKind::TcpPort);
assert!(
refusals[0].reason().contains("fin") && refusals[0].reason().contains("1 target"),
"the refusal names the technique and how much it left: {}",
refusals[0].reason()
);
}
#[test]
fn sctp_on_what_frames_cannot_reach_is_refused_and_nothing_is_reached_by_connect() {
let (_session, ctx) = ScanSession::new();
let beyond = loopback_beyond();
let routes = ensure_coverage(
raw_routes(&beyond, &[Protocol::Sctp]),
&ctx,
TcpScanTechnique::Syn,
&[Protocol::Sctp],
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::AllBut(IpSet::clone(&beyond)),
)
.routes;
assert!(covered_beyond(&routes).is_empty());
let refusals = ctx.take_refusals();
assert_eq!(refusals.len(), 1);
assert_eq!(refusals[0].scanner(), ScannerKind::SctpPort);
assert!(ctx.take_reached_by_connect().is_empty());
}
#[test]
fn a_protocol_with_no_strategy_is_not_refused_twice_for_part_of_the_scan() {
let (_session, ctx) = ScanSession::new();
let _ = ensure_coverage(
Vec::new(),
&ctx,
TcpScanTechnique::Syn,
&[Protocol::Sctp],
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::AllBut(IpSet::clone(&loopback_beyond())),
);
let refusals = ctx.take_refusals();
assert_eq!(
refusals.len(),
1,
"one cause, one entry: {:?}",
refusals.iter().map(Refusal::reason).collect::<Vec<_>>()
);
}
#[test]
fn a_protocol_the_plan_left_out_gains_no_fallback_and_no_second_refusal() {
let (_session, ctx) = ScanSession::new();
let scanners = ensure_coverage(
Vec::new(),
&ctx,
TcpScanTechnique::Fin,
&[Protocol::Udp],
ServiceDetection::default(),
&EvasionProfile::default(),
&RawReach::Everything,
)
.routes;
let protocols: Vec<Protocol> = scanners
.iter()
.flat_map(|(scanner, _)| scanner.supported_protocols())
.collect();
assert_eq!(protocols, vec![Protocol::Udp]);
assert!(
ctx.take_failures().is_empty(),
"the plan already said why, in the same words"
);
}
#[test]
fn a_discovery_sweep_now_names_what_its_own_findings_imply() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.1".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.record_mac("a4:83:e7:00:00:01".parse().expect("an Apple address"));
host.set_hostname(Some("MacBook-Pro".to_owned()));
});
run_passive_os_identification(&ctx, OsDetection::Passive);
let named = ctx
.read_host(ip, |host| host.os().map(ToString::to_string))
.expect("the host is in the store");
assert!(
named.as_deref().is_some_and(|os| os.contains("macOS")),
"{named:?}"
);
}
#[test]
fn detection_turned_off_identifies_nothing() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.1".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.record_mac("a4:83:e7:00:00:01".parse().expect("an Apple address"));
host.set_hostname(Some("MacBook-Pro".to_owned()));
});
run_passive_os_identification(&ctx, OsDetection::Off);
let named = ctx
.read_host(ip, |host| host.os().is_some())
.expect("the host is in the store");
assert!(!named);
}
#[tokio::test(flavor = "current_thread")]
async fn the_kernel_probe_skips_only_hosts_whose_kernel_is_known() {
use crate::model::host::{HostStatus, OsFingerprint, StatusProtocol, StatusReason};
let up = |host: &mut crate::model::host::Host| {
host.record_evidence(
HostStatus::Up,
StatusReason::new(StatusProtocol::Arp, "an address resolution reply"),
);
};
let (_session, ctx) = ScanSession::new();
let named: IpAddr = "127.0.0.2".parse().expect("a valid address");
ctx.update_host(named, |host| {
up(host);
host.set_os(OsFingerprint::new("Debian", 84).with_family("Linux"));
});
let known: IpAddr = "192.0.2.11".parse().expect("a valid address");
ctx.update_host(known, |host| {
up(host);
host.set_os(
OsFingerprint::new("Debian", 84)
.with_family("Linux")
.with_kernel("6.1.0"),
);
});
run_active_os_snmp(&ctx, OsDetection::Active).await;
assert!(ctx.take_failures().is_empty(), "declining is not failing");
assert!(
ctx.read_host(known, |host| host
.os()
.and_then(|os| os.kernel().map(ToOwned::to_owned)))
.flatten()
.as_deref()
== Some("6.1.0"),
"a kernel already on record is left as it was"
);
}
#[test]
fn a_port_the_kernel_probe_found_is_recorded_with_what_found_it() {
let port = crate::fingerprint::baseline_port(161, Protocol::Udp, PortState::Open)
.with_discovery(PortDiscovery::new(ScanResponse::UdpResponse));
assert_eq!(port.number(), 161);
assert_eq!(port.protocol(), Protocol::Udp);
assert_eq!(port.state(), PortState::Open);
assert_eq!(
port.discovery().map(|found| found.reason().clone()),
Some(ScanResponse::UdpResponse),
"a report has to be able to tell this from a port the scan established"
);
}
#[tokio::test(flavor = "current_thread")]
async fn the_kernel_probe_sends_nothing_below_the_active_level() {
for level in [OsDetection::Off, OsDetection::Passive] {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.12".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.record_evidence(
crate::model::host::HostStatus::Up,
crate::model::host::StatusReason::new(
crate::model::host::StatusProtocol::Arp,
"an address resolution reply",
),
);
});
run_active_os_snmp(&ctx, level).await;
assert!(
ctx.take_probe_stats().is_empty(),
"{level} put a probe on the wire"
);
}
}
#[tokio::test(flavor = "current_thread")]
async fn the_series_probe_declines_when_no_host_has_a_port_to_ask_again() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.3".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.record_evidence(
crate::model::host::HostStatus::Up,
crate::model::host::StatusReason::new(
crate::model::host::StatusProtocol::Arp,
"an address resolution reply",
),
);
});
run_active_os_series(
&ctx,
OsDetection::Active,
ProbeTuning::default(),
raw_everywhere(),
)
.await;
assert!(
ctx.take_failures().is_empty(),
"declining is not failing: there was nothing to follow, so nothing \
should have been opened"
);
assert!(
ctx.read_host(ip, |host| host.os().is_none())
.expect("the host is in the store"),
"and nothing may be concluded from probes that were never sent"
);
}
#[tokio::test(flavor = "current_thread")]
async fn the_series_probe_sends_nothing_below_the_active_level() {
use crate::model::port::{Port, PortState, Protocol};
for level in [OsDetection::Off, OsDetection::Passive] {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.4".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.add_port(Port::new(22, Protocol::Tcp, PortState::Open));
});
run_active_os_series(&ctx, level, ProbeTuning::default(), raw_everywhere()).await;
assert!(
ctx.take_probe_stats().is_empty(),
"{level} put a scanner on the wire"
);
}
}
#[test]
fn a_host_with_nothing_to_go_on_is_left_as_it_was() {
let (_session, ctx) = ScanSession::new();
let ip: IpAddr = "192.0.2.2".parse().expect("a valid address");
ctx.update_host(ip, |host| {
host.record_mac(
"02:00:5e:00:53:04"
.parse()
.expect("a locally administered address"),
);
});
run_passive_os_identification(&ctx, OsDetection::Passive);
let named = ctx
.read_host(ip, |host| host.os().is_some())
.expect("the host is in the store");
assert!(!named);
}
fn store_holding(hosts: Vec<Host>) -> (ScanSession, ScanContext) {
let (session, ctx) = ScanSession::new();
for host in hosts {
ctx.store.insert(host.scoped_ip(), host);
}
(session, ctx)
}
fn host_at(ip: &str, status: HostStatus) -> Host {
let mut host = Host::new(ip.parse().expect("an address"));
host.set_status(status);
host
}
#[test]
fn the_silent_are_the_unheard_the_port_probes_finished_asking() {
use crate::model::port::Port;
let unheard = |ip: &str, state: PortState| {
let mut host = host_at(ip, HostStatus::Unknown);
host.add_port(Port::new(443, Protocol::Tcp, state));
host
};
let (session, ctx) = store_holding(vec![
host_at("192.0.2.1", HostStatus::Up),
unheard("192.0.2.2", PortState::Filtered),
unheard("192.0.2.3", PortState::Unasked),
unheard("192.0.2.4", PortState::Filtered),
unheard("192.0.2.9", PortState::Filtered),
]);
ctx.record_unroutable("192.0.2.4".parse().expect("an address"));
forget_the_silent(&ctx, &ip_set(&["192.0.2.1-192.0.2.4"]));
let silent: Vec<IpAddr> = ctx.take_silent().iter().collect();
assert_eq!(silent, ["192.0.2.2".parse::<IpAddr>().expect("an address")]);
let undecided: Vec<IpAddr> = ctx.take_undecided().iter().collect();
assert_eq!(
undecided,
["192.0.2.3".parse::<IpAddr>().expect("an address")]
);
let kept: Vec<String> = session
.hosts()
.snapshot()
.iter()
.map(|host| host.primary_ip().to_string())
.collect();
assert_eq!(kept, ["192.0.2.1", "192.0.2.4", "192.0.2.9"]);
}
#[test]
fn a_host_left_early_is_undecided_rather_than_silent() {
use crate::model::port::Port;
let (session, ctx) = ScanSession::builder()
.host_timeout(Some(std::time::Duration::ZERO))
.build();
let address: IpAddr = "192.0.2.2".parse().expect("an address");
ctx.update_host(address, |host| {
host.add_port(Port::new(443, Protocol::Tcp, PortState::Filtered));
});
assert!(
ctx.host_expired(address),
"the budget is spent before it is asked"
);
forget_the_silent(&ctx, &ip_set(&["192.0.2.2"]));
assert!(ctx.take_silent().is_empty());
assert!(ctx.take_undecided().contains(&address));
assert!(!session.hosts().contains(address));
}
#[test]
fn a_host_that_did_not_answer_is_not_live() {
for status in [HostStatus::Down, HostStatus::Unknown] {
let (_session, ctx) = store_holding(vec![host_at("192.0.2.1", status)]);
assert!(
live_addresses(&ctx).is_empty(),
"{status:?} was treated as alive"
);
}
}
#[test]
fn a_host_that_answered_is_live() {
let (_session, ctx) = store_holding(vec![host_at("192.0.2.1", HostStatus::Up)]);
let live = live_addresses(&ctx);
assert!(live.contains(&"192.0.2.1".parse::<IpAddr>().expect("an address")));
assert_eq!(live.len(), 1);
}
#[test]
fn every_address_of_a_live_host_is_live() {
let mut host = host_at("2001:db8::1", HostStatus::Up);
host.add_ip("192.0.2.1".parse().expect("an address"));
let (_session, ctx) = store_holding(vec![host]);
let live = live_addresses(&ctx);
assert!(
live.contains(&"192.0.2.1".parse::<IpAddr>().expect("an address")),
"the targeted address was lost because the host was filed elsewhere"
);
assert!(live.contains(&"2001:db8::1".parse::<IpAddr>().expect("an address")));
}
#[test]
fn an_empty_store_has_nothing_live() {
let (_session, ctx) = store_holding(Vec::new());
assert!(live_addresses(&ctx).is_empty());
}
#[test]
fn correlation_records_a_known_vulnerability_against_the_software_it_names() {
use crate::model::ip::scoped::ScopedIp;
use crate::model::port::{Port, PortState, Protocol, Service};
let (session, ctx) = crate::scanner::session::ScanSession::new();
let ip: std::net::IpAddr = "203.0.113.1".parse().expect("literal");
ctx.write_host(ScopedIp::unscoped(ip), |host| {
let service = Service::new("http", 90).with_cpe("cpe:/a:apache:http_server:2.4.49");
host.add_port(Port::new(80, Protocol::Tcp, PortState::Open).with_service(service));
true
});
run_correlation(&ctx, ServiceDetection::Probe);
let host = session.hosts().get(ip).expect("the scanned host");
let port = host
.ports()
.find(|port| port.number() == 80)
.expect("port 80");
assert_eq!(
port.findings().count(),
1,
"the vulnerable Apache build should have been correlated"
);
assert!(
port.findings()
.any(|f| f.detection().id() == "zond:cve-kev")
);
}
#[test]
fn correlation_does_not_run_when_no_service_pass_did() {
use crate::model::ip::scoped::ScopedIp;
use crate::model::port::{Port, PortState, Protocol, Service};
let (session, ctx) = crate::scanner::session::ScanSession::new();
let ip: std::net::IpAddr = "203.0.113.1".parse().expect("literal");
ctx.write_host(ScopedIp::unscoped(ip), |host| {
let service = Service::new("http", 90).with_cpe("cpe:/a:apache:http_server:2.4.49");
host.add_port(Port::new(80, Protocol::Tcp, PortState::Open).with_service(service));
true
});
run_correlation(&ctx, ServiceDetection::Off);
let host = session.hosts().get(ip).expect("the scanned host");
let port = host
.ports()
.find(|port| port.number() == 80)
.expect("port 80");
assert_eq!(port.findings().count(), 0);
}
async fn tls_endpoint(suite: u16) -> std::net::SocketAddr {
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
tokio::spawn(async move {
while let Ok((mut stream, _)) = listener.accept().await {
let mut hello = vec![0u8; 4096];
let Ok(read) = stream.read(&mut hello).await else {
continue;
};
let record = answer_to(&hello[..read], |offered| offered == suite)
.unwrap_or_else(|| REFUSAL.to_vec());
let _ = stream.write_all(&record).await;
}
});
addr
}
async fn slow_endpoint_accepting_everything(
pause: std::time::Duration,
) -> (std::net::SocketAddr, Arc<std::sync::atomic::AtomicUsize>) {
use std::sync::atomic::{AtomicUsize, Ordering};
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpListener;
let listener = TcpListener::bind("127.0.0.1:0").await.expect("binds");
let addr = listener.local_addr().expect("has an address");
let seen = Arc::new(AtomicUsize::new(0));
let counter = Arc::clone(&seen);
tokio::spawn(async move {
while let Ok((mut stream, _)) = listener.accept().await {
counter.fetch_add(1, Ordering::SeqCst);
tokio::spawn(async move {
let mut hello = vec![0u8; 4096];
let Ok(read) = stream.read(&mut hello).await else {
return;
};
tokio::time::sleep(pause).await;
let record =
answer_to(&hello[..read], |_| true).unwrap_or_else(|| REFUSAL.to_vec());
let _ = stream.write_all(&record).await;
});
}
});
(addr, seen)
}
const REFUSAL: [u8; 7] = [0x15, 0x03, 0x03, 0x00, 0x02, 0x02, 0x28];
fn answer_to(hello: &[u8], accepts: impl Fn(u16) -> bool) -> Option<Vec<u8>> {
let version = u16::from_be_bytes([*hello.get(9)?, *hello.get(10)?]);
if version != 0x0303 {
return None;
}
let after_random = 5 + 4 + 2 + 32;
let session_len = usize::from(*hello.get(after_random)?);
let rest = hello.get(after_random + 1 + session_len..)?;
let len = usize::from(u16::from_be_bytes([*rest.first()?, *rest.get(1)?]));
let suite = rest
.get(2..2 + len)?
.as_chunks::<2>()
.0
.iter()
.map(|pair| u16::from_be_bytes(*pair))
.find(|offered| accepts(*offered))?;
let mut body = vec![2u8, 0, 0, 0];
body.extend_from_slice(&0x0303u16.to_be_bytes());
body.extend_from_slice(&[0x5A; 32]);
body.push(0);
body.extend_from_slice(&suite.to_be_bytes());
body.push(0);
let length = (body.len() - 4) as u32;
body[1..4].copy_from_slice(&length.to_be_bytes()[1..]);
let mut record = vec![0x16, 0x03, 0x03];
record.extend_from_slice(&(body.len() as u16).to_be_bytes());
record.extend_from_slice(&body);
Some(record)
}
fn context_with_tls_port(
port: u16,
host_timeout: Option<std::time::Duration>,
) -> (crate::scanner::session::ScanSession, ScanContext) {
use crate::model::host::Host;
use crate::model::port::{Port, Security};
let (session, ctx) = crate::scanner::session::ScanSession::builder()
.host_timeout(host_timeout)
.build();
let address: IpAddr = "127.0.0.1".parse().expect("an address");
let mut host = Host::new(address);
host.set_status(crate::model::host::HostStatus::Up);
host.add_port(
Port::new(port, Protocol::Tcp, PortState::Open)
.with_security(Security::new().with_tls_version("TLSv1.2")),
);
ctx.store.insert(host.scoped_ip(), host);
(session, ctx)
}
fn recorded_support(ctx: &ScanContext, port: u16) -> Option<crate::model::tls::TlsSupport> {
let address: IpAddr = "127.0.0.1".parse().expect("an address");
ctx.read_host(
crate::model::ip::scoped::ScopedIp::unscoped(address),
|host| {
host.ports()
.find(|held| held.number() == port)
.and_then(|held| held.security())
.map(|security| security.support().clone())
},
)
.flatten()
}
#[tokio::test]
async fn the_pass_asks_nothing_unless_it_is_switched_on() {
let addr = tls_endpoint(0xC02F).await;
let (_session, ctx) = context_with_tls_port(addr.port(), None);
let cfg = crate::config::ZondConfig::default();
assert!(!cfg.tls_enumeration, "off by default");
run_tls_enumeration(&ctx, &cfg).await;
let support = recorded_support(&ctx, addr.port()).expect("the port is still there");
assert!(
support.is_empty(),
"nothing was asked, so nothing is recorded"
);
}
#[tokio::test]
async fn the_pass_leaves_a_listen_only_port_alone() {
use crate::model::host::Host;
use crate::model::port::{Port, Security};
let addr = tls_endpoint(0xC02F).await;
let (_session, ctx) = crate::scanner::session::ScanSession::builder()
.listening_only_to(std::collections::BTreeSet::from([addr.port()]))
.build();
let mut host = Host::new(addr.ip());
host.set_status(crate::model::host::HostStatus::Up);
host.add_port(
Port::new(addr.port(), Protocol::Tcp, PortState::Open)
.with_security(Security::new().with_tls_version("TLSv1.2")),
);
ctx.store.insert(host.scoped_ip(), host);
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let support = recorded_support(&ctx, addr.port()).expect("the port is still there");
assert!(
support.is_empty(),
"a listen-only port was offered hellos: {support:?}"
);
}
#[tokio::test]
async fn the_pass_records_what_the_endpoint_accepts() {
let addr = tls_endpoint(0x000A).await;
let (_session, ctx) = context_with_tls_port(addr.port(), None);
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let support = recorded_support(&ctx, addr.port()).expect("the port is still there");
assert!(support.accepts(crate::model::tls::TlsVersion::Tls12));
assert_eq!(support.suites().len(), 1);
let address: IpAddr = "127.0.0.1".parse().expect("an address");
ctx.read_host(
crate::model::ip::scoped::ScopedIp::unscoped(address),
|host| {
let port = host
.ports()
.find(|held| held.number() == addr.port())
.expect("the port");
assert_eq!(
port.security().and_then(|s| s.tls_version()),
Some("TLSv1.2"),
"the handshake's own record survives the fold"
);
assert!(
port.findings().count() > 0,
"a suite with a fault produces a finding on the port"
);
},
)
.expect("the host is recorded");
}
#[tokio::test]
async fn the_pass_counts_each_endpoint_as_its_walk_ends() {
use crate::model::port::{Port, Security};
let first = tls_endpoint(0xC02F).await;
let second = tls_endpoint(0xC030).await;
let (session, ctx) = context_with_tls_port(first.port(), None);
let address: IpAddr = "127.0.0.1".parse().expect("an address");
ctx.update_host(address, |host| {
host.add_port(
Port::new(second.port(), Protocol::Tcp, PortState::Open)
.with_security(Security::new().with_tls_version("TLSv1.2")),
);
});
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let progress = session.progress();
assert_eq!(progress.stage(), Stage::Tls);
assert_eq!(progress.stage_total(), Some(2), "one unit to an endpoint");
assert_eq!(
progress.stage_done(),
2,
"each endpoint counted once its walk ended"
);
}
#[tokio::test]
async fn a_resumed_sitting_finishes_a_walk_an_earlier_one_left_unfinished() {
use crate::model::port::{Port, Security};
use crate::model::tls::{
CipherSuite, Interruption, TlsSupport, TlsVersion, UnfinishedVersion, VersionSupport,
};
let addr = tls_endpoint(0xC02F).await;
let (_session, ctx) = context_with_tls_port(addr.port(), None);
let restored = TlsSupport::new().leaving_unfinished(UnfinishedVersion::new(
TlsVersion::Tls12,
Interruption::Stopped,
));
let address: IpAddr = "127.0.0.1".parse().expect("an address");
ctx.update_host(address, |host| {
host.add_port(
Port::new(addr.port(), Protocol::Tcp, PortState::Open)
.with_security(Security::new().with_support(restored)),
);
});
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let accepted = CipherSuite::from_code(0xC02F).expect("a suite in the registry");
assert_eq!(
recorded_support(&ctx, addr.port()),
Some(TlsSupport::new().accepting(VersionSupport::new(
TlsVersion::Tls12,
vec![accepted],
vec![]
))),
"the resumed walk finished, and its answer is the one on record"
);
}
#[tokio::test]
async fn a_host_out_of_time_is_not_enumerated() {
let addr = tls_endpoint(0xC02F).await;
let (_session, ctx) = context_with_tls_port(addr.port(), Some(std::time::Duration::ZERO));
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let support = recorded_support(&ctx, addr.port()).expect("the port is still there");
assert!(support.is_empty(), "a spent budget skips the endpoint");
}
#[tokio::test]
async fn a_walk_under_way_stops_when_its_host_runs_out_of_time() {
use crate::model::tls::{CipherSuite, Interruption, TlsVersion, UnfinishedVersion};
use std::sync::atomic::Ordering;
use std::time::Duration;
let (addr, seen) = slow_endpoint_accepting_everything(Duration::from_millis(50)).await;
let (_session, ctx) = context_with_tls_port(addr.port(), Some(Duration::from_millis(500)));
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let every = CipherSuite::offered_under(TlsVersion::Tls12).count();
let asked = seen.load(Ordering::SeqCst);
assert!(
asked < every / 2,
"the walk stops near its budget, and it went on for {asked} connections \
against {every} suites"
);
let address: IpAddr = "127.0.0.1".parse().expect("an address");
assert_eq!(
ctx.take_timed_out(),
vec![address],
"a host left part way through its walk is named as left early"
);
let support = recorded_support(&ctx, addr.port()).expect("the port is still there");
assert!(
support.accepts(TlsVersion::Tls12),
"what the walk learned before the budget ran out is kept"
);
assert_eq!(
support.unfinished(),
&[UnfinishedVersion::new(
TlsVersion::Tls12,
Interruption::Stopped
)],
"and the walk it cut short says the scan stopped it, not the endpoint"
);
}
#[tokio::test]
async fn a_walk_under_way_stops_when_the_scan_stops() {
use crate::model::tls::{CipherSuite, TlsVersion};
use std::sync::atomic::Ordering;
use std::time::Duration;
let (addr, seen) = slow_endpoint_accepting_everything(Duration::from_millis(50)).await;
let (_session, ctx) = context_with_tls_port(addr.port(), None);
let handle = ctx.handle.clone();
tokio::spawn(async move {
tokio::time::sleep(Duration::from_millis(500)).await;
handle.abort();
});
let cfg = crate::config::ZondConfig {
tls_enumeration: true,
..Default::default()
};
run_tls_enumeration(&ctx, &cfg).await;
let every = CipherSuite::offered_under(TlsVersion::Tls12).count();
let asked = seen.load(Ordering::SeqCst);
assert!(
asked < every / 2,
"the walk stops soon after the scan does, and it went on for {asked} \
connections against {every} suites"
);
}
}