1use std::pin::Pin;
103
104use tokio::task::JoinHandle;
105
106use crate::config::ZondConfig;
107use crate::detect::Detections;
108use crate::journal::cursor::Checkpoint;
109use crate::model::{
110 ip::scoped::Zone,
111 ip::set::{IpSet, Positions},
112 port::PortSet,
113 target::{TargetIndex, TargetMap},
114};
115#[cfg(feature = "journal-format")]
116use crate::report::ScanPhase;
117use crate::report::ScannerKind;
118use crate::report::{LivenessSkip, ScanKind, ScanReport, TargetScope};
119use crate::scanner::orchestrator::{
120 Enrichment, ScanCapabilities, finish_enrichment, probed_subset, run_port_phase,
121};
122use crate::scanner::recorder::PhaseRecorder;
123use crate::scanner::session::{ScanContext, ScanSession, Stage};
124use crate::system::interface;
125use crate::system::privilege::Privilege;
126use strategy::local::Scope;
127use strategy::routed::SynPorts;
128
129pub mod handle;
132pub mod recorder;
133pub mod session;
134
135pub mod plan;
138pub mod strategy;
139
140#[cfg(feature = "journal-format")]
147pub mod checkpoint;
148pub mod detection;
149pub mod dispatcher;
150pub mod rdns;
151pub mod service;
152
153pub(crate) mod audit;
158pub(crate) mod pacing;
159pub(crate) mod payload;
160pub(crate) mod pool;
161
162mod orchestrator;
166mod vantage;
167
168#[non_exhaustive]
170#[derive(Debug, thiserror::Error)]
171pub enum ScanError {
172 #[error("the scan task {}: {detail}", if *.panicked { "panicked" } else { "was cancelled" })]
180 TaskFailed {
181 panicked: bool,
183 detail: String,
185 },
186
187 #[error("this journal records the other phase of a scan")]
192 WrongPhase,
193
194 #[cfg(feature = "journal-format")]
196 #[error("{0}")]
197 PlanChanged(#[from] crate::journal::manifest::PlanChanged),
198
199 #[cfg(feature = "journal-format")]
209 #[error("{0}")]
210 OptionChanged(#[from] crate::journal::manifest::OptionChanged),
211
212 #[error("{0}")]
219 Evasion(#[from] crate::evasion::EvasionError),
220
221 #[error("file descriptor limit {limit} is below the {needed} a scan needs")]
231 TooFewDescriptors {
232 limit: usize,
234 needed: usize,
236 },
237}
238
239#[cfg(feature = "journal-format")]
246fn accepted(
247 journal: crate::journal::Journal,
248 checks: impl FnOnce(&crate::journal::Journal) -> Result<(), ScanError>,
249) -> Result<crate::journal::Journal, ScanError> {
250 match checks(&journal) {
251 Ok(()) => Ok(journal),
252 Err(refused) => {
253 journal.withdraw();
254 Err(refused)
255 }
256 }
257}
258
259#[cfg(feature = "journal-format")]
266fn under_the_recorded_options(
267 journal: &crate::journal::Journal,
268 cfg: &ZondConfig,
269) -> Result<(), ScanError> {
270 match journal.options() {
271 Some(options) => Ok(options.check(cfg)?),
272 None => Ok(()),
273 }
274}
275
276#[cfg(feature = "journal-format")]
285fn under_the_recorded_technique(journal: &crate::journal::Journal, cfg: &ZondConfig) -> ZondConfig {
286 let recorded = journal.manifest().technique();
287 if journal.options().is_some() || recorded == cfg.tcp_technique {
288 return cfg.clone();
289 }
290 crate::info!(
291 verbosity = 1,
292 "{recorded} scan, as the job recorded (not {})",
293 cfg.tcp_technique
294 );
295 ZondConfig {
296 tcp_technique: recorded,
297 ..cfg.clone()
298 }
299}
300
301#[cfg(feature = "journal-format")]
307fn recording_options(
308 mut journal: crate::journal::Journal,
309 cfg: &ZondConfig,
310) -> crate::journal::Journal {
311 use crate::journal::manifest::JobOptions;
312
313 if let Err(e) = journal.record_options(JobOptions::of(cfg)) {
314 crate::warn!("options not recorded ({e})");
315 }
316 journal
317}
318
319fn capture_plan(addresses: &IpSet, cfg: &ZondConfig) -> Result<Vec<Zone>, ScanError> {
328 let mut addresses = addresses.clone();
329 cfg.exclusions.withhold(&mut addresses);
330 let links = crate::transport::probe::capture_links_toward(&addresses, &cfg.send_source);
331 enough_descriptors(captures_needed(Privilege::current(), &links))?;
332 Ok(links)
333}
334
335fn captures_needed(privilege: Privilege, links: &[Zone]) -> usize {
343 match privilege.is_raw() {
344 true => links.len(),
345 false => 0,
346 }
347}
348
349fn enough_descriptors(captures: usize) -> Result<(), ScanError> {
353 match crate::system::descriptors::too_few(captures) {
354 Some((limit, needed)) => Err(ScanError::TooFewDescriptors { limit, needed }),
355 None => Ok(()),
356 }
357}
358
359fn plan_addresses(target_map: &TargetMap) -> IpSet {
361 orchestrator::unsettled_ips(target_map, &Checkpoint::default())
362}
363
364#[cfg(feature = "journal-format")]
381fn counted_as_recorded(
382 journal: &crate::journal::Journal,
383 this_run: &crate::journal::manifest::Plan,
384) -> Result<(), ScanError> {
385 journal.manifest().covers(this_run, Privilege::current())?;
386 Ok(())
387}
388
389fn panic_or_cancellation(error: tokio::task::JoinError) -> ScanError {
395 if !error.is_panic() {
396 return ScanError::TaskFailed {
397 panicked: false,
398 detail: "the runtime shut down before the scan finished".to_string(),
399 };
400 }
401
402 let payload = error.into_panic();
403 let detail = payload
404 .downcast_ref::<&'static str>()
405 .map(|message| (*message).to_string())
406 .or_else(|| payload.downcast_ref::<String>().cloned())
407 .unwrap_or_else(|| "a panic carrying no message".to_string());
408
409 ScanError::TaskFailed {
410 panicked: true,
411 detail,
412 }
413}
414
415pub struct ScanTask {
443 handle: Option<JoinHandle<ScanReport>>,
445 stop: handle::ScanHandle,
447 #[cfg(feature = "journal-format")]
450 journal: Option<checkpoint::Checkpointing>,
451 #[cfg(feature = "journal-format")]
456 earlier: Vec<ScanPhase>,
457}
458
459impl ScanTask {
460 fn new(handle: JoinHandle<ScanReport>, stop: handle::ScanHandle) -> Self {
461 Self {
462 handle: Some(handle),
463 stop,
464 #[cfg(feature = "journal-format")]
465 journal: None,
466 #[cfg(feature = "journal-format")]
467 earlier: Vec::new(),
468 }
469 }
470
471 #[cfg(feature = "journal-format")]
473 fn journalling(
474 handle: JoinHandle<ScanReport>,
475 stop: handle::ScanHandle,
476 journal: checkpoint::Checkpointing,
477 earlier: Vec<ScanPhase>,
478 ) -> Self {
479 Self {
480 handle: Some(handle),
481 stop,
482 journal: Some(journal),
483 earlier,
484 }
485 }
486
487 pub async fn join(mut self) -> Result<ScanReport, ScanError> {
497 let running = self.handle.as_mut().expect("a task is joined at most once");
500 let report = running.await.map_err(panic_or_cancellation);
501 self.handle = None;
502
503 #[cfg(feature = "journal-format")]
507 if let Some(journal) = self.journal.take() {
508 let phases = report.as_ref().map(ScanReport::phases).unwrap_or_default();
509 journal.finish(phases).await;
510 }
511
512 #[cfg(feature = "journal-format")]
514 if !self.earlier.is_empty() {
515 let earlier = std::mem::take(&mut self.earlier);
516 return report.map(|report| {
517 let mut whole = ScanReport::from_phases(earlier, []);
518 whole.merge(report);
519 whole
520 });
521 }
522
523 report
524 }
525}
526
527impl Drop for ScanTask {
528 fn drop(&mut self) {
529 let Some(scan) = self.handle.take() else {
530 return;
531 };
532 self.stop.abort();
533
534 #[cfg(feature = "journal-format")]
538 if let Some(journal) = self.journal.take()
539 && let Ok(runtime) = tokio::runtime::Handle::try_current()
540 {
541 runtime.spawn(async move {
542 let phases = match scan.await {
543 Ok(report) => report.phases().to_vec(),
544 Err(_) => Vec::new(),
545 };
546 journal.finish(&phases).await;
547 });
548 }
549 #[cfg(not(feature = "journal-format"))]
550 drop(scan);
551 }
552}
553
554impl IntoFuture for ScanTask {
555 type Output = Result<ScanReport, ScanError>;
556 type IntoFuture = Pin<Box<dyn Future<Output = Self::Output> + Send>>;
557
558 fn into_future(self) -> Self::IntoFuture {
559 Box::pin(self.join())
560 }
561}
562
563pub async fn discover(
588 targets: IpSet,
589 cfg: &ZondConfig,
590) -> Result<(ScanSession, ScanTask), ScanError> {
591 cfg.evasion.validate()?;
592 let capture_links = capture_plan(&targets, cfg)?;
593
594 let mut numbered = targets.clone();
598 cfg.exclusions.withhold(&mut numbered);
599 numbered.canonicalize();
600 let positions = numbered.positions();
601 let planned = planned_addresses(&positions);
602
603 let (session, ctx) = ScanSession::builder()
604 .excluding(cfg.exclusions.clone())
605 .naming(cfg.target_names.clone())
606 .host_timeout(cfg.host_timeout)
607 .scan_timeout(cfg.scan_timeout)
608 .host_probe_interval(cfg.host_probe_interval)
609 .probe_interval(cfg.probe_interval)
610 .send_source(cfg.send_source.clone())
611 .listening_only_to(cfg.listen_only_ports.clone())
612 .counting(positions)
613 .planning(Stage::Discovery, planned)
614 .staging(discovery_stages(cfg))
615 .build();
616 let handle = spawn_discovery(targets, capture_links, cfg, ctx);
617 let stop = session.handle().clone();
618 Ok((session, ScanTask::new(handle, stop)))
619}
620
621#[cfg(feature = "journal-format")]
654pub async fn discover_with_journal(
655 targets: IpSet,
656 cfg: &ZondConfig,
657 journal: crate::journal::Journal,
658) -> Result<(ScanSession, ScanTask), ScanError> {
659 let mut capture_links = Vec::new();
660 let journal = accepted(journal, |journal| {
661 cfg.evasion.validate()?;
662 if journal.manifest().kind() != ScanKind::Discovery {
663 return Err(ScanError::WrongPhase);
664 }
665 let recorded = journal.manifest().recorded();
666 let Some(addresses) = recorded.addresses() else {
667 return Err(ScanError::WrongPhase);
668 };
669 let swept = if *journal.resume_point() == Checkpoint::default() {
672 &targets
673 } else {
674 addresses
675 };
676 capture_links = capture_plan(swept, cfg)?;
678 let this_run = crate::journal::manifest::Plan::discovery(
679 swept,
680 &cfg.exclusions,
681 recorded.sweeps_the_segment(),
682 );
683 counted_as_recorded(journal, &this_run)?;
684 under_the_recorded_options(journal, cfg)
685 })?;
686 let journal = recording_options(journal, cfg);
687
688 let recorded = journal.manifest().recorded();
689 let Some(addresses) = recorded.addresses() else {
690 return Err(ScanError::WrongPhase);
691 };
692
693 let positions = addresses.positions();
696 let resume_point = journal.resume_point().clone();
697 let order_seed = journal.manifest().order_seed;
700
701 let sweep = if resume_point == Checkpoint::default() {
702 targets
703 } else {
704 resume_point.remaining_addresses(&positions)
705 };
706
707 let planned = planned_addresses(&positions);
708 let finished = journal.finished_hosts().unwrap_or_else(|e| {
709 crate::warn!("passes rerun for every host ({e})");
710 Default::default()
711 });
712
713 let (session, ctx) = ScanSession::builder()
714 .excluding(cfg.exclusions.clone())
715 .naming(cfg.target_names.clone())
716 .host_timeout(cfg.host_timeout)
717 .scan_timeout(cfg.scan_timeout)
718 .host_probe_interval(cfg.host_probe_interval)
719 .probe_interval(cfg.probe_interval)
720 .send_source(cfg.send_source.clone())
721 .listening_only_to(cfg.listen_only_ports.clone())
722 .resuming(&resume_point)
723 .finished(finished, sweep.clone())
724 .counting(positions)
725 .planning(Stage::Discovery, planned)
726 .staging(discovery_stages(cfg))
727 .ordering(order_seed)
728 .build();
729
730 ctx.restore_hosts(journal.restored());
731 let earlier = journal.earlier_phases().to_vec();
732
733 let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
734 let handle = spawn_discovery(sweep, capture_links, cfg, ctx);
735
736 let stop = session.handle().clone();
737 Ok((
738 session,
739 ScanTask::journalling(handle, stop, ticker, earlier),
740 ))
741}
742
743fn planned_addresses(positions: &Positions) -> Option<u64> {
751 positions.unnumbered().is_empty().then(|| positions.total())
752}
753
754fn discovery_stages(cfg: &ZondConfig) -> Vec<Stage> {
756 let mut stages = vec![Stage::Discovery];
757
758 if cfg.os_detection.is_active() {
759 stages.push(Stage::Os);
760 }
761 if cfg.traceroute {
762 stages.push(Stage::Traceroute);
763 }
764 if cfg.characterise {
765 stages.push(Stage::Filters);
766 }
767 if !cfg.ip_protocols.is_empty() {
768 stages.push(Stage::IpProtocols);
769 }
770
771 stages
772}
773
774fn scan_stages(cfg: &ZondConfig, runs_liveness: bool) -> Vec<Stage> {
790 let cfg = &running_under(cfg);
791 let mut stages = Vec::new();
792
793 if runs_liveness {
794 stages.push(Stage::Discovery);
795 }
796 stages.push(Stage::Ports);
797
798 if cfg.service_detection.connects() {
799 stages.push(Stage::Services);
800 }
801 if cfg.service_detection != crate::config::ServiceDetection::Off
802 && cfg.detection.ceiling().is_some()
803 {
804 stages.push(Stage::Detections);
805 }
806 if cfg.tls_enumeration {
807 stages.push(Stage::Tls);
808 }
809 if cfg.os_detection.is_active() {
810 stages.push(Stage::Os);
811 }
812 if cfg.traceroute {
813 stages.push(Stage::Traceroute);
814 }
815 if cfg.characterise {
816 stages.push(Stage::Filters);
817 }
818 if !cfg.ip_protocols.is_empty() {
819 stages.push(Stage::IpProtocols);
820 }
821
822 stages
823}
824
825fn asks_liveness(cfg: &ZondConfig) -> bool {
834 !cfg.assume_up && cfg.idle_scan.is_none()
835}
836
837fn liveness_earns_its_place(cfg: &ZondConfig, map: &TargetMap) -> bool {
871 use crate::model::port::Protocol;
872
873 if !asks_liveness(cfg) {
874 return false;
875 }
876
877 let asked = SynPorts::for_scan(&tcp_ports_of(map))
878 .excluding(&cfg.excluded_ports)
879 .len()
880 + usize::from(orchestrator::sctp_discovery_port(map, &cfg.excluded_ports).is_some());
881 if asked == 0 {
882 return false;
883 }
884
885 if !cfg.tcp_technique.has_connect_fallback() {
886 return true;
887 }
888
889 if map.names(Protocol::Udp) {
890 return true;
891 }
892
893 let per_address = map
895 .units
896 .iter()
897 .map(crate::model::target::TargetSet::port_count)
898 .max()
899 .unwrap_or(0);
900 if per_address > asked {
901 return true;
902 }
903
904 reaches_a_local_segment(cfg, map)
905}
906
907fn liveness_skip(cfg: &ZondConfig, runs_liveness: bool) -> Option<LivenessSkip> {
914 if runs_liveness {
915 None
916 } else if cfg.idle_scan.is_some() {
917 Some(LivenessSkip::IdleScan)
918 } else if cfg.assume_up {
919 Some(LivenessSkip::AssumeUp)
920 } else {
921 Some(LivenessSkip::PortsNoDearer)
922 }
923}
924
925const ON_LINK_CHECK_CEILING: u128 = 1 << 13;
931
932fn reaches_a_local_segment(cfg: &ZondConfig, map: &TargetMap) -> bool {
942 match map.gross_ips() {
943 Ok(count) if count <= ON_LINK_CHECK_CEILING => {}
944 _ => return false,
945 }
946
947 let mut ips = IpSet::new();
948 for unit in &map.units {
949 for range in unit.ips().v4() {
950 ips.push_v4_range(*range);
951 }
952 for range in unit.ips().v6() {
953 ips.push_v6_range(*range);
954 }
955 }
956 ips.canonicalize();
957
958 let plan = plan::DiscoveryPlan::build(ips, Scope::Targeted, &cfg.exclusions, &cfg.send_source);
959 plan.steps()
960 .iter()
961 .any(|step| matches!(step, plan::DiscoveryStep::Local { .. }))
962}
963
964fn running_under(cfg: &ZondConfig) -> ZondConfig {
978 if cfg.idle_scan.is_none() {
979 return cfg.clone();
980 }
981
982 let mut muted = cfg.clone();
983 muted.service_detection = crate::config::ServiceDetection::Off;
984 if muted.detection.ceiling() > Some(crate::model::finding::DetectionClass::Passive) {
985 muted.detection =
986 crate::config::DetectionEnvelope::up_to(crate::model::finding::DetectionClass::Passive);
987 }
988 if muted.os_detection.is_active() {
989 muted.os_detection = crate::config::OsDetection::Passive;
990 }
991 muted.traceroute = false;
992 muted.characterise = false;
993 muted.ip_protocols.clear();
994 muted.tls_enumeration = false;
995 muted
996}
997
998fn record_idle_refusals(cfg: &ZondConfig, ctx: &ScanContext) {
1008 use crate::model::finding::DetectionClass;
1009 use crate::report::ScannerKind;
1010 use plan::RefusedStep;
1011
1012 if cfg.idle_scan.is_none() {
1013 return;
1014 }
1015
1016 if cfg.service_detection.connects() {
1017 crate::info!(verbosity = 1, "service detection skipped (idle scan)");
1018 }
1019 if cfg.detection.ceiling() > Some(DetectionClass::Passive) {
1020 ctx.record_refusal(
1021 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Detection, "active detection")
1022 .into(),
1023 );
1024 }
1025 if cfg.os_detection.is_active() {
1026 ctx.record_refusal(
1027 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::OsSeries, "OS probing").into(),
1028 );
1029 }
1030 if cfg.traceroute {
1031 ctx.record_refusal(
1032 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "route trace").into(),
1033 );
1034 }
1035 if cfg.characterise {
1036 ctx.record_refusal(
1037 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "filter characterisation")
1038 .into(),
1039 );
1040 }
1041 if !cfg.ip_protocols.is_empty() {
1042 ctx.record_refusal(
1043 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Routed, "IP-protocol probe").into(),
1044 );
1045 }
1046 if cfg.tls_enumeration {
1047 ctx.record_refusal(
1048 RefusedStep::pass_not_in_an_idle_scan(ScannerKind::Service, "TLS enumeration").into(),
1049 );
1050 }
1051}
1052
1053fn planned_targets(map: &TargetMap) -> Option<u64> {
1059 let index = TargetIndex::of(map);
1060 index.is_complete().then(|| index.total())
1061}
1062
1063fn spawn_discovery(
1068 mut targets: IpSet,
1069 capture_links: Vec<Zone>,
1070 cfg: &ZondConfig,
1071 ctx: ScanContext,
1072) -> JoinHandle<ScanReport> {
1073 let sends = !targets.is_empty() || cfg.segment_sweep;
1076 let caps = ScanCapabilities::resolve(
1077 cfg,
1078 sends.then(orchestrator::Probing::sweep),
1079 &targets,
1080 interface::FrameSender::Sweep,
1081 );
1082
1083 let scope = address_scope(&mut targets, &ctx);
1087 let recorder =
1088 PhaseRecorder::start(ScanKind::Discovery, caps.privilege, scope, cfg).opening_in(&ctx);
1089
1090 let reach = if cfg.segment_sweep {
1091 Scope::Sweep
1092 } else {
1093 Scope::Targeted
1094 };
1095 let cfg = cfg.clone();
1096 let held_back = crate::system::descriptors::hold_back();
1097
1098 tokio::spawn(async move {
1099 let _held_back = held_back;
1101 ctx.capture_on(capture_links);
1104 ctx.enter_stage(Stage::Discovery, None);
1105 run_discovery(targets, reach, caps, &cfg, &ctx, SynPorts::common(), None).await;
1107 orchestrator::run_active_os_probe(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1109 orchestrator::run_traceroute(&ctx, &cfg, caps).await;
1111 orchestrator::run_characterise(&ctx, &cfg, caps).await;
1112 orchestrator::run_ip_protocols(&ctx, &cfg).await;
1113 ctx.enter_stage(Stage::Finishing, None);
1114 vantage::attribute(&ctx);
1116 orchestrator::correlate(&ctx, cfg.service_detection).await;
1117 recorder.finish_last(ctx)
1118 })
1119}
1120
1121fn machine_policy(ctx: &ScanContext) -> crate::model::exclusion::Exclusions {
1126 ctx.exclusions.widened(ctx.withheld_by_hardware())
1127}
1128
1129fn address_scope(targets: &mut IpSet, ctx: &ScanContext) -> TargetScope {
1137 let tied = ctx.withheld_by_hardware();
1138 for address in &tied {
1139 if targets.contains(address) {
1140 ctx.settle_withheld(*address);
1141 }
1142 }
1143 TargetScope::from_ip_set(targets, &ctx.exclusions.widened(tied))
1144}
1145
1146async fn run_discovery(
1171 targets: IpSet,
1172 reach: Scope,
1173 caps: ScanCapabilities,
1174 cfg: &ZondConfig,
1175 ctx: &ScanContext,
1176 syn_ports: SynPorts,
1177 sctp_port: Option<u16>,
1178) {
1179 let syn_ports = syn_ports.excluding(&cfg.excluded_ports);
1180 if caps.privilege.is_raw() {
1181 let unframed =
1182 caps.beyond_frames(&targets, &cfg.send_source, interface::FrameSender::Sweep);
1183 let mut plan =
1184 plan::DiscoveryPlan::build(targets, reach, &cfg.exclusions, &cfg.send_source);
1185 plan.connect_instead(&unframed.targets);
1186 plan.asking_tcp(syn_ports);
1187 for address in plan.refused_by_route().iter() {
1188 ctx.note_refused_by_route(address);
1189 }
1190 for address in plan.withheld().iter() {
1191 ctx.note_withheld_neighbour(address);
1192 }
1193 if let Some(port) = sctp_port {
1194 plan.also_over_sctp(port);
1195 }
1196 orchestrator::reached_by_connect(&plan, unframed, ctx);
1197 let enrichment = Enrichment::spawn(plan, ctx, caps, cfg.probe_tuning()).await;
1198 finish_enrichment(Some(enrichment), caps, ctx, rdns::Unheard::Skipped).await;
1199 } else {
1200 let targets = orchestrator::walkable(targets, ctx);
1201 if syn_ports.is_empty() {
1202 ctx.record_refusal(
1203 plan::RefusedStep::every_discovery_port_excluded(ScannerKind::Connect).into(),
1204 );
1205 } else if let Err(error) =
1206 strategy::connect::discover_on(targets, ctx.clone(), &cfg.evasion, syn_ports).await
1207 {
1208 ctx.record_failure(ScannerKind::Connect, error.to_string());
1209 }
1210 finish_enrichment(None, caps, ctx, rdns::Unheard::Skipped).await;
1211 }
1212
1213 orchestrator::run_passive_os_identification(ctx, cfg.os_detection);
1214}
1215
1216fn tcp_ports_of(map: &TargetMap) -> PortSet {
1221 map.units
1222 .iter()
1223 .fold(PortSet::new(), |named, unit| named.union(unit.ports()))
1224}
1225
1226#[must_use]
1234#[derive(Debug, Clone)]
1235pub struct ListenScope {
1236 links: Vec<crate::model::ip::scoped::Zone>,
1237 recording: strategy::passive::Recording,
1238 until: Until,
1239}
1240
1241#[non_exhaustive]
1246#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
1247pub enum Until {
1248 #[default]
1253 Stopped,
1254 Elapsed(std::time::Duration),
1259}
1260
1261impl ListenScope {
1262 pub fn on(links: Vec<crate::model::ip::scoped::Zone>) -> Self {
1270 Self {
1271 links,
1272 recording: strategy::passive::Recording::Attached,
1273 until: Until::Stopped,
1274 }
1275 }
1276
1277 pub fn recording_everything(mut self) -> Self {
1282 self.recording = strategy::passive::Recording::Everything;
1283 self
1284 }
1285
1286 pub fn recording_only(mut self, addresses: IpSet) -> Self {
1291 self.recording = strategy::passive::Recording::Only(addresses);
1292 self
1293 }
1294
1295 pub fn for_at_most(mut self, span: std::time::Duration) -> Self {
1297 self.until = Until::Elapsed(span);
1298 self
1299 }
1300
1301 pub fn links(&self) -> &[crate::model::ip::scoped::Zone] {
1303 &self.links
1304 }
1305
1306 pub fn until(&self) -> Until {
1308 self.until
1309 }
1310}
1311
1312pub async fn listen(
1351 scope: ListenScope,
1352 cfg: &ZondConfig,
1353) -> Result<(ScanSession, ScanTask), ScanError> {
1354 let (session, ctx) = ScanSession::builder()
1355 .excluding(cfg.exclusions.clone())
1356 .naming(cfg.target_names.clone())
1357 .host_timeout(cfg.host_timeout)
1358 .scan_timeout(cfg.scan_timeout)
1359 .host_probe_interval(cfg.host_probe_interval)
1360 .probe_interval(cfg.probe_interval)
1361 .staging(vec![Stage::Listening])
1362 .build();
1363 let handle = spawn_listen(scope, cfg, ctx);
1364 let stop = session.handle().clone();
1365 Ok((session, ScanTask::new(handle, stop)))
1366}
1367
1368#[cfg(feature = "journal-format")]
1395pub async fn listen_with_journal(
1396 scope: ListenScope,
1397 cfg: &ZondConfig,
1398 journal: crate::journal::Journal,
1399) -> Result<(ScanSession, ScanTask), ScanError> {
1400 let journal = accepted(journal, |journal| {
1401 if journal.manifest().kind() != ScanKind::Listen {
1402 return Err(ScanError::WrongPhase);
1403 }
1404 Ok(())
1405 })?;
1406
1407 let (session, ctx) = ScanSession::builder()
1408 .excluding(cfg.exclusions.clone())
1409 .naming(cfg.target_names.clone())
1410 .host_timeout(cfg.host_timeout)
1411 .scan_timeout(cfg.scan_timeout)
1412 .host_probe_interval(cfg.host_probe_interval)
1413 .probe_interval(cfg.probe_interval)
1414 .staging(vec![Stage::Listening])
1415 .build();
1416
1417 ctx.restore_hosts(journal.restored());
1420 let earlier = journal.earlier_phases().to_vec();
1421
1422 let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
1423 let handle = spawn_listen(scope, cfg, ctx);
1424
1425 let stop = session.handle().clone();
1426 Ok((
1427 session,
1428 ScanTask::journalling(handle, stop, ticker, earlier),
1429 ))
1430}
1431
1432fn spawn_listen(scope: ListenScope, cfg: &ZondConfig, ctx: ScanContext) -> JoinHandle<ScanReport> {
1434 let cfg = cfg.clone();
1435
1436 tokio::spawn(async move {
1437 ctx.enter_stage(Stage::Listening, None);
1443
1444 let opened =
1445 strategy::passive::PassiveListener::open(&scope.links, scope.recording, ctx.clone());
1446
1447 let recorder = PhaseRecorder::start(
1449 ScanKind::Listen,
1450 listening_privilege(opened.as_ref().err()),
1451 TargetScope::listening_on(scope.links.clone(), &cfg.exclusions),
1452 &cfg,
1453 )
1454 .opening_in(&ctx);
1455
1456 match opened {
1457 Ok(listener) => {
1458 let mut listener = listener.detecting_os(cfg.os_detection);
1459 if let Until::Elapsed(span) = scope.until {
1460 listener = listener.stopping_after(span);
1463 }
1464
1465 if let Err(error) = listener.observe().await {
1466 ctx.record_failure(ScannerKind::Passive, error.to_string());
1467 }
1468 }
1469 Err(error) => ctx.record_failure(ScannerKind::Passive, error.to_string()),
1470 }
1471
1472 vantage::attribute(&ctx);
1473 orchestrator::correlate(&ctx, cfg.service_detection).await;
1474 recorder.finish_last(ctx)
1475 })
1476}
1477
1478fn listening_privilege(refusal: Option<&strategy::StrategyError>) -> Privilege {
1488 use crate::transport::capture::CaptureError;
1489
1490 match refusal {
1491 None => Privilege::Raw,
1492 Some(strategy::StrategyError::Capture(CaptureError::NoInterface { refused }))
1493 if refused.is_empty() =>
1494 {
1495 Privilege::current()
1496 }
1497 Some(strategy::StrategyError::Capture(error)) if error.is_denied() => Privilege::Connect,
1498 Some(strategy::StrategyError::Capture(_)) => Privilege::Raw,
1499 Some(_) => Privilege::current(),
1500 }
1501}
1502
1503pub fn withhold_unprobeable(target_map: &mut TargetMap) {
1512 target_map.take_unprobeable(&[], interface::is_enumerable);
1513}
1514
1515pub async fn scan(
1549 target_map: TargetMap,
1550 cfg: &ZondConfig,
1551 detections: Detections,
1552) -> Result<(ScanSession, ScanTask), ScanError> {
1553 cfg.evasion.validate()?;
1554
1555 let mut target_map = target_map;
1556 target_map.withhold_ports(&cfg.excluded_ports);
1557 let withheld = orchestrator::withhold_unprobeable_targets(&mut target_map);
1558 let capture_links = capture_plan(&plan_addresses(&target_map), cfg)?;
1559 let planned = planned_targets(&target_map);
1560 let runs_liveness = liveness_earns_its_place(cfg, &target_map);
1561
1562 let (session, ctx) = ScanSession::builder()
1563 .excluding(cfg.exclusions.clone())
1564 .naming(cfg.target_names.clone())
1565 .host_timeout(cfg.host_timeout)
1566 .scan_timeout(cfg.scan_timeout)
1567 .host_probe_interval(cfg.host_probe_interval)
1568 .probe_interval(cfg.probe_interval)
1569 .send_source(cfg.send_source.clone())
1570 .listening_only_to(cfg.listen_only_ports.clone())
1571 .detections(detections)
1572 .planning(Stage::Ports, planned)
1573 .staging(scan_stages(cfg, runs_liveness))
1574 .build();
1575 let handle = spawn_scan(
1576 target_map,
1577 withheld,
1578 capture_links,
1579 cfg,
1580 ctx,
1581 Checkpoint::default(),
1582 runs_liveness,
1583 );
1584 let stop = session.handle().clone();
1585 Ok((session, ScanTask::new(handle, stop)))
1586}
1587
1588#[cfg(feature = "journal-format")]
1617pub async fn scan_with_journal(
1618 target_map: TargetMap,
1619 cfg: &ZondConfig,
1620 detections: Detections,
1621 journal: crate::journal::Journal,
1622) -> Result<(ScanSession, ScanTask), ScanError> {
1623 let mut capture_links = Vec::new();
1624 let journal = accepted(journal, |journal| {
1625 cfg.evasion.validate()?;
1626 let mut probed = target_map.clone();
1629 probed.withhold_ports(&cfg.excluded_ports);
1630 orchestrator::withhold_unprobeable_targets(&mut probed);
1631 capture_links = capture_plan(&plan_addresses(&probed), cfg)?;
1632 if journal.manifest().kind() != ScanKind::PortScan {
1633 return Err(ScanError::WrongPhase);
1634 }
1635 let technique = journal.manifest().technique();
1636 let this_run =
1637 crate::journal::manifest::Plan::port_scan(&target_map, &cfg.exclusions, technique);
1638 counted_as_recorded(journal, &this_run)?;
1639 under_the_recorded_options(journal, cfg)
1640 })?;
1641 let cfg = &under_the_recorded_technique(&journal, cfg);
1642 let journal = recording_options(journal, cfg);
1643 let numbered_without = journal.options().map_or_else(
1646 || cfg.excluded_ports.clone(),
1647 crate::journal::manifest::JobOptions::excluded_ports,
1648 );
1649 let withheld_ports = cfg.excluded_ports.difference(&numbered_without);
1650 let mut target_map = target_map;
1651 target_map.withhold_ports(&numbered_without);
1652 let withheld = orchestrator::withhold_unprobeable_targets(&mut target_map);
1653 let runs_liveness = liveness_earns_its_place(cfg, &target_map);
1654 let finished = journal.finished_hosts().unwrap_or_else(|e| {
1655 crate::warn!("passes rerun for every host ({e})");
1656 Default::default()
1657 });
1658 let mut numbered = target_map.clone();
1660 cfg.exclusions.withhold_targets(&mut numbered);
1661 let asked = orchestrator::unsettled_ips(&numbered, journal.resume_point());
1662
1663 let (session, ctx) = ScanSession::builder()
1664 .excluding(cfg.exclusions.clone())
1665 .naming(cfg.target_names.clone())
1666 .host_timeout(cfg.host_timeout)
1667 .scan_timeout(cfg.scan_timeout)
1668 .host_probe_interval(cfg.host_probe_interval)
1669 .probe_interval(cfg.probe_interval)
1670 .send_source(cfg.send_source.clone())
1671 .listening_only_to(cfg.listen_only_ports.clone())
1672 .withholding_ports(withheld_ports)
1673 .resuming(journal.resume_point())
1674 .finished(finished, asked)
1675 .detections(detections)
1676 .planning(Stage::Ports, planned_targets(&target_map))
1677 .staging(scan_stages(cfg, runs_liveness))
1678 .ordering(journal.manifest().order_seed)
1680 .build();
1681
1682 ctx.restore_hosts(journal.restored());
1685
1686 let earlier = journal.earlier_phases().to_vec();
1687 let resume_point = journal.resume_point().clone();
1688
1689 let ticker = checkpoint::spawn_checkpoints(journal, ctx.progress());
1692 let handle = spawn_scan(
1693 target_map,
1694 withheld,
1695 capture_links,
1696 cfg,
1697 ctx,
1698 resume_point,
1699 runs_liveness,
1700 );
1701
1702 let stop = session.handle().clone();
1703 Ok((
1704 session,
1705 ScanTask::journalling(handle, stop, ticker, earlier),
1706 ))
1707}
1708
1709fn sitting_probes(
1716 cfg: &ZondConfig,
1717 target_map: &TargetMap,
1718 numbered: &TargetMap,
1719 settled: &Checkpoint,
1720) -> Option<orchestrator::Probing> {
1721 (!orchestrator::unsettled_ips(numbered, settled).is_empty())
1722 .then(|| orchestrator::Probing::ports(cfg, target_map))
1723}
1724
1725#[allow(clippy::too_many_arguments)]
1736fn spawn_scan(
1737 target_map: TargetMap,
1738 withheld: orchestrator::Withheld,
1739 capture_links: Vec<Zone>,
1740 cfg: &ZondConfig,
1741 ctx: ScanContext,
1742 settled: Checkpoint,
1743 runs_liveness: bool,
1744) -> JoinHandle<ScanReport> {
1745 let mut numbered = target_map.clone();
1747 cfg.exclusions.withhold_targets(&mut numbered);
1748 let caps = ScanCapabilities::resolve(
1749 cfg,
1750 sitting_probes(cfg, &target_map, &numbered, &settled),
1751 &orchestrator::unsettled_ips(&numbered, &settled),
1752 interface::FrameSender::Probe,
1753 );
1754 let requested = cfg.clone();
1757 let cfg = running_under(&requested);
1758 let held_back = crate::system::descriptors::hold_back();
1759
1760 tokio::spawn(async move {
1761 let _held_back = held_back;
1763 crate::fingerprint::start_loading_corpus();
1764 ctx.number_targets(TargetIndex::of(&numbered));
1767 ctx.capture_on(capture_links);
1770
1771 let skipped = liveness_skip(&cfg, runs_liveness);
1778 let (liveness, live) = if let Some(why) = skipped {
1779 match why {
1780 LivenessSkip::IdleScan => {
1781 crate::info!(verbosity = 1, "liveness pass skipped (idle scan)");
1782 }
1783 LivenessSkip::PortsNoDearer => {
1784 crate::info!(verbosity = 1, "liveness pass skipped (port scan no dearer)");
1785 }
1786 _ => {}
1788 }
1789 (None, None)
1790 } else {
1791 let unnumbered = Checkpoint::default();
1796 let mut finished = orchestrator::unsettled_ips(&numbered, &unnumbered);
1797 finished.subtract(&orchestrator::unsettled_ips(&numbered, &settled));
1798 let mut ips = orchestrator::unsettled_ips(&target_map, &unnumbered);
1799 ips.subtract(&finished);
1800 let scope = address_scope(&mut ips, &ctx);
1801 let recorder = PhaseRecorder::start(ScanKind::Discovery, caps.privilege, scope, &cfg)
1802 .opening_in(&ctx);
1803
1804 ctx.enter_stage(Stage::Discovery, None);
1810 let syn_ports = SynPorts::for_scan(&tcp_ports_of(&target_map));
1811 let sctp = orchestrator::sctp_discovery_port(&target_map, &cfg.excluded_ports);
1812 run_discovery(ips, Scope::Targeted, caps, &cfg, &ctx, syn_ports, sctp).await;
1813
1814 orchestrator::correlate(&ctx, cfg.service_detection).await;
1815 let (report, liveness) = recorder.close(&ctx);
1816 (Some(report), liveness)
1817 };
1818
1819 let mut covered = match &live {
1826 Some(live) => probed_subset(&target_map, &live.live),
1827 None => target_map.clone(),
1828 };
1829 let scope = TargetScope::from_target_map(&mut covered, &machine_policy(&ctx));
1834 let mut recorder = PhaseRecorder::start(ScanKind::PortScan, caps.privilege, scope, &cfg);
1835 if let Some(why) = skipped {
1836 recorder = recorder.skipping_liveness(why);
1837 }
1838 let recorder = recorder.opening_in(&ctx);
1839
1840 ctx.enter_stage(Stage::Ports, None);
1841 record_idle_refusals(&requested, &ctx);
1843 let port_scanner = match caps.privilege.is_raw() {
1844 true => ScannerKind::SynPort,
1845 false => ScannerKind::Connect,
1846 };
1847 withheld.refuse(&ctx, port_scanner);
1848 let stands_in = skipped == Some(LivenessSkip::PortsNoDearer);
1849 run_port_phase(
1850 numbered,
1851 withheld.zones(),
1852 live,
1853 &ctx,
1854 caps,
1855 &cfg,
1856 settled,
1857 stands_in,
1858 )
1859 .await;
1860
1861 orchestrator::run_tls_enumeration(&ctx, &cfg).await;
1864
1865 orchestrator::run_active_os_series(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1868 orchestrator::run_active_os_snmp(&ctx, cfg.os_detection, &cfg.excluded_ports).await;
1869 orchestrator::run_active_os_mdns(&ctx, cfg.os_detection, !cfg.no_dns, &cfg.excluded_ports)
1872 .await;
1873 orchestrator::run_active_os_probe(&ctx, cfg.os_detection, cfg.probe_tuning(), caps).await;
1874 orchestrator::run_traceroute(&ctx, &cfg, caps).await;
1876 orchestrator::run_characterise(&ctx, &cfg, caps).await;
1877 orchestrator::run_ip_protocols(&ctx, &cfg).await;
1878 ctx.enter_stage(Stage::Finishing, None);
1879 vantage::attribute(&ctx);
1880 orchestrator::correlate(&ctx, cfg.service_detection).await;
1881 orchestrator::run_cert_posture(&ctx);
1882 let report = recorder.finish_last(ctx);
1883
1884 match liveness {
1887 Some(mut first) => {
1888 first.merge_later_copy(report);
1889 first
1890 }
1891 None => report,
1892 }
1893 })
1894}
1895
1896#[cfg(test)]
1906mod tests {
1907 use super::*;
1908 use crate::testing::loopback::accept_from_this_process;
1909
1910 #[test]
1913 fn a_sitting_with_nothing_left_to_ask_names_no_probes() {
1914 let mut map = TargetMap::new();
1915 map.add_unit(crate::model::target::TargetSet::new(
1916 "192.0.2.1".parse().expect("an address"),
1917 "80".parse().expect("a port"),
1918 ));
1919 let cfg = ZondConfig::default();
1920
1921 let everything = Checkpoint::new(1, []);
1922 assert_eq!(sitting_probes(&cfg, &map, &map, &everything), None);
1923 assert!(
1924 sitting_probes(&cfg, &map, &map, &Checkpoint::default()).is_some(),
1925 "a sitting with its target left to ask probes it"
1926 );
1927 }
1928
1929 #[cfg(feature = "journal-format")]
1932 fn journal_root(name: &str) -> std::path::PathBuf {
1933 let root = std::env::temp_dir().join(format!("zond-{name}-{}", std::process::id()));
1934 let _ = std::fs::remove_dir_all(&root);
1935 std::fs::create_dir_all(&root).expect("a scratch root");
1936 root
1937 }
1938
1939 #[test]
1943 fn a_named_address_of_an_excluded_machine_leaves_the_sweeps_scope() {
1944 use crate::journal::settle::Outcome;
1945 use crate::model::exclusion::Exclusions;
1946 use crate::model::ip::set::{IpSet, Positions};
1947 use crate::model::mac::MacAddr;
1948 use std::net::IpAddr;
1949
1950 let machine = MacAddr::new(0x02, 0, 0, 0, 0, 0x30);
1951 let excluded: IpAddr = "192.0.2.30".parse().expect("literal");
1952 let other: IpAddr = "192.0.2.40".parse().expect("literal");
1953 let mut policy = IpSet::new();
1954 policy.insert(excluded);
1955 let mut targets: IpSet = "192.0.2.39-192.0.2.41".parse().expect("a range");
1956 let (_session, ctx) = ScanSession::builder()
1957 .excluding(Exclusions::new(policy))
1958 .with_neighbours(vec![(excluded, Some(machine)), (other, Some(machine))])
1959 .counting(Positions::of(&targets))
1960 .build();
1961
1962 let scope = address_scope(&mut targets, &ctx);
1963
1964 assert!(!targets.contains(&other), "it is still a target");
1965 assert_eq!(targets.len(), 2);
1966 assert_eq!((scope.addresses(), scope.withheld()), (2, 1));
1967 let excluded_starts: Vec<IpAddr> = scope
1968 .excluded()
1969 .iter()
1970 .map(|range| range.start_addr())
1971 .collect();
1972 assert!(excluded_starts.contains(&other), "{excluded_starts:?}");
1973 assert!(excluded_starts.contains(&excluded), "{excluded_starts:?}");
1974 assert_eq!(
1975 ctx.settlements().count(Outcome::Withheld { position: 0 }),
1976 1
1977 );
1978 assert_eq!(ctx.settlements().checkpoint().settled_count(), 1);
1979 }
1980
1981 fn refused_up_front() -> ZondConfig {
1983 ZondConfig {
1984 evasion: crate::evasion::EvasionProfile::default().with_ttl(0),
1985 ..ZondConfig::default()
1986 }
1987 }
1988
1989 #[cfg(feature = "journal-format")]
1995 #[tokio::test]
1996 async fn a_journalled_scan_refused_up_front_leaves_no_record() {
1997 use crate::journal::Journal;
1998 use crate::journal::manifest::Plan;
1999 use crate::model::ip::set::IpSet;
2000 use crate::model::target::TargetSet;
2001
2002 let root = journal_root("refused");
2003 let addresses: IpSet = "192.0.2.1".parse().expect("an address");
2004 let mut map = TargetMap::new();
2005 map.add_unit(TargetSet::new(
2006 addresses.clone(),
2007 "22".parse().expect("ports"),
2008 ));
2009 let cfg = refused_up_front();
2010
2011 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2012 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2013 let directory = journal.directory().to_path_buf();
2014 let refused = scan_with_journal(map, &cfg, Detections::embedded(), journal).await;
2015 assert!(
2016 matches!(refused, Err(ScanError::Evasion(_))),
2017 "{:?}",
2018 refused.err()
2019 );
2020 assert!(
2021 !directory.exists(),
2022 "a port scan that never ran left a record"
2023 );
2024
2025 let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
2026 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2027 let directory = journal.directory().to_path_buf();
2028 let refused = discover_with_journal(addresses, &cfg, journal).await;
2029 assert!(
2030 matches!(refused, Err(ScanError::Evasion(_))),
2031 "{:?}",
2032 refused.err()
2033 );
2034 assert!(!directory.exists(), "a sweep that never ran left a record");
2035
2036 std::fs::remove_dir_all(&root).ok();
2037 }
2038
2039 #[test]
2042 fn a_raw_scan_needs_a_capture_device_for_each_link_it_captures_on() {
2043 use crate::model::ip::scoped::Zone;
2044
2045 let links = [Zone::new(1, "lo0"), Zone::new(4, "en0")];
2046 assert_eq!(captures_needed(Privilege::Raw, &links), 2);
2047 assert_eq!(captures_needed(Privilege::Connect, &links), 0);
2048 }
2049
2050 #[test]
2053 fn a_scan_of_loopback_plans_its_captures_on_loopback_alone() {
2054 let cfg = ZondConfig::default();
2055 let links =
2056 capture_plan(&"127.0.0.1".parse().expect("an address"), &cfg).expect("room for it");
2057
2058 let loopback: Vec<_> = crate::system::interface::interfaces()
2059 .expect("this machine's interfaces")
2060 .into_iter()
2061 .filter(crate::system::interface::Link::is_loopback)
2062 .map(|link| link.zone())
2063 .collect();
2064 assert_eq!(links, loopback);
2065 }
2066
2067 #[tokio::test]
2070 async fn a_port_scan_of_a_range_too_wide_to_walk_refuses_it_and_ends() {
2071 use crate::model::target::TargetSet;
2072
2073 let mut map = TargetMap::new();
2074 map.add_unit(TargetSet::new(
2075 "2001:db8::/64".parse().expect("a prefix"),
2076 "80,443".parse().expect("ports"),
2077 ));
2078 let cfg = ZondConfig {
2079 no_dns: true,
2080 ..ZondConfig::default()
2081 };
2082
2083 let (_session, task) = scan(map, &cfg, Detections::embedded())
2084 .await
2085 .expect("the scan starts");
2086 let report = tokio::time::timeout(std::time::Duration::from_secs(120), task)
2088 .await
2089 .expect("the scan ended")
2090 .expect("the scan ran");
2091
2092 let refused: Vec<_> = report
2093 .phases()
2094 .iter()
2095 .filter(|phase| phase.kind() == ScanKind::PortScan)
2096 .flat_map(|phase| phase.refusals().iter())
2097 .filter(|refusal| refusal.reason().contains("too large to walk"))
2098 .collect();
2099 assert_eq!(refused.len(), 1, "{:?}", report.phases());
2100 }
2101
2102 #[cfg(feature = "journal-format")]
2108 #[tokio::test]
2109 async fn a_withheld_link_local_target_leaves_one_numbering_across_sittings() {
2110 use crate::journal::Journal;
2111 use crate::journal::manifest::Plan;
2112 use crate::model::ip::set::IpSet;
2113 use crate::model::target::TargetSet;
2114 use crate::testing::loopback::SilentPort;
2115
2116 let peer = SilentPort::open();
2117 let mut map = TargetMap::new();
2118 map.add_unit(TargetSet::new(
2119 "fe80::1-fe80::2".parse::<IpSet>().expect("addresses"),
2120 "80".parse().expect("ports"),
2121 ));
2122 map.add_unit(TargetSet::new(
2123 IpSet::from(peer.addr().ip()),
2124 peer.addr().port().to_string().parse().expect("ports"),
2125 ));
2126 let cfg = ZondConfig {
2127 no_dns: true,
2128 assume_up: true,
2129 service_detection: crate::config::ServiceDetection::Off,
2130 ..ZondConfig::default()
2131 };
2132 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2133 let root = journal_root("withheld-link-local");
2134 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2135 let directory = journal.directory().to_path_buf();
2136
2137 let (session, task) = scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2138 .await
2139 .expect("the first sitting starts");
2140 let report = task.join().await.expect("it finishes");
2141 assert!(
2142 report
2143 .phases()
2144 .iter()
2145 .flat_map(|phase| phase.refusals())
2146 .any(|refusal| refusal.reason().contains("link-local, name the interface")),
2147 "the unscoped targets are refused: {:?}",
2148 report.phases()
2149 );
2150 let progress = session.progress();
2151 assert_eq!(progress.planned(), Some(1), "the plan walked is one target");
2152 assert_eq!(
2153 progress.remaining(),
2154 Some(0),
2155 "and a finished sitting owes none"
2156 );
2157
2158 let (journal, settled) =
2159 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2160 assert_eq!(settled.settled_count(), 1, "the job recorded it settled");
2161 let (session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2162 .await
2163 .expect("the second sitting starts");
2164 let _report = task.join().await.expect("it finishes");
2165 assert_eq!(
2166 session.progress().remaining(),
2167 Some(0),
2168 "a resume walks the plan the first sitting numbered"
2169 );
2170
2171 std::fs::remove_dir_all(&root).ok();
2172 }
2173
2174 #[tokio::test]
2176 async fn a_sweep_counts_the_addresses_it_settles() {
2177 let cfg = ZondConfig {
2178 no_dns: true,
2179 ..ZondConfig::default()
2180 };
2181 let (session, task) = discover("127.0.0.1".parse().expect("an address"), &cfg)
2182 .await
2183 .expect("the sweep starts");
2184 let _report = task.await.expect("the sweep ran");
2185
2186 let progress = session.progress();
2187 assert_eq!(progress.planned(), Some(1));
2188 assert_eq!(progress.settled(), 1, "the one address answered");
2189 }
2190
2191 #[tokio::test]
2194 async fn dropping_the_task_stops_the_scan() {
2195 use crate::model::target::TargetSet;
2196
2197 let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
2198 .await
2199 .expect("a free port");
2200 let port = listener.local_addr().expect("its address").port();
2201 tokio::spawn(async move {
2203 let mut held = Vec::new();
2204 while let Ok(stream) = accept_from_this_process(&listener).await {
2205 held.push(stream);
2206 }
2207 });
2208
2209 let mut map = TargetMap::new();
2210 map.add_unit(TargetSet::new(
2211 "127.0.0.1".parse().expect("an address"),
2212 port.to_string().parse().expect("a port"),
2213 ));
2214 let cfg = ZondConfig {
2215 no_dns: true,
2216 service_detection: crate::config::ServiceDetection::Thorough,
2217 ..ZondConfig::default()
2218 };
2219 let (mut session, task) = scan(map, &cfg, Detections::embedded())
2220 .await
2221 .expect("the scan starts");
2222 drop(task);
2223
2224 assert_eq!(
2225 session.handle().stopped(),
2226 Some(handle::StopCause::Aborted),
2227 "the scan runs on with nobody to collect it"
2228 );
2229 while session.events().recv().await.is_some() {}
2230 }
2231
2232 #[tokio::test]
2236 async fn a_scan_stopped_before_its_ports_starts_no_later_pass() {
2237 use crate::model::target::TargetSet;
2238 use crate::scanner::session::ScanEvent;
2239
2240 let mut map = TargetMap::new();
2241 map.add_unit(TargetSet::new(
2242 "127.0.0.1".parse().expect("an address"),
2243 "1-16".parse().expect("ports"),
2244 ));
2245 let cfg = ZondConfig {
2246 no_dns: true,
2247 os_detection: crate::config::OsDetection::Active,
2248 traceroute: true,
2249 tls_enumeration: true,
2250 ..ZondConfig::default()
2251 };
2252
2253 let (mut session, task) = scan(map, &cfg, Detections::embedded())
2254 .await
2255 .expect("the scan starts");
2256 session.handle().abort();
2257 let _report = task.await.expect("the scan ran");
2258
2259 let mut stages = Vec::new();
2260 while let Some(event) = session.events().try_recv() {
2261 if let ScanEvent::StageChanged { stage } = event {
2262 stages.push(stage);
2263 }
2264 }
2265 assert!(
2266 stages
2267 .iter()
2268 .all(|stage| matches!(stage, Stage::Discovery | Stage::Ports | Stage::Finishing)),
2269 "a pass began after the stop: {stages:?}"
2270 );
2271 }
2272
2273 #[cfg(feature = "journal-format")]
2277 #[tokio::test]
2278 async fn a_resume_asking_what_its_job_did_not_is_refused_and_keeps_its_record() {
2279 use crate::journal::Journal;
2280 use crate::journal::manifest::{JobOptions, OptionChanged, Plan};
2281 use crate::journal::settle::{Outcome, Settlements};
2282 use crate::model::ip::set::IpSet;
2283
2284 let root = journal_root("option-changed");
2285 let addresses: IpSet = "192.0.2.1-192.0.2.4".parse().expect("addresses");
2286 let first = ZondConfig {
2287 traceroute: true,
2288 ..ZondConfig::default()
2289 };
2290 let plan = Plan::discovery(&addresses, &first.exclusions, false);
2291
2292 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2293 journal
2294 .record_options(JobOptions::of(&first))
2295 .expect("records");
2296 let settlements = Settlements::default();
2297 settlements.record(Outcome::Answered { position: 0 });
2298 journal.checkpoint(&settlements).expect("checkpoints");
2299 let directory = journal.directory().to_path_buf();
2300 journal.close().expect("closes");
2301
2302 let (journal, _) =
2303 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2304 let refused = discover_with_journal(addresses, &ZondConfig::default(), journal).await;
2305 assert!(
2306 matches!(
2307 refused,
2308 Err(ScanError::OptionChanged(OptionChanged {
2309 option: "traceroute"
2310 }))
2311 ),
2312 "{:?}",
2313 refused.err()
2314 );
2315 assert!(directory.join("manifest.json").exists(), "the record went");
2316
2317 std::fs::remove_dir_all(&root).ok();
2318 }
2319
2320 #[cfg(feature = "journal-format")]
2323 #[tokio::test]
2324 async fn a_job_recorded_without_options_resumes_under_its_manifests_technique() {
2325 use crate::journal::Journal;
2326 use crate::journal::manifest::Plan;
2327 use crate::model::ip::set::IpSet;
2328 use crate::model::target::TargetSet;
2329 use crate::model::technique::TcpScanTechnique;
2330
2331 let root = journal_root("recorded-technique");
2332 let mut map = TargetMap::new();
2333 map.add_unit(TargetSet::new(
2334 "127.0.0.1".parse::<IpSet>().expect("an address"),
2335 "9".parse().expect("ports"),
2336 ));
2337 let cfg = ZondConfig {
2338 no_dns: true,
2339 assume_up: true,
2340 ..ZondConfig::default()
2341 };
2342 assert_ne!(cfg.tcp_technique, TcpScanTechnique::Ack, "test premise");
2343
2344 let plan = Plan::port_scan(&map, &cfg.exclusions, TcpScanTechnique::Ack);
2345 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2346 let directory = journal.directory().to_path_buf();
2347 journal.close().expect("closes");
2348 let (journal, _) =
2349 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2350 assert!(journal.options().is_none(), "test premise: no options");
2351
2352 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2353 .await
2354 .expect("the sitting starts");
2355 let report = task.join().await.expect("it finishes");
2356
2357 let ports = report
2358 .phases()
2359 .iter()
2360 .find(|phase| phase.kind() == ScanKind::PortScan)
2361 .expect("a port phase");
2362 assert_eq!(ports.settings().tcp_technique, TcpScanTechnique::Ack);
2363
2364 std::fs::remove_dir_all(&root).ok();
2365 }
2366
2367 #[cfg(feature = "journal-format")]
2370 #[tokio::test]
2371 async fn a_watch_records_no_options_to_hold_a_later_sitting_to() {
2372 use crate::journal::Journal;
2373 use crate::journal::manifest::Plan;
2374 use crate::model::ip::scoped::Zone;
2375
2376 let root = journal_root("watch-options");
2377 let links = vec![Zone::new(u32::MAX, "zond-no-such-link")];
2380 let plan = Plan::listen(links.clone());
2381 let scope =
2382 || ListenScope::on(links.clone()).for_at_most(std::time::Duration::from_millis(1));
2383
2384 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2385 let directory = journal.directory().to_path_buf();
2386 let (_session, task) = listen_with_journal(scope(), &ZondConfig::default(), journal)
2387 .await
2388 .expect("the watch starts");
2389 let _ = task.join().await.expect("it ends");
2390 assert!(
2391 !directory.join("options.json").exists(),
2392 "a watch recorded options"
2393 );
2394
2395 let (journal, _) =
2396 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2397 let other = ZondConfig {
2398 traceroute: true,
2399 tcp_technique: crate::model::technique::TcpScanTechnique::Fin,
2400 ..ZondConfig::default()
2401 };
2402 let (_session, task) = listen_with_journal(scope(), &other, journal)
2403 .await
2404 .expect("a watch resumed under other settings continues");
2405 let _ = task.join().await.expect("it ends");
2406
2407 std::fs::remove_dir_all(&root).ok();
2408 }
2409
2410 #[cfg(feature = "journal-format")]
2416 #[tokio::test]
2417 async fn a_sweeps_journal_is_refused_to_a_port_scan() {
2418 use crate::journal::Journal;
2419 use crate::journal::manifest::Plan;
2420 use crate::model::ip::set::IpSet;
2421 use crate::model::target::TargetSet;
2422
2423 let root = journal_root("other-phase");
2424 let addresses: IpSet = "127.0.0.1".parse().expect("an address");
2425 let mut map = TargetMap::new();
2426 map.add_unit(TargetSet::new(
2427 addresses.clone(),
2428 "9".parse().expect("ports"),
2429 ));
2430 let cfg = ZondConfig::default();
2431
2432 let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
2433 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2434 let refused = scan_with_journal(map, &cfg, Detections::embedded(), journal).await;
2435 assert!(
2436 matches!(refused, Err(ScanError::WrongPhase)),
2437 "{:?}",
2438 refused.err()
2439 );
2440
2441 std::fs::remove_dir_all(&root).ok();
2442 }
2443
2444 #[cfg(feature = "journal-format")]
2452 #[tokio::test]
2453 async fn a_resumed_liveness_pass_counts_what_the_policy_leaves() {
2454 use crate::journal::Journal;
2455 use crate::journal::manifest::Plan;
2456 use crate::journal::settle::{Outcome, Settlements};
2457 use crate::model::exclusion::Exclusions;
2458 use crate::model::target::TargetSet;
2459
2460 let mut map = TargetMap::new();
2461 map.add_unit(TargetSet::new(
2462 "127.0.0.1-127.0.0.4".parse().expect("addresses"),
2463 "1-100".parse().expect("ports"),
2465 ));
2466 let cfg = ZondConfig {
2467 no_dns: true,
2468 scan_timeout: Some(std::time::Duration::from_secs(1)),
2471 exclusions: Exclusions::new("127.0.0.1".parse().expect("an address")),
2472 ..ZondConfig::default()
2473 };
2474 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2475
2476 let root = journal_root("liveness-numbering");
2477 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2478 let settlements = Settlements::default();
2481 for position in 0..200 {
2482 settlements.record(Outcome::Answered { position });
2483 }
2484 journal.checkpoint(&settlements).expect("checkpoints");
2485 let directory = journal.directory().to_path_buf();
2486 journal.close().expect("closes");
2487
2488 let (journal, _) =
2489 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2490 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2491 .await
2492 .expect("the sitting starts");
2493 let report = task.join().await.expect("the sitting ends");
2494
2495 let liveness = report
2496 .phases()
2497 .iter()
2498 .find(|phase| phase.kind() == ScanKind::Discovery)
2499 .expect("a liveness pass ran");
2500 assert_eq!(
2501 liveness.targets().addresses(),
2502 1,
2503 "{:?}",
2504 liveness.targets().ranges()
2505 );
2506 assert_eq!(liveness.targets().withheld(), 1, "the policy's cost went");
2507 std::fs::remove_dir_all(&root).ok();
2508 }
2509
2510 #[cfg(feature = "journal-format")]
2516 #[tokio::test]
2517 async fn a_sitting_killed_after_a_checkpoint_leaves_its_hosts_owed() {
2518 use crate::journal::Journal;
2519 use crate::journal::manifest::Plan;
2520 use crate::model::exclusion::Exclusions;
2521 use crate::model::host::HostStatus;
2522 use crate::model::ip::set::IpSet;
2523 use crate::model::target::TargetSet;
2524 use crate::scanner::checkpoint::spawn_checkpoints;
2525
2526 let address: std::net::IpAddr = "127.0.0.1".parse().expect("an address");
2527 let mut map = TargetMap::new();
2528 map.add_unit(TargetSet::new(
2529 IpSet::from(address),
2530 "80".parse().expect("ports"),
2531 ));
2532 let cfg = ZondConfig::default();
2533 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2534 let root = journal_root("killed-owed");
2535 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2536 let directory = journal.directory().to_path_buf();
2537
2538 let (_session, ctx) = ScanSession::new();
2541 let mut scope = IpSet::from(address);
2542 let _open = PhaseRecorder::start(
2543 ScanKind::PortScan,
2544 Privilege::current(),
2545 TargetScope::from_ip_set(&mut scope, &Exclusions::none()),
2546 &cfg,
2547 )
2548 .opening_in(&ctx);
2549 ctx.update_host(address, |host| host.set_status(HostStatus::Up));
2550 let mut ticker = spawn_checkpoints(journal, ctx.progress());
2551 ticker.checkpointed().await;
2552 ticker.kill().await;
2553
2554 let (journal, _) =
2555 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2556 assert!(
2557 journal
2558 .earlier_phases()
2559 .iter()
2560 .any(|phase| phase.stopped().is_none()),
2561 "the killed sitting's standing phase is read back"
2562 );
2563 let finished = journal.finished_hosts().expect("reads");
2564 let (_resumed, resumed) = ScanSession::builder()
2565 .finished(finished.clone(), IpSet::new())
2566 .build();
2567 resumed.restore_hosts(journal.restored());
2568 let owed = resumed
2569 .read_host(address, |host| resumed.owes_passes(host))
2570 .expect("the host came back");
2571 assert!(
2572 owed,
2573 "a killed sitting's host was taken as finished: {finished:?}"
2574 );
2575
2576 journal.close().expect("closes");
2577 std::fs::remove_dir_all(&root).ok();
2578 }
2579
2580 #[cfg(feature = "journal-format")]
2584 #[tokio::test]
2585 async fn only_a_sitting_that_ran_to_its_end_records_its_hosts_finished() {
2586 use crate::journal::Journal;
2587 use crate::journal::manifest::Plan;
2588 use crate::model::target::TargetSet;
2589
2590 let mut map = TargetMap::new();
2591 map.add_unit(TargetSet::new(
2592 "127.0.0.1".parse().expect("an address"),
2593 "9".parse().expect("ports"),
2594 ));
2595 let cfg = ZondConfig {
2596 no_dns: true,
2597 assume_up: true,
2598 ..ZondConfig::default()
2599 };
2600 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2601
2602 for stopped in [false, true] {
2603 let root = journal_root(&format!("records-finished-{stopped}"));
2604 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2605 let directory = journal.directory().to_path_buf();
2606 let (session, task) =
2607 scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2608 .await
2609 .expect("the sitting starts");
2610 if stopped {
2611 session.handle().abort();
2612 }
2613 let report = task.join().await.expect("the sitting ends");
2614 assert!(report.host_count() > 0 || stopped, "the host was not found");
2615
2616 let (journal, _) =
2617 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2618 let finished = journal.finished_hosts().expect("reads");
2619 assert_eq!(
2620 finished.contains("127.0.0.1"),
2621 !stopped,
2622 "stopped: {stopped}, finished: {finished:?}"
2623 );
2624 drop(journal);
2625 std::fs::remove_dir_all(&root).ok();
2626 }
2627 }
2628
2629 #[cfg(feature = "journal-format")]
2634 #[tokio::test]
2635 async fn a_resumed_job_asks_a_host_a_sitting_finished_nothing_it_already_asked() {
2636 use crate::journal::Journal;
2637 use crate::journal::manifest::Plan;
2638 use crate::journal::settle::{Outcome, Settlements};
2639 use crate::model::host::{Host, HostStatus};
2640 use crate::model::port::{Port, PortState, Protocol, Service};
2641 use crate::model::target::TargetSet;
2642
2643 let mut map = TargetMap::new();
2644 map.add_unit(TargetSet::new(
2645 "127.0.0.1".parse().expect("an address"),
2646 "80".parse().expect("ports"),
2647 ));
2648 let cfg = ZondConfig {
2649 no_dns: true,
2650 ..ZondConfig::default()
2651 };
2652 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2653
2654 let resumed = |finished: bool| {
2657 let (root, map, cfg, plan) = (
2658 journal_root(&format!("finished-{finished}")),
2659 map.clone(),
2660 cfg.clone(),
2661 plan.clone(),
2662 );
2663 async move {
2664 let mut journal =
2665 Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2666 let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2667 host.set_status(HostStatus::Up);
2668 host.add_port(
2669 Port::new(80, Protocol::Tcp, PortState::Open)
2670 .with_service(Service::new("http", 100)),
2671 );
2672 journal.record_hosts(&[host]).expect("records the host");
2673 let settlements = Settlements::default();
2674 settlements.record(Outcome::Answered { position: 0 });
2675 journal.checkpoint(&settlements).expect("checkpoints");
2676 if finished {
2677 journal
2678 .record_finished(["127.0.0.1".to_string()])
2679 .expect("records the sitting's end");
2680 }
2681 let directory = journal.directory().to_path_buf();
2682 journal.close().expect("closes");
2683
2684 let written = |directory: &std::path::Path| {
2685 std::fs::metadata(directory.join("hosts.jsonl")).map_or(0, |file| file.len())
2686 };
2687 let before = written(&directory);
2688 let (journal, _) =
2689 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2690 let (_session, task) =
2691 scan_with_journal(map, &cfg, Detections::embedded(), journal)
2692 .await
2693 .expect("the sitting starts");
2694 let _report = task.join().await.expect("the sitting ends");
2695
2696 let runs = crate::journal::store::read_detections(&directory).expect("reads");
2697 let rewritten = written(&directory) > before;
2698 std::fs::remove_dir_all(&root).ok();
2699 (runs.len(), rewritten)
2700 }
2701 };
2702
2703 let (runs, _) = resumed(false).await;
2704 assert!(
2705 runs > 0,
2706 "a host no sitting finished is owed its detections"
2707 );
2708 let (runs, rewritten) = resumed(true).await;
2709 assert_eq!(runs, 0, "a finished host was asked its detections again");
2710 assert!(!rewritten, "a finished host was written down again");
2711 }
2712
2713 #[cfg(feature = "journal-format")]
2720 #[tokio::test]
2721 async fn a_resumed_sitting_reports_each_recorded_round_trip_once() {
2722 use crate::journal::Journal;
2723 use crate::journal::manifest::Plan;
2724 use crate::journal::settle::{Outcome, Settlements};
2725 use crate::model::host::{Host, HostStatus};
2726 use crate::model::target::TargetSet;
2727 use std::time::Duration;
2728
2729 let mut map = TargetMap::new();
2732 map.add_unit(TargetSet::new(
2733 "127.0.0.1".parse().expect("an address"),
2734 "20000-20015".parse().expect("ports"),
2735 ));
2736 let cfg = ZondConfig {
2737 no_dns: true,
2738 ..ZondConfig::default()
2739 };
2740 assert!(liveness_earns_its_place(&cfg, &map), "the pass runs");
2741 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2742
2743 let root = journal_root("round-trips-once");
2746 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2747 let recorded: Vec<Duration> = (91..=96).map(Duration::from_millis).collect();
2748 let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2749 host.set_status(HostStatus::Up);
2750 host.add_rtts(recorded.iter().copied());
2751 journal.record_hosts(&[host]).expect("records the host");
2752 let settlements = Settlements::default();
2753 for position in 0..16 {
2754 settlements.record(Outcome::Answered { position });
2755 }
2756 journal.checkpoint(&settlements).expect("checkpoints");
2757 journal
2758 .record_finished(["127.0.0.1".to_string()])
2759 .expect("records the sitting's end");
2760 let directory = journal.directory().to_path_buf();
2761 journal.close().expect("closes");
2762
2763 let (journal, _) =
2764 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2765 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2766 .await
2767 .expect("the sitting starts");
2768 let report = task.join().await.expect("the sitting ends");
2769 std::fs::remove_dir_all(&root).ok();
2770
2771 let [host] = report.hosts().collect::<Vec<_>>()[..] else {
2772 panic!("one host reported");
2773 };
2774 let held: Vec<Duration> = host
2775 .telemetry()
2776 .history()
2777 .iter()
2778 .map(|sample| sample.rtt)
2779 .collect();
2780 for rtt in &recorded {
2781 assert_eq!(
2782 held.iter().filter(|held| *held == rtt).count(),
2783 1,
2784 "{rtt:?} is reported other than once: {held:?}"
2785 );
2786 }
2787 }
2788
2789 #[cfg(feature = "journal-format")]
2798 #[tokio::test]
2799 async fn a_resume_draws_the_detections_a_killed_sitting_owed_a_port_it_settled() {
2800 use crate::journal::Journal;
2801 use crate::journal::manifest::Plan;
2802 use crate::journal::settle::{Outcome, Settlements};
2803 use crate::model::host::{Host, HostStatus};
2804 use crate::model::port::{Port, PortState, Protocol, Service};
2805 use crate::model::target::TargetSet;
2806 use crate::testing::loopback::accept_from_this_process;
2807 use tokio::io::{AsyncReadExt, AsyncWriteExt};
2808
2809 let web_server = || async {
2812 let listener = tokio::net::TcpListener::bind("127.0.0.1:0")
2813 .await
2814 .expect("binds loopback");
2815 let addr = listener.local_addr().expect("a local address");
2816 tokio::spawn(async move {
2817 while let Ok(mut sock) = accept_from_this_process(&listener).await {
2818 tokio::spawn(async move {
2819 let mut buffer = [0u8; 1024];
2820 if !matches!(sock.read(&mut buffer).await, Ok(n) if n > 0) {
2821 return;
2822 }
2823 let _ = sock
2824 .write_all(
2825 b"HTTP/1.1 200 OK\r\nServer: nginx/1.24.0\r\n\
2826 Content-Type: text/html\r\nContent-Length: 0\r\n\
2827 Connection: close\r\n\r\n",
2828 )
2829 .await;
2830 });
2831 }
2832 });
2833 addr
2834 };
2835 let addr = web_server().await;
2836 let unreached = web_server().await.port();
2839 let mut map = TargetMap::new();
2840 map.add_unit(TargetSet::new(
2841 addr.ip().into(),
2842 format!("{},{unreached}", addr.port())
2843 .parse()
2844 .expect("ports"),
2845 ));
2846 let cfg = ZondConfig {
2847 no_dns: true,
2848 ..ZondConfig::default()
2849 };
2850 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
2851 let settled = map
2852 .iter()
2853 .position(|target| target.port == addr.port())
2854 .expect("the server's port is planned") as u64;
2855 let findings = |report: &ScanReport| {
2856 report
2857 .hosts()
2858 .flat_map(Host::ports)
2859 .flat_map(Port::findings)
2860 .count()
2861 };
2862
2863 let root = journal_root("owed-detections-whole");
2864 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2865 let (_session, task) =
2866 scan_with_journal(map.clone(), &cfg, Detections::embedded(), journal)
2867 .await
2868 .expect("the sitting starts");
2869 let whole = findings(&task.join().await.expect("the sitting ends"));
2870 std::fs::remove_dir_all(&root).ok();
2871 assert!(whole > 0, "the server draws no finding to lose");
2872
2873 let root = journal_root("owed-detections-killed");
2875 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2876 let mut host = Host::new(addr.ip());
2877 host.set_status(HostStatus::Up);
2878 host.add_port(
2879 Port::new(addr.port(), Protocol::Tcp, PortState::Open)
2880 .with_service(Service::new("http", 90)),
2881 );
2882 journal.record_hosts(&[host]).expect("records the host");
2883 let settlements = Settlements::default();
2884 settlements.record(Outcome::Answered { position: settled });
2885 journal.checkpoint(&settlements).expect("checkpoints");
2886 let directory = journal.directory().to_path_buf();
2887 journal.close().expect("closes");
2888
2889 let (journal, _) =
2890 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2891 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2892 .await
2893 .expect("the sitting starts");
2894 let resumed = findings(&task.join().await.expect("the sitting ends"));
2895 std::fs::remove_dir_all(&root).ok();
2896 assert_eq!(
2897 resumed, whole,
2898 "the resume drew other findings than one sitting"
2899 );
2900 }
2901
2902 #[cfg(feature = "journal-format")]
2910 #[tokio::test]
2911 async fn a_resume_excluding_another_port_sends_it_nothing_and_keeps_the_numbering() {
2912 use crate::journal::Journal;
2913 use crate::journal::manifest::{JobOptions, Plan};
2914 use crate::journal::settle::{Outcome, Settlements};
2915 use crate::model::host::{Host, HostStatus};
2916 use crate::model::port::{Port, PortSet, PortState, Protocol};
2917 use crate::model::target::TargetSet;
2918 use crate::testing::loopback::SilentPort;
2919
2920 let (first, second) = (SilentPort::open(), SilentPort::open());
2921 let (excluded, settled) = if first.addr().port() < second.addr().port() {
2924 (first, second)
2925 } else {
2926 (second, first)
2927 };
2928 let mut map = TargetMap::new();
2929 map.add_unit(TargetSet::new(
2930 "127.0.0.1".parse().expect("an address"),
2931 format!("{},{}", excluded.addr().port(), settled.addr().port())
2932 .parse()
2933 .expect("ports"),
2934 ));
2935 let recorded = ZondConfig {
2936 no_dns: true,
2937 assume_up: true,
2938 ..ZondConfig::default()
2939 };
2940 let plan = Plan::port_scan(&map, &recorded.exclusions, recorded.tcp_technique);
2941
2942 let root = journal_root("added-exclusion");
2943 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
2944 journal
2945 .record_options(JobOptions::of(&recorded))
2946 .expect("records the options");
2947 let mut host = Host::new("127.0.0.1".parse().expect("an address"));
2949 host.set_status(HostStatus::Up);
2950 host.add_port(Port::new(
2951 excluded.addr().port(),
2952 Protocol::Tcp,
2953 PortState::Open,
2954 ));
2955 journal.record_hosts(&[host]).expect("records the host");
2956 let settlements = Settlements::default();
2957 settlements.record(Outcome::Answered { position: 1 });
2958 journal.checkpoint(&settlements).expect("checkpoints");
2959 let directory = journal.directory().to_path_buf();
2960 journal.close().expect("closes");
2961
2962 let mut cfg = recorded.clone();
2963 cfg.excluded_ports =
2964 PortSet::try_from(excluded.addr().port().to_string().as_str()).expect("a port");
2965 let (journal, _) =
2966 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
2967 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
2968 .await
2969 .expect("a sitting excluding more is continued");
2970 let report = task.join().await.expect("the sitting ends");
2971 std::fs::remove_dir_all(&root).ok();
2972
2973 assert_eq!(
2974 crate::transport::dial::dialled::to(excluded.addr()),
2975 0,
2976 "the excluded port was asked"
2977 );
2978 assert_eq!(
2979 crate::transport::dial::dialled::to(settled.addr()),
2980 0,
2981 "a settled target was asked again"
2982 );
2983 assert!(
2984 report
2985 .hosts()
2986 .flat_map(Host::ports)
2987 .all(|port| port.number() != excluded.addr().port()),
2988 "the excluded port is still reported"
2989 );
2990 assert!(
2991 report
2992 .phases()
2993 .last()
2994 .expect("the sitting's phase")
2995 .settings()
2996 .excluded_ports
2997 .contains(excluded.addr().port(), Protocol::Tcp),
2998 "the report does not say the port was excluded"
2999 );
3000 }
3001
3002 #[cfg(feature = "journal-format")]
3008 #[tokio::test]
3009 async fn a_job_excluding_a_port_is_complete_once_it_has_asked_the_rest() {
3010 use crate::journal::Journal;
3011 use crate::journal::manifest::Plan;
3012 use crate::model::port::PortSet;
3013 use crate::model::target::TargetSet;
3014 use crate::testing::loopback::SilentPort;
3015
3016 let (excluded, asked) = (SilentPort::open(), SilentPort::open());
3017 let mut map = TargetMap::new();
3018 map.add_unit(TargetSet::new(
3019 "127.0.0.1".parse().expect("an address"),
3020 format!("{},{}", excluded.addr().port(), asked.addr().port())
3021 .parse()
3022 .expect("ports"),
3023 ));
3024 let cfg = ZondConfig {
3025 no_dns: true,
3026 assume_up: true,
3027 excluded_ports: PortSet::try_from(excluded.addr().port().to_string().as_str())
3028 .expect("a port"),
3029 ..ZondConfig::default()
3030 };
3031 let plan = Plan::port_scan(&map, &cfg.exclusions, cfg.tcp_technique);
3032
3033 let root = journal_root("excluded-complete");
3034 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3035 let (_session, task) = scan_with_journal(map, &cfg, Detections::embedded(), journal)
3036 .await
3037 .expect("the sitting starts");
3038 let _report = task.join().await.expect("the sitting ends");
3039 let listed = crate::journal::store::list(&root).expect("lists").entries;
3040 std::fs::remove_dir_all(&root).ok();
3041
3042 assert_eq!(
3043 crate::transport::dial::dialled::to(excluded.addr()),
3044 0,
3045 "the excluded port was asked"
3046 );
3047 let [entry] = listed.as_slice() else {
3048 panic!("one job on record: {listed:?}");
3049 };
3050 assert_eq!(
3051 (entry.settled(), entry.manifest.total_targets),
3052 (Some(1), 1),
3053 "settled against the total"
3054 );
3055 assert!(entry.is_complete(), "the finished job reads as unfinished");
3056 }
3057
3058 #[cfg(feature = "journal-format")]
3066 #[tokio::test]
3067 async fn a_resumed_sweep_with_nothing_left_passes_nothing_over_what_it_finished() {
3068 use crate::journal::Journal;
3069 use crate::journal::manifest::Plan;
3070 use crate::model::ip::set::IpSet;
3071
3072 let addresses: IpSet = "127.0.0.1".parse().expect("an address");
3073 let cfg = ZondConfig {
3074 no_dns: true,
3075 traceroute: true,
3076 ..ZondConfig::default()
3077 };
3078 let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
3079 let root = journal_root("finished-sweep");
3080 let journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3081 let directory = journal.directory().to_path_buf();
3082 let (_session, task) = discover_with_journal(addresses.clone(), &cfg, journal)
3083 .await
3084 .expect("the sitting starts");
3085 let first = task.join().await.expect("the sitting ends");
3086 assert!(first.host_count() > 0, "loopback was not found");
3087
3088 let written =
3089 || std::fs::metadata(directory.join("hosts.jsonl")).map_or(0, |file| file.len());
3090 let before = written();
3091 let (journal, _) =
3092 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
3093 let (_session, task) = discover_with_journal(addresses, &cfg, journal)
3094 .await
3095 .expect("the sitting starts");
3096 let resumed = task.join().await.expect("the sitting ends");
3097 let after = written();
3098 std::fs::remove_dir_all(&root).ok();
3099
3100 let traced = resumed
3103 .phases()
3104 .last()
3105 .expect("the sitting's phase")
3106 .refusals()
3107 .iter()
3108 .any(|refusal| refusal.reason().contains("route trace"));
3109 assert!(!traced, "the finished host was owed its route trace");
3110 assert_eq!(after, before, "the finished host was written down again");
3111 }
3112
3113 #[cfg(feature = "journal-format")]
3121 #[tokio::test]
3122 async fn a_port_scan_handed_a_journal_of_another_plan_is_refused() {
3123 use crate::journal::Journal;
3124 use crate::journal::manifest::Plan;
3125 use crate::model::target::TargetSet;
3126
3127 let root = journal_root("other-plan");
3128 let map = |ports: &str| {
3129 let mut map = TargetMap::new();
3130 map.add_unit(TargetSet::new(
3131 "127.0.0.1".parse().expect("an address"),
3132 ports.parse().expect("ports"),
3133 ));
3134 map
3135 };
3136 let cfg = ZondConfig::default();
3137 let recorded = Plan::port_scan(&map("1-100"), &cfg.exclusions, cfg.tcp_technique);
3138
3139 let journal = Journal::create(&root, &recorded, Privilege::current(), "").expect("creates");
3140 let refused = scan_with_journal(map("1000-1100"), &cfg, Detections::embedded(), journal)
3141 .await
3142 .err();
3143 assert!(
3144 matches!(refused, Some(ScanError::PlanChanged(_))),
3145 "{refused:?}"
3146 );
3147
3148 let other = Privilege::from_raw(!Privilege::current().is_raw());
3149 let journal = Journal::create(&root, &recorded, other, "").expect("creates");
3150 let refused = scan_with_journal(map("1-100"), &cfg, Detections::embedded(), journal)
3151 .await
3152 .err();
3153 assert!(
3154 matches!(refused, Some(ScanError::PlanChanged(_))),
3155 "{refused:?}"
3156 );
3157
3158 std::fs::remove_dir_all(&root).ok();
3159 }
3160
3161 #[cfg(feature = "journal-format")]
3163 #[tokio::test]
3164 async fn a_refused_resume_keeps_the_record_of_the_sitting_before_it() {
3165 use crate::journal::Journal;
3166 use crate::journal::manifest::Plan;
3167 use crate::journal::settle::{Outcome, Settlements};
3168 use crate::model::ip::set::IpSet;
3169
3170 let root = journal_root("refused-resume");
3171 let addresses: IpSet = "192.0.2.1-192.0.2.4".parse().expect("addresses");
3172 let cfg = refused_up_front();
3173 let plan = Plan::discovery(&addresses, &cfg.exclusions, false);
3174
3175 let mut journal = Journal::create(&root, &plan, Privilege::current(), "").expect("creates");
3176 let settlements = Settlements::default();
3177 settlements.record(Outcome::Answered { position: 0 });
3178 journal.checkpoint(&settlements).expect("checkpoints");
3179 let directory = journal.directory().to_path_buf();
3180 journal.close().expect("closes");
3181
3182 let (journal, _) =
3183 Journal::resume(&directory, &plan, Privilege::current()).expect("resumes");
3184 let refused = discover_with_journal(addresses, &cfg, journal).await;
3185 assert!(
3186 matches!(refused, Err(ScanError::Evasion(_))),
3187 "{:?}",
3188 refused.err()
3189 );
3190 assert!(directory.join("manifest.json").exists(), "the record went");
3191
3192 std::fs::remove_dir_all(&root).ok();
3193 }
3194
3195 #[test]
3199 fn a_listener_is_recorded_unprivileged_only_where_privilege_refused_it() {
3200 use crate::scanner::strategy::StrategyError;
3201 use crate::transport::capture::{CaptureError, LibraryError};
3202
3203 let denied = |link: &str| CaptureError::Denied {
3204 interface: link.into(),
3205 source: LibraryError::new(pcap::Error::PcapError("permission denied".into())),
3206 };
3207 let filter = CaptureError::Filter {
3208 filter: "ip6 and ether proto 0x86dd".into(),
3209 source: LibraryError::new(pcap::Error::PcapError("not an ethernet link".into())),
3210 };
3211 let refused = |refused| StrategyError::Capture(CaptureError::NoInterface { refused });
3212
3213 assert_eq!(
3214 listening_privilege(Some(&refused(vec![("en0".into(), denied("en0"))]))),
3215 Privilege::Connect,
3216 "the platform refused this process"
3217 );
3218 assert_eq!(
3219 listening_privilege(Some(&refused(vec![("utun4".into(), filter)]))),
3220 Privilege::Raw,
3221 "the link refused the filter, after the platform let it open"
3222 );
3223 assert_eq!(listening_privilege(None), Privilege::Raw, "it listened");
3224 assert_eq!(
3225 listening_privilege(Some(&refused(Vec::new()))),
3226 Privilege::current(),
3227 "no link was tried, so the process's own answer is all there is"
3228 );
3229 }
3230
3231 #[tokio::test]
3233 async fn a_panicking_scan_reports_what_the_panic_said() {
3234 for spawned in [
3235 tokio::spawn(async { panic!("a literal message") }),
3236 tokio::spawn(async { panic!("a formatted {}", "message") }),
3237 ] {
3238 let error = panic_or_cancellation(spawned.await.expect_err("the task panicked"));
3239
3240 let ScanError::TaskFailed { panicked, detail } = error else {
3241 unreachable!("a panic is a TaskFailed")
3242 };
3243 assert!(panicked);
3244 assert!(detail.contains("message"), "the payload was lost: {detail}");
3245 }
3246 }
3247
3248 #[tokio::test]
3250 async fn a_cancelled_scan_is_not_reported_as_a_panic() {
3251 let spawned = tokio::spawn(std::future::pending::<()>());
3252 spawned.abort();
3253
3254 let error = panic_or_cancellation(spawned.await.expect_err("the task was cancelled"));
3255
3256 let ScanError::TaskFailed { panicked, .. } = error else {
3257 unreachable!("a cancellation is a TaskFailed")
3258 };
3259 assert!(!panicked);
3260 }
3261
3262 #[test]
3268 fn an_idle_scans_declined_passes_are_filed_once_each_in_a_short_line() {
3269 use crate::config::{DetectionEnvelope, OsDetection};
3270 use crate::model::finding::DetectionClass;
3271
3272 let cfg = ZondConfig {
3273 idle_scan: Some(crate::config::IdleScan::new(
3274 "192.0.2.9".parse().expect("an address"),
3275 )),
3276 os_detection: OsDetection::Active,
3277 traceroute: true,
3278 characterise: true,
3279 tls_enumeration: true,
3280 ip_protocols: [47].into_iter().collect(),
3281 detection: DetectionEnvelope::up_to(DetectionClass::ActiveBenign),
3282 ..ZondConfig::default()
3283 };
3284 let (_session, ctx) = ScanSession::new();
3285
3286 let said = crate::logging::logged(|| record_idle_refusals(&cfg, &ctx));
3287
3288 let refusals = ctx.take_refusals();
3289 assert_eq!(refusals.len(), 6, "{refusals:?}");
3290 for refusal in &refusals {
3291 let line = format!("not covered: {}", refusal.reason());
3292 assert!(line.len() <= 64, "{} characters: {line}", line.len());
3293 }
3294 assert!(
3295 said.iter()
3296 .all(|line| !line.message.contains("not covered")),
3297 "a refusal was said on filing as well as in the report: {said:?}"
3298 );
3299 }
3300}