use std::net::IpAddr;
use std::pin::Pin;
use async_trait::async_trait;
use tokio::sync::mpsc::{self, UnboundedReceiver, UnboundedSender};
use tokio::task::JoinHandle;
use crate::core::config::{ProbeTuning, ZondConfig};
use crate::core::models::ip::range::IpRange;
use crate::core::models::{
ip::set::IpSet,
port::Protocol,
target::{Target, TargetMap},
};
use crate::core::report::{PhaseRecorder, ScanKind, ScanReport, TargetScope};
use crate::core::session::{ScanContext, ScanSession, ScannerKind};
use crate::scanner::resolver::HostnameResolver;
use crate::system::interface;
use crate::system::privilege::is_elevated;
use crate::{error, info, success, warn};
use local::{LocalScanner, Scope};
use routed::RoutedScanner;
mod audit;
mod composite;
mod connect;
pub mod dispatcher;
mod payload;
mod pool;
mod service;
#[cfg(not(feature = "test-support"))]
mod local;
#[cfg(feature = "test-support")]
pub mod local;
#[cfg(not(feature = "test-support"))]
mod resolver;
#[cfg(feature = "test-support")]
pub mod resolver;
#[cfg(not(feature = "test-support"))]
mod routed;
#[cfg(feature = "test-support")]
pub mod routed;
mod tuning;
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum ScanError {
#[error("scan task terminated abnormally")]
TaskFailed,
}
pub struct ScanTask {
handle: JoinHandle<ScanReport>,
}
impl ScanTask {
fn new(handle: JoinHandle<ScanReport>) -> Self {
Self { handle }
}
pub async fn join(self) -> Result<ScanReport, ScanError> {
self.handle.await.map_err(|_| ScanError::TaskFailed)
}
}
impl IntoFuture for ScanTask {
type Output = Result<ScanReport, ScanError>;
type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;
fn into_future(self) -> Self::IntoFuture {
Box::pin(self.join())
}
}
pub async fn discover(
mut targets: IpSet,
cfg: &ZondConfig,
) -> Result<(ScanSession, ScanTask), ScanError> {
let (session, ctx) = ScanSession::new();
let caps = ScanCapabilities::resolve(cfg);
let scope = TargetScope::from_ip_set(&mut targets);
let recorder = PhaseRecorder::start(ScanKind::Discovery, caps.privileged, scope, cfg);
if !caps.privileged {
let handle = tokio::spawn(async move {
if let Err(e) = connect::discover(targets, ctx.clone()).await {
ctx.record_failure(ScannerKind::Connect, e.to_string());
}
finish_enrichment(None, caps, &ctx).await;
recorder.finish(&ctx)
});
return Ok((session, ScanTask::new(handle)));
}
let enrichment = Enrichment::spawn(targets, &ctx, caps, cfg.probe_tuning(), Scope::Sweep).await;
let handle = tokio::spawn(async move {
finish_enrichment(Some(enrichment), caps, &ctx).await;
recorder.finish(&ctx)
});
Ok((session, ScanTask::new(handle)))
}
pub async fn scan(
mut target_map: TargetMap,
cfg: &ZondConfig,
) -> Result<(ScanSession, ScanTask), ScanError> {
let (session, ctx) = ScanSession::new();
let caps = ScanCapabilities::resolve(cfg);
let ips = target_ips(&target_map);
let target_count = target_map.gross_targets().unwrap_or(0) as usize;
let scope = TargetScope::from_target_map(&mut target_map);
let recorder = PhaseRecorder::start(ScanKind::PortScan, caps.privileged, scope, cfg);
let (syn_scanner, udp_scanner) = if caps.privileged {
(
build_syn_scanner(ctx.clone(), target_count, cfg.probe_tuning()),
build_udp_scanner(ctx.clone(), target_count, cfg.probe_tuning()),
)
} else {
(None, None)
};
let enrichment = if syn_scanner.is_some() || udp_scanner.is_some() {
Some(Enrichment::spawn(ips, &ctx, caps, cfg.probe_tuning(), Scope::Targeted).await)
} else {
None
};
let mut scanners: Vec<Box<dyn PortScanner>> = Vec::new();
if let Some(scanner) = syn_scanner {
scanners.push(Box::new(scanner));
}
if let Some(scanner) = udp_scanner {
scanners.push(Box::new(scanner));
}
let scanner = into_port_scanner(scanners, ctx.clone());
let handle = tokio::spawn(async move {
let dispatcher = dispatcher::Dispatcher::new(target_map);
let rx = dispatcher.run_shuffled(&ctx.handle);
run_port_scan(scanner, rx, &ctx).await;
finish_enrichment(enrichment, caps, &ctx).await;
recorder.finish(&ctx)
});
Ok((session, ScanTask::new(handle)))
}
#[async_trait]
pub trait NetworkExplorer {
async fn discover_hosts(self: Box<Self>) -> anyhow::Result<()>;
}
#[async_trait]
pub trait PortScanner: Send {
fn kind(&self) -> ScannerKind;
fn supported_protocols(&self) -> Vec<Protocol>;
async fn scan(&mut self, targets: mpsc::Receiver<Target>) -> anyhow::Result<()>;
async fn detect_services(&mut self, _ctx: &ScanContext) {}
}
#[derive(Clone, Copy)]
struct ScanCapabilities {
privileged: bool,
dns: bool,
}
impl ScanCapabilities {
fn resolve(cfg: &ZondConfig) -> Self {
let privileged = is_elevated();
if privileged {
success!("Root privileges detected, raw socket scan enabled");
} else {
warn!("Root privileges missing, defaulting to unprivileged TCP scan");
}
Self {
privileged,
dns: !cfg.no_dns,
}
}
}
struct Enrichment {
scanners: Vec<(ScannerKind, JoinHandle<anyhow::Result<()>>)>,
resolver: Option<JoinHandle<Option<HostnameResolver>>>,
}
impl Enrichment {
async fn spawn(
targets: IpSet,
ctx: &ScanContext,
caps: ScanCapabilities,
tuning: ProbeTuning,
scope: Scope,
) -> 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(targets, ctx, dns_tx, tuning, scope).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.store.clone());
}
}
}
async fn spawn_explorers(
targets: IpSet,
ctx: &ScanContext,
dns_tx: Option<UnboundedSender<IpAddr>>,
tuning: ProbeTuning,
scope: Scope,
) -> Vec<(ScannerKind, JoinHandle<anyhow::Result<()>>)> {
let mut explorers: Vec<(ScannerKind, Box<dyn NetworkExplorer + Send>)> = Vec::new();
let interface::RoutedTargets {
local,
routed,
unmapped,
} = interface::map_ips_to_interfaces(targets);
for (intf, local_ips) in local {
if local_ips.is_empty() {
continue;
}
info!(verbosity = 1, "Spawning local scanner for {}", intf.name);
match LocalScanner::new(
intf.clone(),
local_ips,
ctx.clone(),
dns_tx.clone(),
scope,
tuning.retry,
) {
Ok(scanner) => explorers.push((ScannerKind::Local, Box::new(scanner))),
Err(e) => ctx.record_failure(ScannerKind::Local, format!("{}: {e}", intf.name)),
}
}
if !routed.is_empty() {
info!(
verbosity = 1,
"Spawning routed scanner for {} target(s)",
routed.len()
);
match RoutedScanner::new(routed, ctx.clone(), dns_tx.clone(), tuning) {
Ok(scanner) => explorers.push((ScannerKind::Routed, Box::new(scanner))),
Err(e) => ctx.record_failure(ScannerKind::Routed, e.to_string()),
}
}
if !unmapped.is_empty() {
warn!(
verbosity = 1,
"Spawning fallback scanner for unmapped targets"
);
explorers.push((
ScannerKind::Connect,
Box::new(connect::ConnectScanner::new(unmapped, ctx.clone())),
));
}
explorers
.into_iter()
.map(|(kind, explorer)| {
(
kind,
tokio::spawn(async move { explorer.discover_hosts().await }),
)
})
.collect()
}
fn build_syn_scanner(
ctx: ScanContext,
target_count: usize,
tuning: ProbeTuning,
) -> Option<routed::SynPortScanner> {
let resolver = interface::SourceResolver::from_system();
if !resolver.has_sources() {
warn!("No usable network interface found; using TCP connect fallback");
return None;
}
match routed::SynPortScanner::new(resolver, ctx, target_count, tuning) {
Ok(scanner) => Some(scanner),
Err(e) => {
error!("Failed to initialize SYN port scanner: {e}");
None
}
}
}
fn build_udp_scanner(
ctx: ScanContext,
target_count: usize,
tuning: ProbeTuning,
) -> Option<routed::UdpPortScanner> {
let resolver = interface::SourceResolver::from_system();
if !resolver.has_sources() {
return None; }
match routed::UdpPortScanner::new(resolver, ctx, target_count, tuning) {
Ok(scanner) => Some(scanner),
Err(e) => {
error!("Failed to initialize UDP port scanner: {e}");
None
}
}
}
fn into_port_scanner(
mut scanners: Vec<Box<dyn PortScanner>>,
ctx: ScanContext,
) -> Box<dyn PortScanner> {
let covered: Vec<Protocol> = scanners
.iter()
.flat_map(|scanner| scanner.supported_protocols())
.collect();
if !covered.contains(&Protocol::Tcp) {
scanners.push(Box::new(connect::ConnectPortScanner::new(
ctx.clone(),
tuning::CONNECT_CONCURRENCY,
)));
}
if !covered.contains(&Protocol::Udp) {
scanners.push(Box::new(connect::ConnectUdpPortScanner::new(
ctx,
tuning::CONNECT_CONCURRENCY,
)));
}
Box::new(composite::CompositePortScanner::new(scanners))
}
async fn run_port_scan(
mut scanner: Box<dyn PortScanner>,
rx: mpsc::Receiver<Target>,
ctx: &ScanContext,
) {
let kind = scanner.kind();
match scanner.scan(rx).await {
Ok(()) => {
if !ctx.handle.should_stop() {
scanner.detect_services(ctx).await;
}
}
Err(e) => ctx.record_failure(kind, e.to_string()),
}
}
async fn finish_enrichment(
enrichment: Option<Enrichment>,
caps: ScanCapabilities,
ctx: &ScanContext,
) {
match enrichment {
Some(enrichment) => enrichment.finish(ctx).await,
None if caps.dns => resolver::resolve_hosts_async(ctx.store.clone()).await,
None => {}
}
}
fn target_ips(target_map: &TargetMap) -> IpSet {
let mut ips = IpSet::new();
for unit in &target_map.units {
for range in unit.ips().v4() {
ips.insert_range(IpRange::V4(*range));
}
for range in unit.ips().v6() {
ips.insert_range(IpRange::V6(*range));
}
}
ips.canonicalize();
ips
}
async fn spawn_resolver(dns_rx: UnboundedReceiver<IpAddr>) -> JoinHandle<Option<HostnameResolver>> {
tokio::spawn(async move {
match HostnameResolver::new(dns_rx) {
Ok(resolver) => {
success!("Successfully initialized hostname resolver");
Some(resolver.run().await)
}
Err(e) => {
error!("Resolver failed to start: {e}");
None
}
}
})
}
#[cfg(test)]
mod tests {
use super::*;
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<Target>) -> anyhow::Result<()> {
Ok(())
}
}
fn covered(scanners: Vec<Box<dyn PortScanner>>) -> Vec<Protocol> {
let (_session, ctx) = ScanSession::new();
into_port_scanner(scanners, ctx).supported_protocols()
}
#[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_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 scanner = into_port_scanner(
vec![
Box::new(StubScanner(vec![Protocol::Tcp])),
Box::new(StubScanner(vec![Protocol::Udp])),
],
ctx,
);
assert_eq!(scanner.supported_protocols().len(), 2);
}
}