zond_engine/model/parse.rs
1// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
2//
3// This file is part of Zond Engine, licensed under the GNU Affero General
4// Public License, version 3 or later. See the LICENSE file for details, or
5// <https://www.gnu.org/licenses/agpl-3.0.html>.
6//
7// SPDX-License-Identifier: AGPL-3.0-or-later
8
9//! # Written down, and read back
10//!
11//! The grammars that turn what a person typed into the values in
12//! [`crate::model`]. [`ip`] handles the address half, covering literals,
13//! ranges, CIDR blocks, zones and keywords. [`target`] handles an address with
14//! a port specification after it.
15//!
16//! Every way of naming a target ends here: a command-line argument, a form field, a
17//! line of a target list, a CSV row and a hostname read from an nmap report are one
18//! grammar, so the file formats only decide where the tokens come from.
19//!
20//! Resolution that has to ask the machine, such as what `lan` means or which interface
21//! a `%zone` names, arrives as a caller-supplied callback ([`ip::ResolverFn`],
22//! [`ip::ZoneResolverFn`]). The engine passes [`crate::system::interface`]'s answers in,
23//! which keeps this module a leaf.
24
25pub mod ip;
26pub mod target;
27
28pub use ip::{IpParseError, Keyword, names_keyword, to_set};
29pub use target::{HostLookup, TargetContext, TargetExpr, TargetMapBuilder, TargetParseError};
30
31use crate::model::port::PortSet;
32use crate::model::target::TargetMap;
33
34/// Parses target expressions such as `["1.1.1.1:80,443", "8.8.8.8"]` into a
35/// [`TargetMap`], giving each one the ports it names or `global_ports` if it
36/// names none.
37///
38/// [`target::to_target_map`] with only a keyword resolver. To resolve interface zones
39/// or hostnames as well, build a [`TargetContext`] and call that function directly.
40///
41/// # Errors
42///
43/// The first expression that does not parse. Nothing is returned partially; to log the
44/// bad lines and scan the rest, drive [`TargetMapBuilder`] directly.
45pub fn to_target_map(
46 targets: &[String],
47 global_ports: PortSet,
48 resolver: Option<ip::ResolverFn<'_>>,
49) -> Result<TargetMap, target::TargetParseError> {
50 let mut ctx = target::TargetContext::new();
51 ctx.keywords = resolver;
52
53 target::to_target_map(targets, global_ports, &ctx)
54}
55
56// ╔════════════════════════════════════════════╗
57// ║ ████████╗███████╗███████╗████████╗███████╗ ║
58// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
59// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
60// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
61// ║ ██║ ███████╗███████║ ██║ ███████║ ║
62// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
63// ╚════════════════════════════════════════════╝
64
65#[cfg(test)]
66mod tests {
67 use super::*;
68
69 /// A context built from only a keyword resolver still parses literal targets and
70 /// groups them by port specification.
71 #[test]
72 fn the_facade_builds_a_map_from_targets_that_need_no_resolver() {
73 let targets = ["198.51.100.1:22".to_string(), "198.51.100.2".to_string()];
74 let map = to_target_map(&targets, PortSet::try_from("80").unwrap(), None)
75 .expect("literal addresses need nothing resolved");
76
77 assert_eq!(map.units.len(), 2, "port 22, and the default 80");
78 assert_eq!(map.gross_targets().unwrap(), 2);
79 }
80
81 /// A target needing a lookup this function cannot make is refused, so a scan never
82 /// silently covers less than its input said.
83 #[test]
84 fn the_facade_refuses_a_target_it_cannot_resolve() {
85 let targets = ["scanme.example".to_string()];
86 let error = to_target_map(&targets, PortSet::try_from("80").unwrap(), None)
87 .expect_err("a hostname needs a lookup this shape cannot take");
88
89 assert!(error.to_string().contains("scanme.example"), "{error}");
90 }
91}