use std::collections::BTreeSet;
use std::net::IpAddr;
use serde::Deserialize;
use crate::config::envelope::DetectionEnvelope;
use crate::config::{IdleScan, OsDetection, ServiceDetection, ZondConfig};
use crate::evasion::EvasionProfile;
use crate::import::settings::{Settings, de_named};
use crate::model::exclusion::Exclusions;
use crate::model::ip::set::IpSet;
use crate::model::mac::MacAddr;
use crate::model::parse::target::TargetParseError;
use crate::model::port::PortSet;
use crate::resolve::{self, DiscoveryTargets, PortScanTargets, Resolver};
#[non_exhaustive]
#[derive(Debug, thiserror::Error)]
pub enum RequestError {
#[error("{0}")]
Targets(#[from] TargetParseError),
#[error("ports = '{spec}': {reason}")]
Ports {
spec: String,
reason: String,
},
#[error("the request names no targets")]
NoTargets,
}
#[non_exhaustive]
#[derive(Debug, Clone, Default, PartialEq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct ScanRequest {
pub targets: Vec<String>,
pub exclude: Vec<String>,
pub ports: Option<String>,
pub settings: Settings,
pub assume_up: Option<bool>,
pub traceroute: Option<bool>,
pub characterise: Option<bool>,
pub icmp_evidence: Option<bool>,
pub ip_protocols: Option<BTreeSet<u8>>,
pub send_source: Option<Vec<IpAddr>>,
#[serde(deserialize_with = "de_named")]
pub os_detection: Option<OsDetection>,
#[serde(deserialize_with = "de_named")]
pub service_detection: Option<ServiceDetection>,
#[serde(deserialize_with = "de_named")]
pub detection: Option<DetectionEnvelope>,
#[serde(deserialize_with = "de_idle_scan")]
pub idle_scan: Option<IdleScan>,
#[serde(deserialize_with = "de_evasion")]
pub evasion: Option<EvasionProfile>,
}
impl ScanRequest {
pub fn new() -> Self {
Self::default()
}
pub fn ports(&self) -> Option<Result<PortSet, RequestError>> {
if let Some(spec) = self.ports.as_deref() {
return Some(
PortSet::parse_scan(spec).map_err(|error| RequestError::Ports {
spec: spec.to_string(),
reason: error.to_string(),
}),
);
}
self.settings.ports().map(|parsed| {
parsed.map_err(|error| RequestError::Ports {
spec: self.settings.default_ports.clone().unwrap_or_default(),
reason: error.to_string(),
})
})
}
pub fn apply_to(&self, config: &mut ZondConfig) {
self.settings.apply_to(config);
if let Some(value) = self.assume_up {
config.assume_up = value;
}
if let Some(value) = self.traceroute {
config.traceroute = value;
}
if let Some(value) = self.characterise {
config.characterise = value;
}
if let Some(value) = self.icmp_evidence {
config.icmp_evidence = value;
}
if let Some(protocols) = &self.ip_protocols {
config.ip_protocols = protocols.clone();
}
if let Some(sources) = &self.send_source {
config.send_source = sources.clone();
}
if let Some(value) = self.os_detection {
config.os_detection = value;
}
if let Some(value) = self.service_detection {
config.service_detection = value;
}
if let Some(value) = self.detection {
config.detection = value;
}
if self.idle_scan.is_some() {
config.idle_scan = self.idle_scan;
}
if let Some(profile) = &self.evasion {
config.evasion = profile.clone();
}
}
pub async fn resolve(&self, names: Option<&Resolver>) -> Result<Resolved, RequestError> {
if self.targets.is_empty() {
return Err(RequestError::NoTargets);
}
let (targets, plan) = resolve::for_request(&self.targets, names).await?;
let exclude = if self.exclude.is_empty() {
Exclusions::none()
} else {
resolve::for_exclusion(&self.exclude, names).await?
};
let ports = self.ports().transpose()?;
Ok(Resolved {
targets,
plan,
exclude,
ports,
})
}
}
#[non_exhaustive]
#[derive(Debug, Clone)]
pub struct Resolved {
targets: DiscoveryTargets,
plan: PortScanTargets,
exclude: Exclusions,
ports: Option<PortSet>,
}
impl Resolved {
pub fn ips(&self) -> &IpSet {
self.targets.ips()
}
pub fn into_ips(self) -> IpSet {
self.targets.into_ips()
}
pub fn ports(&self) -> Option<&PortSet> {
self.ports.as_ref()
}
pub fn port_scan(&self, default_ports: &PortSet) -> PortScanTargets {
self.plan
.with_unported_on(self.ports.as_ref().unwrap_or(default_ports))
}
pub fn exclusions(&self) -> &Exclusions {
&self.exclude
}
pub fn into_parts(self) -> (IpSet, Option<PortSet>) {
(self.targets.into_ips(), self.ports)
}
pub fn apply_to(&self, config: &mut ZondConfig) {
self.targets.apply_to(config);
self.plan.apply_to(config);
config.exclusions.extend(&self.exclude);
}
}
#[derive(Deserialize)]
#[serde(deny_unknown_fields)]
struct IdleScanDocument {
zombie: IpAddr,
#[serde(default)]
zombie_port: Option<u16>,
}
fn de_idle_scan<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<IdleScan>, D::Error> {
let Some(document) = Option::<IdleScanDocument>::deserialize(d)? else {
return Ok(None);
};
Ok(Some(IdleScan {
zombie: document.zombie,
zombie_port: document.zombie_port,
}))
}
#[derive(Default, Deserialize)]
#[serde(default, deny_unknown_fields)]
struct EvasionDocument {
source_port: Option<u16>,
ttl: Option<u8>,
padding: Option<u16>,
bad_tcp_checksum: bool,
#[serde(deserialize_with = "de_named")]
spoof_mac: Option<MacAddr>,
fragment: Option<u16>,
decoys: Vec<IpAddr>,
flags: Option<u8>,
}
fn de_evasion<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<EvasionProfile>, D::Error> {
let Some(document) = Option::<EvasionDocument>::deserialize(d)? else {
return Ok(None);
};
let profile = EvasionProfile {
source_port: document.source_port,
ttl: document.ttl,
padding: document.padding,
bad_tcp_checksum: document.bad_tcp_checksum,
spoof_mac: document.spoof_mac,
fragment: document.fragment,
decoys: document.decoys,
flags: document.flags,
};
profile.validate().map_err(serde::de::Error::custom)?;
Ok(Some(profile))
}
#[cfg(test)]
mod tests {
use super::*;
use crate::config::ScanEffort;
use crate::model::finding::DetectionClass;
use crate::model::technique::TcpScanTechnique;
fn request(document: &str) -> ScanRequest {
toml::from_str(document).expect("the document is a request")
}
fn settled() -> ZondConfig {
ZondConfig {
assume_up: true,
traceroute: true,
characterise: true,
icmp_evidence: true,
os_detection: OsDetection::Aggressive,
service_detection: ServiceDetection::Thorough,
tcp_technique: TcpScanTechnique::Fin,
send_source: vec!["198.51.100.1".parse().expect("literal")],
..Default::default()
}
}
#[test]
fn no_request_can_take_a_port_off_the_listen_only_list() {
for text in [
"listen_only_ports = []\n",
"probe_print_ports = true\n",
"[settings]\nlisten_only_ports = []\n",
] {
let Ok(request) = toml::from_str::<ScanRequest>(text) else {
continue;
};
let mut config = ZondConfig::default();
request.apply_to(&mut config);
for port in crate::config::RAW_PRINT_PORTS {
assert!(
config.listen_only_ports.contains(port),
"{text:?} took {port} off the list"
);
}
}
}
#[test]
fn a_request_that_says_nothing_changes_no_setting() {
let mut config = settled();
ScanRequest::new().apply_to(&mut config);
assert!(config.assume_up);
assert!(config.traceroute);
assert!(config.characterise);
assert!(config.icmp_evidence);
assert_eq!(config.os_detection, OsDetection::Aggressive);
assert_eq!(config.service_detection, ServiceDetection::Thorough);
assert_eq!(config.tcp_technique, TcpScanTechnique::Fin);
assert_eq!(config.send_source, settled().send_source);
assert!(config.idle_scan.is_none());
assert!(!config.evasion.is_active());
}
#[test]
fn every_key_a_request_understands_reaches_the_configuration() {
let request = request(
r#"
targets = ["192.0.2.0/24"]
ports = "22,80"
assume_up = false
traceroute = false
characterise = false
icmp_evidence = false
ip_protocols = [1, 47, 50]
send_source = ["192.0.2.2"]
os_detection = "passive"
service_detection = "banner"
detection = "exploit"
[settings]
effort = "single"
tcp_technique = "syn"
[idle_scan]
zombie = "192.0.2.9"
zombie_port = 445
[evasion]
source_port = 53
ttl = 12
decoys = ["192.0.2.5"]
"#,
);
let mut config = settled();
request.apply_to(&mut config);
assert!(!config.assume_up);
assert!(!config.traceroute);
assert!(!config.characterise);
assert!(!config.icmp_evidence);
assert_eq!(config.ip_protocols, BTreeSet::from([1, 47, 50]));
assert_eq!(
config.send_source,
vec!["192.0.2.2".parse::<IpAddr>().expect("literal")]
);
assert_eq!(config.os_detection, OsDetection::Passive);
assert_eq!(config.service_detection, ServiceDetection::Banner);
assert_eq!(config.detection.ceiling(), Some(DetectionClass::Exploit));
assert_eq!(config.retry.effort, ScanEffort::Single);
assert_eq!(config.tcp_technique, TcpScanTechnique::Syn);
let idle = config.idle_scan.expect("the request named a zombie");
assert_eq!(idle.zombie, "192.0.2.9".parse::<IpAddr>().expect("literal"));
assert_eq!(idle.zombie_port, Some(445));
assert_eq!(config.evasion.source_port, Some(53));
assert_eq!(config.evasion.ttl, Some(12));
assert_eq!(config.evasion.decoys.len(), 1);
let ports = request
.ports()
.expect("the request named ports")
.expect("valid");
assert!(ports.has_tcp(22) && ports.has_tcp(80));
}
#[test]
fn a_misspelled_key_is_refused_rather_than_ignored() {
let error = toml::from_str::<ScanRequest>("traceroot = true\n")
.expect_err("a key nobody knows is not a request");
let message = error.to_string();
assert!(
message.contains("traceroot"),
"the error should name the key that was written: {message}"
);
assert!(
message.contains("traceroute"),
"the error should name the keys that would have worked: {message}"
);
}
#[test]
fn a_request_overrides_the_settings_a_file_had_already_applied() {
let mut config = ZondConfig::default();
let from_disk: Settings =
toml::from_str("effort = \"single\"\ntls_enumeration = false\n").expect("settings");
from_disk.apply_to(&mut config);
request("[settings]\neffort = \"thorough\"\n").apply_to(&mut config);
assert_eq!(config.retry.effort, ScanEffort::Thorough);
assert!(
!config.tls_enumeration,
"a key the request said nothing about keeps what the file set"
);
}
#[test]
fn an_evasion_table_the_engine_would_refuse_is_refused_as_it_is_read() {
let error = toml::from_str::<ScanRequest>("[evasion]\nfragment = 4\n")
.expect_err("an unfragmentable MTU is not a profile");
assert!(
error.to_string().contains("fragment"),
"the error should say which value was wrong: {error}"
);
}
#[test]
fn ports_fall_back_to_the_settings_table_when_the_request_names_none() {
let request = request("[settings]\ndefault_ports = \"443\"\n");
let ports = request
.ports()
.expect("the settings named ports")
.expect("valid");
assert!(ports.has_tcp(443));
assert_eq!(ports.len(), 1);
}
#[test]
fn a_port_specification_that_is_not_one_names_what_was_written() {
let request = request("ports = \"nope\"\n");
let error = request
.ports()
.expect("the request named ports")
.expect_err("'nope' is not a port specification");
assert!(matches!(&error, RequestError::Ports { spec, .. } if spec == "nope"));
}
#[test]
fn a_port_specification_naming_nothing_is_refused_rather_than_scanning_nothing() {
for document in [
"ports = \"\"\n",
"ports = \" , \"\n",
"[settings]\ndefault_ports = \"\"\n",
] {
let error = request(document)
.ports()
.expect("the request named ports")
.expect_err("a specification naming nothing");
assert!(
error.to_string().contains("names no ports"),
"{document}: {error}"
);
}
}
#[tokio::test]
async fn resolving_adds_exclusions_to_what_the_configuration_already_forbids() {
let mut already = IpSet::new();
already.insert_range("198.51.100.0/24".parse().expect("a valid range"));
let mut config = ZondConfig {
exclusions: Exclusions::new(already),
..Default::default()
};
let resolved = request("targets = [\"192.0.2.0/24\"]\nexclude = [\"192.0.2.7\"]\n")
.resolve(None)
.await
.expect("literal addresses resolve without a resolver");
resolved.apply_to(&mut config);
for excluded in ["198.51.100.1", "192.0.2.7"] {
assert!(
config
.exclusions
.excludes(&excluded.parse().expect("literal")),
"{excluded} was excluded by one of the two and must still be"
);
}
assert!(
!config
.exclusions
.excludes(&"192.0.2.8".parse().expect("literal"))
);
assert_eq!(resolved.ips().len(), 256);
}
#[tokio::test]
async fn a_port_written_on_a_target_is_the_port_it_is_scanned_on() {
let defaults = PortSet::try_from("22").expect("a specification");
let on = |plan: &PortScanTargets, address: &str| {
let address: IpAddr = address.parse().expect("literal");
plan.map()
.units
.iter()
.find(|unit| unit.ips().contains(&address))
.map(|unit| unit.ports().to_string())
};
let unported = request("targets = [\"192.0.2.1:8080\", \"192.0.2.2\"]\n")
.resolve(None)
.await
.expect("literal addresses resolve without a resolver");
let plan = unported.port_scan(&defaults);
assert_eq!(on(&plan, "192.0.2.1").as_deref(), Some("8080"));
assert_eq!(on(&plan, "192.0.2.2").as_deref(), Some("22"));
assert_eq!(unported.ips().len(), 2, "both reach the discovery sweep");
let ported = request("targets = [\"192.0.2.1:u:53\", \"192.0.2.2\"]\nports = \"443\"\n")
.resolve(None)
.await
.expect("resolves");
let plan = ported.port_scan(&defaults);
assert_eq!(on(&plan, "192.0.2.1").as_deref(), Some("u:53"));
assert_eq!(on(&plan, "192.0.2.2").as_deref(), Some("443"));
}
#[tokio::test]
async fn a_request_naming_no_targets_is_refused_rather_than_resolving_to_nothing() {
let error = ScanRequest::new()
.resolve(None)
.await
.expect_err("a request with no targets cannot be resolved");
assert!(matches!(error, RequestError::NoTargets));
}
}