#[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 = 256 * 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
}
}
struct Bounded<'a> {
inner: &'a mut dyn BufRead,
left: u64,
exhausted: bool,
}
impl<'a> Bounded<'a> {
fn new(inner: &'a mut dyn BufRead, limit: u64) -> Self {
Self {
inner,
left: limit,
exhausted: false,
}
}
fn over_budget(&mut self) -> std::io::Error {
self.exhausted = true;
std::io::Error::new(
std::io::ErrorKind::InvalidData,
"the document is past its byte ceiling",
)
}
}
impl Bounded<'_> {
fn overran(&mut self) -> std::io::Result<bool> {
Ok(self.left == 0 && !self.inner.fill_buf()?.is_empty())
}
}
impl std::io::Read for Bounded<'_> {
fn read(&mut self, buf: &mut [u8]) -> std::io::Result<usize> {
if self.overran()? {
return Err(self.over_budget());
}
let ceiling = usize::try_from(self.left).unwrap_or(usize::MAX);
let take = buf.len().min(ceiling);
let read = self.inner.read(&mut buf[..take])?;
self.left -= read as u64;
Ok(read)
}
}
impl BufRead for Bounded<'_> {
fn fill_buf(&mut self) -> std::io::Result<&[u8]> {
if self.overran()? {
return Err(self.over_budget());
}
let ceiling = usize::try_from(self.left).unwrap_or(usize::MAX);
let available = self.inner.fill_buf()?;
Ok(&available[..available.len().min(ceiling)])
}
fn consume(&mut self, amount: usize) {
self.left = self.left.saturating_sub(amount as u64);
self.inner.consume(amount);
}
}
#[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),
}
}
pub fn read(
self,
input: &mut dyn BufRead,
options: ReportOptions,
) -> Result<ScanReport, ImportError> {
let limit = options.max_document_bytes;
let mut bounded = Bounded::new(input, limit);
let read = match self {
#[cfg(feature = "import-json")]
ReportFormat::Json => json::JsonReportReader::new(options).read(&mut bounded),
#[cfg(feature = "import-json")]
ReportFormat::JsonLines => json::JsonLinesReportReader::new(options).read(&mut bounded),
#[cfg(feature = "import-nmap")]
ReportFormat::Nmap => nmap::NmapXmlReportReader::new(options).read(&mut bounded),
};
match read {
Err(_) if bounded.exhausted => Err(ImportError::DocumentTooLarge { limit }),
other => other,
}
}
}
#[cfg(all(test, feature = "import-json", feature = "import-nmap"))]
mod tests {
use std::io::Cursor;
use std::path::Path;
use super::*;
#[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.168.0.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"
);
}
#[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
);
}
}