#[cfg(feature = "import-json")]
pub mod json;
#[cfg(feature = "import-nmap")]
pub mod nmap;
use std::io::BufRead;
use std::path::Path;
use crate::import::{ImportError, ImportLimits};
use crate::report::ScanReport;
pub trait ReportReader {
fn read(&self, input: &mut dyn BufRead) -> Result<ScanReport, ImportError>;
}
#[must_use]
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ReportOptions {
pub limits: ImportLimits,
pub max_document_bytes: u64,
}
const DEFAULT_MAX_DOCUMENT_BYTES: u64 = 1024 * 1024 * 1024;
impl Default for ReportOptions {
fn default() -> Self {
Self {
limits: ImportLimits::default(),
max_document_bytes: DEFAULT_MAX_DOCUMENT_BYTES,
}
}
}
impl ReportOptions {
pub fn new() -> Self {
Self::default()
}
pub fn with_limits(mut self, limits: ImportLimits) -> Self {
self.limits = limits;
self
}
pub fn with_max_document_bytes(mut self, bytes: u64) -> Self {
self.max_document_bytes = bytes;
self
}
}
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ReportFormat {
#[cfg(feature = "import-json")]
Json,
#[cfg(feature = "import-json")]
JsonLines,
#[cfg(feature = "import-nmap")]
Nmap,
}
impl ReportFormat {
pub fn from_extension(extension: &str) -> Option<Self> {
match extension
.trim_start_matches('.')
.to_ascii_lowercase()
.as_str()
{
#[cfg(feature = "import-json")]
"json" => Some(ReportFormat::Json),
#[cfg(feature = "import-json")]
"jsonl" | "ndjson" => Some(ReportFormat::JsonLines),
#[cfg(feature = "import-nmap")]
"xml" => Some(ReportFormat::Nmap),
_ => None,
}
}
pub fn extension(self) -> &'static str {
match self {
#[cfg(feature = "import-json")]
ReportFormat::Json => "json",
#[cfg(feature = "import-json")]
ReportFormat::JsonLines => "jsonl",
#[cfg(feature = "import-nmap")]
ReportFormat::Nmap => "xml",
}
}
pub fn all() -> &'static [ReportFormat] {
&[
#[cfg(feature = "import-json")]
ReportFormat::Json,
#[cfg(feature = "import-json")]
ReportFormat::JsonLines,
#[cfg(feature = "import-nmap")]
ReportFormat::Nmap,
]
}
pub fn from_path(path: &Path) -> Option<Self> {
path.extension()
.and_then(|extension| extension.to_str())
.and_then(Self::from_extension)
}
pub fn sniff(input: &mut dyn BufRead) -> Result<Self, ImportError> {
#[cfg(feature = "import-json")]
const REPORT_TAG: &[u8] = br#""type":"report""#;
let available = input.fill_buf()?;
let prefix = crate::import::without_bom(available).trim_ascii_start();
let _ = &prefix;
#[cfg(feature = "import-nmap")]
if prefix.first() == Some(&b'<') {
return Ok(ReportFormat::Nmap);
}
#[cfg(feature = "import-json")]
if prefix.first() == Some(&b'{') {
let head = &prefix[..prefix.len().min(256)];
let tagged = head
.windows(REPORT_TAG.len())
.any(|window| window == REPORT_TAG);
return Ok(if tagged {
ReportFormat::JsonLines
} else {
ReportFormat::Json
});
}
Err(ImportError::Malformed {
format: "report",
origin: crate::import::ImportOrigin::unknown(),
message: "the input begins as neither a JSON document nor an XML one".to_string(),
})
}
pub fn resolve(path: Option<&Path>, input: &mut dyn BufRead) -> Result<Self, ImportError> {
match path.and_then(Self::from_path) {
Some(format) => Ok(format),
None => Self::sniff(input),
}
}
#[cfg_attr(
not(any(feature = "import-json", feature = "import-nmap")),
allow(unused_variables)
)]
pub fn read(
self,
input: &mut dyn BufRead,
options: ReportOptions,
) -> Result<ScanReport, ImportError> {
match self {
#[cfg(feature = "import-json")]
ReportFormat::Json => json::JsonReportReader::new(options).read(input),
#[cfg(feature = "import-json")]
ReportFormat::JsonLines => json::JsonLinesReportReader::new(options).read(input),
#[cfg(feature = "import-nmap")]
ReportFormat::Nmap => nmap::NmapXmlReportReader::new(options).read(input),
}
}
}
#[cfg(all(test, feature = "import-json", feature = "import-nmap"))]
mod tests {
use std::io::Cursor;
use std::path::Path;
use super::*;
#[test]
fn a_reader_used_directly_holds_a_document_to_its_byte_ceiling() {
let options = ReportOptions::new().with_max_document_bytes(16);
let json = format!("{{\"hosts\": []{}}}", " ".repeat(64));
let xml = format!("<nmaprun>{}</nmaprun>", "<a/>".repeat(16));
let readers: [(&dyn ReportReader, &str); 3] = [
(&json::JsonReportReader::new(options), &json),
(&json::JsonLinesReportReader::new(options), &json),
(&nmap::NmapXmlReportReader::new(options), &xml),
];
for (reader, document) in readers {
let read = reader.read(&mut Cursor::new(document.as_bytes()));
assert!(
matches!(read, Err(ImportError::DocumentTooLarge { limit: 16 })),
"{document}: {read:?}"
);
}
}
#[test]
fn an_extension_names_the_format() {
assert_eq!(
ReportFormat::from_path(Path::new("engagement/scan.xml")),
Some(ReportFormat::Nmap)
);
assert_eq!(
ReportFormat::from_path(Path::new("scan.JSON")),
Some(ReportFormat::Json)
);
assert_eq!(ReportFormat::from_path(Path::new("scan.txt")), None);
}
#[test]
fn the_first_byte_names_the_format_when_nothing_else_does() {
let mut json = Cursor::new(b" {\"schema_version\":1}".as_slice());
assert_eq!(ReportFormat::sniff(&mut json).unwrap(), ReportFormat::Json);
let mut xml = Cursor::new(b"<?xml version=\"1.0\"?><nmaprun/>".as_slice());
assert_eq!(ReportFormat::sniff(&mut xml).unwrap(), ReportFormat::Nmap);
let mut neither = Cursor::new(b"192.0.2.1\n".as_slice());
assert!(ReportFormat::sniff(&mut neither).is_err());
}
#[test]
fn sniffing_leaves_the_input_where_it_found_it() {
let document = b"<?xml version=\"1.0\"?><nmaprun/>";
let mut input = Cursor::new(document.as_slice());
let format = ReportFormat::sniff(&mut input).unwrap();
let report = format.read(&mut input, ReportOptions::new());
assert!(
report.is_ok(),
"a sniff must not consume the bytes the reader needs: {report:?}"
);
}
#[test]
fn a_byte_order_mark_hides_neither_format() {
let marked = |text: &str| {
let mut bytes = crate::format::UTF8_BOM.to_vec();
bytes.extend_from_slice(text.as_bytes());
Cursor::new(bytes)
};
for (document, expected) in [
(r#"{"schema_version":1}"#, ReportFormat::Json),
(
"{\"type\":\"report\",\"schema_version\":1}\n",
ReportFormat::JsonLines,
),
(r#"<?xml version="1.0"?><nmaprun/>"#, ReportFormat::Nmap),
] {
assert_eq!(
ReportFormat::sniff(&mut marked(document)).expect("sniffs"),
expected,
"{document}"
);
}
let mut input = marked(r#"<?xml version="1.0"?><nmaprun/>"#);
let format = ReportFormat::sniff(&mut input).expect("sniffs");
assert!(
format.read(&mut input, ReportOptions::new()).is_ok(),
"the format was recognised and then refused the same bytes"
);
}
#[cfg(all(
feature = "export-json",
feature = "export-jsonl",
feature = "export-nmap"
))]
mod own_exports {
use std::io::Cursor;
use std::net::{IpAddr, Ipv4Addr};
use std::time::Duration;
use super::super::*;
use crate::export::{
ExportOptions, Exporter, JsonExporter, JsonLinesExporter, NmapXmlExporter,
};
use crate::import::xml::elements_within;
use crate::model::host::Host;
use crate::model::port::{Discovery, Port, PortState, Protocol, ScanResponse};
const FULL_RANGE_HOSTS_AS_JSON: u64 = 32;
const FULL_RANGE_HOSTS_AS_JSON_LINES: u64 = 64;
const FULL_RANGE_HOSTS_AS_XML: u64 = 128;
fn full_range_report() -> ScanReport {
let ip = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1));
let mut host = Host::new(ip);
for number in 1..=u16::MAX {
host.add_port(
Port::new(number, Protocol::Tcp, PortState::Closed).with_discovery(
Discovery::new(ScanResponse::TcpRst)
.with_rtt(Duration::from_micros(1_234))
.with_ttl(64),
),
);
}
ScanReport::recorded("zond", Vec::new(), vec![host])
}
fn written(exporter: &dyn Exporter, report: &ScanReport) -> Vec<u8> {
let mut out = Vec::new();
exporter.export(report, &mut out).expect("exports");
out
}
#[test]
fn a_full_range_host_reads_back_from_its_own_record_per_line_export() {
let report = full_range_report();
let document = written(&JsonLinesExporter::new(ExportOptions::new()), &report);
let restored = ReportFormat::JsonLines
.read(&mut Cursor::new(document), ReportOptions::new())
.expect("a document this engine wrote reads back");
let host = restored.hosts().next().expect("the host");
assert_eq!(host.port_count(), usize::from(u16::MAX));
}
#[test]
fn the_default_ceiling_admits_the_full_range_hosts_it_promises() {
let report = full_range_report();
let ceiling = ReportOptions::new().max_document_bytes;
let json = written(&JsonExporter::new(ExportOptions::new()), &report).len() as u64;
let lines =
written(&JsonLinesExporter::new(ExportOptions::new()), &report).len() as u64;
let xml = written(&NmapXmlExporter::new(ExportOptions::new()), &report);
let elements = xml
.windows(2)
.filter(|pair| pair[0] == b'<' && pair[1].is_ascii_alphabetic())
.count() as u64;
let xml = xml.len() as u64;
for (format, bytes, promised) in [
("indented JSON", json, FULL_RANGE_HOSTS_AS_JSON),
("JSON lines", lines, FULL_RANGE_HOSTS_AS_JSON_LINES),
("nmap XML", xml, FULL_RANGE_HOSTS_AS_XML),
] {
assert!(
bytes * promised <= ceiling,
"{promised} full-range hosts of {format} are {} bytes, past the {ceiling}-byte ceiling",
bytes * promised,
);
}
assert!(
ceiling / xml * elements <= elements_within(ceiling),
"a document of full-range hosts at the byte ceiling holds {} elements, past {}",
ceiling / xml * elements,
elements_within(ceiling),
);
}
}
#[test]
fn an_extension_outranks_what_the_bytes_look_like() {
let mut input = Cursor::new(b"{}".as_slice());
assert_eq!(
ReportFormat::resolve(Some(Path::new("scan.xml")), &mut input).unwrap(),
ReportFormat::Nmap
);
}
}