use std::io::BufRead;
use crate::import::{ImportError, ImportLimits, Importer, Origin, TargetSink};
const FORMAT: &str = "nmap XML";
const MAX_DEPTH: usize = 64;
const MAX_NAME_BYTES: usize = 64;
const MAX_VALUE_BYTES: usize = 256;
const MAX_ELEMENTS: u64 = 1 << 24;
const MAX_ENTITY_BYTES: usize = 16;
#[derive(Debug, Clone, Copy, Default)]
pub struct NmapXmlImporter {
limits: ImportLimits,
}
impl NmapXmlImporter {
pub fn new(limits: ImportLimits) -> Self {
Self { limits }
}
}
impl Importer for NmapXmlImporter {
fn import(
&self,
input: &mut dyn BufRead,
sink: &mut dyn TargetSink,
) -> Result<(), ImportError> {
let mut parser = Parser::new(input, self.limits.max_line_bytes);
let mut host: Option<Accumulator> = None;
let mut depth = 0usize;
let mut saw_root = false;
let mut token = String::new();
loop {
match parser.next_event()? {
Event::Eof => break,
Event::Start { self_closing } => {
if !self_closing {
depth += 1;
if depth > MAX_DEPTH {
return Err(parser
.malformed(format!("elements nested more than {MAX_DEPTH} deep")));
}
}
match parser.element.name.as_slice() {
b"nmaprun" => saw_root = true,
b"host" => host = Some(Accumulator::default()),
b"address" => {
if let Some(accumulator) = host.as_mut() {
accumulator.address(&parser.element)?;
}
}
b"port" => {
if let Some(accumulator) = host.as_mut() {
accumulator.port(&parser.element, &parser)?;
}
}
_ => {}
}
if self_closing && parser.element.name == b"host" {
emit(host.take(), sink, &mut token, parser.origin())?;
}
}
Event::End => {
depth = depth.saturating_sub(1);
if parser.element.name == b"host" {
emit(host.take(), sink, &mut token, parser.origin())?;
}
}
}
}
if !saw_root {
return Err(ImportError::Malformed {
format: FORMAT,
origin: Origin::unknown(),
message: "no <nmaprun> element: this is not an nmap document".to_string(),
});
}
Ok(())
}
}
#[derive(Debug, Default)]
struct Accumulator {
addresses: Vec<String>,
ports: Vec<(u16, bool)>,
}
impl Accumulator {
fn address(&mut self, element: &Element) -> Result<(), ImportError> {
let kind = element.value(b"addrtype").unwrap_or("");
if kind != "ipv4" && kind != "ipv6" {
return Ok(());
}
if let Some(address) = element.value(b"addr")
&& !address.is_empty()
{
self.addresses.push(address.to_string());
}
Ok(())
}
fn port(&mut self, element: &Element, parser: &Parser<'_>) -> Result<(), ImportError> {
let Some(number) = element.value(b"portid") else {
return Ok(());
};
let number: u16 = number
.parse()
.map_err(|_| parser.malformed(format!("'{number}' is not a port number")))?;
let protocol = element.value(b"protocol").unwrap_or("tcp");
let udp = match protocol {
"tcp" => false,
"udp" => true,
other => {
return Err(parser.malformed(format!(
"port {number} names transport '{other}', which this build cannot probe"
)));
}
};
self.ports.push((number, udp));
Ok(())
}
}
fn emit(
host: Option<Accumulator>,
sink: &mut dyn TargetSink,
token: &mut String,
origin: Origin,
) -> Result<(), ImportError> {
let Some(host) = host else {
return Ok(());
};
let mut ports = String::new();
for (number, udp) in &host.ports {
if !ports.is_empty() {
ports.push(',');
}
if *udp {
ports.push_str("u:");
}
ports.push_str(&number.to_string());
}
for address in &host.addresses {
token.clear();
if ports.is_empty() {
token.push_str(address);
} else {
token.push('[');
token.push_str(address);
token.push_str("]:");
token.push_str(&ports);
}
sink.accept(token, origin)?;
}
Ok(())
}
enum Event {
Start { self_closing: bool },
End,
Eof,
}
#[derive(Debug, Default)]
struct Element {
name: Vec<u8>,
values: Vec<(Vec<u8>, Vec<u8>)>,
}
impl Element {
fn clear(&mut self) {
self.name.clear();
self.values.clear();
}
fn value(&self, name: &[u8]) -> Option<&str> {
self.values
.iter()
.find(|(key, _)| key == name)
.and_then(|(_, value)| std::str::from_utf8(value).ok())
}
}
const KEPT_ATTRIBUTES: [&[u8]; 4] = [b"addr", b"addrtype", b"protocol", b"portid"];
struct Parser<'a> {
input: &'a mut dyn BufRead,
buffer: Vec<u8>,
position: usize,
line: u64,
element_bytes: usize,
max_element_bytes: usize,
elements: u64,
element: Element,
}
impl<'a> Parser<'a> {
fn new(input: &'a mut dyn BufRead, max_element_bytes: usize) -> Self {
Self {
input,
buffer: Vec::new(),
position: 0,
line: 1,
element_bytes: 0,
max_element_bytes,
elements: 0,
element: Element::default(),
}
}
fn origin(&self) -> Origin {
Origin::line(self.line)
}
fn malformed(&self, message: String) -> ImportError {
ImportError::Malformed {
format: FORMAT,
origin: self.origin(),
message,
}
}
fn fill(&mut self) -> Result<bool, ImportError> {
if self.position < self.buffer.len() {
return Ok(true);
}
let Self {
input,
buffer,
position,
..
} = self;
buffer.clear();
*position = 0;
let available = input.fill_buf()?;
if available.is_empty() {
return Ok(false);
}
let taken = available.len();
buffer.extend_from_slice(available);
input.consume(taken);
Ok(true)
}
fn peek(&mut self) -> Result<Option<u8>, ImportError> {
if !self.fill()? {
return Ok(None);
}
Ok(Some(self.buffer[self.position]))
}
fn bump(&mut self) -> Result<Option<u8>, ImportError> {
let Some(byte) = self.peek()? else {
return Ok(None);
};
self.position += 1;
if byte == b'\n' {
self.line += 1;
}
self.element_bytes += 1;
if self.element_bytes > self.max_element_bytes {
return Err(ImportError::LineTooLong {
origin: self.origin(),
limit: self.max_element_bytes,
});
}
Ok(Some(byte))
}
fn next_event(&mut self) -> Result<Event, ImportError> {
loop {
loop {
match self.peek()? {
None => return Ok(Event::Eof),
Some(b'<') => break,
Some(_) => {
self.element_bytes = 0;
self.bump()?;
}
}
}
self.element_bytes = 0;
self.bump()?;
match self.peek()? {
None => return Err(self.malformed("the document ends inside a tag".to_string())),
Some(b'?') => {
self.skip_until(b"?>")?;
continue;
}
Some(b'!') => {
self.declaration()?;
continue;
}
Some(b'/') => {
self.bump()?;
self.element.clear();
self.read_name()?;
self.skip_until(b">")?;
return Ok(Event::End);
}
Some(_) => {
self.elements += 1;
if self.elements > MAX_ELEMENTS {
return Err(self.malformed(format!("more than {MAX_ELEMENTS} elements")));
}
self.element.clear();
self.read_name()?;
let self_closing = self.read_attributes()?;
return Ok(Event::Start { self_closing });
}
}
}
}
fn declaration(&mut self) -> Result<(), ImportError> {
self.bump()?;
if self.matches(b"--")? {
return self.skip_until(b"-->");
}
if self.matches(b"[CDATA[")? {
return self.skip_until(b"]]>");
}
if self.matches(b"DOCTYPE")? {
return self.doctype();
}
Err(self.malformed(
"a declaration other than a comment, CDATA or DOCTYPE: this parser \
accepts no declarations, which is what makes entity expansion \
impossible rather than merely unimplemented"
.to_string(),
))
}
fn doctype(&mut self) -> Result<(), ImportError> {
loop {
let Some(byte) = self.bump()? else {
return Err(self.malformed("the document ends inside a DOCTYPE".to_string()));
};
match byte {
b'>' => return Ok(()),
b'[' => {
return Err(self.malformed(
"a DOCTYPE with an internal subset, which is where entity \
declarations live. Only a bare '<!DOCTYPE name>' is accepted"
.to_string(),
));
}
b'S' | b'P' => {
let word = if byte == b'S' {
b"YSTEM".as_slice()
} else {
b"UBLIC".as_slice()
};
if self.matches(word)? {
return Err(self.malformed(
"a DOCTYPE naming an external identifier, which asks the \
parser to fetch a document. Only a bare \
'<!DOCTYPE name>' is accepted"
.to_string(),
));
}
}
_ => {}
}
}
}
fn read_name(&mut self) -> Result<(), ImportError> {
loop {
match self.peek()? {
None => return Err(self.malformed("the document ends inside a name".to_string())),
Some(byte) if is_name_byte(byte) => {
self.bump()?;
if self.element.name.len() >= MAX_NAME_BYTES {
return Err(
self.malformed(format!("a name longer than {MAX_NAME_BYTES} bytes"))
);
}
self.element.name.push(byte);
}
Some(_) => return Ok(()),
}
}
}
fn read_attributes(&mut self) -> Result<bool, ImportError> {
loop {
self.skip_whitespace()?;
match self.peek()? {
None => {
return Err(self.malformed("the document ends inside a tag".to_string()));
}
Some(b'>') => {
self.bump()?;
return Ok(false);
}
Some(b'/') => {
self.bump()?;
if self.peek()? != Some(b'>') {
return Err(self.malformed("'/' not followed by '>'".to_string()));
}
self.bump()?;
return Ok(true);
}
Some(_) => self.read_attribute()?,
}
}
}
fn read_attribute(&mut self) -> Result<(), ImportError> {
let mut name = Vec::new();
loop {
match self.peek()? {
None => return Err(self.malformed("the document ends inside a tag".to_string())),
Some(byte) if is_name_byte(byte) => {
self.bump()?;
if name.len() >= MAX_NAME_BYTES {
return Err(self.malformed(format!(
"an attribute name longer than {MAX_NAME_BYTES} bytes"
)));
}
name.push(byte);
}
Some(_) => break,
}
}
self.skip_whitespace()?;
if self.peek()? != Some(b'=') {
return Err(self.malformed(format!(
"attribute '{}' has no value",
String::from_utf8_lossy(&name)
)));
}
self.bump()?;
self.skip_whitespace()?;
let keep = KEPT_ATTRIBUTES.contains(&name.as_slice());
let value = self.read_value(keep)?;
if keep {
self.element.values.push((name, value));
}
Ok(())
}
fn read_value(&mut self, keep: bool) -> Result<Vec<u8>, ImportError> {
let Some(quote) = self.peek()? else {
return Err(self.malformed("the document ends inside a tag".to_string()));
};
if quote != b'"' && quote != b'\'' {
return Err(self.malformed("an attribute value that is not quoted".to_string()));
}
self.bump()?;
let mut value = Vec::new();
loop {
let Some(byte) = self.peek()? else {
return Err(
self.malformed("the document ends inside an attribute value".to_string())
);
};
if byte == quote {
self.bump()?;
return Ok(value);
}
if byte == b'&' {
let resolved = self.entity()?;
if keep {
push_bounded(&mut value, &resolved, self)?;
}
continue;
}
self.bump()?;
if keep {
push_bounded(&mut value, &[byte], self)?;
}
}
}
fn entity(&mut self) -> Result<Vec<u8>, ImportError> {
self.bump()?;
let mut name = Vec::new();
loop {
let Some(byte) = self.peek()? else {
return Err(self.malformed("the document ends inside an entity".to_string()));
};
self.bump()?;
if byte == b';' {
break;
}
if name.len() >= MAX_ENTITY_BYTES {
return Err(self.malformed("an entity reference with no ';'".to_string()));
}
name.push(byte);
}
match name.as_slice() {
b"lt" => Ok(vec![b'<']),
b"gt" => Ok(vec![b'>']),
b"amp" => Ok(vec![b'&']),
b"quot" => Ok(vec![b'"']),
b"apos" => Ok(vec![b'\'']),
reference if reference.first() == Some(&b'#') => self.character_reference(reference),
other => Err(self.malformed(format!(
"'&{};' is not a predefined entity, and this parser permits no \
declarations, so nothing can have defined it",
String::from_utf8_lossy(other)
))),
}
}
fn character_reference(&self, reference: &[u8]) -> Result<Vec<u8>, ImportError> {
let digits = String::from_utf8_lossy(&reference[1..]);
let code = match digits.strip_prefix(['x', 'X']) {
Some(hex) => u32::from_str_radix(hex, 16).ok(),
None => digits.parse::<u32>().ok(),
};
let Some(character) = code.and_then(char::from_u32) else {
return Err(self.malformed(format!("'&{digits};' is not a character")));
};
let mut encoded = [0u8; 4];
Ok(character.encode_utf8(&mut encoded).as_bytes().to_vec())
}
fn matches(&mut self, expected: &[u8]) -> Result<bool, ImportError> {
for wanted in expected {
match self.peek()? {
Some(byte) if byte == *wanted => {
self.bump()?;
}
_ => return Ok(false),
}
}
Ok(true)
}
fn skip_whitespace(&mut self) -> Result<(), ImportError> {
while matches!(self.peek()?, Some(b' ' | b'\t' | b'\r' | b'\n')) {
self.bump()?;
}
Ok(())
}
fn skip_until(&mut self, terminator: &[u8]) -> Result<(), ImportError> {
let mut matched = 0usize;
loop {
let Some(byte) = self.bump()? else {
return Err(self.malformed(format!(
"the document ends before '{}'",
String::from_utf8_lossy(terminator)
)));
};
if byte == terminator[matched] {
matched += 1;
if matched == terminator.len() {
return Ok(());
}
} else {
matched = usize::from(byte == terminator[0]);
}
}
}
}
fn push_bounded(value: &mut Vec<u8>, bytes: &[u8], parser: &Parser<'_>) -> Result<(), ImportError> {
if value.len() + bytes.len() > MAX_VALUE_BYTES {
return Err(parser.malformed(format!(
"an attribute value longer than {MAX_VALUE_BYTES} bytes"
)));
}
value.extend_from_slice(bytes);
Ok(())
}
fn is_name_byte(byte: u8) -> bool {
!matches!(
byte,
b' ' | b'\t' | b'\r' | b'\n' | b'/' | b'>' | b'=' | b'<'
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::import::{ImportFormat, ImportOptions, Imported};
use crate::model::port::PortSet;
use std::io::Cursor;
const REAL_PREAMBLE: &str = concat!(
"<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n",
"<!DOCTYPE nmaprun>\n",
"<?xml-stylesheet href=\"file:///usr/share/nmap/nmap.xsl\" type=\"text/xsl\"?>\n",
"<!-- Nmap 7.99 scan initiated Tue Aug 11 19:09:27 2026 as: nmap -oX out.xml -->\n",
);
fn options() -> ImportOptions<'static> {
ImportOptions::new(PortSet::try_from("80").unwrap())
}
fn read(input: &str) -> Result<Imported, ImportError> {
ImportFormat::NmapXml.read(&mut Cursor::new(input), &options())
}
#[test]
fn a_real_nmap_document_reads_as_its_hosts_and_ports() {
let document = format!(
"{REAL_PREAMBLE}{}",
concat!(
r#"<nmaprun scanner="nmap" args="nmap -oX out.xml 10.0.0.0/24" start="1786468167" version="7.99" xmloutputversion="1.05">"#,
"\n<scaninfo type=\"syn\" protocol=\"tcp\" numservices=\"1000\" services=\"1,3-4,6-7,9,13,17,19-26\"/>\n",
"<verbose level=\"0\"/>\n<debugging level=\"0\"/>\n",
"<host starttime=\"1\" endtime=\"2\">\n",
"<status state=\"up\" reason=\"echo-reply\" reason_ttl=\"64\"/>\n",
"<address addr=\"10.0.0.1\" addrtype=\"ipv4\"/>\n",
"<address addr=\"aa:bb:cc:dd:ee:ff\" addrtype=\"mac\" vendor=\"Arris\"/>\n",
"<hostnames>\n<hostname name=\"router.lan\" type=\"PTR\"/>\n</hostnames>\n",
"<ports>\n",
"<extraports state=\"closed\" count=\"998\"><extrareasons reason=\"resets\" count=\"998\"/></extraports>\n",
"<port protocol=\"tcp\" portid=\"22\"><state state=\"open\" reason=\"syn-ack\" reason_ttl=\"64\"/><service name=\"ssh\" product=\"OpenSSH\" method=\"probed\" conf=\"10\"/></port>\n",
"<port protocol=\"udp\" portid=\"53\"><state state=\"open\" reason=\"udp-response\"/></port>\n",
"</ports>\n<times srtt=\"39\" rttvar=\"5000\" to=\"100000\"/>\n</host>\n",
"<host><status state=\"up\" reason=\"conn-refused\"/><address addr=\"2001:db8::1\" addrtype=\"ipv6\"/></host>\n",
"<runstats><finished time=\"3\" elapsed=\"0.01\" exit=\"success\"/><hosts up=\"2\" down=\"0\" total=\"2\"/></runstats>\n",
"</nmaprun>\n",
)
);
let imported = read(&document).expect("a real nmap document reads");
assert_eq!(imported.addresses, 2, "one IPv4 host and one IPv6 host");
assert!(
imported
.map
.units
.iter()
.any(|unit| unit.ports().has_tcp(22) && unit.ports().has_udp(53)),
"the ports nmap found have to come back on the host it found them on"
);
assert!(
imported
.map
.units
.iter()
.any(|unit| unit.ports().has_tcp(80)),
"the host with no ports takes the caller's defaults"
);
}
#[test]
fn the_preamble_nmap_actually_writes_is_accepted() {
let document = format!(
"{REAL_PREAMBLE}<nmaprun><host><address addr=\"10.0.0.1\" addrtype=\"ipv4\"/></host></nmaprun>"
);
assert_eq!(read(&document).expect("accepted").addresses, 1);
}
#[test]
fn an_entity_declaration_is_refused_outright() {
let document = concat!(
r#"<?xml version="1.0"?>"#,
"\n<!DOCTYPE nmaprun [\n",
" <!ENTITY lol \"lol\">\n",
" <!ENTITY lol2 \"&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;&lol;\">\n",
" <!ENTITY lol3 \"&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;&lol2;\">\n",
"]>\n",
r#"<nmaprun><host><address addr="&lol3;" addrtype="ipv4"/></host></nmaprun>"#,
);
let error = read(document).expect_err("an internal subset is refused");
let message = error.to_string();
assert!(
message.contains("internal subset"),
"the refusal has to say what it refused: {message}"
);
}
#[test]
fn an_external_entity_is_refused_at_the_doctype() {
for document in [
concat!(
r#"<!DOCTYPE nmaprun [<!ENTITY xxe SYSTEM "file:///etc/passwd">]>"#,
r#"<nmaprun><host><address addr="&xxe;" addrtype="ipv4"/></host></nmaprun>"#,
),
concat!(
r#"<!DOCTYPE nmaprun SYSTEM "http://example.invalid/evil.dtd">"#,
r#"<nmaprun><host><address addr="10.0.0.1" addrtype="ipv4"/></host></nmaprun>"#,
),
concat!(
r#"<!DOCTYPE nmaprun PUBLIC "-//x//y" "http://example.invalid/evil.dtd">"#,
r#"<nmaprun><host><address addr="10.0.0.1" addrtype="ipv4"/></host></nmaprun>"#,
),
] {
let error = read(document).expect_err("refused");
assert!(matches!(error, ImportError::Malformed { .. }), "{error:?}");
}
}
#[test]
fn an_undeclared_entity_reference_is_refused_naming_it() {
let document =
r#"<nmaprun><host><address addr="&secret;" addrtype="ipv4"/></host></nmaprun>"#;
let message = read(document).expect_err("refused").to_string();
assert!(message.contains("secret"), "{message}");
}
#[test]
fn the_predefined_and_numeric_references_resolve() {
let document =
r#"<nmaprun><host><address addr="a&bA" addrtype="ipv4"/></host></nmaprun>"#;
let message = read(document)
.expect_err("'a&bA' is not an address")
.to_string();
assert!(
message.contains("a&bA"),
"the entity was not resolved: {message}"
);
}
#[test]
fn a_document_that_is_not_nmaps_is_refused() {
let message = read("<rss><channel><item/></channel></rss>")
.expect_err("not an nmap document")
.to_string();
assert!(message.contains("nmaprun"), "{message}");
}
#[test]
fn nesting_past_the_limit_is_refused() {
let deep = format!(
"<nmaprun>{}{}</nmaprun>",
"<a>".repeat(MAX_DEPTH + 8),
"</a>".repeat(MAX_DEPTH + 8)
);
let error = read(&deep).expect_err("refused");
assert!(error.to_string().contains("nested"), "{error}");
}
#[test]
fn an_element_past_the_byte_limit_is_refused() {
let options = options().with_limits(ImportLimits {
max_line_bytes: 256,
..ImportLimits::default()
});
let runaway = format!("<nmaprun><host attr=\"{}\"/></nmaprun>", "x".repeat(4096));
assert!(matches!(
ImportFormat::NmapXml.read(&mut Cursor::new(runaway), &options),
Err(ImportError::LineTooLong { .. })
));
}
#[test]
fn a_long_attribute_this_parser_ignores_is_not_a_problem() {
let services: String = (1..2000).map(|port| format!("{port},")).collect();
let document = format!(
"<nmaprun><scaninfo services=\"{services}\"/>\
<host><address addr=\"10.0.0.1\" addrtype=\"ipv4\"/></host></nmaprun>"
);
assert_eq!(read(&document).expect("reads").addresses, 1);
}
#[test]
fn an_unknown_transport_is_refused() {
let document = concat!(
r#"<nmaprun><host><address addr="10.0.0.1" addrtype="ipv4"/>"#,
r#"<ports><port protocol="sctp" portid="9"><state state="open"/></port></ports>"#,
r#"</host></nmaprun>"#,
);
let message = read(document).expect_err("refused").to_string();
assert!(message.contains("sctp"), "{message}");
}
#[test]
fn an_empty_document_is_refused_and_a_hostless_one_is_not() {
assert!(read("").is_err(), "nothing is not an nmap document");
let imported = read("<nmaprun><runstats/></nmaprun>").expect("a scan that found nothing");
assert_eq!(imported.tokens, 0);
assert!(imported.map.is_empty());
}
#[test]
#[ignore = "needs a real nmap file named by ZOND_NMAP_XML"]
fn a_file_nmap_itself_wrote() {
let path =
std::env::var("ZOND_NMAP_XML").expect("set ZOND_NMAP_XML to a file nmap produced");
let document = std::fs::read_to_string(&path).expect("the file is readable");
let imported = ImportFormat::NmapXml
.read(&mut Cursor::new(document), &options())
.expect("a file nmap wrote has to read");
println!(
"{path}: {} addresses, {} refused",
imported.addresses,
imported.refusals.len()
);
for unit in &imported.map.units {
let ports: Vec<String> = unit
.ports()
.iter()
.map(|(number, protocol)| format!("{number}/{protocol:?}"))
.collect();
println!(" {} addresses on {}", unit.ips().len(), ports.join(", "));
}
assert!(
imported.addresses > 0,
"a real scan's output produced no targets at all"
);
}
#[cfg(feature = "export-nmap")]
#[test]
fn a_document_this_engine_wrote_reads_back_as_its_own_targets() {
use crate::export::{ExportOptions, Exporter, NmapXmlExporter};
use std::collections::BTreeSet;
let report = crate::export::fixture::report();
let mut expected: BTreeSet<(String, u16)> = BTreeSet::new();
for host in report.hosts() {
for ip in host.ips() {
if host.port_count() == 0 {
expected.insert((ip.to_string(), 80));
continue;
}
for port in host.ports() {
expected.insert((ip.to_string(), port.number()));
}
}
}
let mut document = Vec::new();
NmapXmlExporter::new(ExportOptions::new())
.export(&report, &mut document)
.expect("the fixture exports");
let imported = ImportFormat::NmapXml
.read(&mut Cursor::new(document), &options())
.expect("this engine reads back what it wrote");
let mut found: BTreeSet<(String, u16)> = BTreeSet::new();
for target in imported.map.iter() {
found.insert((target.ip.to_string(), target.port));
}
assert_eq!(
found, expected,
"the hosts and ports the scan found are not the ones that came back"
);
assert!(
!expected.is_empty(),
"a fixture with no ports proves nothing"
);
}
}