1use std::collections::BTreeSet;
96use std::net::IpAddr;
97
98use serde::Deserialize;
99
100use crate::config::envelope::DetectionEnvelope;
101use crate::config::{IdleScan, OsDetection, ServiceDetection, ZondConfig};
102use crate::evasion::EvasionProfile;
103use crate::import::settings::{Settings, de_named};
104use crate::model::exclusion::Exclusions;
105use crate::model::ip::set::IpSet;
106use crate::model::mac::MacAddr;
107use crate::model::parse::target::TargetParseError;
108use crate::model::port::PortSet;
109use crate::resolve::{self, DiscoveryTargets, PortScanTargets, Resolver};
110
111#[non_exhaustive]
113#[derive(Debug, thiserror::Error)]
114pub enum RequestError {
115 #[error("{0}")]
117 Targets(#[from] TargetParseError),
118
119 #[error("ports = '{spec}': {reason}")]
121 Ports {
122 spec: String,
124 reason: String,
126 },
127
128 #[error("the request names no targets")]
130 NoTargets,
131}
132
133#[non_exhaustive]
144#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
145#[serde(default, deny_unknown_fields)]
146pub struct ScanRequest {
147 pub targets: Vec<String>,
152
153 pub exclude: Vec<String>,
162
163 pub ports: Option<String>,
169
170 pub settings: Settings,
175
176 pub assume_up: Option<bool>,
178
179 pub traceroute: Option<bool>,
181
182 pub characterise: Option<bool>,
185
186 pub icmp_evidence: Option<bool>,
189
190 pub ip_protocols: Option<BTreeSet<u8>>,
193
194 pub send_source: Option<Vec<IpAddr>>,
198
199 #[serde(deserialize_with = "de_named")]
202 pub os_detection: Option<OsDetection>,
203
204 #[serde(deserialize_with = "de_named")]
207 pub service_detection: Option<ServiceDetection>,
208
209 #[serde(deserialize_with = "de_named")]
211 pub detection: Option<DetectionEnvelope>,
212
213 #[serde(deserialize_with = "de_idle_scan")]
215 pub idle_scan: Option<IdleScan>,
216
217 #[serde(deserialize_with = "de_evasion")]
223 pub evasion: Option<EvasionProfile>,
224}
225
226impl ScanRequest {
227 pub fn new() -> Self {
229 Self::default()
230 }
231
232 pub fn ports(&self) -> Option<Result<PortSet, RequestError>> {
244 if let Some(spec) = self.ports.as_deref() {
245 return Some(
246 PortSet::parse_scan(spec).map_err(|error| RequestError::Ports {
247 spec: spec.to_string(),
248 reason: error.to_string(),
249 }),
250 );
251 }
252
253 self.settings.ports().map(|parsed| {
254 parsed.map_err(|error| RequestError::Ports {
255 spec: self.settings.default_ports.clone().unwrap_or_default(),
256 reason: error.to_string(),
257 })
258 })
259 }
260
261 pub fn apply_to(&self, config: &mut ZondConfig) {
270 self.settings.apply_to(config);
271
272 if let Some(value) = self.assume_up {
273 config.assume_up = value;
274 }
275 if let Some(value) = self.traceroute {
276 config.traceroute = value;
277 }
278 if let Some(value) = self.characterise {
279 config.characterise = value;
280 }
281 if let Some(value) = self.icmp_evidence {
282 config.icmp_evidence = value;
283 }
284 if let Some(protocols) = &self.ip_protocols {
285 config.ip_protocols = protocols.clone();
286 }
287 if let Some(sources) = &self.send_source {
288 config.send_source = sources.clone();
289 }
290 if let Some(value) = self.os_detection {
291 config.os_detection = value;
292 }
293 if let Some(value) = self.service_detection {
294 config.service_detection = value;
295 }
296 if let Some(value) = self.detection {
297 config.detection = value;
298 }
299 if self.idle_scan.is_some() {
300 config.idle_scan = self.idle_scan;
301 }
302 if let Some(profile) = &self.evasion {
303 config.evasion = profile.clone();
304 }
305 }
306
307 pub async fn resolve(&self, names: Option<&Resolver>) -> Result<Resolved, RequestError> {
319 if self.targets.is_empty() {
320 return Err(RequestError::NoTargets);
321 }
322
323 let (targets, plan) = resolve::for_request(&self.targets, names).await?;
324 let exclude = if self.exclude.is_empty() {
325 Exclusions::none()
326 } else {
327 resolve::for_exclusion(&self.exclude, names).await?
328 };
329 let ports = self.ports().transpose()?;
330
331 Ok(Resolved {
332 targets,
333 plan,
334 exclude,
335 ports,
336 })
337 }
338}
339
340#[non_exhaustive]
346#[derive(Debug, Clone)]
347pub struct Resolved {
348 targets: DiscoveryTargets,
349 plan: PortScanTargets,
352 exclude: Exclusions,
353 ports: Option<PortSet>,
354}
355
356impl Resolved {
357 pub fn ips(&self) -> &IpSet {
359 self.targets.ips()
360 }
361
362 pub fn into_ips(self) -> IpSet {
364 self.targets.into_ips()
365 }
366
367 pub fn ports(&self) -> Option<&PortSet> {
373 self.ports.as_ref()
374 }
375
376 pub fn port_scan(&self, default_ports: &PortSet) -> PortScanTargets {
383 self.plan
384 .with_unported_on(self.ports.as_ref().unwrap_or(default_ports))
385 }
386
387 pub fn exclusions(&self) -> &Exclusions {
389 &self.exclude
390 }
391
392 pub fn into_parts(self) -> (IpSet, Option<PortSet>) {
398 (self.targets.into_ips(), self.ports)
399 }
400
401 pub fn apply_to(&self, config: &mut ZondConfig) {
408 self.targets.apply_to(config);
409 self.plan.apply_to(config);
410 config.exclusions.extend(&self.exclude);
411 }
412}
413
414#[derive(Deserialize)]
420#[serde(deny_unknown_fields)]
421struct IdleScanDocument {
422 zombie: IpAddr,
423 #[serde(default)]
424 zombie_port: Option<u16>,
425}
426
427fn de_idle_scan<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<IdleScan>, D::Error> {
429 let Some(document) = Option::<IdleScanDocument>::deserialize(d)? else {
430 return Ok(None);
431 };
432
433 Ok(Some(IdleScan {
434 zombie: document.zombie,
435 zombie_port: document.zombie_port,
436 }))
437}
438
439#[derive(Default, Deserialize)]
441#[serde(default, deny_unknown_fields)]
442struct EvasionDocument {
443 source_port: Option<u16>,
444 ttl: Option<u8>,
445 padding: Option<u16>,
446 bad_tcp_checksum: bool,
447 #[serde(deserialize_with = "de_named")]
448 spoof_mac: Option<MacAddr>,
449 fragment: Option<u16>,
450 decoys: Vec<IpAddr>,
451 flags: Option<u8>,
454}
455
456fn de_evasion<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<EvasionProfile>, D::Error> {
458 let Some(document) = Option::<EvasionDocument>::deserialize(d)? else {
459 return Ok(None);
460 };
461
462 let profile = EvasionProfile {
463 source_port: document.source_port,
464 ttl: document.ttl,
465 padding: document.padding,
466 bad_tcp_checksum: document.bad_tcp_checksum,
467 spoof_mac: document.spoof_mac,
468 fragment: document.fragment,
469 decoys: document.decoys,
470 flags: document.flags,
471 };
472
473 profile.validate().map_err(serde::de::Error::custom)?;
474
475 Ok(Some(profile))
476}
477
478#[cfg(test)]
479mod tests {
480 use super::*;
481 use crate::config::ScanEffort;
482 use crate::model::finding::DetectionClass;
483 use crate::model::technique::TcpScanTechnique;
484
485 fn request(document: &str) -> ScanRequest {
487 toml::from_str(document).expect("the document is a request")
488 }
489
490 fn settled() -> ZondConfig {
493 ZondConfig {
494 assume_up: true,
495 traceroute: true,
496 characterise: true,
497 icmp_evidence: true,
498 os_detection: OsDetection::Aggressive,
499 service_detection: ServiceDetection::Thorough,
500 tcp_technique: TcpScanTechnique::Fin,
501 send_source: vec!["198.51.100.1".parse().expect("literal")],
502 ..Default::default()
503 }
504 }
505
506 #[test]
510 fn no_request_can_take_a_port_off_the_listen_only_list() {
511 for text in [
512 "listen_only_ports = []\n",
513 "probe_print_ports = true\n",
514 "[settings]\nlisten_only_ports = []\n",
515 ] {
516 let Ok(request) = toml::from_str::<ScanRequest>(text) else {
517 continue;
519 };
520 let mut config = ZondConfig::default();
521 request.apply_to(&mut config);
522
523 for port in crate::config::RAW_PRINT_PORTS {
524 assert!(
525 config.listen_only_ports.contains(port),
526 "{text:?} took {port} off the list"
527 );
528 }
529 }
530 }
531
532 #[test]
535 fn a_request_that_says_nothing_changes_no_setting() {
536 let mut config = settled();
537 ScanRequest::new().apply_to(&mut config);
538
539 assert!(config.assume_up);
540 assert!(config.traceroute);
541 assert!(config.characterise);
542 assert!(config.icmp_evidence);
543 assert_eq!(config.os_detection, OsDetection::Aggressive);
544 assert_eq!(config.service_detection, ServiceDetection::Thorough);
545 assert_eq!(config.tcp_technique, TcpScanTechnique::Fin);
546 assert_eq!(config.send_source, settled().send_source);
547 assert!(config.idle_scan.is_none());
548 assert!(!config.evasion.is_active());
549 }
550
551 #[test]
552 fn every_key_a_request_understands_reaches_the_configuration() {
553 let request = request(
554 r#"
555 targets = ["192.0.2.0/24"]
556 ports = "22,80"
557 assume_up = false
558 traceroute = false
559 characterise = false
560 icmp_evidence = false
561 ip_protocols = [1, 47, 50]
562 send_source = ["192.0.2.2"]
563 os_detection = "passive"
564 service_detection = "banner"
565 detection = "exploit"
566
567 [settings]
568 effort = "single"
569 tcp_technique = "syn"
570
571 [idle_scan]
572 zombie = "192.0.2.9"
573 zombie_port = 445
574
575 [evasion]
576 source_port = 53
577 ttl = 12
578 decoys = ["192.0.2.5"]
579 "#,
580 );
581
582 let mut config = settled();
583 request.apply_to(&mut config);
584
585 assert!(!config.assume_up);
586 assert!(!config.traceroute);
587 assert!(!config.characterise);
588 assert!(!config.icmp_evidence);
589 assert_eq!(config.ip_protocols, BTreeSet::from([1, 47, 50]));
590 assert_eq!(
591 config.send_source,
592 vec!["192.0.2.2".parse::<IpAddr>().expect("literal")]
593 );
594 assert_eq!(config.os_detection, OsDetection::Passive);
595 assert_eq!(config.service_detection, ServiceDetection::Banner);
596 assert_eq!(config.detection.ceiling(), Some(DetectionClass::Exploit));
597 assert_eq!(config.retry.effort, ScanEffort::Single);
598 assert_eq!(config.tcp_technique, TcpScanTechnique::Syn);
599
600 let idle = config.idle_scan.expect("the request named a zombie");
601 assert_eq!(idle.zombie, "192.0.2.9".parse::<IpAddr>().expect("literal"));
602 assert_eq!(idle.zombie_port, Some(445));
603
604 assert_eq!(config.evasion.source_port, Some(53));
605 assert_eq!(config.evasion.ttl, Some(12));
606 assert_eq!(config.evasion.decoys.len(), 1);
607
608 let ports = request
609 .ports()
610 .expect("the request named ports")
611 .expect("valid");
612 assert!(ports.has_tcp(22) && ports.has_tcp(80));
613 }
614
615 #[test]
618 fn a_misspelled_key_is_refused_rather_than_ignored() {
619 let error = toml::from_str::<ScanRequest>("traceroot = true\n")
620 .expect_err("a key nobody knows is not a request");
621
622 let message = error.to_string();
623 assert!(
624 message.contains("traceroot"),
625 "the error should name the key that was written: {message}"
626 );
627 assert!(
628 message.contains("traceroute"),
629 "the error should name the keys that would have worked: {message}"
630 );
631 }
632
633 #[test]
636 fn a_request_overrides_the_settings_a_file_had_already_applied() {
637 let mut config = ZondConfig::default();
638
639 let from_disk: Settings =
640 toml::from_str("effort = \"single\"\ntls_enumeration = false\n").expect("settings");
641 from_disk.apply_to(&mut config);
642
643 request("[settings]\neffort = \"thorough\"\n").apply_to(&mut config);
644
645 assert_eq!(config.retry.effort, ScanEffort::Thorough);
646 assert!(
647 !config.tls_enumeration,
648 "a key the request said nothing about keeps what the file set"
649 );
650 }
651
652 #[test]
655 fn an_evasion_table_the_engine_would_refuse_is_refused_as_it_is_read() {
656 let error = toml::from_str::<ScanRequest>("[evasion]\nfragment = 4\n")
657 .expect_err("an unfragmentable MTU is not a profile");
658
659 assert!(
660 error.to_string().contains("fragment"),
661 "the error should say which value was wrong: {error}"
662 );
663 }
664
665 #[test]
666 fn ports_fall_back_to_the_settings_table_when_the_request_names_none() {
667 let request = request("[settings]\ndefault_ports = \"443\"\n");
668 let ports = request
669 .ports()
670 .expect("the settings named ports")
671 .expect("valid");
672
673 assert!(ports.has_tcp(443));
674 assert_eq!(ports.len(), 1);
675 }
676
677 #[test]
678 fn a_port_specification_that_is_not_one_names_what_was_written() {
679 let request = request("ports = \"nope\"\n");
680 let error = request
681 .ports()
682 .expect("the request named ports")
683 .expect_err("'nope' is not a port specification");
684
685 assert!(matches!(&error, RequestError::Ports { spec, .. } if spec == "nope"));
686 }
687
688 #[test]
691 fn a_port_specification_naming_nothing_is_refused_rather_than_scanning_nothing() {
692 for document in [
693 "ports = \"\"\n",
694 "ports = \" , \"\n",
695 "[settings]\ndefault_ports = \"\"\n",
696 ] {
697 let error = request(document)
698 .ports()
699 .expect("the request named ports")
700 .expect_err("a specification naming nothing");
701 assert!(
702 error.to_string().contains("names no ports"),
703 "{document}: {error}"
704 );
705 }
706 }
707
708 #[tokio::test]
709 async fn resolving_adds_exclusions_to_what_the_configuration_already_forbids() {
710 let mut already = IpSet::new();
711 already.insert_range("198.51.100.0/24".parse().expect("a valid range"));
712
713 let mut config = ZondConfig {
714 exclusions: Exclusions::new(already),
715 ..Default::default()
716 };
717
718 let resolved = request("targets = [\"192.0.2.0/24\"]\nexclude = [\"192.0.2.7\"]\n")
719 .resolve(None)
720 .await
721 .expect("literal addresses resolve without a resolver");
722
723 resolved.apply_to(&mut config);
724
725 for excluded in ["198.51.100.1", "192.0.2.7"] {
726 assert!(
727 config
728 .exclusions
729 .excludes(&excluded.parse().expect("literal")),
730 "{excluded} was excluded by one of the two and must still be"
731 );
732 }
733 assert!(
734 !config
735 .exclusions
736 .excludes(&"192.0.2.8".parse().expect("literal"))
737 );
738 assert_eq!(resolved.ips().len(), 256);
739 }
740
741 #[tokio::test]
743 async fn a_port_written_on_a_target_is_the_port_it_is_scanned_on() {
744 let defaults = PortSet::try_from("22").expect("a specification");
745 let on = |plan: &PortScanTargets, address: &str| {
746 let address: IpAddr = address.parse().expect("literal");
747 plan.map()
748 .units
749 .iter()
750 .find(|unit| unit.ips().contains(&address))
751 .map(|unit| unit.ports().to_string())
752 };
753
754 let unported = request("targets = [\"192.0.2.1:8080\", \"192.0.2.2\"]\n")
755 .resolve(None)
756 .await
757 .expect("literal addresses resolve without a resolver");
758 let plan = unported.port_scan(&defaults);
759 assert_eq!(on(&plan, "192.0.2.1").as_deref(), Some("8080"));
760 assert_eq!(on(&plan, "192.0.2.2").as_deref(), Some("22"));
761 assert_eq!(unported.ips().len(), 2, "both reach the discovery sweep");
762
763 let ported = request("targets = [\"192.0.2.1:u:53\", \"192.0.2.2\"]\nports = \"443\"\n")
764 .resolve(None)
765 .await
766 .expect("resolves");
767 let plan = ported.port_scan(&defaults);
768 assert_eq!(on(&plan, "192.0.2.1").as_deref(), Some("u:53"));
769 assert_eq!(on(&plan, "192.0.2.2").as_deref(), Some("443"));
770 }
771
772 #[tokio::test]
773 async fn a_request_naming_no_targets_is_refused_rather_than_resolving_to_nothing() {
774 let error = ScanRequest::new()
775 .resolve(None)
776 .await
777 .expect_err("a request with no targets cannot be resolved");
778
779 assert!(matches!(error, RequestError::NoTargets));
780 }
781}