use std::io::Write;
use crate::core::models::host::Host;
use crate::core::models::port::Port;
use crate::core::report::ScanReport;
use crate::export::schema::{
host_status_name, network_role_name, port_state_name, protocol_name, scan_response_name,
};
use crate::export::time::rfc3339;
use crate::export::{ExportError, ExportOptions, Exporter};
pub const COLUMNS: [&str; 25] = [
"ip",
"hostname",
"status",
"alive",
"ips",
"mac",
"mac_vendor",
"os",
"os_accuracy",
"roles",
"rtt_median_us",
"ttl",
"first_seen",
"last_seen",
"port",
"protocol",
"state",
"service",
"service_product",
"service_version",
"service_confidence",
"discovery_reason",
"tls_version",
"cert_common_name",
"cert_not_after",
];
const FORMULA_LEADERS: [char; 5] = ['=', '+', '-', '@', '\t'];
const UTF8_BOM: &[u8] = &[0xEF, 0xBB, 0xBF];
#[derive(Debug, Clone, Default)]
pub struct CsvExporter {
options: ExportOptions,
excel_bom: bool,
}
impl CsvExporter {
pub fn new(options: ExportOptions) -> Self {
Self {
options,
excel_bom: false,
}
}
pub fn with_excel_bom(mut self) -> Self {
self.excel_bom = true;
self
}
pub fn options(&self) -> &ExportOptions {
&self.options
}
}
impl Exporter for CsvExporter {
fn export(&self, report: &ScanReport, out: &mut dyn Write) -> Result<(), ExportError> {
if self.excel_bom {
out.write_all(UTF8_BOM)?;
}
let mut row = Row::new();
for column in COLUMNS {
row.push(column);
}
row.finish(out)?;
for host in report.hosts() {
let host_columns = HostColumns::new(host, &self.options);
if host.port_count() == 0 {
let mut row = Row::new();
host_columns.write(&mut row);
for _ in 0..PORT_COLUMNS {
row.push("");
}
row.finish(out)?;
continue;
}
for port in host.ports() {
let mut row = Row::new();
host_columns.write(&mut row);
write_port(&mut row, port, &self.options);
row.finish(out)?;
}
}
Ok(())
}
}
const PORT_COLUMNS: usize = 11;
struct HostColumns {
ip: String,
hostname: String,
status: &'static str,
alive: &'static str,
ips: String,
mac: String,
mac_vendor: String,
os: String,
os_accuracy: String,
roles: String,
rtt_median_us: String,
ttl: String,
first_seen: String,
last_seen: String,
}
impl HostColumns {
fn new(host: &Host, options: &ExportOptions) -> Self {
let redaction = options.redaction;
let mut roles: Vec<&str> = host
.network_roles()
.iter()
.copied()
.map(network_role_name)
.collect();
roles.sort_unstable();
Self {
ip: host.primary_ip().to_string(),
hostname: host
.hostname()
.map(|name| redaction.hostname(name).into_owned())
.unwrap_or_default(),
status: host_status_name(host.status()),
alive: bool_cell(host.is_alive()),
ips: join(host.ips().iter().map(|ip| ip.to_string())),
mac: host
.mac()
.map(|mac| redaction.mac(&mac))
.unwrap_or_default(),
mac_vendor: host.vendor().unwrap_or_default().to_string(),
os: host.os().map(|os| os.name.to_string()).unwrap_or_default(),
os_accuracy: host
.os()
.map(|os| os.accuracy.to_string())
.unwrap_or_default(),
roles: join(roles.into_iter().map(str::to_string)),
rtt_median_us: host
.median_rtt()
.map(|rtt| rtt.as_micros().to_string())
.unwrap_or_default(),
ttl: host
.telemetry()
.ttl
.map(|ttl| ttl.to_string())
.unwrap_or_default(),
first_seen: rfc3339(host.first_seen()),
last_seen: rfc3339(host.last_seen()),
}
}
fn write(&self, row: &mut Row) {
row.push(&self.ip);
row.push(&self.hostname);
row.push(self.status);
row.push(self.alive);
row.push(&self.ips);
row.push(&self.mac);
row.push(&self.mac_vendor);
row.push(&self.os);
row.push(&self.os_accuracy);
row.push(&self.roles);
row.push(&self.rtt_median_us);
row.push(&self.ttl);
row.push(&self.first_seen);
row.push(&self.last_seen);
}
}
fn write_port(row: &mut Row, port: &Port, options: &ExportOptions) {
let service = port.service();
let certificate = port.security().and_then(|security| security.certificate());
row.push(port.number().to_string());
row.push(protocol_name(port.protocol()));
row.push(port_state_name(port.state()));
row.push(service.map(|service| service.name()).unwrap_or_default());
row.push(
service
.and_then(|service| service.product())
.unwrap_or_default(),
);
row.push(
service
.and_then(|service| service.version())
.unwrap_or_default(),
);
row.push(
service
.map(|service| service.confidence().to_string())
.unwrap_or_default(),
);
row.push(
port.discovery()
.map(|discovery| scan_response_name(discovery.reason()).into_owned())
.unwrap_or_default(),
);
row.push(
port.security()
.and_then(|security| security.tls_version())
.unwrap_or_default(),
);
row.push(
certificate
.map(|cert| options.redaction.hostname(cert.common_name()).into_owned())
.unwrap_or_default(),
);
row.push(
certificate
.map(|cert| rfc3339(cert.validity_end()))
.unwrap_or_default(),
);
}
fn bool_cell(value: bool) -> &'static str {
if value { "true" } else { "false" }
}
fn join(values: impl Iterator<Item = String>) -> String {
values.collect::<Vec<_>>().join(" ")
}
struct Row {
text: String,
fields: usize,
}
impl Row {
fn new() -> Self {
Self {
text: String::new(),
fields: 0,
}
}
fn push(&mut self, field: impl AsRef<str>) {
if self.fields > 0 {
self.text.push(',');
}
self.fields += 1;
let field = field.as_ref();
let needs_formula_guard = field.starts_with(FORMULA_LEADERS) || field.starts_with('\r');
let needs_quotes = needs_formula_guard
|| field.contains([',', '"', '\n', '\r'])
|| field.starts_with(' ')
|| field.ends_with(' ');
if !needs_quotes {
self.text.push_str(field);
return;
}
self.text.push('"');
if needs_formula_guard {
self.text.push('\'');
}
for character in field.chars() {
if character == '"' {
self.text.push('"');
}
self.text.push(character);
}
self.text.push('"');
}
fn finish(mut self, out: &mut dyn Write) -> Result<(), ExportError> {
debug_assert_eq!(
self.fields,
COLUMNS.len(),
"every row must have one field per column"
);
self.text.push('\n');
out.write_all(self.text.as_bytes())?;
Ok(())
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::export::{Redaction, fixture};
fn parse_row(line: &str) -> Vec<String> {
let mut fields = Vec::new();
let mut field = String::new();
let mut quoted = false;
let mut characters = line.chars().peekable();
while let Some(character) = characters.next() {
match character {
'"' if !quoted && field.is_empty() => quoted = true,
'"' if quoted => {
if characters.peek() == Some(&'"') {
characters.next();
field.push('"');
} else {
quoted = false;
}
}
',' if !quoted => fields.push(std::mem::take(&mut field)),
other => field.push(other),
}
}
fields.push(field);
fields
}
fn rows(exporter: &CsvExporter) -> Vec<Vec<String>> {
String::from_utf8(bytes(exporter, &fixture::report()))
.expect("utf-8")
.lines()
.map(parse_row)
.collect()
}
fn bytes(exporter: &CsvExporter, report: &crate::core::report::ScanReport) -> Vec<u8> {
let mut bytes = Vec::new();
exporter
.export(report, &mut bytes)
.expect("the export succeeds");
bytes
}
fn column(row: &[String], name: &str) -> String {
let index = COLUMNS
.iter()
.position(|column| *column == name)
.expect("a known column");
row[index].clone()
}
#[test]
fn every_host_and_port_pairing_gets_a_row() {
let rows = rows(&CsvExporter::new(ExportOptions::new()));
assert_eq!(rows[0], COLUMNS.to_vec());
assert_eq!(rows.len(), 1 + 3 + 1 + 1);
for row in &rows {
assert_eq!(
row.len(),
COLUMNS.len(),
"a row with the wrong column count shifts every value after it"
);
}
assert_eq!(column(&rows[1], "ip"), "192.168.0.1");
assert_eq!(column(&rows[1], "port"), "22");
assert_eq!(column(&rows[2], "port"), "80");
assert_eq!(column(&rows[3], "port"), "443");
assert_eq!(column(&rows[4], "ip"), "192.168.0.2");
}
#[test]
fn a_host_with_no_ports_still_gets_a_row() {
let rows = rows(&CsvExporter::new(ExportOptions::new()));
let bare = rows.last().expect("a final row");
assert_eq!(column(bare, "ip"), "192.168.0.9");
assert_eq!(column(bare, "status"), "down");
assert_eq!(column(bare, "port"), "");
assert_eq!(column(bare, "state"), "");
assert_eq!(column(bare, "protocol"), "");
}
#[test]
fn a_row_carries_the_host_and_the_port_together() {
let rows = rows(&CsvExporter::new(ExportOptions::new()));
let ssh = &rows[1];
assert_eq!(column(ssh, "hostname"), "router.local");
assert_eq!(column(ssh, "mac_vendor"), "Raspberry Pi Trading Ltd");
assert_eq!(column(ssh, "os"), "Linux");
assert_eq!(column(ssh, "os_accuracy"), "95");
assert_eq!(column(ssh, "roles"), "gateway");
assert_eq!(column(ssh, "rtt_median_us"), "1800");
assert_eq!(column(ssh, "service"), "ssh");
assert_eq!(column(ssh, "service_product"), "OpenSSH");
assert_eq!(column(ssh, "service_version"), "8.9p1");
assert_eq!(column(ssh, "discovery_reason"), "tcp_syn_ack");
let https = &rows[3];
assert_eq!(column(https, "tls_version"), "TLSv1.3");
assert_eq!(column(https, "cert_common_name"), "router.local");
assert_eq!(
column(https, "cert_not_after"),
"2027-01-01T00:00:00.000000Z"
);
}
#[test]
fn redaction_applies_to_every_column_that_names_something() {
let rows = rows(&CsvExporter::new(
ExportOptions::new().with_redaction(Redaction::Standard),
));
assert_eq!(column(&rows[1], "hostname"), "roXXXXXal");
assert_eq!(column(&rows[1], "mac"), "2c:cf:67:XX:XX:XX");
assert_eq!(column(&rows[3], "cert_common_name"), "roXXXXXal");
assert_eq!(column(&rows[1], "mac_vendor"), "Raspberry Pi Trading Ltd");
}
#[test]
fn a_cell_that_would_execute_is_neutralised() {
let mut row = Row::new();
row.push("=cmd|'/c calc'!A1");
row.push("+1+1");
row.push("-2+3");
row.push("@SUM(A1)");
row.push("\tstarts-with-tab");
row.push("harmless=inside");
assert_eq!(
row.text,
"\"'=cmd|'/c calc'!A1\",\"'+1+1\",\"'-2+3\",\"'@SUM(A1)\",\"'\tstarts-with-tab\",harmless=inside"
);
for field in parse_row(&row.text).iter().take(5) {
assert!(field.starts_with('\''), "{field} escaped the guard");
}
}
#[test]
fn ordinary_values_are_left_alone() {
let rows = rows(&CsvExporter::new(ExportOptions::new()));
for row in rows.iter().skip(1) {
for field in row {
assert!(
!field.starts_with('\''),
"a real scan value tripped the formula guard: {field}"
);
}
}
}
#[test]
fn separators_and_quotes_survive_a_round_trip() {
let awkward = [
"plain",
"has,comma",
"has\"quote",
"has\nnewline",
"has\r\ncrlf",
" leading space",
"trailing space ",
"",
];
let mut row = Row::new();
for field in awkward {
row.push(field);
}
assert_eq!(parse_row(&row.text), awkward.to_vec());
}
#[test]
fn the_excel_byte_order_mark_is_opt_in() {
let report = fixture::report();
let without = bytes(&CsvExporter::new(ExportOptions::new()), &report);
assert!(without.starts_with(b"ip,"));
let with = bytes(
&CsvExporter::new(ExportOptions::new()).with_excel_bom(),
&report,
);
assert!(with.starts_with(UTF8_BOM));
assert_eq!(&with[UTF8_BOM.len()..], &without[..]);
}
#[test]
fn a_failing_destination_surfaces_as_an_error() {
struct Full;
impl Write for Full {
fn write(&mut self, _: &[u8]) -> std::io::Result<usize> {
Err(std::io::Error::new(
std::io::ErrorKind::StorageFull,
"no space left on device",
))
}
fn flush(&mut self) -> std::io::Result<()> {
Ok(())
}
}
let error = CsvExporter::new(ExportOptions::new())
.export(&fixture::report(), &mut Full)
.expect_err("a full disk fails the export");
assert!(matches!(error, ExportError::Io(_)), "got {error:?}");
}
}