use std::collections::HashMap;
use std::fmt;
use std::net::IpAddr;
use thiserror::Error;
use crate::model::ip::set::IpSet;
use crate::model::parse::ip::{IpParseError, ResolverFn, ZoneResolverFn, insert_expression};
use crate::model::port::{PortSet, PortSetParseError};
use crate::model::target::{TargetMap, TargetSet};
pub type HostLookup<'a> = &'a dyn Fn(&str) -> Option<Vec<IpAddr>>;
#[derive(Default, Clone, Copy)]
pub struct TargetContext<'a> {
pub keywords: Option<ResolverFn<'a>>,
pub zones: Option<ZoneResolverFn<'a>>,
pub hosts: Option<HostLookup<'a>>,
}
impl<'a> TargetContext<'a> {
pub fn new() -> Self {
Self::default()
}
pub fn with_keywords(mut self, keywords: ResolverFn<'a>) -> Self {
self.keywords = Some(keywords);
self
}
pub fn with_zones(mut self, zones: ZoneResolverFn<'a>) -> Self {
self.zones = Some(zones);
self
}
pub fn with_hosts(mut self, hosts: HostLookup<'a>) -> Self {
self.hosts = Some(hosts);
self
}
}
impl fmt::Debug for TargetContext<'_> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("TargetContext")
.field("keywords", &self.keywords.is_some())
.field("zones", &self.zones.is_some())
.field("hosts", &self.hosts.is_some())
.finish()
}
}
#[non_exhaustive]
#[derive(Debug, Error)]
pub enum TargetParseError {
#[error("a target expression cannot be empty")]
Empty,
#[error("'{0}': a bracketed address must be closed with ']'")]
UnbalancedBracket(String),
#[error("'{0}': expected ':' and a port specification after ']'")]
TrailingText(String),
#[error("'{0}': the ':' is not followed by a port specification")]
EmptyPorts(String),
#[error("'{expression}': {source}")]
Address {
expression: String,
#[source]
source: IpParseError,
},
#[error("'{expression}': {source}")]
Ports {
expression: String,
#[source]
source: PortSetParseError,
},
#[error("'{0}': this is a hostname, and no host lookup was supplied to resolve it")]
NoHostLookup(String),
#[error("'{0}': not a valid address, and too numeric to be a hostname")]
MistypedAddress(String),
#[error(
"'{0}': not an address, and a hostname cannot contain ':'. \
An IPv6 target carrying ports must be bracketed, as in `[2001:db8::1]:443`"
)]
UnbracketedAddress(String),
#[error("'{0}': no address could be resolved for this name")]
UnknownHost(String),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TargetExpr<'a> {
pub address: &'a str,
pub ports: Option<&'a str>,
}
impl<'a> TargetExpr<'a> {
pub fn parse(token: &'a str) -> Result<Self, TargetParseError> {
let token = token.trim();
if token.is_empty() {
return Err(TargetParseError::Empty);
}
if let Some(rest) = token.strip_prefix('[') {
let close = rest
.find(']')
.ok_or_else(|| TargetParseError::UnbalancedBracket(token.to_string()))?;
let address = &rest[..close];
let tail = &rest[close + 1..];
if address.is_empty() {
return Err(TargetParseError::Empty);
}
return match tail.strip_prefix(':') {
None if tail.is_empty() => Ok(Self {
address,
ports: None,
}),
None => Err(TargetParseError::TrailingText(token.to_string())),
Some("") => Err(TargetParseError::EmptyPorts(token.to_string())),
Some(ports) => Ok(Self {
address,
ports: Some(ports),
}),
};
}
let colons = token.matches(':').count();
let dotted_first = match (token.find('.'), token.find(':')) {
(Some(dot), Some(colon)) => dot < colon,
_ => false,
};
if colons >= 1 && (dotted_first || colons == 1) {
let (address, ports) = token.split_once(':').expect("a colon was found");
if address.is_empty() {
return Err(TargetParseError::Empty);
}
if ports.is_empty() {
return Err(TargetParseError::EmptyPorts(token.to_string()));
}
return Ok(Self {
address,
ports: Some(ports),
});
}
Ok(Self {
address: token,
ports: None,
})
}
pub fn addresses(&self) -> impl Iterator<Item = &'a str> {
self.address
.split(',')
.map(str::trim)
.filter(|part| !part.is_empty())
}
}
#[derive(Debug, Clone)]
pub struct TargetMapBuilder {
default_ports: PortSet,
groups: Vec<(PortSet, IpSet)>,
index: HashMap<PortSet, usize>,
gross_addresses: u128,
}
impl TargetMapBuilder {
pub fn new(default_ports: PortSet) -> Self {
Self {
default_ports,
groups: Vec::new(),
index: HashMap::new(),
gross_addresses: 0,
}
}
pub fn push(&mut self, token: &str, ctx: &TargetContext<'_>) -> Result<(), TargetParseError> {
let expr = TargetExpr::parse(token)?;
let ports = match expr.ports {
Some(spec) => PortSet::try_from(spec).map_err(|source| TargetParseError::Ports {
expression: token.trim().to_string(),
source,
})?,
None => self.default_ports.clone(),
};
let mut resolved = IpSet::new();
for address in expr.addresses() {
match insert_expression(address, &mut resolved, ctx.keywords, ctx.zones) {
Ok(()) => {}
Err(IpParseError::Malformed(_)) => {
self.resolve_host(address, &mut resolved, ctx)?;
}
Err(source) => {
return Err(TargetParseError::Address {
expression: token.trim().to_string(),
source,
});
}
}
}
if resolved.is_empty() {
return Err(TargetParseError::Empty);
}
self.gross_addresses = self.gross_addresses.saturating_add(resolved.len_gross());
let slot = match self.index.get(&ports) {
Some(&slot) => slot,
None => {
let slot = self.groups.len();
self.index.insert(ports.clone(), slot);
self.groups.push((ports, IpSet::new()));
slot
}
};
let target = &mut self.groups[slot].1;
for range in resolved.v4() {
target.push_v4_range(*range);
}
for range in resolved.v6() {
target.push_v6_range(*range);
}
Ok(())
}
fn resolve_host(
&self,
name: &str,
into: &mut IpSet,
ctx: &TargetContext<'_>,
) -> Result<(), TargetParseError> {
if name.contains(':') {
return Err(TargetParseError::UnbracketedAddress(name.to_string()));
}
if !name.is_empty() && name.chars().all(|c| c.is_ascii_digit() || c == '.') {
return Err(TargetParseError::MistypedAddress(name.to_string()));
}
let lookup = ctx
.hosts
.ok_or_else(|| TargetParseError::NoHostLookup(name.to_string()))?;
let addresses = lookup(name).unwrap_or_default();
if addresses.is_empty() {
return Err(TargetParseError::UnknownHost(name.to_string()));
}
for address in addresses {
into.insert(address);
}
Ok(())
}
pub fn group_count(&self) -> usize {
self.groups.len()
}
pub fn address_count(&mut self) -> u128 {
self.groups
.iter_mut()
.map(|(_, ips)| {
ips.canonicalize();
ips.len()
})
.fold(0u128, |total, count| total.saturating_add(count))
}
pub fn gross_address_count(&self) -> u128 {
self.gross_addresses
}
pub fn is_empty(&self) -> bool {
self.groups.iter().all(|(_, ips)| ips.is_empty())
}
pub fn build(self) -> TargetMap {
let mut map = TargetMap::new();
for (ports, ips) in self.groups {
if ips.is_empty() {
continue;
}
map.add_unit(TargetSet::new(ips, ports));
}
map
}
}
pub fn to_target_map<S>(
targets: &[S],
default_ports: PortSet,
ctx: &TargetContext<'_>,
) -> Result<TargetMap, TargetParseError>
where
S: AsRef<str>,
{
let mut builder = TargetMapBuilder::new(default_ports);
for target in targets {
builder.push(target.as_ref(), ctx)?;
}
Ok(builder.build())
}
#[cfg(test)]
mod tests {
use super::*;
use std::net::Ipv4Addr;
fn ports(spec: &str) -> PortSet {
PortSet::try_from(spec).expect("test port specification parses")
}
#[test]
fn an_ipv6_address_is_never_split_at_its_own_colons() {
for token in [
"fe80::1",
"2001:db8::1",
"2001:db8::1:80",
"fe80::1%en0",
"2001:db8::1-2001:db8::5",
"::1",
] {
let expr = TargetExpr::parse(token).expect("parses");
assert_eq!(expr.address, token, "{token} lost part of its address");
assert_eq!(expr.ports, None, "{token} acquired ports it does not name");
}
}
#[test]
fn brackets_separate_an_ipv6_address_from_its_ports() {
let cases = [
("[2001:db8::1]:443", "2001:db8::1", Some("443")),
("[fe80::1%en0]:22", "fe80::1%en0", Some("22")),
("[2001:db8::1]", "2001:db8::1", None),
(
"[2001:db8::]:80,443,u:53",
"2001:db8::",
Some("80,443,u:53"),
),
];
for (token, address, port_spec) in cases {
let expr = TargetExpr::parse(token).expect("parses");
assert_eq!(expr.address, address);
assert_eq!(expr.ports, port_spec);
}
}
#[test]
fn a_single_colon_separates_ports() {
let cases = [
("192.168.1.1:80", "192.168.1.1", Some("80")),
("10.0.0.0/24:1-1024", "10.0.0.0/24", Some("1-1024")),
("10.0.0.1-50:80,443", "10.0.0.1-50", Some("80,443")),
("scanme.example:22", "scanme.example", Some("22")),
(" 192.168.1.1:80 ", "192.168.1.1", Some("80")),
];
for (token, address, port_spec) in cases {
let expr = TargetExpr::parse(token).expect("parses");
assert_eq!(expr.address, address);
assert_eq!(expr.ports, port_spec);
}
}
#[test]
fn a_udp_port_needs_no_brackets_on_an_address_that_has_a_dot() {
let cases = [
("192.168.0.1:u:53", "192.168.0.1", Some("u:53")),
("192.168.0.1:u:53,u:161", "192.168.0.1", Some("u:53,u:161")),
("10.0.0.0/24:80,u:53", "10.0.0.0/24", Some("80,u:53")),
("db.internal:u:53", "db.internal", Some("u:53")),
];
for (token, address, port_spec) in cases {
let expr = TargetExpr::parse(token).expect("parses");
assert_eq!(expr.address, address, "{token}");
assert_eq!(expr.ports, port_spec, "{token}");
}
for token in ["2001:db8::1", "::ffff:192.168.0.1", "2001:db8::192.168.0.1"] {
let expr = TargetExpr::parse(token).expect("parses");
assert_eq!(expr.address, token, "{token} was split");
assert_eq!(expr.ports, None, "{token} acquired ports");
}
}
#[test]
fn an_unbracketed_ipv6_target_with_ports_says_what_to_do_about_it() {
let mut builder = TargetMapBuilder::new(ports("80"));
let err = builder
.push("2001:db8::zz:443", &TargetContext::new())
.expect_err("not an address");
assert!(
matches!(err, TargetParseError::UnbracketedAddress(_)),
"got {err:?}"
);
assert!(
err.to_string().contains("[2001:db8::1]:443"),
"the error has to show the way out: {err}"
);
}
#[test]
fn a_separator_without_a_port_specification_is_refused() {
assert!(matches!(
TargetExpr::parse("192.168.1.1:"),
Err(TargetParseError::EmptyPorts(_))
));
assert!(matches!(
TargetExpr::parse("[2001:db8::1]:"),
Err(TargetParseError::EmptyPorts(_))
));
assert!(matches!(
TargetExpr::parse("[2001:db8::1"),
Err(TargetParseError::UnbalancedBracket(_))
));
assert!(matches!(
TargetExpr::parse("[2001:db8::1]443"),
Err(TargetParseError::TrailingText(_))
));
assert!(matches!(
TargetExpr::parse(":80"),
Err(TargetParseError::Empty)
));
assert!(matches!(
TargetExpr::parse(" "),
Err(TargetParseError::Empty)
));
}
#[test]
fn targets_are_grouped_by_port_specification_not_by_token() {
let mut builder = TargetMapBuilder::new(ports("80"));
let ctx = TargetContext::new();
for octet in 0..=255u8 {
let target = format!("192.168.1.{octet}");
builder.push(&target, &ctx).expect("parses");
}
assert_eq!(builder.group_count(), 1, "one port specification, one unit");
assert_eq!(builder.address_count(), 256);
let map = builder.build();
assert_eq!(map.units.len(), 1);
assert_eq!(map.gross_targets().unwrap(), 256);
}
#[test]
fn distinct_port_specifications_get_distinct_units_in_first_seen_order() {
let mut builder = TargetMapBuilder::new(ports("80"));
let ctx = TargetContext::new();
builder.push("10.0.0.1:22", &ctx).unwrap();
builder.push("10.0.0.2:443", &ctx).unwrap();
builder.push("10.0.0.3:22", &ctx).unwrap();
builder.push("10.0.0.4", &ctx).unwrap();
assert_eq!(builder.group_count(), 3, "22, 443, and the default 80");
let map = builder.build();
assert_eq!(map.units[0].ports(), &ports("22"));
assert_eq!(map.units[0].ips().len(), 2, "10.0.0.1 and 10.0.0.3");
assert_eq!(map.units[1].ports(), &ports("443"));
assert_eq!(map.units[2].ports(), &ports("80"));
}
#[test]
fn port_specifications_group_by_what_they_mean_not_how_they_are_written() {
let mut builder = TargetMapBuilder::new(ports("80"));
let ctx = TargetContext::new();
builder.push("10.0.0.1:80,443", &ctx).unwrap();
builder.push("10.0.0.2:443,80", &ctx).unwrap();
builder.push("10.0.0.3:80-81,443", &ctx).unwrap();
assert_eq!(
builder.group_count(),
2,
"80 with 443 once, 80 through 81 with 443 once"
);
}
#[test]
fn a_hostname_without_a_lookup_is_refused_rather_than_skipped() {
let mut builder = TargetMapBuilder::new(ports("80"));
let err = builder
.push("scanme.example", &TargetContext::new())
.expect_err("a hostname needs a lookup");
assert!(
matches!(err, TargetParseError::NoHostLookup(ref name) if name == "scanme.example")
);
assert!(builder.is_empty(), "a refused target left nothing behind");
}
#[test]
fn a_hostname_resolves_through_the_callers_lookup() {
let lookup = |name: &str| match name {
"one.example" => Some(vec![IpAddr::V4(Ipv4Addr::new(10, 0, 0, 1))]),
"two.example" => Some(vec![
IpAddr::V4(Ipv4Addr::new(10, 0, 0, 2)),
IpAddr::V4(Ipv4Addr::new(10, 0, 0, 3)),
]),
_ => None,
};
let ctx = TargetContext::new().with_hosts(&lookup);
let mut builder = TargetMapBuilder::new(ports("80"));
builder.push("one.example", &ctx).unwrap();
builder.push("two.example:443", &ctx).unwrap();
assert_eq!(builder.address_count(), 3);
assert_eq!(builder.group_count(), 2);
let err = builder
.push("nowhere.example", &ctx)
.expect_err("a name with no records is not a target");
assert!(matches!(err, TargetParseError::UnknownHost(_)));
}
#[test]
fn a_malformed_address_is_reported_as_an_address() {
let lookup = |_: &str| -> Option<Vec<IpAddr>> {
panic!("a bad prefix must never be offered to a host lookup")
};
let ctx = TargetContext::new().with_hosts(&lookup);
let mut builder = TargetMapBuilder::new(ports("80"));
let err = builder.push("192.168.1.1/33", &ctx).expect_err("refused");
assert!(matches!(
err,
TargetParseError::Address {
source: IpParseError::InvalidPrefix(33),
..
}
));
}
#[test]
fn a_malformed_port_specification_is_reported_as_ports() {
let mut builder = TargetMapBuilder::new(ports("80"));
let err = builder
.push("10.0.0.1:http", &TargetContext::new())
.expect_err("refused");
assert!(matches!(err, TargetParseError::Ports { .. }));
assert!(builder.is_empty());
}
#[test]
fn a_bracketed_link_local_target_keeps_its_interface() {
fn zones(name: &str) -> Option<u32> {
(name == "en0").then_some(7)
}
let ctx = TargetContext::new().with_zones(&zones);
let mut builder = TargetMapBuilder::new(ports("80"));
builder.push("[fe80::aa%en0]:22", &ctx).unwrap();
let map = builder.build();
assert_eq!(map.units[0].ips().v6()[0].zone(), Some(7));
assert_eq!(map.units[0].ports(), &ports("22"));
}
#[test]
fn a_resolver_may_close_over_what_it_needs_to_answer() {
let interfaces = [("en0".to_string(), 7u32), ("utun3".to_string(), 12)];
let zones = |name: &str| {
interfaces
.iter()
.find(|(known, _)| known == name)
.map(|(_, index)| *index)
};
let ctx = TargetContext::new().with_zones(&zones);
let mut builder = TargetMapBuilder::new(ports("80"));
builder.push("[fe80::aa%utun3]:22", &ctx).expect("parses");
let map = builder.build();
assert_eq!(map.units[0].ips().v6()[0].zone(), Some(12));
}
#[test]
fn the_running_address_total_matches_what_the_groups_hold() {
let ctx = TargetContext::new();
let mut builder = TargetMapBuilder::new(ports("80"));
for target in [
"10.0.0.0/24",
"10.0.0.5",
"192.168.1.1:22",
"2001:db8::/120",
"172.16.0.1,172.16.0.2,172.16.0.3",
"[fe80::1]:443",
] {
builder.push(target, &ctx).expect("parses");
}
let walked = builder
.groups
.iter()
.fold(0u128, |total, (_, ips)| total + ips.len_gross());
assert_eq!(builder.gross_address_count(), walked);
assert!(builder.gross_address_count() >= builder.address_count());
}
#[test]
fn address_count_reports_what_a_block_holds_not_what_was_written() {
let mut builder = TargetMapBuilder::new(ports("80"));
builder.push("10.0.0.0/8", &TargetContext::new()).unwrap();
assert_eq!(builder.address_count(), 16_777_216);
let mut everything = TargetMapBuilder::new(ports("80"));
everything.push("::/0", &TargetContext::new()).unwrap();
assert_eq!(everything.address_count(), u128::MAX);
}
#[test]
fn a_comma_separates_addresses_before_the_ports_and_ports_after_them() {
let ctx = TargetContext::new();
let mut hosts = TargetMapBuilder::new(ports("80"));
hosts.push("10.0.0.1,10.0.0.2:443", &ctx).unwrap();
assert_eq!(hosts.address_count(), 2);
assert_eq!(hosts.build().units[0].ports(), &ports("443"));
let mut services = TargetMapBuilder::new(ports("80"));
services.push("10.0.0.1:80,443", &ctx).unwrap();
assert_eq!(services.address_count(), 1);
assert_eq!(services.build().units[0].ports(), &ports("80,443"));
let mut bare = TargetMapBuilder::new(ports("80"));
bare.push("10.0.0.1, 10.0.0.2 ,10.0.0.3", &ctx).unwrap();
assert_eq!(bare.address_count(), 3);
}
#[test]
fn overlapping_targets_in_one_group_merge_rather_than_duplicate() {
let mut builder = TargetMapBuilder::new(ports("80"));
let ctx = TargetContext::new();
builder.push("10.0.0.0/24", &ctx).unwrap();
builder.push("10.0.0.5", &ctx).unwrap();
builder.push("10.0.0.128-10.0.1.10", &ctx).unwrap();
assert_eq!(builder.address_count(), 267, "0.0-1.10, counted once each");
assert_eq!(builder.group_count(), 1);
}
}