Skip to main content

zond_engine/
record.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//! # The model, as data that can be written down and read back
10//!
11//! [`model`](crate::model) holds the domain: types with invariants, private
12//! fields, and no opinion about serialization. This module is the same
13//! information in a shape that survives a file.
14//!
15//! ## Why the model does not serialize itself
16//!
17//! Deriving `serde` on [`Host`] and its neighbours would tie the file format to the
18//! struct layout, bypass the constructors' invariants (a rebuilt host could have an
19//! `open_port_count` that disagrees with its ports), and make `Serialize` public API.
20//! It also does not compile: [`RttSample`](crate::model::host::telemetry::RttSample)
21//! carries an [`Instant`](std::time::Instant), which means nothing outside its process.
22//!
23//! So the conversion lives here: reading uses the model's getters and rebuilding its
24//! constructors, so a rebuilt value passes the same checks a scanned one did.
25//!
26//! ## What does not survive
27//!
28//! - **Round-trip sample timestamps**, which are monotonic
29//!   [`Instant`](std::time::Instant)s. A rebuilt host keeps the durations and restamps
30//!   them.
31//! - **Nothing else.** `a_fully_populated_host_survives_a_round_trip` checks that.
32//!
33//! ## Not `#[non_exhaustive]`
34//!
35//! A record is interchange, written out as a struct literal naming every field. A new
36//! field is a breaking change; the serialized shape is versioned by
37//! [`JOURNAL_VERSION`](crate::journal::JOURNAL_VERSION) for a journal and
38//! [`SCHEMA_VERSION`](crate::format::SCHEMA_VERSION) for a report, so readers are told
39//! when a document has moved.
40//!
41//! ## Who uses it
42//!
43//! [`journal`](crate::journal) writes findings as a scan produces them and reads them
44//! back to continue one. A differ, or an importer richer than
45//! [`import::json`](crate::import), would use the same reader.
46
47pub mod wire;
48
49use std::net::IpAddr;
50use std::time::{Duration, SystemTime};
51
52use serde::{Deserialize, Serialize};
53
54use crate::config::DetectionEnvelope;
55use crate::config::{IdleScan, RetryConfig, TimeoutScale};
56use crate::info;
57use crate::model::capture::CaptureCounts;
58use crate::model::confidence::Confidence;
59use crate::model::finding::{
60    DetectionClass, DetectionId, Excerpt, Exploitation, Finding, FindingGroup, Reference, Severity,
61    Version,
62};
63use crate::model::host::os::OsFingerprint;
64use crate::model::host::path::Hop;
65use crate::model::host::telemetry::{HostTelemetry, RttSource};
66use crate::model::host::{
67    EvidenceSource, HardwareInfo, Host, HostName, IpProtocolState, StatusProtocol, StatusReason,
68};
69use crate::model::host::{OsEvidence, OsSource};
70use crate::model::ip::range::{IpRange, Ipv4Range, Ipv6Range};
71use crate::model::ip::scoped::Zone;
72use crate::model::ip::set::IpSet;
73use crate::model::mac::MacAddr;
74use crate::model::port::discovery::{Discovery, ScanResponse};
75use crate::model::port::security::{CertificateInfo, Security};
76use crate::model::port::{Build, Port, PortSet, PortState, Release, ReleaseBasis, Service};
77use crate::model::target::{TargetMap, TargetSet};
78use crate::model::tls::{
79    CipherSuite, Interruption, TlsSupport, TlsVersion, UnfinishedVersion, VersionSupport,
80};
81use crate::report::ScannerKind;
82use crate::report::WindowSummary;
83use crate::report::{
84    Attachment, AttachmentSource, EvasionRecord, PhaseOrigin, PhaseParts, PortScope, ProbeStats,
85    ProbeStatsParts, Refusal, ScanKind, ScanPhase, ScanSettings, ScannerFailure, ScopeParts,
86    StopReason, TargetScope,
87};
88use crate::system::privilege::Privilege;
89use std::num::{NonZeroU8, NonZeroU32};
90
91/// One host, as a file holds it.
92#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
93pub struct HostRecord {
94    /// The address this host is reported under.
95    pub primary_ip: IpAddr,
96    /// Every address it is known to answer at, the primary included.
97    #[serde(default)]
98    pub ips: Vec<IpAddr>,
99    /// Its resolved name, if one was found.
100    #[serde(default)]
101    pub hostname: Option<String>,
102    /// The names it gave for itself, in the order the model holds them.
103    #[serde(default)]
104    pub names: Vec<NameRecord>,
105    /// Whether it answered, by wire name.
106    pub status: String,
107    /// What the status rests on.
108    #[serde(default)]
109    pub reasons: Vec<StatusReasonRecord>,
110    /// What it was identified as running.
111    #[serde(default)]
112    pub os: Option<OsRecord>,
113    /// What each source concluded about the operating system, kept so that a
114    /// later source can corroborate an earlier one.
115    #[serde(default)]
116    pub os_evidence: Vec<OsEvidenceRecord>,
117    /// Its hardware address and vendor, where the link layer reached it.
118    #[serde(default)]
119    pub hardware: Option<HardwareRecord>,
120    /// The interface a link-local address is valid on.
121    #[serde(default)]
122    pub zone: Option<ZoneRecord>,
123    /// Round-trip summary and hop counter.
124    #[serde(default)]
125    pub telemetry: TelemetryRecord,
126    /// The routers between the scanning host and this one.
127    #[serde(default)]
128    pub path: Vec<HopRecord>,
129    /// Roles inferred from where it sits or what it runs, by wire name.
130    #[serde(default)]
131    pub roles: Vec<String>,
132    /// What the filter in front of the host was shown to be doing, by wire name.
133    #[serde(default)]
134    pub filtering: Vec<String>,
135    /// What a scan concluded about each IP protocol it asked this host about,
136    /// ascending by number. Empty for a scan that did not ask.
137    ///
138    /// A list, so every key in the document is a field name; the report writes the
139    /// same list.
140    #[serde(default)]
141    pub ip_protocols: Vec<IpProtocolRecord>,
142    /// When it was first seen.
143    pub first_seen: SystemTime,
144    /// When it was last seen.
145    pub last_seen: SystemTime,
146    /// Its ports, in the order the model holds them.
147    #[serde(default)]
148    pub ports: Vec<PortRecord>,
149    /// What a detection concluded was wrong with the host as a whole, in claim
150    /// order.
151    #[serde(default)]
152    pub findings: Vec<FindingRecord>,
153}
154
155impl From<&Host> for HostRecord {
156    fn from(host: &Host) -> Self {
157        Self {
158            primary_ip: host.primary_ip(),
159            ips: host.ips().iter().copied().collect(),
160            hostname: host.hostname().map(str::to_owned),
161            // Already ordered by the model's set.
162            names: host.names().map(NameRecord::from).collect(),
163            status: wire::host_status_name(host.status()).to_owned(),
164            // Sorted, since the model holds these in a hash set and two runs must
165            // write the same file.
166            reasons: {
167                let mut reasons: Vec<_> = host
168                    .reasons()
169                    .iter()
170                    .map(StatusReasonRecord::from)
171                    .collect();
172                reasons.sort();
173                reasons
174            },
175            os: host.os().map(OsRecord::from),
176            os_evidence: host.os_evidence().map(OsEvidenceRecord::from).collect(),
177            hardware: host.hardware().map(HardwareRecord::from),
178            zone: host.zone().map(ZoneRecord::from),
179            telemetry: TelemetryRecord::from(host.telemetry()),
180            path: host.path().hops().iter().map(HopRecord::from).collect(),
181            roles: {
182                let mut roles: Vec<_> = host
183                    .network_roles()
184                    .iter()
185                    .map(|role| wire::network_role_name(*role).to_owned())
186                    .collect();
187                roles.sort();
188                roles
189            },
190            filtering: {
191                let mut filtering: Vec<_> = host
192                    .filtering()
193                    .iter()
194                    .map(|f| wire::filtering_name(*f).to_owned())
195                    .collect();
196                filtering.sort();
197                filtering
198            },
199            ip_protocols: host
200                .ip_protocols()
201                .iter()
202                .map(|(number, state)| IpProtocolRecord {
203                    protocol: *number,
204                    state: wire::ip_protocol_state_name(*state).to_owned(),
205                })
206                .collect(),
207            first_seen: host.first_seen(),
208            last_seen: host.last_seen(),
209            ports: host.ports().map(PortRecord::from).collect(),
210            // Already claim-ordered by the model's map.
211            findings: host.findings().map(FindingRecord::from).collect(),
212        }
213    }
214}
215
216impl From<&HostRecord> for Host {
217    fn from(record: &HostRecord) -> Self {
218        // A port under an unknown transport is left out (see
219        // `PortRecord::rebuild`) and the omission logged.
220        let ports = record.ports.iter().filter_map(|entry| {
221            let port = entry.rebuild();
222            if port.is_none() {
223                info!(
224                    verbosity = 2,
225                    "port {}/{} was recorded under a protocol this build cannot read; \
226                     leaving it out rather than filing it under another",
227                    entry.port,
228                    entry.protocol
229                );
230            }
231            port
232        });
233        record.rebuild_with(ports)
234    }
235}
236
237impl HostRecord {
238    /// This record as a host, holding `ports` in place of the ones it lists.
239    ///
240    /// For a reader that rebuilt a host's ports as it parsed them, so a full-range host's
241    /// port list is not held twice.
242    pub(crate) fn rebuild_with(&self, ports: impl IntoIterator<Item = Port>) -> Host {
243        let mut host = Host::new(self.primary_ip);
244
245        host.extend_ips(self.ips.iter().copied());
246        if let Some(hostname) = &self.hostname {
247            host.set_hostname(Some(hostname.clone()));
248        }
249        for name in self.names.iter().filter_map(NameRecord::rebuild) {
250            host.record_name(name);
251        }
252        // An unrecognised name leaves the status `Unknown`, which claims least.
253        if let Some(status) = wire::host_status(&self.status) {
254            host.set_status(status);
255        }
256        for reason in &self.reasons {
257            host.add_reason(reason.into());
258        }
259        if let Some(os) = &self.os {
260            host.set_os(os.into());
261        }
262        for evidence in &self.os_evidence {
263            host.record_os_evidence(evidence.into());
264        }
265        if let Some(hardware) = self.hardware.as_ref().and_then(HardwareRecord::rebuild) {
266            host.set_hardware(hardware);
267        }
268        if let Some(zone) = &self.zone {
269            host.set_zone(zone.into());
270        }
271
272        self.telemetry.restore(&mut host);
273        for hop in &self.path {
274            host.record_hop(hop.into());
275        }
276        for role in self.roles.iter().filter_map(|r| wire::network_role(r)) {
277            host.add_network_role(role);
278        }
279        for filtering in self.filtering.iter().filter_map(|f| wire::filtering(f)) {
280            host.add_filtering(filtering);
281        }
282        // An unknown state reads as `Unasked`, which claims nothing, as for ports.
283        for entry in &self.ip_protocols {
284            let state = wire::ip_protocol_state(&entry.state).unwrap_or(IpProtocolState::Unasked);
285            host.record_ip_protocol(entry.protocol, state);
286        }
287        for port in ports {
288            host.add_port(port);
289        }
290        for finding in self.findings.iter().filter_map(FindingRecord::rebuild) {
291            host.add_finding(finding);
292        }
293
294        // Last, since everything above moves `last_seen`.
295        host.restore_seen(self.first_seen, self.last_seen);
296        host
297    }
298}
299
300/// One piece of evidence for a host's reachability.
301#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
302pub struct StatusReasonRecord {
303    /// The protocol the finding came from, by wire name.
304    pub protocol: String,
305    /// The address that sent it, where that was not the host itself.
306    #[serde(default)]
307    pub source: Option<IpAddr>,
308    /// Whether something other than the host sent it, from an address the
309    /// scan's exclusions withheld. `source` is empty when it is set.
310    #[serde(default)]
311    pub source_withheld: bool,
312    /// What was observed, in words.
313    #[serde(default)]
314    pub details: Option<String>,
315}
316
317impl From<&StatusReason> for StatusReasonRecord {
318    fn from(reason: &StatusReason) -> Self {
319        Self {
320            protocol: wire::status_protocol_name(&reason.protocol).into_owned(),
321            source: reason.source.address(),
322            source_withheld: reason.source.is_withheld(),
323            details: reason.details.as_ref().map(|d| d.to_string()),
324        }
325    }
326}
327
328impl From<&StatusReasonRecord> for StatusReason {
329    fn from(record: &StatusReasonRecord) -> Self {
330        let protocol = wire::status_protocol(&record.protocol)
331            .unwrap_or_else(|| StatusProtocol::Custom(record.protocol.as_str().into()));
332
333        let mut reason = StatusReason::new(protocol, "");
334        reason.details = record.details.as_deref().map(Into::into);
335        // A withheld sender that is also named reads as withheld, which reports
336        // less.
337        reason.source = match record.source {
338            _ if record.source_withheld => EvidenceSource::Withheld,
339            Some(address) => EvidenceSource::Intermediary(address),
340            None => EvidenceSource::Host,
341        };
342        reason
343    }
344}
345
346/// What a host was identified as running.
347#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
348pub struct OsRecord {
349    /// The name to show.
350    pub name: String,
351    /// How sure the identification is, out of a hundred.
352    pub accuracy: u8,
353    /// What kind of box it is, such as `Printer`.
354    #[serde(default)]
355    pub device: Option<String>,
356    /// The broad family, such as `Linux`.
357    #[serde(default)]
358    pub family: Option<String>,
359    /// The release within the family.
360    #[serde(default)]
361    pub generation: Option<String>,
362    /// Who makes it.
363    #[serde(default)]
364    pub vendor: Option<String>,
365    /// The kernel, where one was named separately.
366    #[serde(default)]
367    pub kernel: Option<String>,
368    /// The instruction set, such as `x86_64`.
369    #[serde(default)]
370    pub arch: Option<String>,
371    /// How sure the detail beyond the family is.
372    #[serde(default)]
373    pub detail_accuracy: Option<u8>,
374    /// What the identification rests on.
375    #[serde(default)]
376    pub evidence: Option<String>,
377    /// Platform identifiers.
378    #[serde(default)]
379    pub cpes: Vec<String>,
380}
381
382/// A distributor's build of a service's software, as a file holds it.
383#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
384pub struct BuildRecord {
385    /// Who built it, by wire name.
386    pub distributor: String,
387    /// The package revision, where one was stated.
388    #[serde(default)]
389    pub revision: Option<String>,
390    /// The release it belongs to, where anything said.
391    #[serde(default)]
392    pub release: Option<ReleaseRecord>,
393}
394
395/// Which of a distributor's releases a build belongs to, as a file holds it.
396#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
397pub struct ReleaseRecord {
398    /// The release, as the distributor numbers it.
399    pub name: String,
400    /// What it was read from, by wire name.
401    pub basis: String,
402}
403
404impl From<&Build> for BuildRecord {
405    fn from(build: &Build) -> Self {
406        Self {
407            distributor: wire::distributor_name(build.distributor()).to_owned(),
408            revision: build.revision().map(str::to_owned),
409            release: build.release().map(|release| ReleaseRecord {
410                name: release.name().to_owned(),
411                basis: wire::release_basis_name(release.basis()).to_owned(),
412            }),
413        }
414    }
415}
416
417impl BuildRecord {
418    /// Rebuilds the build, or [`None`] for a distributor this engine does not
419    /// know.
420    ///
421    /// A release whose basis does not parse reads as the weaker basis, a rule's
422    /// inference; the release still says which fix data applies.
423    pub fn rebuild(&self) -> Option<Build> {
424        let mut build = Build::new(wire::distributor(&self.distributor)?);
425        if let Some(revision) = &self.revision {
426            build = build.with_revision(revision.clone());
427        }
428        if let Some(release) = &self.release {
429            let basis = wire::release_basis(&release.basis).unwrap_or(ReleaseBasis::Banner);
430            build = build.with_release(Release::new(release.name.clone(), basis));
431        }
432        Some(build)
433    }
434}
435
436impl From<&OsFingerprint> for OsRecord {
437    fn from(os: &OsFingerprint) -> Self {
438        Self {
439            name: os.name().to_owned(),
440            accuracy: os.accuracy(),
441            family: os.family().map(str::to_owned),
442            device: os.device().map(str::to_owned),
443            generation: os.generation().map(str::to_owned),
444            vendor: os.vendor().map(str::to_owned),
445            kernel: os.kernel().map(str::to_owned),
446            arch: os.arch().map(str::to_owned),
447            detail_accuracy: os.detail_accuracy(),
448            evidence: os.evidence().map(str::to_owned),
449            cpes: os.cpes().iter().map(|cpe| cpe.to_string()).collect(),
450        }
451    }
452}
453
454impl From<&OsRecord> for OsFingerprint {
455    fn from(record: &OsRecord) -> Self {
456        let mut os = OsFingerprint::new(record.name.clone(), record.accuracy);
457        if let Some(family) = &record.family {
458            os = os.with_family(family.clone());
459        }
460        if let Some(device) = &record.device {
461            os = os.with_device(device.clone());
462        }
463        if let Some(generation) = &record.generation {
464            os = os.with_generation(generation.clone());
465        }
466        if let Some(vendor) = &record.vendor {
467            os = os.with_vendor(vendor.clone());
468        }
469        if let Some(kernel) = &record.kernel {
470            os = os.with_kernel(kernel.clone());
471        }
472        if let Some(arch) = &record.arch {
473            os = os.with_arch(arch.clone());
474        }
475        if let Some(accuracy) = record.detail_accuracy {
476            os = os.with_detail_accuracy(accuracy);
477        }
478        if let Some(evidence) = &record.evidence {
479            os = os.with_evidence(evidence.clone());
480        }
481        for cpe in &record.cpes {
482            os.add_cpe(cpe.clone());
483        }
484        os
485    }
486}
487
488/// What one source concluded about a host's operating system.
489#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
490pub struct OsEvidenceRecord {
491    /// Which source said so, by wire name.
492    pub source: String,
493    /// The family it named, where it could name one.
494    #[serde(default)]
495    pub family: Option<String>,
496    /// The device class it named, where it named one.
497    #[serde(default)]
498    pub device: Option<String>,
499    /// The vendor, where it named one.
500    #[serde(default)]
501    pub vendor: Option<String>,
502    /// The product, where it named one.
503    #[serde(default)]
504    pub product: Option<String>,
505    /// The version, where it named one.
506    #[serde(default)]
507    pub version: Option<String>,
508    /// The kernel, where it named one.
509    #[serde(default)]
510    pub kernel: Option<String>,
511    /// The instruction set, where it named one.
512    #[serde(default)]
513    pub arch: Option<String>,
514    /// A platform identifier, where it carried one.
515    #[serde(default)]
516    pub cpe: Option<String>,
517    /// How sure it was, from zero to one.
518    pub confidence: f32,
519    /// What it read to conclude this.
520    pub evidence: String,
521}
522
523impl From<&OsEvidence> for OsEvidenceRecord {
524    fn from(evidence: &OsEvidence) -> Self {
525        Self {
526            source: wire::os_source_name(evidence.source).to_owned(),
527            family: evidence.family.clone(),
528            device: evidence.device.clone(),
529            vendor: evidence.vendor.clone(),
530            product: evidence.product.clone(),
531            version: evidence.version.clone(),
532            kernel: evidence.kernel.clone(),
533            arch: evidence.arch.clone(),
534            cpe: evidence.cpe.clone(),
535            confidence: evidence.confidence,
536            evidence: evidence.evidence.clone(),
537        }
538    }
539}
540
541impl From<&OsEvidenceRecord> for OsEvidence {
542    fn from(record: &OsEvidenceRecord) -> Self {
543        OsEvidence {
544            // An unknown source reads as the weakest one.
545            source: wire::os_source(&record.source).unwrap_or(OsSource::Hostname),
546            family: record.family.clone(),
547            device: record.device.clone(),
548            vendor: record.vendor.clone(),
549            product: record.product.clone(),
550            version: record.version.clone(),
551            kernel: record.kernel.clone(),
552            arch: record.arch.clone(),
553            cpe: record.cpe.clone(),
554            confidence: record.confidence,
555            evidence: record.evidence.clone(),
556        }
557    }
558}
559
560/// Hardware addresses and the vendor they attribute to.
561#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
562pub struct HardwareRecord {
563    /// Each address and when it was last seen.
564    pub macs: Vec<(String, SystemTime)>,
565    /// The vendor, where a service named it. A vendor read from an address block is
566    /// resolved again on rebuild.
567    #[serde(default, skip_serializing_if = "Option::is_none")]
568    pub vendor: Option<String>,
569    /// The model a service named.
570    #[serde(default, skip_serializing_if = "Option::is_none")]
571    pub product: Option<String>,
572    /// The line that model belongs to.
573    #[serde(default, skip_serializing_if = "Option::is_none")]
574    pub family: Option<String>,
575    /// The hardware's platform identifier.
576    #[serde(default, skip_serializing_if = "Option::is_none")]
577    pub cpe23: Option<String>,
578    /// A finer designation than the product.
579    #[serde(default, skip_serializing_if = "Option::is_none")]
580    pub model: Option<String>,
581    /// The hardware revision, which is not the operating system's version.
582    #[serde(default, skip_serializing_if = "Option::is_none")]
583    pub version: Option<String>,
584    /// The unit's own serial number.
585    #[serde(default, skip_serializing_if = "Option::is_none")]
586    pub serial_number: Option<String>,
587}
588
589impl From<&HardwareInfo> for HardwareRecord {
590    fn from(hardware: &HardwareInfo) -> Self {
591        let mut macs: Vec<(String, SystemTime)> = hardware
592            .macs()
593            .iter()
594            .map(|(mac, at)| (mac.to_string(), *at))
595            .collect();
596
597        // The vendor comes from the first address seen, but the model sorts
598        // addresses, so the one that produced it is written first for the rebuild
599        // to agree. The vendor itself stays out of the file, derived from the OUI
600        // table.
601        if let Some(vendor) = hardware.vendor() {
602            let source = macs.iter().position(|(mac, _)| {
603                mac.parse::<MacAddr>()
604                    .ok()
605                    .and_then(|mac| crate::model::mac::vendor(&mac))
606                    .is_some_and(|found| found == vendor)
607            });
608            if let Some(source) = source {
609                macs.swap(0, source);
610            }
611        }
612
613        // A vendor a service *stated* cannot be re-derived, so it is recorded:
614        // otherwise a NETGEAR ReadyNAS named by its FTP banner would come back
615        // unnamed.
616        let derivable = hardware.vendor().is_some_and(|vendor| {
617            macs.iter().any(|(mac, _)| {
618                mac.parse::<MacAddr>()
619                    .ok()
620                    .and_then(|mac| crate::model::mac::vendor(&mac))
621                    .is_some_and(|found| found == vendor)
622            })
623        });
624
625        Self {
626            macs,
627            vendor: (!derivable)
628                .then(|| hardware.vendor().map(str::to_string))
629                .flatten(),
630            product: hardware.product().map(str::to_string),
631            family: hardware.family().map(str::to_string),
632            cpe23: hardware.cpe23().map(str::to_string),
633            model: hardware.model().map(str::to_string),
634            version: hardware.hardware_version().map(str::to_string),
635            serial_number: hardware.serial_number().map(str::to_string),
636        }
637    }
638}
639
640impl HardwareRecord {
641    /// Rebuilds the hardware, or `None` where the record names no address this
642    /// build can read.
643    ///
644    /// A vendor from the address's OUI is resolved from the same table the scan used.
645    pub fn rebuild(&self) -> Option<HardwareInfo> {
646        let mut macs = self
647            .macs
648            .iter()
649            .filter_map(|(mac, at)| mac.parse::<MacAddr>().ok().map(|mac| (mac, *at)));
650
651        // A record may hold no address, as for a host behind a gateway described
652        // by a banner.
653        let described = HardwareInfo::described(crate::model::host::HardwareDescription {
654            vendor: self.vendor.as_deref(),
655            product: self.product.as_deref(),
656            family: self.family.as_deref(),
657            cpe23: self.cpe23.as_deref(),
658            model: self.model.as_deref(),
659            version: self.version.as_deref(),
660            serial_number: self.serial_number.as_deref(),
661        });
662
663        let Some((first, first_at)) = macs.next() else {
664            return described;
665        };
666
667        let mut hardware = HardwareInfo::new(first);
668        hardware.record_mac_seen_at(first, first_at);
669        for (mac, at) in macs {
670            hardware.record_mac_seen_at(mac, at);
671        }
672        if let Some(described) = described {
673            hardware.merge(described);
674        }
675        Some(hardware)
676    }
677}
678
679/// The interface a link-local address is valid on.
680#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
681pub struct ZoneRecord {
682    /// The scope id, where the host resolved one.
683    #[serde(default)]
684    pub index: Option<u32>,
685    /// The interface's name.
686    pub name: String,
687}
688
689impl From<&Zone> for ZoneRecord {
690    fn from(zone: &Zone) -> Self {
691        Self {
692            index: zone.index(),
693            name: zone.name().to_owned(),
694        }
695    }
696}
697
698impl From<&ZoneRecord> for Zone {
699    fn from(record: &ZoneRecord) -> Self {
700        match record.index {
701            Some(index) => Zone::new(index, record.name.clone()),
702            None => Zone::unresolved(record.name.clone()),
703        }
704    }
705}
706
707/// A host's round-trip samples: each one's duration and kind, and the probe
708/// they were measured from.
709///
710/// Not when each was taken: samples are stamped with a monotonic
711/// [`Instant`](std::time::Instant), so they are replayed in written order and stamped
712/// as read. A scan reads its journal before sending, so restored samples precede new
713/// ones.
714#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
715pub struct TelemetryRecord {
716    /// The measured round trips, oldest first.
717    #[serde(default)]
718    pub rtts: Vec<Duration>,
719    /// The hop counter the most recent reply arrived with.
720    #[serde(default)]
721    pub hop_counter: Option<u8>,
722    /// Which probe the round trips were measured from, where they agree on one.
723    ///
724    /// One name for the list, since the figures are only named when they share it.
725    /// Absent reads back as unnamed figures.
726    #[serde(default, skip_serializing_if = "Option::is_none")]
727    pub rtt_protocol: Option<String>,
728    /// What kind of round trip each of `rtts` is, position by position:
729    /// `direct`, or one of the upper bounds `segment_wide` and
730    /// `first_to_neighbour`, which a host's latency is drawn from only where
731    /// it has no direct sample. See
732    /// [`RttSource`].
733    ///
734    /// Empty where every sample is direct, which is most hosts. An unknown name reads as
735    /// an upper bound, which claims less; a sample past the end of the list reads as
736    /// direct.
737    #[serde(default, skip_serializing_if = "Vec::is_empty")]
738    pub rtt_sources: Vec<String>,
739}
740
741impl From<&HostTelemetry> for TelemetryRecord {
742    fn from(telemetry: &HostTelemetry) -> Self {
743        Self {
744            rtts: telemetry
745                .history()
746                .iter()
747                .map(|sample| sample.rtt)
748                .collect(),
749            hop_counter: telemetry.hop_counter(),
750            rtt_protocol: telemetry
751                .rtt_protocol()
752                .map(|protocol| wire::status_protocol_name(&protocol).into_owned()),
753            rtt_sources: if telemetry
754                .history()
755                .iter()
756                .all(|sample| sample.source == RttSource::Direct)
757            {
758                Vec::new()
759            } else {
760                telemetry
761                    .history()
762                    .iter()
763                    .map(|sample| wire::rtt_source_name(sample.source).to_owned())
764                    .collect()
765            },
766        }
767    }
768}
769
770impl TelemetryRecord {
771    /// Replays the measurements onto `host`.
772    fn restore(&self, host: &mut Host) {
773        let protocol = self.rtt_protocol.as_deref().and_then(wire::status_protocol);
774        for (index, rtt) in self.rtts.iter().enumerate() {
775            let source = self
776                .rtt_sources
777                .get(index)
778                .map_or(RttSource::Direct, |name| {
779                    wire::rtt_source(name).unwrap_or(RttSource::SegmentWide)
780                });
781            host.restore_rtt(*rtt, source, protocol.clone());
782        }
783        if let Some(arrived) = self.hop_counter {
784            host.record_hop_counter(arrived);
785        }
786    }
787}
788
789/// One router between the scanning host and the target.
790#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
791pub struct HopRecord {
792    /// How many routers out it sits.
793    pub distance: u8,
794    /// Its address, where it answered.
795    #[serde(default)]
796    pub address: Option<IpAddr>,
797    /// The measured round trip to it.
798    #[serde(default)]
799    pub rtt: Option<Duration>,
800    /// Whether it was spliced from another host's path rather than measured.
801    #[serde(default)]
802    pub inferred: bool,
803    /// Whether a router answered here from an address the scan's exclusions
804    /// withheld. `address` and `rtt` are empty when it is set.
805    #[serde(default)]
806    pub withheld: bool,
807}
808
809impl From<&Hop> for HopRecord {
810    fn from(hop: &Hop) -> Self {
811        Self {
812            distance: hop.distance(),
813            address: hop.address(),
814            rtt: hop.rtt(),
815            inferred: hop.inferred(),
816            withheld: hop.is_withheld(),
817        }
818    }
819}
820
821impl From<&HopRecord> for Hop {
822    fn from(record: &HopRecord) -> Self {
823        // A withheld router that is also named reads as withheld.
824        let hop = match record.address {
825            _ if record.withheld => Hop::withheld(record.distance),
826            Some(address) => Hop::answered(record.distance, address, record.rtt),
827            None => Hop::silent(record.distance),
828        };
829
830        if record.inferred {
831            hop.as_inferred()
832        } else {
833            hop
834        }
835    }
836}
837
838/// One port and what was established about it.
839#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
840pub struct PortRecord {
841    /// The port number.
842    pub port: u16,
843    /// The transport it was reached over, by wire name.
844    pub protocol: String,
845    /// What a probe established, by wire name.
846    pub state: String,
847    /// What is listening, where it was identified.
848    #[serde(default)]
849    pub service: Option<ServiceRecord>,
850    /// What a TLS handshake negotiated.
851    #[serde(default)]
852    pub security: Option<SecurityRecord>,
853    /// The packet that settled the state.
854    #[serde(default)]
855    pub discovery: Option<DiscoveryRecord>,
856    /// What a detection concluded was wrong with what is listening here, in
857    /// claim order.
858    #[serde(default)]
859    pub findings: Vec<FindingRecord>,
860}
861
862impl From<&Port> for PortRecord {
863    fn from(port: &Port) -> Self {
864        Self {
865            port: port.number(),
866            protocol: wire::protocol_name(port.protocol()).to_owned(),
867            state: wire::port_state_name(port.state()).to_owned(),
868            service: port.service().map(ServiceRecord::from),
869            security: port.security().map(SecurityRecord::from),
870            discovery: port.discovery().map(DiscoveryRecord::from),
871            // Already claim-ordered.
872            findings: port.findings().map(FindingRecord::from).collect(),
873        }
874    }
875}
876
877impl PortRecord {
878    /// Rebuilds the port, or [`None`] where the record names a transport this
879    /// build cannot read.
880    ///
881    /// An unknown state reads down to [`PortState::Unasked`]. An unknown transport
882    /// cannot read down, since transports have no ordering: filed under TCP, it would
883    /// collide with the real TCP port of that number and [`Host::add_port`] would merge
884    /// the two. So the record is left out.
885    pub fn rebuild(&self) -> Option<Port> {
886        let protocol = wire::protocol(&self.protocol)?;
887        let state = wire::port_state(&self.state).unwrap_or(PortState::Unasked);
888
889        let mut port = Port::new(self.port, protocol, state);
890        if let Some(service) = &self.service {
891            port = port.with_service(service.into());
892        }
893        if let Some(security) = &self.security {
894            port = port.with_security(security.into());
895        }
896        if let Some(discovery) = &self.discovery {
897            port = port.with_discovery(discovery.into());
898        }
899        for finding in self.findings.iter().filter_map(FindingRecord::rebuild) {
900            port.add_finding(finding);
901        }
902        Some(port)
903    }
904}
905
906/// A name a host gave for itself, as a file holds it.
907#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
908pub struct NameRecord {
909    /// Which protocol it was given in, by wire name.
910    pub source: String,
911    /// What it names, by wire name.
912    pub kind: String,
913    /// The name.
914    pub name: String,
915}
916
917impl From<&HostName> for NameRecord {
918    fn from(name: &HostName) -> Self {
919        Self {
920            source: wire::name_source_name(name.source()).to_owned(),
921            kind: wire::name_kind_name(name.kind()).to_owned(),
922            name: name.name().to_owned(),
923        }
924    }
925}
926
927impl NameRecord {
928    /// The name this records, or `None` where it cannot be read.
929    ///
930    /// An unknown source or kind, or a name the model refuses, leaves the name out:
931    /// filed under another kind, a forest would read as the host's own name.
932    pub fn rebuild(&self) -> Option<HostName> {
933        HostName::new(
934            wire::name_kind(&self.kind)?,
935            wire::name_source(&self.source)?,
936            &self.name,
937        )
938    }
939}
940
941/// What a scan concluded about one IP protocol on one host, as a file holds it.
942#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
943pub struct IpProtocolRecord {
944    /// The IP protocol number.
945    pub protocol: u8,
946    /// What the scan established, by wire name.
947    pub state: String,
948}
949
950/// A finding, as a file holds it.
951#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
952pub struct FindingRecord {
953    /// Which detection produced it, to which version, from which bytes.
954    pub detection: DetectionIdRecord,
955    /// Its one-line title.
956    pub title: String,
957    /// How bad it is if true, by wire name.
958    pub severity: String,
959    /// How sure it is true, by wire name.
960    pub confidence: String,
961    /// The intrusiveness the detection ran under, by wire name.
962    pub class: String,
963    /// The bytes that justify it, if any.
964    #[serde(default)]
965    pub excerpt: Option<String>,
966    /// Its external references, in sorted order.
967    #[serde(default)]
968    pub references: Vec<ReferenceRecord>,
969    /// Remediation advice, if any.
970    ///
971    /// Omitted when absent, as in the report; `export::conformance` holds the two to
972    /// the same spelling.
973    #[serde(default, skip_serializing_if = "Option::is_none")]
974    pub remediation: Option<String>,
975    /// The lowest of [`cpes`](Self::cpes), for readers that expect one. Omitted when
976    /// absent. Read back beside `cpes`.
977    #[serde(default, skip_serializing_if = "Option::is_none")]
978    pub cpe: Option<String>,
979    /// Every platform identifier a correlation drew it from, ascending.
980    ///
981    /// Omitted when empty and defaulted on read.
982    #[serde(default, skip_serializing_if = "Vec::is_empty")]
983    pub cpes: Vec<String>,
984    /// What the claim is about, where the detection named it.
985    ///
986    /// Omitted when absent.
987    #[serde(default, skip_serializing_if = "Option::is_none")]
988    pub subject: Option<String>,
989    /// The distribution build a correlation judged. Omitted when absent.
990    #[serde(default, skip_serializing_if = "Option::is_none")]
991    pub build: Option<BuildRecord>,
992    /// The distributor's advisory data a correlation consulted. Omitted when
993    /// absent.
994    #[serde(default, skip_serializing_if = "Option::is_none")]
995    pub advised_by: Option<DetectionIdRecord>,
996    /// Which of the vulnerabilities it cites are known to be exploited, and
997    /// whose list says so. Omitted when absent.
998    #[serde(default, skip_serializing_if = "Option::is_none")]
999    pub exploited: Option<ExploitationRecord>,
1000    /// The group of detections this finding's own detection covers a weakness
1001    /// with, where it declared one.
1002    ///
1003    /// Omitted when absent.
1004    #[serde(default, skip_serializing_if = "Option::is_none")]
1005    pub group: Option<FindingGroupRecord>,
1006}
1007
1008/// Which of a finding's vulnerabilities are known to be exploited, as a journal
1009/// records it.
1010#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1011pub struct ExploitationRecord {
1012    /// The list that names them.
1013    pub by: DetectionIdRecord,
1014    /// The CVE identifiers it names, in the order the finding cites them.
1015    pub cves: Vec<String>,
1016}
1017
1018impl From<&Exploitation> for ExploitationRecord {
1019    fn from(exploitation: &Exploitation) -> Self {
1020        Self {
1021            by: DetectionIdRecord::from(exploitation.by()),
1022            cves: exploitation.cves().map(str::to_owned).collect(),
1023        }
1024    }
1025}
1026
1027impl ExploitationRecord {
1028    /// Rebuilds the marking, or [`None`] where the list names nothing or none
1029    /// of the identifiers is a CVE's. A finding whose marking does not rebuild
1030    /// is kept without it.
1031    pub fn rebuild(&self) -> Option<Exploitation> {
1032        Exploitation::new(self.by.rebuild()?, self.cves.iter().cloned()).ok()
1033    }
1034}
1035
1036/// A finding's group, as a journal records it: the identity its members share
1037/// and the phrase they read as together.
1038#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1039pub struct FindingGroupRecord {
1040    /// The identity every member of the group repeats.
1041    pub id: String,
1042    /// How the group reads when its findings are spoken of as one.
1043    pub summary: String,
1044}
1045
1046impl From<&FindingGroup> for FindingGroupRecord {
1047    fn from(group: &FindingGroup) -> Self {
1048        Self {
1049            id: group.id().to_owned(),
1050            summary: group.summary().to_owned(),
1051        }
1052    }
1053}
1054
1055impl FindingGroupRecord {
1056    /// Rebuilds the group, or [`None`] where either half is blank. The finding is kept
1057    /// without it.
1058    pub fn rebuild(&self) -> Option<FindingGroup> {
1059        FindingGroup::new(self.id.clone(), self.summary.clone()).ok()
1060    }
1061}
1062
1063impl From<&Finding> for FindingRecord {
1064    fn from(finding: &Finding) -> Self {
1065        Self {
1066            detection: DetectionIdRecord::from(finding.detection()),
1067            title: finding.title().to_owned(),
1068            severity: wire::severity_name(finding.severity()).to_owned(),
1069            confidence: wire::confidence_name(finding.confidence()).to_owned(),
1070            class: wire::detection_class_name(finding.class()).to_owned(),
1071            excerpt: (!finding.excerpt().is_empty()).then(|| finding.excerpt().as_str().to_owned()),
1072            references: finding.references().map(ReferenceRecord::from).collect(),
1073            remediation: finding.remediation().map(str::to_owned),
1074            cpe: finding.cpes().next().map(str::to_owned),
1075            cpes: finding.cpes().map(str::to_owned).collect(),
1076            subject: finding.subject().map(str::to_owned),
1077            build: finding.build().map(BuildRecord::from),
1078            advised_by: finding.advised_by().map(DetectionIdRecord::from),
1079            exploited: finding.exploitation().map(ExploitationRecord::from),
1080            group: finding.group().map(FindingGroupRecord::from),
1081        }
1082    }
1083}
1084
1085impl FindingRecord {
1086    /// Rebuilds the finding, or [`None`] if it names no detection or has no
1087    /// title, the two things a finding cannot be without.
1088    ///
1089    /// Everything else reads downward: an unknown severity, confidence or class reads
1090    /// as the least it could claim, and an unreadable reference is dropped while the
1091    /// finding is kept.
1092    pub fn rebuild(&self) -> Option<Finding> {
1093        let severity = wire::severity(&self.severity).unwrap_or(Severity::Info);
1094        let confidence = wire::confidence(&self.confidence).unwrap_or(Confidence::Heuristic);
1095        let class = wire::detection_class(&self.class).unwrap_or(DetectionClass::Passive);
1096
1097        let mut finding = Finding::new(
1098            self.detection.rebuild()?,
1099            self.title.clone(),
1100            severity,
1101            confidence,
1102            class,
1103        )
1104        .ok()?;
1105
1106        if let Some(excerpt) = &self.excerpt {
1107            finding = finding.with_excerpt(Excerpt::new(excerpt.clone()));
1108        }
1109        if let Some(remediation) = &self.remediation {
1110            finding = finding.with_remediation(remediation.clone());
1111        }
1112        for cpe in self.cpe.iter().chain(&self.cpes) {
1113            finding = finding.with_cpe(cpe.clone());
1114        }
1115        for reference in self.references.iter().filter_map(ReferenceRecord::rebuild) {
1116            finding = finding.with_reference(reference);
1117        }
1118        if let Some(subject) = &self.subject {
1119            finding = finding.with_subject(subject.clone());
1120        }
1121        if let Some(build) = self.build.as_ref().and_then(BuildRecord::rebuild) {
1122            finding = finding.with_build(build);
1123        }
1124        if let Some(advised_by) = self
1125            .advised_by
1126            .as_ref()
1127            .and_then(DetectionIdRecord::rebuild)
1128        {
1129            finding = finding.with_advised_by(advised_by);
1130        }
1131        if let Some(exploitation) = self
1132            .exploited
1133            .as_ref()
1134            .and_then(ExploitationRecord::rebuild)
1135        {
1136            finding = finding.with_exploitation(exploitation);
1137        }
1138        if let Some(group) = self.group.as_ref().and_then(FindingGroupRecord::rebuild) {
1139            finding = finding.with_group(group);
1140        }
1141        Some(finding)
1142    }
1143}
1144
1145/// A detection identity, as a file holds it.
1146#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1147pub struct DetectionIdRecord {
1148    /// The author-chosen identifier.
1149    pub id: String,
1150    /// Its version, as `major.minor.patch`.
1151    pub version: String,
1152    /// The content hash of the detection body.
1153    pub content_hash: String,
1154}
1155
1156impl From<&DetectionId> for DetectionIdRecord {
1157    fn from(detection: &DetectionId) -> Self {
1158        Self {
1159            id: detection.id().to_owned(),
1160            version: detection.version().to_string(),
1161            content_hash: detection.content_hash().to_owned(),
1162        }
1163    }
1164}
1165
1166impl DetectionIdRecord {
1167    /// Rebuilds the identity, or [`None`] if it names nothing. An unparseable version
1168    /// reads as `0.0.0`, the least trusted.
1169    pub fn rebuild(&self) -> Option<DetectionId> {
1170        let version = self.version.parse().unwrap_or(Version::new(0, 0, 0));
1171        DetectionId::new(self.id.clone(), version, self.content_hash.clone()).ok()
1172    }
1173}
1174
1175/// An external reference, as a file holds it: a kind and the value it carries.
1176#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1177pub struct ReferenceRecord {
1178    /// Which kind of reference, by wire name.
1179    pub kind: String,
1180    /// The value it carries: a CVE id, a CWE number, or a URL.
1181    pub value: String,
1182}
1183
1184impl From<&Reference> for ReferenceRecord {
1185    fn from(reference: &Reference) -> Self {
1186        Self {
1187            kind: wire::reference_kind_name(reference).to_owned(),
1188            value: match reference {
1189                Reference::Cve(id) | Reference::Url(id) => id.clone(),
1190                Reference::Cwe(number) => number.to_string(),
1191            },
1192        }
1193    }
1194}
1195
1196impl ReferenceRecord {
1197    /// Rebuilds the reference, or [`None`] for an unknown kind or a malformed
1198    /// value.
1199    pub fn rebuild(&self) -> Option<Reference> {
1200        wire::reference(&self.kind, &self.value)
1201    }
1202}
1203
1204/// What is listening on a port.
1205#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1206pub struct ServiceRecord {
1207    /// What it is, such as `http`.
1208    pub name: String,
1209    /// How sure the identification is, out of a hundred.
1210    pub confidence: u8,
1211    /// The product behind it.
1212    #[serde(default)]
1213    pub product: Option<String>,
1214    /// Who makes it.
1215    #[serde(default)]
1216    pub vendor: Option<String>,
1217    /// Its version.
1218    #[serde(default)]
1219    pub version: Option<String>,
1220    /// Detail that is not the product itself.
1221    #[serde(default)]
1222    pub extrainfo: Option<String>,
1223    /// Platform identifiers.
1224    #[serde(default)]
1225    pub cpes: Vec<String>,
1226    /// Whose build of the software it is, where the reply said.
1227    ///
1228    /// Omitted when absent and defaulted on read.
1229    #[serde(default, skip_serializing_if = "Option::is_none")]
1230    pub build: Option<BuildRecord>,
1231}
1232
1233impl From<&Service> for ServiceRecord {
1234    fn from(service: &Service) -> Self {
1235        Self {
1236            name: service.name().to_owned(),
1237            confidence: service.confidence(),
1238            product: service.product().map(str::to_owned),
1239            vendor: service.vendor().map(str::to_owned),
1240            version: service.version().map(str::to_owned),
1241            extrainfo: service.extrainfo().map(str::to_owned),
1242            cpes: service.cpes().iter().map(|cpe| cpe.to_string()).collect(),
1243            build: service.build().map(BuildRecord::from),
1244        }
1245    }
1246}
1247
1248impl From<&ServiceRecord> for Service {
1249    fn from(record: &ServiceRecord) -> Self {
1250        let mut service = Service::new(record.name.clone(), record.confidence);
1251        if let Some(product) = &record.product {
1252            service = service.with_product(product.clone());
1253        }
1254        if let Some(vendor) = &record.vendor {
1255            service = service.with_vendor(vendor.clone());
1256        }
1257        if let Some(version) = &record.version {
1258            service = service.with_version(version.clone());
1259        }
1260        if let Some(extrainfo) = &record.extrainfo {
1261            service = service.with_extrainfo(extrainfo.clone());
1262        }
1263        for cpe in &record.cpes {
1264            service.add_cpe(cpe.clone());
1265        }
1266        if let Some(build) = record.build.as_ref().and_then(BuildRecord::rebuild) {
1267            service = service.with_build(build);
1268        }
1269        service
1270    }
1271}
1272
1273/// What a TLS handshake negotiated.
1274#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1275pub struct SecurityRecord {
1276    /// The protocol version agreed.
1277    #[serde(default)]
1278    pub tls_version: Option<String>,
1279    /// The cipher suite agreed.
1280    #[serde(default)]
1281    pub cipher_suite: Option<String>,
1282    /// The protocols offered over ALPN.
1283    #[serde(default)]
1284    pub alpn: Vec<String>,
1285    /// The certificate presented.
1286    #[serde(default)]
1287    pub certificate: Option<CertificateRecord>,
1288    /// What the endpoint accepts, one entry per version, where a scan asked.
1289    ///
1290    /// Skipped when empty and defaulted on read.
1291    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1292    pub accepts: Vec<AcceptedVersionRecord>,
1293    /// The versions whose enumeration did not finish, where any did.
1294    ///
1295    /// Skipped when empty and defaulted on read.
1296    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1297    pub unfinished: Vec<UnfinishedVersionRecord>,
1298}
1299
1300/// One version whose enumeration did not finish, and why.
1301#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1302pub struct UnfinishedVersionRecord {
1303    /// The version, by the name it prints.
1304    pub version: String,
1305    /// Why the walk ended, by the name it prints.
1306    pub interruption: String,
1307}
1308
1309/// One version an endpoint accepted, and the suites chosen under it.
1310///
1311/// Suites are written as wire numbers: what the server sent, smaller, and stable when
1312/// a suite is renamed. A number this build does not carry reads back into
1313/// `unrecognised`.
1314#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1315pub struct AcceptedVersionRecord {
1316    /// The version, by the name it prints.
1317    pub version: String,
1318    /// The suites accepted, by wire number, in the order the server chose them.
1319    #[serde(default)]
1320    pub suites: Vec<u16>,
1321    /// Suites the scanning build could not name, by wire number.
1322    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1323    pub unrecognised: Vec<u16>,
1324}
1325
1326impl From<&Security> for SecurityRecord {
1327    fn from(security: &Security) -> Self {
1328        Self {
1329            tls_version: security.tls_version().map(str::to_owned),
1330            cipher_suite: security.cipher_suite().map(str::to_owned),
1331            alpn: security.alpn().iter().map(|p| p.to_string()).collect(),
1332            certificate: security.certificate().map(CertificateRecord::from),
1333            accepts: security
1334                .support()
1335                .versions()
1336                .iter()
1337                .map(|held| AcceptedVersionRecord {
1338                    version: held.version().name().to_owned(),
1339                    suites: held.suites().iter().map(|suite| suite.code()).collect(),
1340                    unrecognised: held.unrecognised().to_vec(),
1341                })
1342                .collect(),
1343            unfinished: security
1344                .support()
1345                .unfinished()
1346                .iter()
1347                .map(|held| UnfinishedVersionRecord {
1348                    version: held.version().name().to_owned(),
1349                    interruption: held.interruption().name().to_owned(),
1350                })
1351                .collect(),
1352        }
1353    }
1354}
1355
1356impl From<&SecurityRecord> for Security {
1357    fn from(record: &SecurityRecord) -> Self {
1358        let mut security = Security::new();
1359        if let Some(version) = &record.tls_version {
1360            security = security.with_tls_version(version.clone());
1361        }
1362        if let Some(cipher) = &record.cipher_suite {
1363            security = security.with_cipher_suite(cipher.clone());
1364        }
1365        for protocol in &record.alpn {
1366            security.add_alpn(protocol.clone());
1367        }
1368        if let Some(certificate) = &record.certificate {
1369            security = security.with_certificate(certificate.into());
1370        }
1371
1372        let mut support = TlsSupport::new();
1373        for held in &record.accepts {
1374            // An unknown version is dropped: there is nothing to file its suites
1375            // under.
1376            let Ok(version) = held.version.parse::<TlsVersion>() else {
1377                continue;
1378            };
1379            let mut suites = Vec::with_capacity(held.suites.len());
1380            let mut unrecognised = held.unrecognised.clone();
1381            for code in &held.suites {
1382                match CipherSuite::from_code(*code) {
1383                    Some(suite) => suites.push(suite),
1384                    // A suite this build does not carry stays a number.
1385                    None => unrecognised.push(*code),
1386                }
1387            }
1388            support.record(VersionSupport::new(version, suites, unrecognised));
1389        }
1390        for held in &record.unfinished {
1391            let Ok(version) = held.version.parse::<TlsVersion>() else {
1392                continue;
1393            };
1394            // Read downward to `Stopped`: dropping the entry would claim the walk
1395            // finished.
1396            let interruption =
1397                Interruption::from_name(&held.interruption).unwrap_or(Interruption::Stopped);
1398            support.record_unfinished(UnfinishedVersion::new(version, interruption));
1399        }
1400        security.set_support(support);
1401
1402        security
1403    }
1404}
1405
1406/// The certificate a TLS endpoint presented.
1407#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1408pub struct CertificateRecord {
1409    /// Who it is for.
1410    pub common_name: String,
1411    /// The other names it covers.
1412    #[serde(default)]
1413    pub sans: Vec<String>,
1414    /// Who signed it.
1415    pub issuer: String,
1416    /// When it becomes valid.
1417    pub validity_start: SystemTime,
1418    /// When it stops being valid.
1419    pub validity_end: SystemTime,
1420    /// The SHA-256 of the certificate.
1421    pub fingerprint_sha256: String,
1422    /// The public key's algorithm, or `unknown` where it was not read.
1423    #[serde(default)]
1424    pub pubkey_type: String,
1425    /// The public key's size in bits, or zero where it was not read.
1426    #[serde(default)]
1427    pub pubkey_bits: u32,
1428}
1429
1430impl From<&CertificateInfo> for CertificateRecord {
1431    fn from(certificate: &CertificateInfo) -> Self {
1432        Self {
1433            common_name: certificate.common_name().to_owned(),
1434            sans: certificate.sans().iter().map(|s| s.to_string()).collect(),
1435            issuer: certificate.issuer().to_owned(),
1436            validity_start: certificate.validity_start(),
1437            validity_end: certificate.validity_end(),
1438            fingerprint_sha256: certificate.fingerprint_sha256().to_owned(),
1439            pubkey_type: certificate.pubkey_type().to_owned(),
1440            pubkey_bits: certificate.pubkey_bits(),
1441        }
1442    }
1443}
1444
1445impl From<&CertificateRecord> for CertificateInfo {
1446    fn from(record: &CertificateRecord) -> Self {
1447        CertificateInfo::new(
1448            record.common_name.clone(),
1449            record.issuer.clone(),
1450            record.validity_start,
1451            record.validity_end,
1452            record.fingerprint_sha256.clone(),
1453        )
1454        .with_sans(record.sans.iter().map(|s| s.as_str().into()))
1455        .with_public_key(record.pubkey_type.clone(), record.pubkey_bits)
1456    }
1457}
1458
1459/// The packet that settled a port's state.
1460#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1461pub struct DiscoveryRecord {
1462    /// What came back, by wire name.
1463    pub reason: String,
1464    /// When it arrived.
1465    pub timestamp: SystemTime,
1466    /// The measured round trip.
1467    #[serde(default)]
1468    pub rtt: Option<Duration>,
1469    /// The hop counter it carried.
1470    #[serde(default)]
1471    pub ttl: Option<u8>,
1472    /// Who sent it: the source address its IP header carried.
1473    #[serde(default)]
1474    pub source_ip: Option<IpAddr>,
1475}
1476
1477impl From<&Discovery> for DiscoveryRecord {
1478    fn from(discovery: &Discovery) -> Self {
1479        Self {
1480            reason: wire::scan_response_name(discovery.reason()).into_owned(),
1481            timestamp: discovery.timestamp(),
1482            rtt: discovery.rtt(),
1483            ttl: discovery.ttl(),
1484            source_ip: discovery.source_ip(),
1485        }
1486    }
1487}
1488
1489impl From<&DiscoveryRecord> for Discovery {
1490    fn from(record: &DiscoveryRecord) -> Self {
1491        let reason = wire::scan_response(&record.reason)
1492            .unwrap_or_else(|| ScanResponse::Custom(record.reason.clone()));
1493
1494        let mut discovery = Discovery::new(reason).seen_at(record.timestamp);
1495        if let Some(rtt) = record.rtt {
1496            discovery = discovery.with_rtt(rtt);
1497        }
1498        if let Some(ttl) = record.ttl {
1499            discovery = discovery.with_ttl(ttl);
1500        }
1501        if let Some(source) = record.source_ip {
1502            discovery = discovery.with_source_ip(source);
1503        }
1504        discovery
1505    }
1506}
1507
1508/// One sitting of a scan, as a file holds it.
1509///
1510/// Mirrors [`PhaseParts`], which mirrors the phase; the compiler keeps the three in
1511/// step.
1512#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
1513pub struct PhaseRecord {
1514    /// Which entry point this sitting recorded, by wire name.
1515    pub kind: String,
1516    /// When it began.
1517    pub started_at: SystemTime,
1518    /// How long it ran.
1519    pub elapsed: Duration,
1520    /// Whether it held the privileges its raw strategies need, or absent where
1521    /// this engine did not measure the phase and cannot say.
1522    pub privileged: Option<bool>,
1523    /// What it covered, and what it was forbidden.
1524    pub targets: ScopeRecord,
1525    /// The settings it ran under.
1526    pub settings: SettingsRecord,
1527    /// The strategies that could not do their job.
1528    #[serde(default)]
1529    pub failures: Vec<FailureRecord>,
1530    /// Ground the sitting declined before sending anything.
1531    ///
1532    /// Skipped when empty and defaulted on read.
1533    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1534    pub refusals: Vec<RefusalRecord>,
1535    /// Addresses the scanning host could not reach, so no probe was sent to
1536    /// them.
1537    #[serde(default)]
1538    pub unroutable: Vec<IpAddr>,
1539    /// The addresses among `unroutable` the scanning host's routing table
1540    /// refuses.
1541    ///
1542    /// Skipped when empty and defaulted on read.
1543    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1544    pub refused_by_route: Vec<IpAddr>,
1545    /// Addresses the sitting left before it had finished with them, because
1546    /// their own budget ran out.
1547    ///
1548    /// Skipped when empty and defaulted on read.
1549    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1550    pub timed_out: Vec<IpAddr>,
1551    /// Addresses whose ICMP errors the sitting found rate-limited.
1552    ///
1553    /// Skipped when empty and defaulted on read.
1554    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1555    pub icmp_rate_limited: Vec<IpAddr>,
1556    /// Addresses a raw sitting reached by TCP connect instead.
1557    ///
1558    /// Skipped when empty and defaulted on read.
1559    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1560    pub reached_by_connect: Vec<RangeRecord>,
1561    /// Addresses in scope the sitting reached no verdict on.
1562    ///
1563    /// Skipped when empty and defaulted on read.
1564    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1565    pub undecided: Vec<RangeRecord>,
1566    /// Why a port sitting ran with no liveness pass in front of it, by its wire
1567    /// name.
1568    ///
1569    /// Skipped when absent and defaulted on read. An unknown name reads back as absent.
1570    #[serde(default, skip_serializing_if = "Option::is_none")]
1571    pub liveness_skipped: Option<String>,
1572    /// Addresses a port sitting standing in for its liveness pass asked on
1573    /// every port and heard nothing from.
1574    ///
1575    /// Skipped when empty and defaulted on read. Keeps journalled records at these
1576    /// addresses out of the report.
1577    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1578    pub silent: Vec<RangeRecord>,
1579    /// Why the scan was stopped while this sitting ran, by wire name.
1580    ///
1581    /// Skipped when absent and defaulted on read. An unknown name reads back as absent.
1582    #[serde(default, skip_serializing_if = "Option::is_none")]
1583    pub stopped: Option<String>,
1584    /// The passes a stop skipped or cut short, by wire name.
1585    ///
1586    /// Skipped when empty and defaulted on read. An unknown name is dropped.
1587    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1588    pub passes_cut: Vec<String>,
1589    /// How many of a port sitting's targets it never asked and holds on no
1590    /// host.
1591    ///
1592    /// Skipped when zero and defaulted on read.
1593    #[serde(default, skip_serializing_if = "is_zero")]
1594    pub unreached: u128,
1595    /// How many of a port sitting's targets it asked at the addresses it lists
1596    /// no host at.
1597    ///
1598    /// Skipped when zero and defaulted on read.
1599    #[serde(default, skip_serializing_if = "is_zero")]
1600    pub unheard_probes: u128,
1601    /// What each strategy recorded about its own run.
1602    #[serde(default)]
1603    pub probe_stats: Vec<ProbeStatsRecord>,
1604    /// Which document this sitting was folded in from, for a merged report.
1605    #[serde(default, skip_serializing_if = "Option::is_none")]
1606    pub origin: Option<PhaseOriginRecord>,
1607    /// Which switch ports the machine running this sitting was plugged into.
1608    #[serde(default, skip_serializing_if = "Vec::is_empty")]
1609    pub attachments: Vec<AttachmentRecord>,
1610    /// Whether this is the sitting as it stood before it closed, as a sitting
1611    /// writes itself down while it runs.
1612    ///
1613    /// Skipped when false and defaulted on read.
1614    #[serde(default, skip_serializing_if = "is_false")]
1615    pub open: bool,
1616}
1617
1618/// Where the machine running a sitting was plugged in, as a file holds it.
1619#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1620pub struct AttachmentRecord {
1621    /// Which of the scanning machine's interfaces the announcement arrived on.
1622    pub link: String,
1623    /// The interface index, where known. Absent, not zero, since zero means "no
1624    /// interface" to a kernel.
1625    #[serde(default, skip_serializing_if = "Option::is_none")]
1626    pub link_index: Option<u32>,
1627    /// Which protocol the announcement was read from.
1628    pub source: String,
1629    /// The hardware address the device identified its chassis with.
1630    #[serde(default, skip_serializing_if = "Option::is_none")]
1631    pub device_mac: Option<String>,
1632    /// What the device calls itself.
1633    #[serde(default, skip_serializing_if = "Option::is_none")]
1634    pub device_name: Option<String>,
1635    /// What the device calls the port this machine is plugged into.
1636    #[serde(default, skip_serializing_if = "Option::is_none")]
1637    pub port: Option<String>,
1638    /// The VLAN untagged traffic on this port lands in.
1639    #[serde(default, skip_serializing_if = "Option::is_none")]
1640    pub native_vlan: Option<u16>,
1641    /// An address the device is managed at.
1642    #[serde(default, skip_serializing_if = "Option::is_none")]
1643    pub management_address: Option<IpAddr>,
1644    /// When the announcement arrived.
1645    pub observed_at: SystemTime,
1646}
1647
1648impl From<&Attachment> for AttachmentRecord {
1649    fn from(attachment: &Attachment) -> Self {
1650        Self {
1651            link: attachment.link().name().to_owned(),
1652            link_index: attachment.link().index(),
1653            source: wire::attachment_source_name(attachment.source()).to_owned(),
1654            device_mac: attachment.device_mac().map(|mac| mac.to_string()),
1655            device_name: attachment.device_name().map(str::to_owned),
1656            port: attachment.port().map(str::to_owned),
1657            native_vlan: attachment.native_vlan(),
1658            management_address: attachment.management_address(),
1659            observed_at: attachment.observed_at(),
1660        }
1661    }
1662}
1663
1664impl From<&AttachmentRecord> for Attachment {
1665    fn from(record: &AttachmentRecord) -> Self {
1666        let link = match record.link_index {
1667            Some(index) => Zone::new(index, record.link.as_str()),
1668            None => Zone::unresolved(record.link.as_str()),
1669        };
1670
1671        // An unknown source reads as LLDP, the standard one; it changes no field's
1672        // meaning.
1673        let source = wire::attachment_source(&record.source).unwrap_or(AttachmentSource::Lldp);
1674
1675        let mut attachment = Attachment::new(link, source, record.observed_at);
1676        if let Some(mac) = record
1677            .device_mac
1678            .as_deref()
1679            .and_then(|mac| mac.parse().ok())
1680        {
1681            attachment = attachment.with_device_mac(mac);
1682        }
1683        if let Some(name) = record.device_name.as_deref() {
1684            attachment = attachment.with_device_name(name);
1685        }
1686        if let Some(port) = record.port.as_deref() {
1687            attachment = attachment.with_port(port);
1688        }
1689        if let Some(vlan) = record.native_vlan {
1690            attachment = attachment.with_native_vlan(vlan);
1691        }
1692        if let Some(address) = record.management_address {
1693            attachment = attachment.with_management_address(address);
1694        }
1695        attachment
1696    }
1697}
1698
1699/// Which document a sitting came from, as a file holds it.
1700#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1701pub struct PhaseOriginRecord {
1702    /// What the caller called the document it was read from.
1703    #[serde(default, skip_serializing_if = "Option::is_none")]
1704    pub label: Option<String>,
1705    /// What produced it, as that scanner attributed itself.
1706    pub engine_version: String,
1707}
1708
1709impl From<&PhaseOrigin> for PhaseOriginRecord {
1710    fn from(origin: &PhaseOrigin) -> Self {
1711        Self {
1712            label: origin.label().map(str::to_owned),
1713            engine_version: origin.engine_version().to_owned(),
1714        }
1715    }
1716}
1717
1718impl From<&PhaseOriginRecord> for PhaseOrigin {
1719    fn from(record: &PhaseOriginRecord) -> Self {
1720        let origin = PhaseOrigin::new(record.engine_version.as_str());
1721        match &record.label {
1722            Some(label) => origin.with_label(label.as_str()),
1723            None => origin,
1724        }
1725    }
1726}
1727
1728/// Whether a count is zero, for leaving it out of a record that has nothing to
1729/// say with it.
1730fn is_zero(count: &u128) -> bool {
1731    *count == 0
1732}
1733
1734impl From<&ScanPhase> for PhaseRecord {
1735    fn from(phase: &ScanPhase) -> Self {
1736        Self {
1737            kind: wire::scan_kind_name(phase.kind()).to_owned(),
1738            started_at: phase.started_at(),
1739            elapsed: phase.elapsed(),
1740            privileged: phase.privilege().map(Privilege::is_raw),
1741            targets: ScopeRecord::from(phase.targets()),
1742            settings: SettingsRecord::from(phase.settings()),
1743            failures: phase.failures().iter().map(FailureRecord::from).collect(),
1744            refusals: phase.refusals().iter().map(RefusalRecord::from).collect(),
1745            unroutable: phase.unroutable().to_vec(),
1746            refused_by_route: phase.refused_by_route().to_vec(),
1747            timed_out: phase.timed_out().to_vec(),
1748            icmp_rate_limited: phase.icmp_rate_limited().to_vec(),
1749            reached_by_connect: phase
1750                .reached_by_connect()
1751                .iter()
1752                .map(RangeRecord::from)
1753                .collect(),
1754            undecided: phase.undecided().iter().map(RangeRecord::from).collect(),
1755            liveness_skipped: phase
1756                .liveness_skipped()
1757                .map(|skip| wire::liveness_skip_name(skip).to_owned()),
1758            silent: phase.silent().iter().map(RangeRecord::from).collect(),
1759            stopped: phase
1760                .stopped()
1761                .map(|reason| wire::stop_reason_name(reason).to_owned()),
1762            passes_cut: phase
1763                .passes_cut()
1764                .iter()
1765                .map(|pass| wire::pass_name(*pass).to_owned())
1766                .collect(),
1767            unreached: phase.unreached(),
1768            unheard_probes: phase.unheard_probes(),
1769            probe_stats: phase
1770                .probe_stats()
1771                .iter()
1772                .map(ProbeStatsRecord::from)
1773                .collect(),
1774            origin: phase.origin().map(PhaseOriginRecord::from),
1775            attachments: phase
1776                .attachments()
1777                .iter()
1778                .map(AttachmentRecord::from)
1779                .collect(),
1780            open: phase.is_open(),
1781        }
1782    }
1783}
1784
1785impl From<&PhaseRecord> for ScanPhase {
1786    fn from(record: &PhaseRecord) -> Self {
1787        ScanPhase::from_parts(PhaseParts {
1788            // An unknown kind reads as a discovery sweep, which claims least while
1789            // still saying the addresses were walked.
1790            kind: wire::scan_kind(&record.kind).unwrap_or(ScanKind::Discovery),
1791            started_at: record.started_at,
1792            elapsed: record.elapsed,
1793            privilege: record.privileged.map(Privilege::from_raw),
1794            targets: TargetScope::from(&record.targets),
1795            settings: ScanSettings::from(&record.settings),
1796            failures: record.failures.iter().map(ScannerFailure::from).collect(),
1797            refusals: record.refusals.iter().map(Refusal::from).collect(),
1798            unroutable: record.unroutable.clone(),
1799            refused_by_route: record.refused_by_route.clone(),
1800            timed_out: record.timed_out.clone(),
1801            icmp_rate_limited: record.icmp_rate_limited.clone(),
1802            // A range whose ends do not describe one is dropped.
1803            reached_by_connect: record
1804                .reached_by_connect
1805                .iter()
1806                .filter_map(RangeRecord::rebuild)
1807                .collect(),
1808            // Dropped on the same terms.
1809            undecided: record
1810                .undecided
1811                .iter()
1812                .filter_map(RangeRecord::rebuild)
1813                .collect(),
1814            liveness_skipped: record
1815                .liveness_skipped
1816                .as_deref()
1817                .and_then(wire::liveness_skip),
1818            silent: record
1819                .silent
1820                .iter()
1821                .filter_map(RangeRecord::rebuild)
1822                .collect(),
1823            stopped: record.stopped.as_deref().and_then(wire::stop_reason),
1824            passes_cut: record
1825                .passes_cut
1826                .iter()
1827                .filter_map(|name| wire::pass(name))
1828                .collect(),
1829            unreached: record.unreached,
1830            unheard_probes: record.unheard_probes,
1831            probes: record.probe_stats.iter().map(ProbeStats::from).collect(),
1832            origin: record.origin.as_ref().map(PhaseOrigin::from),
1833            attachments: record.attachments.iter().map(Attachment::from).collect(),
1834            open: record.open,
1835        })
1836    }
1837}
1838
1839/// What a sitting was asked to cover, and what it was forbidden.
1840#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1841pub struct ScopeRecord {
1842    /// The ranges walked, after exclusions, as `start-end`.
1843    #[serde(default)]
1844    pub ranges: Vec<RangeRecord>,
1845    /// The links swept whole, by the interface each is on. Defaulted on read.
1846    #[serde(default)]
1847    pub links: Vec<ZoneRecord>,
1848    /// The links whose traffic was read without anything being probed on them.
1849    /// Never coverage; see `TargetScope::listened`. Defaulted on read.
1850    #[serde(default)]
1851    pub listened: Vec<ZoneRecord>,
1852    /// How many distinct addresses those hold.
1853    pub addresses: u128,
1854    /// How many probes the scope implies, where ports were known.
1855    #[serde(default)]
1856    pub probes: Option<u128>,
1857    /// Which ports were walked, and whether uniformly. Absent reads back as unstated.
1858    #[serde(default)]
1859    pub ports: Option<PortsRecord>,
1860    /// The transports covered, by wire name.
1861    #[serde(default)]
1862    pub protocols: Vec<String>,
1863    /// The ranges the policy withheld.
1864    #[serde(default)]
1865    pub excluded: Vec<RangeRecord>,
1866    /// How many addresses that withheld.
1867    pub withheld: u128,
1868}
1869
1870impl From<&TargetScope> for ScopeRecord {
1871    fn from(scope: &TargetScope) -> Self {
1872        Self {
1873            ranges: scope.ranges().iter().map(RangeRecord::from).collect(),
1874            links: scope.links().iter().map(ZoneRecord::from).collect(),
1875            listened: scope.listened().iter().map(ZoneRecord::from).collect(),
1876            addresses: scope.addresses(),
1877            probes: scope.probes(),
1878            ports: PortsRecord::of(scope.ports()),
1879            protocols: scope
1880                .protocols()
1881                .iter()
1882                .map(|p| wire::protocol_name(*p).to_owned())
1883                .collect(),
1884            excluded: scope.excluded().iter().map(RangeRecord::from).collect(),
1885            withheld: scope.withheld(),
1886        }
1887    }
1888}
1889
1890impl From<&ScopeRecord> for TargetScope {
1891    fn from(record: &ScopeRecord) -> Self {
1892        TargetScope::from_parts(ScopeParts {
1893            ranges: record
1894                .ranges
1895                .iter()
1896                .filter_map(RangeRecord::rebuild)
1897                .collect(),
1898            links: record.links.iter().map(Zone::from).collect(),
1899            listened: record.listened.iter().map(Zone::from).collect(),
1900            addresses: record.addresses,
1901            probes: record.probes,
1902            ports: record
1903                .ports
1904                .as_ref()
1905                .map_or(PortScope::Unstated, PortsRecord::rebuild),
1906            protocols: record
1907                .protocols
1908                .iter()
1909                .filter_map(|p| wire::protocol(p))
1910                .collect(),
1911            excluded: record
1912                .excluded
1913                .iter()
1914                .filter_map(RangeRecord::rebuild)
1915                .collect(),
1916            withheld: record.withheld,
1917        })
1918    }
1919}
1920
1921/// A phase's port scope, as a file holds it.
1922///
1923/// The set is written as the specification [`PortSet`] parses, so a full sweep is six
1924/// bytes and readable.
1925#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1926pub struct PortsRecord {
1927    /// Which of the four things the set below is, by wire name.
1928    ///
1929    /// `every` is the only value from which a reader may conclude an endpoint of a
1930    /// covered address was probed.
1931    pub kind: String,
1932    /// The ports, as the specification
1933    /// [`PortSet`] parses. Empty where the kind
1934    /// carries no set.
1935    #[serde(default)]
1936    pub spec: String,
1937}
1938
1939impl PortsRecord {
1940    /// The record of a port scope, or `None` where it states nothing.
1941    pub fn of(scope: &PortScope) -> Option<Self> {
1942        match scope {
1943            PortScope::Unstated => None,
1944            other => Some(Self {
1945                kind: wire::port_scope_name(other).to_owned(),
1946                spec: other.ports().map(PortSet::to_string).unwrap_or_default(),
1947            }),
1948        }
1949    }
1950
1951    /// The scope this records.
1952    ///
1953    /// An unknown kind or unparseable specification rebuilds as
1954    /// [`Unstated`](PortScope::Unstated), which claims nothing.
1955    pub fn rebuild(&self) -> PortScope {
1956        let ports = PortSet::try_from(self.spec.as_str())
1957            .ok()
1958            .filter(|ports| !ports.is_empty());
1959
1960        wire::port_scope(&self.kind, ports).unwrap_or(PortScope::Unstated)
1961    }
1962}
1963
1964/// One address range, by its ends.
1965#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
1966pub struct RangeRecord {
1967    /// The first address in the range.
1968    pub start: IpAddr,
1969    /// The last address in the range.
1970    pub end: IpAddr,
1971    /// The interface a link-local range is valid on.
1972    #[serde(default)]
1973    pub zone: Option<u32>,
1974}
1975
1976impl From<&IpRange> for RangeRecord {
1977    fn from(range: &IpRange) -> Self {
1978        Self {
1979            start: range.start_addr(),
1980            end: range.end_addr(),
1981            zone: match range {
1982                IpRange::V6(range) => range.zone(),
1983                IpRange::V4(_) => None,
1984            },
1985        }
1986    }
1987}
1988
1989impl RangeRecord {
1990    /// Rebuilds the range, or `None` where its ends do not describe one, meaning
1991    /// a mixed pair or an end before its start.
1992    pub fn rebuild(&self) -> Option<IpRange> {
1993        match (self.start, self.end) {
1994            (IpAddr::V4(start), IpAddr::V4(end)) => {
1995                Ipv4Range::new(start, end).ok().map(IpRange::V4)
1996            }
1997            (IpAddr::V6(start), IpAddr::V6(end)) => Ipv6Range::scoped(start, end, self.zone)
1998                .ok()
1999                .map(IpRange::V6),
2000            _ => None,
2001        }
2002    }
2003}
2004
2005/// Ground a sitting declined to cover.
2006///
2007/// No timestamp, unlike [`FailureRecord`]: a refusal is decided before the phase
2008/// begins.
2009#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2010pub struct RefusalRecord {
2011    /// Which strategy would have taken the work, by wire name.
2012    pub scanner: String,
2013    /// What was not done, and what could be asked for instead.
2014    pub reason: String,
2015}
2016
2017impl From<&Refusal> for RefusalRecord {
2018    fn from(refusal: &Refusal) -> Self {
2019        Self {
2020            scanner: wire::scanner_kind_name(refusal.scanner()).to_owned(),
2021            reason: refusal.reason().to_owned(),
2022        }
2023    }
2024}
2025
2026impl From<&RefusalRecord> for Refusal {
2027    fn from(record: &RefusalRecord) -> Self {
2028        Refusal::new(
2029            wire::scanner_kind(&record.scanner).unwrap_or(ScannerKind::Composite),
2030            record.reason.clone(),
2031        )
2032    }
2033}
2034
2035/// A strategy that could not do its job.
2036#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2037pub struct FailureRecord {
2038    /// Which strategy, by wire name.
2039    pub scanner: String,
2040    /// What went wrong.
2041    pub reason: String,
2042    /// When it was recorded.
2043    pub at: SystemTime,
2044    /// Whether a limit cut the work short rather than a fault stopping it. Absent reads
2045    /// as false.
2046    #[serde(default, skip_serializing_if = "is_false")]
2047    pub cut_short: bool,
2048}
2049
2050impl From<&ScannerFailure> for FailureRecord {
2051    fn from(failure: &ScannerFailure) -> Self {
2052        Self {
2053            scanner: wire::scanner_kind_name(failure.scanner()).to_owned(),
2054            reason: failure.reason().to_owned(),
2055            at: failure.at(),
2056            cut_short: failure.is_cut_short(),
2057        }
2058    }
2059}
2060
2061impl From<&FailureRecord> for ScannerFailure {
2062    fn from(record: &FailureRecord) -> Self {
2063        let scanner = wire::scanner_kind(&record.scanner).unwrap_or(ScannerKind::Composite);
2064        let reason = record.reason.clone();
2065        let failure = if record.cut_short {
2066            ScannerFailure::cut_short(scanner, reason)
2067        } else {
2068            ScannerFailure::new(scanner, reason)
2069        };
2070        failure.recorded_at(record.at)
2071    }
2072}
2073
2074/// The settings one sitting ran under.
2075///
2076/// The enums here read and write their own names, so this carries those.
2077#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
2078pub struct SettingsRecord {
2079    /// How raw probes were placed on the wire.
2080    pub send_mode: String,
2081    /// Which segment each TCP port probe carried.
2082    pub tcp_technique: String,
2083    /// Which chunk each SCTP port probe carried.
2084    ///
2085    /// Defaulted on read to INIT.
2086    #[serde(default)]
2087    pub sctp_technique: String,
2088    /// The retransmission effort in force.
2089    pub retry_effort: String,
2090    /// A caller's override of the attempt budget.
2091    ///
2092    /// A plain number, read back through the configuration's bound: zero reads as no
2093    /// override.
2094    #[serde(default)]
2095    pub retry_max_attempts: Option<u8>,
2096    /// A caller's scaling of the timeout. An invalid scale reads as absent.
2097    #[serde(default)]
2098    pub retry_timeout_scale: Option<f64>,
2099    /// Whether silent hosts were probed less.
2100    pub retry_dampen_silent_hosts: bool,
2101    /// The probe-rate ceiling, where one applied.
2102    #[serde(default)]
2103    pub max_probe_rate: Option<u32>,
2104    /// The probe-rate floor, where one applied.
2105    ///
2106    /// Defaulted on read.
2107    #[serde(default)]
2108    pub min_probe_rate: Option<u32>,
2109    /// The shortest gap kept between two probes at one host, where one applied.
2110    #[serde(default)]
2111    pub host_probe_interval: Option<Duration>,
2112    /// The shortest gap kept between any two probes, where one applied.
2113    #[serde(default)]
2114    pub probe_interval: Option<Duration>,
2115    /// The wall-clock budget each host was given, where one applied.
2116    ///
2117    /// Defaulted on read.
2118    #[serde(default)]
2119    pub host_timeout: Option<Duration>,
2120    /// The wall-clock budget the whole sitting was given, where one applied.
2121    #[serde(default)]
2122    pub scan_timeout: Option<Duration>,
2123    /// Whether name resolution could generate traffic.
2124    pub dns_enabled: bool,
2125    /// Whether identifying detail was masked.
2126    pub redact: bool,
2127    /// How far the sitting went to identify operating systems.
2128    pub os_detection: String,
2129    /// How far it went to identify services.
2130    pub service_detection: String,
2131    /// The intrusiveness ceiling detections ran under, by wire name. Defaulted on read.
2132    #[serde(default)]
2133    pub detection: String,
2134    /// Whether it traced the path to each host.
2135    pub traceroute: bool,
2136    /// Whether it characterised the filter in front of each host.
2137    #[serde(default)]
2138    pub characterise: bool,
2139
2140    /// Which IP protocols it asked each host about, ascending. Empty for a phase that
2141    /// ran no such pass.
2142    #[serde(default)]
2143    pub ip_protocols: Vec<u8>,
2144    /// Whether it established what each TLS port accepts.
2145    ///
2146    /// Defaulted on read.
2147    #[serde(default)]
2148    pub tls_enumeration: bool,
2149    /// The TCP ports it connected to and listened on and sent nothing,
2150    /// ascending.
2151    ///
2152    /// Defaulted on read.
2153    #[serde(default)]
2154    pub listen_only_ports: Vec<u16>,
2155    /// The ports it sent nothing to on any target, as the specification
2156    /// [`PortSet`] parses, omitted when it excluded none.
2157    ///
2158    /// Defaulted on read.
2159    #[serde(default, skip_serializing_if = "String::is_empty")]
2160    pub excluded_ports: String,
2161    /// What the sitting changed about the packets it sent, omitted when it
2162    /// changed nothing.
2163    #[serde(default, skip_serializing_if = "Option::is_none")]
2164    pub evasion: Option<EvasionSettingsRecord>,
2165    /// The zombie a TCP port scan read its verdicts through, omitted for an
2166    /// ordinary scan.
2167    #[serde(default, skip_serializing_if = "Option::is_none")]
2168    pub idle_scan: Option<IdleScanRecord>,
2169    /// Whether the capture kept ICMP errors a technique did not need.
2170    ///
2171    /// Defaulted on read.
2172    #[serde(default)]
2173    pub icmp_evidence: bool,
2174}
2175
2176/// The zombie an idle scan ran through, as written to the journal. The
2177/// serialized form of [`IdleScan`].
2178#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2179pub struct IdleScanRecord {
2180    /// The zombie's address.
2181    pub zombie: String,
2182    /// The port on the zombie its counter was read from, omitted for the
2183    /// scanner's default.
2184    #[serde(default, skip_serializing_if = "Option::is_none")]
2185    pub zombie_port: Option<u16>,
2186}
2187
2188/// What a sitting changed about the packets it sent, as written to the journal.
2189/// The serialized form of
2190/// [`EvasionRecord`].
2191#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2192pub struct EvasionSettingsRecord {
2193    /// The source port every probe left from.
2194    #[serde(default, skip_serializing_if = "Option::is_none")]
2195    pub source_port: Option<u16>,
2196    /// The hop limit every ordinary probe carried.
2197    #[serde(default, skip_serializing_if = "Option::is_none")]
2198    pub ttl: Option<u8>,
2199    /// The number of random bytes appended to each probe's payload.
2200    #[serde(default, skip_serializing_if = "Option::is_none")]
2201    pub padding: Option<u16>,
2202    /// Whether TCP probes carried a deliberately wrong checksum.
2203    #[serde(default, skip_serializing_if = "is_false")]
2204    pub bad_tcp_checksum: bool,
2205    /// The hardware address every frame claimed to come from.
2206    #[serde(default, skip_serializing_if = "Option::is_none")]
2207    pub spoof_mac: Option<String>,
2208    /// The largest each IP fragment a probe was split into, in bytes.
2209    #[serde(default, skip_serializing_if = "Option::is_none")]
2210    pub fragment: Option<u16>,
2211    /// The addresses probes were also sent from as decoys.
2212    #[serde(default, skip_serializing_if = "Vec::is_empty")]
2213    pub decoys: Vec<String>,
2214    /// The TCP flags every port probe carried in place of the technique's own,
2215    /// named (e.g. `fin|psh|urg`).
2216    #[serde(default, skip_serializing_if = "Option::is_none")]
2217    pub flags: Option<String>,
2218}
2219
2220/// Omits a `false` boolean, so a recorded technique appears only when it was
2221/// used. The counterpart of `skip_serializing_if` on the optional fields.
2222fn is_false(value: &bool) -> bool {
2223    !*value
2224}
2225
2226impl From<&ScanSettings> for SettingsRecord {
2227    fn from(settings: &ScanSettings) -> Self {
2228        Self {
2229            send_mode: settings.send_mode.name().to_owned(),
2230            tcp_technique: settings.tcp_technique.name().to_owned(),
2231            sctp_technique: settings.sctp_technique.name().to_owned(),
2232            retry_effort: settings.retry.effort.name().to_owned(),
2233            retry_max_attempts: settings.retry.max_attempts.map(NonZeroU8::get),
2234            retry_timeout_scale: settings.retry.timeout_scale.map(TimeoutScale::get),
2235            retry_dampen_silent_hosts: settings.retry.dampen_silent_hosts,
2236            max_probe_rate: settings.max_probe_rate.map(NonZeroU32::get),
2237            min_probe_rate: settings.min_probe_rate.map(NonZeroU32::get),
2238            host_probe_interval: settings.host_probe_interval,
2239            probe_interval: settings.probe_interval,
2240            host_timeout: settings.host_timeout,
2241            scan_timeout: settings.scan_timeout,
2242            dns_enabled: settings.dns_enabled,
2243            redact: settings.redact,
2244            os_detection: settings.os_detection.name().to_owned(),
2245            service_detection: settings.service_detection.name().to_owned(),
2246            detection: wire::detection_ceiling_name(settings.detection.ceiling()).to_owned(),
2247            traceroute: settings.traceroute,
2248            characterise: settings.characterise,
2249            ip_protocols: settings.ip_protocols.clone(),
2250            tls_enumeration: settings.tls_enumeration,
2251            listen_only_ports: settings.listen_only_ports.clone(),
2252            excluded_ports: settings.excluded_ports.to_string(),
2253            evasion: settings.evasion.as_ref().map(|e| EvasionSettingsRecord {
2254                source_port: e.source_port,
2255                ttl: e.ttl,
2256                padding: e.padding,
2257                bad_tcp_checksum: e.bad_tcp_checksum,
2258                spoof_mac: e.spoof_mac.map(|mac| mac.to_string()),
2259                fragment: e.fragment,
2260                decoys: e.decoys.iter().map(|ip| ip.to_string()).collect(),
2261                flags: e.flags.map(wire::tcp_flags_name),
2262            }),
2263            idle_scan: settings.idle_scan.map(|i| IdleScanRecord {
2264                zombie: i.zombie.to_string(),
2265                zombie_port: i.zombie_port,
2266            }),
2267            icmp_evidence: settings.icmp_evidence,
2268        }
2269    }
2270}
2271
2272impl From<&SettingsRecord> for ScanSettings {
2273    fn from(record: &SettingsRecord) -> Self {
2274        Self {
2275            send_mode: record.send_mode.parse().unwrap_or_default(),
2276            tcp_technique: record.tcp_technique.parse().unwrap_or_default(),
2277            sctp_technique: record.sctp_technique.parse().unwrap_or_default(),
2278            retry: RetryConfig {
2279                effort: record.retry_effort.parse().unwrap_or_default(),
2280                // A zero budget or a NaN scale never applied, so it reads as absent.
2281                max_attempts: record.retry_max_attempts.and_then(NonZeroU8::new),
2282                timeout_scale: record.retry_timeout_scale.and_then(TimeoutScale::new),
2283                dampen_silent_hosts: record.retry_dampen_silent_hosts,
2284            },
2285            max_probe_rate: record.max_probe_rate.and_then(NonZeroU32::new),
2286            min_probe_rate: record.min_probe_rate.and_then(NonZeroU32::new),
2287            host_probe_interval: record.host_probe_interval,
2288            probe_interval: record.probe_interval,
2289            host_timeout: record.host_timeout,
2290            scan_timeout: record.scan_timeout,
2291            dns_enabled: record.dns_enabled,
2292            redact: record.redact,
2293            os_detection: record.os_detection.parse().unwrap_or_default(),
2294            service_detection: record.service_detection.parse().unwrap_or_default(),
2295            detection: match record.detection.as_str() {
2296                "off" => DetectionEnvelope::none(),
2297                name => wire::detection_class(name)
2298                    .map(DetectionEnvelope::up_to)
2299                    .unwrap_or_default(),
2300            },
2301            traceroute: record.traceroute,
2302            characterise: record.characterise,
2303            ip_protocols: record.ip_protocols.clone(),
2304            tls_enumeration: record.tls_enumeration,
2305            listen_only_ports: record.listen_only_ports.clone(),
2306            // Read downward; this engine writes the canonical form, which always
2307            // reads back.
2308            excluded_ports: PortSet::try_from(record.excluded_ports.as_str()).unwrap_or_default(),
2309            evasion: record.evasion.as_ref().map(|e| EvasionRecord {
2310                source_port: e.source_port,
2311                ttl: e.ttl,
2312                padding: e.padding,
2313                bad_tcp_checksum: e.bad_tcp_checksum,
2314                spoof_mac: e.spoof_mac.as_ref().and_then(|s| s.parse().ok()),
2315                fragment: e.fragment,
2316                decoys: e.decoys.iter().filter_map(|s| s.parse().ok()).collect(),
2317                flags: e.flags.as_deref().map(wire::tcp_flags),
2318            }),
2319            idle_scan: record.idle_scan.as_ref().and_then(|i| {
2320                i.zombie.parse().ok().map(|zombie| IdleScan {
2321                    zombie,
2322                    zombie_port: i.zombie_port,
2323                })
2324            }),
2325            icmp_evidence: record.icmp_evidence,
2326        }
2327    }
2328}
2329
2330/// What one strategy recorded about its own run.
2331#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2332pub struct ProbeStatsRecord {
2333    /// Which strategy, by wire name.
2334    pub scanner: String,
2335    /// How many targets it was given.
2336    pub targets: u128,
2337    /// Why its receive loop stopped, by wire name.
2338    pub stop_reason: String,
2339    /// How long it ran.
2340    pub elapsed: Duration,
2341    /// How many sends it attempted.
2342    pub sends_attempted: u64,
2343    /// How many never left this host, refused or unable to reach their
2344    /// address.
2345    pub sends_failed: u64,
2346    /// How many were seen leaving on the wire. Defaulted on read.
2347    #[serde(default)]
2348    pub sends_witnessed: u64,
2349    /// How many segments its capture handed it.
2350    pub segments_seen: u64,
2351    /// Where its congestion window ended up.
2352    #[serde(default)]
2353    pub window: Option<WindowRecord>,
2354    /// How many captured segments belonged to something else.
2355    pub segments_off_target: u64,
2356    /// How many replies named no attempt.
2357    pub replies_without_rtt: u64,
2358    /// How many of those were refusals that named no attempt.
2359    pub refusals_unattributed: u64,
2360    /// How many hosts it found.
2361    pub hosts_found: u64,
2362    /// How many answers arrived on each attempt.
2363    #[serde(default)]
2364    pub answered_on: Vec<u64>,
2365    /// How many answers could not be attributed.
2366    pub answered_unattributed: u64,
2367    /// When the first reply arrived.
2368    #[serde(default)]
2369    pub first_reply: Option<Duration>,
2370    /// When the last did.
2371    #[serde(default)]
2372    pub last_reply: Option<Duration>,
2373    /// How many hosts were found in each time bucket.
2374    #[serde(default)]
2375    pub found_at: Vec<u64>,
2376    /// What the capture reported about its own losses.
2377    #[serde(default)]
2378    pub capture: Option<CaptureRecord>,
2379}
2380
2381impl From<&ProbeStats> for ProbeStatsRecord {
2382    fn from(stats: &ProbeStats) -> Self {
2383        Self {
2384            scanner: wire::scanner_kind_name(stats.scanner()).to_owned(),
2385            targets: stats.targets(),
2386            stop_reason: wire::stop_reason_name(stats.stop_reason()).to_owned(),
2387            elapsed: stats.elapsed(),
2388            sends_attempted: stats.sends_attempted(),
2389            sends_failed: stats.sends_failed(),
2390            sends_witnessed: stats.sends_witnessed(),
2391            segments_seen: stats.segments_seen(),
2392            window: stats.window().map(WindowRecord::from),
2393            segments_off_target: stats.segments_off_target(),
2394            replies_without_rtt: stats.replies_without_rtt(),
2395            refusals_unattributed: stats.refusals_unattributed(),
2396            hosts_found: stats.hosts_found(),
2397            answered_on: stats.answered_on().to_vec(),
2398            answered_unattributed: stats.answered_unattributed(),
2399            first_reply: stats.first_reply(),
2400            last_reply: stats.last_reply(),
2401            found_at: stats.found_at().to_vec(),
2402            capture: stats.capture().map(CaptureRecord::from),
2403        }
2404    }
2405}
2406
2407impl From<&ProbeStatsRecord> for ProbeStats {
2408    fn from(record: &ProbeStatsRecord) -> Self {
2409        // `from_parts` fits each distribution to this build.
2410        ProbeStats::from_parts(ProbeStatsParts {
2411            scanner: wire::scanner_kind(&record.scanner).unwrap_or(ScannerKind::Composite),
2412            targets: record.targets,
2413            // An unknown stop reason reads as a run cut short, which claims least.
2414            stop_reason: wire::stop_reason(&record.stop_reason)
2415                .unwrap_or(StopReason::DeadlineExpired),
2416            elapsed: record.elapsed,
2417            sends_attempted: record.sends_attempted,
2418            sends_failed: record.sends_failed,
2419            sends_witnessed: record.sends_witnessed,
2420            segments_seen: record.segments_seen,
2421            window: record.window.as_ref().map(WindowSummary::from),
2422            segments_off_target: record.segments_off_target,
2423            replies_without_rtt: record.replies_without_rtt,
2424            refusals_unattributed: record.refusals_unattributed,
2425            hosts_found: record.hosts_found,
2426            answered_on: record.answered_on.clone(),
2427            answered_unattributed: record.answered_unattributed,
2428            first_reply: record.first_reply,
2429            last_reply: record.last_reply,
2430            found_at: record.found_at.clone(),
2431            capture: record.capture.as_ref().map(CaptureCounts::from),
2432        })
2433    }
2434}
2435
2436/// Where a strategy's congestion window ended up.
2437#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
2438pub struct WindowRecord {
2439    /// The capacity it finished at.
2440    pub capacity: usize,
2441    /// The largest it reached.
2442    pub peak: usize,
2443    /// How many times it was cut.
2444    pub reductions: u32,
2445    /// Whether it was allowed to adapt.
2446    pub adaptive: bool,
2447    /// Whether it ended at its floor.
2448    pub at_floor: bool,
2449}
2450
2451impl From<WindowSummary> for WindowRecord {
2452    fn from(window: WindowSummary) -> Self {
2453        Self {
2454            capacity: window.capacity,
2455            peak: window.peak,
2456            reductions: window.reductions,
2457            adaptive: window.adaptive,
2458            at_floor: window.at_floor,
2459        }
2460    }
2461}
2462
2463impl From<&WindowRecord> for WindowSummary {
2464    fn from(record: &WindowRecord) -> Self {
2465        Self {
2466            capacity: record.capacity,
2467            peak: record.peak,
2468            reductions: record.reductions,
2469            adaptive: record.adaptive,
2470            at_floor: record.at_floor,
2471        }
2472    }
2473}
2474
2475/// What a capture reported about its own losses.
2476#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
2477pub struct CaptureRecord {
2478    /// How many packets it handed over.
2479    pub received: u64,
2480    /// How many it dropped.
2481    pub dropped: u64,
2482    /// How many the interface dropped before it.
2483    pub if_dropped: u64,
2484    /// How many captures ended before they were told to.
2485    ///
2486    /// Defaulted on read.
2487    #[serde(default)]
2488    pub stopped_early: u64,
2489}
2490
2491impl From<CaptureCounts> for CaptureRecord {
2492    fn from(counts: CaptureCounts) -> Self {
2493        Self {
2494            received: counts.received,
2495            dropped: counts.dropped,
2496            if_dropped: counts.if_dropped,
2497            stopped_early: counts.stopped_early,
2498        }
2499    }
2500}
2501
2502impl From<&CaptureRecord> for CaptureCounts {
2503    fn from(record: &CaptureRecord) -> Self {
2504        Self {
2505            received: record.received,
2506            dropped: record.dropped,
2507            if_dropped: record.if_dropped,
2508            stopped_early: record.stopped_early,
2509        }
2510    }
2511}
2512
2513/// The plan a scan ran against, as a file holds it.
2514///
2515/// Ranges and port lists, so a `/16` on every port is a few dozen bytes. A resume uses
2516/// the plan that ran.
2517///
2518/// A host-discovery plan is written as a single unit with an empty port list, so one
2519/// shape covers both phases.
2520#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
2521pub struct PlanRecord {
2522    /// The units, in the order they were walked. Order is part of the plan:
2523    /// positions are counted through it.
2524    #[serde(default)]
2525    pub units: Vec<UnitRecord>,
2526}
2527
2528impl PlanRecord {
2529    /// Every address the plan covers, whatever its ports.
2530    ///
2531    /// For a port-scan plan, the addresses with ports dropped, so units naming the same
2532    /// address collapse.
2533    pub fn addresses(&self) -> IpSet {
2534        let mut ips = IpSet::new();
2535        for unit in &self.units {
2536            for range in unit.ranges.iter().filter_map(RangeRecord::rebuild) {
2537                ips.insert_range(range);
2538            }
2539        }
2540        ips.canonicalize();
2541        ips
2542    }
2543}
2544
2545impl From<&IpSet> for PlanRecord {
2546    /// Records a host-discovery plan: the addresses, and no ports.
2547    fn from(addresses: &IpSet) -> Self {
2548        Self {
2549            units: vec![UnitRecord {
2550                ranges: ranges_of(addresses),
2551                spec: String::new(),
2552            }],
2553        }
2554    }
2555}
2556
2557/// An address set's ranges, v4 before v6, in the order the set enumerates them.
2558fn ranges_of(ips: &IpSet) -> Vec<RangeRecord> {
2559    ips.v4()
2560        .iter()
2561        .map(|range| RangeRecord::from(&IpRange::V4(*range)))
2562        .chain(
2563            ips.v6()
2564                .iter()
2565                .map(|range| RangeRecord::from(&IpRange::V6(*range))),
2566        )
2567        .collect()
2568}
2569
2570/// One set of addresses paired with the ports to try on each.
2571#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
2572pub struct UnitRecord {
2573    /// The addresses, as ranges.
2574    #[serde(default)]
2575    pub ranges: Vec<RangeRecord>,
2576    /// The ports, as the specification [`PortSet`] parses.
2577    ///
2578    /// As in [`PortsRecord`]. A [`PortSet`] is canonical, so the specification and the
2579    /// enumeration have the same order and positions survive the round trip.
2580    #[serde(default, skip_serializing_if = "String::is_empty")]
2581    pub spec: String,
2582}
2583
2584impl UnitRecord {
2585    /// The ports this unit walks: none for a record whose specification is
2586    /// absent or does not parse, as a host-discovery plan's is.
2587    fn port_set(&self) -> PortSet {
2588        PortSet::try_from(self.spec.as_str()).unwrap_or_default()
2589    }
2590}
2591
2592impl From<&TargetMap> for PlanRecord {
2593    fn from(plan: &TargetMap) -> Self {
2594        Self {
2595            units: plan
2596                .units
2597                .iter()
2598                .map(|unit| UnitRecord {
2599                    ranges: ranges_of(unit.ips()),
2600                    spec: unit.ports().to_string(),
2601                })
2602                .collect(),
2603        }
2604    }
2605}
2606
2607impl From<&PlanRecord> for TargetMap {
2608    fn from(record: &PlanRecord) -> Self {
2609        let mut plan = TargetMap::new();
2610
2611        for unit in &record.units {
2612            let mut ips = IpSet::new();
2613            for range in unit.ranges.iter().filter_map(RangeRecord::rebuild) {
2614                ips.insert_range(range);
2615            }
2616
2617            let ports = unit.port_set();
2618
2619            // An unreadable unit is kept empty, so later positions keep their
2620            // numbers.
2621            plan.add_unit(TargetSet::new(ips, ports));
2622        }
2623
2624        plan
2625    }
2626}
2627
2628// ╔════════════════════════════════════════════╗
2629// ║ ████████╗███████╗███████╗████████╗███████╗ ║
2630// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
2631// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
2632// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
2633// ║    ██║   ███████╗███████║   ██║   ███████║ ║
2634// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
2635// ╚════════════════════════════════════════════╝
2636
2637#[cfg(test)]
2638mod tests {
2639    use super::*;
2640    use crate::model::host::{HostStatus, NetworkRole};
2641    use crate::model::mac::MacAddr;
2642    use crate::model::port::Protocol;
2643    use std::net::Ipv4Addr;
2644    use std::time::UNIX_EPOCH;
2645
2646    fn at(seconds: u64) -> SystemTime {
2647        UNIX_EPOCH + Duration::from_secs(seconds)
2648    }
2649
2650    /// A host carrying something in every field the model has.
2651    ///
2652    /// The round-trip oracle is only as good as this is complete; a new model field
2653    /// belongs here.
2654    fn maximal_host() -> Host {
2655        let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)));
2656        host.add_ip(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 2)));
2657        host.add_ip("2001:db8::1".parse().expect("an address"));
2658        host.set_hostname(Some("router.example".to_string()));
2659        host.set_status(HostStatus::Up);
2660        // Every kind from every source.
2661        for &kind in crate::model::host::NameKind::ALL {
2662            for &source in crate::model::host::NameSource::ALL {
2663                let name = format!("{kind:?}-{source:?}.example");
2664                host.record_name(HostName::new(kind, source, &name).expect("a name"));
2665            }
2666        }
2667
2668        let mut arp = StatusReason::new(StatusProtocol::Arp, "reply from gateway");
2669        arp.source = EvidenceSource::Intermediary(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 254)));
2670        host.add_reason(arp);
2671        let mut unreachable = StatusReason::basic(StatusProtocol::IcmpUnreachable);
2672        unreachable.source = EvidenceSource::Withheld;
2673        host.add_reason(unreachable);
2674        host.add_reason(StatusReason::new(
2675            StatusProtocol::Custom("a-strategy".into()),
2676            "said so",
2677        ));
2678
2679        let mut os = OsFingerprint::new("Linux 5.15", 95)
2680            .with_family("Unix-like")
2681            .with_generation("5.15.0")
2682            .with_vendor("Canonical")
2683            .with_kernel("5.15.0-91-generic")
2684            .with_detail_accuracy(70)
2685            .with_evidence("syn-ack hops>=64 opts=M,S,T,N,W");
2686        os.add_cpe("cpe:/o:linux:linux_kernel:5.15.0");
2687        os.add_cpe("cpe:/o:canonical:ubuntu_linux:22.04");
2688        host.set_os(os);
2689
2690        host.record_os_evidence(OsEvidence {
2691            source: OsSource::TcpStack,
2692            family: Some("Linux".to_string()),
2693            device: None,
2694            vendor: Some("Canonical".to_string()),
2695            product: Some("Ubuntu".to_string()),
2696            version: Some("22.04".to_string()),
2697            kernel: Some("5.15.0".to_string()),
2698            arch: None,
2699            cpe: Some("cpe:/o:canonical:ubuntu_linux:22.04".to_string()),
2700            confidence: 0.65,
2701            evidence: "stack reading".to_string(),
2702        });
2703        host.record_os_evidence(OsEvidence {
2704            source: OsSource::ServiceBanner,
2705            family: Some("Linux".to_string()),
2706            device: None,
2707            vendor: None,
2708            product: None,
2709            version: None,
2710            kernel: None,
2711            arch: None,
2712            cpe: None,
2713            confidence: 0.4,
2714            evidence: "ssh banner".to_string(),
2715        });
2716
2717        host.record_mac(MacAddr::new(0x2c, 0xcf, 0x67, 0x00, 0x00, 0x01));
2718        host.record_mac(MacAddr::new(0x00, 0x1a, 0x2b, 0x3c, 0x4d, 0x5e));
2719        host.set_zone(Zone::new(7, "eth0"));
2720
2721        host.add_rtts([
2722            Duration::from_micros(1_200),
2723            Duration::from_micros(1_800),
2724            Duration::from_micros(3_000),
2725        ]);
2726        host.record_hop_counter(58);
2727
2728        host.record_hop(Hop::answered(
2729            3,
2730            IpAddr::V4(Ipv4Addr::new(198, 51, 100, 1)),
2731            Some(Duration::from_micros(4_100)),
2732        ));
2733        host.record_hop(Hop::silent(2));
2734        host.record_hop(
2735            Hop::answered(1, IpAddr::V4(Ipv4Addr::new(192, 0, 2, 254)), None).as_inferred(),
2736        );
2737        host.record_hop(Hop::withheld(4).as_inferred());
2738
2739        host.add_network_role(NetworkRole::Tarpit);
2740        host.add_network_role(NetworkRole::Truncated);
2741
2742        host.record_ip_protocol(47, IpProtocolState::Open);
2743        host.record_ip_protocol(89, IpProtocolState::Closed);
2744        host.record_ip_protocol(103, IpProtocolState::Unasked);
2745
2746        host.add_port(maximal_port());
2747        host.add_port(Port::new(53, Protocol::Udp, PortState::OpenOrNoReply));
2748        host.add_port(Port::new(80, Protocol::Tcp, PortState::Closed));
2749
2750        host.add_finding(maximal_finding());
2751
2752        host.restore_seen(at(1_700_000_000), at(1_700_003_600));
2753        host
2754    }
2755
2756    fn maximal_port() -> Port {
2757        let service = Service::new("http", 100)
2758            .with_product("nginx")
2759            .with_vendor("F5")
2760            .with_version("1.24.0")
2761            .with_extrainfo("Ubuntu")
2762            .with_cpe("cpe:/a:nginx:nginx:1.24.0");
2763
2764        let certificate = CertificateInfo::new(
2765            "example.com",
2766            "R3",
2767            at(1_690_000_000),
2768            at(1_720_000_000),
2769            "ab:cd:ef",
2770        )
2771        .with_sans(["example.com".into(), "www.example.com".into()])
2772        .with_public_key("rsa", 2048);
2773
2774        let support = TlsSupport::new()
2775            .accepting(VersionSupport::new(
2776                TlsVersion::Tls12,
2777                vec![CipherSuite::from_code(0xC02F).expect("a registered suite")],
2778                vec![0xFF01],
2779            ))
2780            .leaving_unfinished(UnfinishedVersion::new(
2781                TlsVersion::Tls12,
2782                Interruption::Unanswered,
2783            ));
2784
2785        let security = Security::new()
2786            .with_tls_version("TLSv1.3")
2787            .with_cipher_suite("TLS_AES_256_GCM_SHA384")
2788            .with_alpn("h2")
2789            .with_alpn("http/1.1")
2790            .with_certificate(certificate)
2791            .with_support(support);
2792
2793        let discovery = Discovery::new(ScanResponse::TcpSynAck)
2794            .seen_at(at(1_700_000_500))
2795            .with_rtt(Duration::from_micros(2_400))
2796            .with_ttl(58)
2797            .with_source_ip(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 1)));
2798
2799        let mut port = Port::new(443, Protocol::Tcp, PortState::Open)
2800            .with_service(service)
2801            .with_security(security)
2802            .with_discovery(discovery);
2803        port.add_finding(maximal_finding());
2804        port
2805    }
2806
2807    /// The oracle.
2808    ///
2809    /// A host renders identically through the export path before and after a round
2810    /// trip; the export DTO is an independent view, so a forgotten field shows up.
2811    #[test]
2812    fn a_fully_populated_host_survives_a_round_trip() {
2813        let original = maximal_host();
2814        let rebuilt = Host::from(&HostRecord::from(&original));
2815
2816        let options = crate::export::ExportOptions::default();
2817        let render = |host: &Host| {
2818            serde_json::to_value(crate::export::schema::HostDto::new(host, &options))
2819                .expect("a host renders")
2820        };
2821
2822        assert_eq!(
2823            render(&original),
2824            render(&rebuilt),
2825            "a field was lost in the round trip"
2826        );
2827    }
2828
2829    fn maximal_finding() -> Finding {
2830        Finding::new(
2831            DetectionId::new("grafana-path-traversal", Version::new(1, 2, 3), "deadbeef").unwrap(),
2832            "Grafana plugin path traversal",
2833            Severity::Critical,
2834            Confidence::Strong,
2835            DetectionClass::ActiveBenign,
2836        )
2837        .unwrap()
2838        .with_excerpt(Excerpt::new("root:x:0:0:root:/root:/bin/bash"))
2839        .with_reference(Reference::cve("CVE-2021-43798").unwrap())
2840        .with_reference(Reference::cwe(22))
2841        .with_reference(Reference::url("https://grafana.com/security/"))
2842        .with_remediation("Upgrade to 8.3.1 or later.")
2843        .with_cpe("cpe:/a:grafana:grafana:8.3.0")
2844        .with_cpe("cpe:2.3:a:grafana:grafana:8.3.0:*:*:*:*:*:*:*")
2845        .with_group(
2846            FindingGroup::new("grafana-plugin-paths", "Grafana plugin path weaknesses").unwrap(),
2847        )
2848    }
2849
2850    /// A half group is dropped and the finding kept.
2851    #[test]
2852    fn a_record_carrying_half_a_group_reads_back_without_one() {
2853        let mut record = FindingRecord::from(&maximal_finding());
2854        record.group = Some(FindingGroupRecord {
2855            id: "grafana-plugin-paths".into(),
2856            summary: String::new(),
2857        });
2858
2859        let rebuilt = record.rebuild().expect("the finding still rebuilds");
2860        assert!(rebuilt.group().is_none(), "and belongs to no group");
2861    }
2862
2863    #[test]
2864    fn a_fully_populated_finding_survives_a_round_trip() {
2865        let original = maximal_finding();
2866        let rebuilt = FindingRecord::from(&original)
2867            .rebuild()
2868            .expect("a finding rebuilds");
2869        assert_eq!(original, rebuilt, "a field was lost in the round trip");
2870    }
2871
2872    /// A record carrying only `cpe` reads back resting on it.
2873    #[test]
2874    fn a_finding_recorded_with_one_identifier_reads_back_resting_on_it() {
2875        let mut record = FindingRecord::from(&maximal_finding());
2876        record.cpes.clear();
2877        let rebuilt = record.rebuild().expect("a finding rebuilds");
2878
2879        assert_eq!(
2880            rebuilt.cpes().collect::<Vec<_>>(),
2881            ["cpe:/a:grafana:grafana:8.3.0"]
2882        );
2883    }
2884
2885    #[test]
2886    fn a_finding_record_reads_unknown_names_downward_and_a_nameless_one_away() {
2887        // Unknown soft fields read to the least they could claim.
2888        let softened = FindingRecord {
2889            group: None,
2890            detection: DetectionIdRecord {
2891                id: "det".into(),
2892                version: "not-a-version".into(), // -> 0.0.0
2893                content_hash: "h".into(),
2894            },
2895            title: "A finding".into(),
2896            severity: "catastrophic".into(), // -> Info
2897            confidence: "absolute".into(),   // -> Heuristic
2898            class: "nosy".into(),            // -> Passive
2899            excerpt: None,
2900            references: vec![ReferenceRecord {
2901                kind: "mystery".into(),
2902                value: "x".into(),
2903            }],
2904            remediation: None,
2905            cpe: None,
2906            cpes: Vec::new(),
2907            subject: None,
2908            build: None,
2909            advised_by: None,
2910            exploited: None,
2911        };
2912        let finding = softened
2913            .rebuild()
2914            .expect("an unparseable-but-named finding still rebuilds");
2915        assert_eq!(finding.severity(), Severity::Info);
2916        assert_eq!(finding.confidence(), Confidence::Heuristic);
2917        assert_eq!(finding.class(), DetectionClass::Passive);
2918        assert_eq!(finding.detection().version(), Version::new(0, 0, 0));
2919        assert_eq!(
2920            finding.references().count(),
2921            0,
2922            "an unknown reference is dropped, the finding kept"
2923        );
2924
2925        // No detection or no title is refused.
2926        let nameless = FindingRecord {
2927            detection: DetectionIdRecord {
2928                id: "  ".into(),
2929                ..softened.detection.clone()
2930            },
2931            ..softened.clone()
2932        };
2933        assert!(nameless.rebuild().is_none());
2934        let titleless = FindingRecord {
2935            title: "  ".into(),
2936            ..softened.clone()
2937        };
2938        assert!(titleless.rebuild().is_none());
2939    }
2940
2941    #[test]
2942    fn a_hosts_findings_survive_a_record_round_trip() {
2943        // Findings must survive the round trip.
2944        let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 9)));
2945        host.add_finding(maximal_finding());
2946        let rebuilt = Host::from(&HostRecord::from(&host));
2947
2948        let original: Vec<_> = host.findings().cloned().collect();
2949        let round: Vec<_> = rebuilt.findings().cloned().collect();
2950        assert_eq!(original, round, "a host's findings were lost in the record");
2951    }
2952
2953    #[test]
2954    fn a_ports_findings_survive_a_record_round_trip() {
2955        let mut port = Port::new(3000, Protocol::Tcp, PortState::Open);
2956        port.add_finding(maximal_finding());
2957        let rebuilt = PortRecord::from(&port)
2958            .rebuild()
2959            .expect("a TCP port rebuilds");
2960
2961        let original: Vec<_> = port.findings().cloned().collect();
2962        let round: Vec<_> = rebuilt.findings().cloned().collect();
2963        assert_eq!(original, round, "a port's findings were lost in the record");
2964    }
2965
2966    /// The record is the same after a round trip through the model.
2967    #[test]
2968    fn the_record_is_stable_across_a_rebuild() {
2969        let record = HostRecord::from(&maximal_host());
2970        let rebuilt = HostRecord::from(&Host::from(&record));
2971
2972        assert_eq!(record, rebuilt);
2973    }
2974
2975    /// And through a file.
2976    #[test]
2977    fn the_record_survives_json() {
2978        let record = HostRecord::from(&maximal_host());
2979
2980        let text = serde_json::to_string(&record).expect("serializes");
2981        let read: HostRecord = serde_json::from_str(&text).expect("deserializes");
2982
2983        assert_eq!(record, read);
2984    }
2985
2986    /// First- and last-seen times survive a round trip.
2987    #[test]
2988    fn the_times_a_host_was_seen_survive() {
2989        let rebuilt = Host::from(&HostRecord::from(&maximal_host()));
2990
2991        assert_eq!(rebuilt.first_seen(), at(1_700_000_000));
2992        assert_eq!(rebuilt.last_seen(), at(1_700_003_600));
2993    }
2994
2995    /// A record naming values this build does not know reads as the least it
2996    /// could have established, never as more.
2997    #[test]
2998    fn unknown_names_read_downwards() {
2999        let mut record = HostRecord::from(&maximal_host());
3000        let recorded = record.ports.len();
3001        let unreadable = (record.ports[0].port, record.ports[0].protocol.clone());
3002        record.status = "ascended".to_string();
3003        record.ports[0].state = "ajar".to_string();
3004        record.ports[0].protocol = "dccp".to_string();
3005
3006        let rebuilt = Host::from(&record);
3007
3008        assert_eq!(rebuilt.status(), HostStatus::Unknown);
3009
3010        // A status and a state read down to their bottom. A protocol has no
3011        // ordering, so an unknown one is left out; see `PortRecord::rebuild`.
3012        assert_eq!(
3013            rebuilt.ports().count(),
3014            recorded - 1,
3015            "the one port under an unreadable protocol is dropped and the rest stay"
3016        );
3017        assert!(
3018            !rebuilt.ports().any(|port| port.number() == unreadable.0
3019                && wire::protocol_name(port.protocol()) == unreadable.1),
3020            "and it is not filed under the protocol it was originally written as"
3021        );
3022
3023        // An unknown state under a known protocol reads as the bottom.
3024        let mut record = HostRecord::from(&maximal_host());
3025        record.ports[0].state = "ajar".to_string();
3026        let number = record.ports[0].port;
3027        let protocol = wire::protocol(&record.ports[0].protocol).expect("a readable protocol");
3028
3029        let rebuilt = Host::from(&record);
3030        let port = rebuilt
3031            .ports()
3032            .find(|port| port.number() == number && port.protocol() == protocol)
3033            .expect("the port is still recorded");
3034        assert_eq!(
3035            port.state(),
3036            PortState::Unasked,
3037            "a verdict this build cannot read is no verdict, which is what the \
3038             bottom of the ordering says"
3039        );
3040    }
3041
3042    /// **A record this build cannot read does not become a claim about one it
3043    /// can.**
3044    ///
3045    /// A port under an unknown transport does not merge into the TCP port of the same
3046    /// number.
3047    #[test]
3048    fn an_unreadable_protocol_does_not_contaminate_the_port_it_would_collide_with() {
3049        let mut host = Host::new("192.0.2.1".parse().expect("literal"));
3050        host.set_status(HostStatus::Up);
3051        host.add_port(Port::new(443, Protocol::Tcp, PortState::Open));
3052
3053        let record = HostRecord::from(&host);
3054        let mut value: serde_json::Value = serde_json::to_value(&record).expect("serialises");
3055
3056        // The same number under an unknown transport, with its own service.
3057        let mut future = value["ports"][0].clone();
3058        future["protocol"] = serde_json::json!("quic");
3059        future["state"] = serde_json::json!("closed");
3060        future["service"] = serde_json::json!({"name": "quic-only", "confidence": 95});
3061        value["ports"]
3062            .as_array_mut()
3063            .expect("an array")
3064            .push(future);
3065
3066        let read: HostRecord = serde_json::from_value(value).expect("reads back");
3067        let rebuilt = Host::from(&read);
3068
3069        let ports: Vec<_> = rebuilt.ports().collect();
3070        assert_eq!(ports.len(), 1, "the readable port, and only it");
3071        assert_eq!(ports[0].protocol(), Protocol::Tcp);
3072        assert_eq!(ports[0].state(), PortState::Open);
3073        assert!(
3074            ports[0].service().is_none(),
3075            "the TCP port must not acquire a service named on an endpoint this \
3076             build could not read"
3077        );
3078    }
3079
3080    /// **The same holds for a port record rebuilt on its own.**
3081    ///
3082    /// A `PortRecord` under an unknown transport rebuilds to `None`.
3083    #[test]
3084    fn a_port_record_under_an_unreadable_transport_rebuilds_as_no_port() {
3085        let mut record = PortRecord::from(&Port::new(443, Protocol::Tcp, PortState::Open));
3086        record.protocol = "quic".to_string();
3087
3088        assert_eq!(
3089            record.rebuild(),
3090            None,
3091            "a transport this build cannot read is not TCP, or any other it can"
3092        );
3093
3094        // An unknown state reads down instead.
3095        let mut record = PortRecord::from(&Port::new(443, Protocol::Tcp, PortState::Open));
3096        record.state = "ajar".to_string();
3097        let port = record.rebuild().expect("a readable transport rebuilds");
3098        assert_eq!(port.protocol(), Protocol::Tcp);
3099        assert_eq!(port.state(), PortState::Unasked);
3100    }
3101
3102    /// A plan's ports survive as a specification, in the same enumeration order.
3103    #[test]
3104    fn a_plans_ports_round_trip_as_a_specification() {
3105        use crate::model::ip::set::IpSet;
3106        use crate::model::target::TargetSet;
3107
3108        let mut plan = TargetMap::new();
3109        plan.add_unit(TargetSet::new(
3110            "192.0.2.0/30".parse::<IpSet>().expect("a range"),
3111            "80,443,1000-1010,u:53".parse::<PortSet>().expect("ports"),
3112        ));
3113
3114        let record = PlanRecord::from(&plan);
3115        assert_eq!(
3116            TargetMap::from(&record).iter().collect::<Vec<_>>(),
3117            plan.iter().collect::<Vec<_>>(),
3118            "the enumeration a position is counted through has to be identical"
3119        );
3120
3121        // A few bytes, not one entry per port.
3122        assert!(record.units[0].spec.len() < 40, "{}", record.units[0].spec);
3123    }
3124
3125    #[test]
3126    fn a_phase_survives_a_round_trip() {
3127        let report = crate::export::fixture::report();
3128
3129        for phase in report.phases() {
3130            let rebuilt = ScanPhase::from(&PhaseRecord::from(phase));
3131
3132            let options = crate::export::ExportOptions::default();
3133            let render = |phase: &ScanPhase| {
3134                serde_json::to_value(crate::export::schema::PhaseDto::new(phase, &options))
3135                    .expect("a phase renders")
3136            };
3137            assert_eq!(render(phase), render(&rebuilt), "a field was lost");
3138        }
3139    }
3140
3141    /// A capture that stopped early survives the journal, and a record without the
3142    /// field still opens.
3143    #[test]
3144    fn a_capture_that_stopped_early_survives_the_journal() {
3145        let counts = CaptureCounts {
3146            received: 271,
3147            dropped: 4,
3148            if_dropped: 1,
3149            stopped_early: 2,
3150        };
3151
3152        let record = CaptureRecord::from(counts);
3153        assert_eq!(CaptureCounts::from(&record), counts, "a field was lost");
3154
3155        // Through the serialized form.
3156        let json = serde_json::to_string(&record).expect("a record serializes");
3157        assert!(json.contains("stopped_early"), "{json}");
3158        let read: CaptureRecord = serde_json::from_str(&json).expect("and reads back");
3159        assert_eq!(CaptureCounts::from(&read), counts);
3160
3161        // A record without the field reports none.
3162        let older = r#"{"received":271,"dropped":4,"if_dropped":1}"#;
3163        let read: CaptureRecord = serde_json::from_str(older).expect("an older journal opens");
3164        assert_eq!(CaptureCounts::from(&read).stopped_early, 0);
3165        assert_eq!(CaptureCounts::from(&read).received, 271);
3166    }
3167
3168    /// Privilege is a `Privilege` in the model and a boolean on the wire; the
3169    /// conversion is exact both ways.
3170    #[test]
3171    fn privilege_crosses_the_record_boundary_as_the_boolean_the_format_promised() {
3172        let report = crate::export::fixture::report();
3173        let original = report.phases().first().expect("the fixture has a phase");
3174
3175        for (privilege, written) in [
3176            (Some(Privilege::Raw), Some(true)),
3177            (Some(Privilege::Connect), Some(false)),
3178            // Unmeasured, as for a phase imported from another scanner.
3179            (None, None),
3180        ] {
3181            let mut record = PhaseRecord::from(original);
3182            record.privileged = written;
3183
3184            let phase = ScanPhase::from(&record);
3185            assert_eq!(phase.privilege(), privilege, "reading {written:?}");
3186            assert_eq!(
3187                PhaseRecord::from(&phase).privileged,
3188                written,
3189                "writing {privilege:?}"
3190            );
3191        }
3192    }
3193
3194    /// Which probe measured the round trips survives.
3195    #[test]
3196    fn the_probe_behind_a_round_trip_survives_the_record() {
3197        use crate::model::host::StatusProtocol;
3198
3199        let mut host = Host::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 9)));
3200        host.add_rtt_from(Duration::from_micros(90), StatusProtocol::Arp);
3201        host.add_rtt_from(Duration::from_micros(110), StatusProtocol::Arp);
3202
3203        let record = HostRecord::from(&host);
3204        assert_eq!(record.telemetry.rtt_protocol.as_deref(), Some("arp"));
3205        assert!(
3206            record.telemetry.rtt_sources.is_empty(),
3207            "round trips alone are written as they always were"
3208        );
3209
3210        let mut restored = Host::new(IpAddr::V4(Ipv4Addr::new(192, 0, 2, 9)));
3211        record.telemetry.restore(&mut restored);
3212
3213        assert_eq!(restored.rtt_protocol(), Some(StatusProtocol::Arp));
3214        assert_eq!(restored.min_rtt(), host.min_rtt());
3215    }
3216
3217    /// An upper bound on a round trip comes back as an upper bound, and a
3218    /// round trip as a round trip.
3219    ///
3220    /// A resumed scan sizes waits and reports latencies from what it read back.
3221    #[test]
3222    fn what_kind_of_round_trip_a_sample_is_survives_the_journal() {
3223        use crate::model::host::StatusProtocol;
3224
3225        let ip = IpAddr::V4(Ipv4Addr::new(192, 0, 2, 9));
3226        let mut host = Host::new(ip);
3227        host.add_first_to_neighbour_rtt_from(Duration::from_millis(40), StatusProtocol::TcpConnect);
3228        host.add_rtt_from(Duration::from_millis(7), StatusProtocol::TcpConnect);
3229        host.add_rtt_from(Duration::from_millis(9), StatusProtocol::TcpConnect);
3230        let mut bounded = Host::new(ip);
3231        bounded.add_segment_wide_rtt_from(Duration::from_millis(5), StatusProtocol::IcmpEcho);
3232        bounded.add_segment_wide_rtt_from(Duration::from_millis(50), StatusProtocol::IcmpEcho);
3233
3234        for (host, average) in [(host, 8), (bounded, 5)] {
3235            let line = serde_json::to_string(&HostRecord::from(&host)).expect("serializes");
3236            let record: HostRecord = serde_json::from_str(&line).expect("deserializes");
3237            let mut restored = Host::new(ip);
3238            record.telemetry.restore(&mut restored);
3239
3240            assert_eq!(host.average_rtt(), Some(Duration::from_millis(average)));
3241            assert_eq!(
3242                restored.average_rtt(),
3243                host.average_rtt(),
3244                "read back from {line}"
3245            );
3246            let sources = |host: &Host| {
3247                host.telemetry()
3248                    .history()
3249                    .iter()
3250                    .map(|sample| sample.source)
3251                    .collect::<Vec<_>>()
3252            };
3253            assert_eq!(sources(&restored), sources(&host));
3254        }
3255    }
3256
3257    /// `icmp_evidence` survives a round trip.
3258    #[test]
3259    fn asking_for_icmp_evidence_survives_the_settings_round_trip() {
3260        use crate::config::ZondConfig;
3261
3262        let mut settings = ScanSettings::from(&ZondConfig::default());
3263        assert!(settings.icmp_evidence, "on unless declined");
3264
3265        // Both ways round.
3266        settings.icmp_evidence = false;
3267        assert!(!ScanSettings::from(&SettingsRecord::from(&settings)).icmp_evidence);
3268
3269        settings.icmp_evidence = true;
3270        assert!(ScanSettings::from(&SettingsRecord::from(&settings)).icmp_evidence);
3271    }
3272
3273    /// The detection envelope comes back as the scan ran it, not as the default.
3274    #[test]
3275    fn the_detection_envelope_survives_the_settings_round_trip() {
3276        use crate::config::DetectionEnvelope;
3277        use crate::config::ZondConfig;
3278        use crate::model::finding::DetectionClass;
3279        use crate::report::ScanSettings;
3280
3281        // A raised ceiling, so the default cannot pass by accident.
3282        let mut settings = ScanSettings::from(&ZondConfig::default());
3283        settings.detection = DetectionEnvelope::up_to(DetectionClass::Exploit);
3284
3285        let rebuilt = ScanSettings::from(&SettingsRecord::from(&settings));
3286        assert_eq!(
3287            rebuilt.detection.ceiling(),
3288            Some(DetectionClass::Exploit),
3289            "the envelope ceiling was lost in the round trip"
3290        );
3291    }
3292
3293    /// And through a file.
3294    #[test]
3295    fn a_phase_survives_json() {
3296        let report = crate::export::fixture::report();
3297
3298        for phase in report.phases() {
3299            let record = PhaseRecord::from(phase);
3300            let text = serde_json::to_string(&record).expect("serializes");
3301            let read: PhaseRecord = serde_json::from_str(&text).expect("deserializes");
3302
3303            assert_eq!(record, read);
3304        }
3305    }
3306
3307    /// What a scan measured comes back unchanged.
3308    #[test]
3309    fn a_hosts_measurements_survive_the_round_trip() {
3310        use crate::model::host::{HostStatus, StatusProtocol, StatusReason};
3311        use std::time::Duration;
3312
3313        let mut host = Host::new("192.0.2.1".parse().expect("an address"));
3314        host.set_status(HostStatus::Up);
3315
3316        for protocol in [
3317            StatusProtocol::Arp,
3318            StatusProtocol::IcmpEcho,
3319            StatusProtocol::TcpSyn,
3320        ] {
3321            host.record_evidence(HostStatus::Up, StatusReason::new(protocol, "answered"));
3322        }
3323        host.add_rtts([
3324            Duration::from_micros(5_100),
3325            Duration::from_micros(6_060),
3326            Duration::from_micros(6_540),
3327        ]);
3328
3329        let restored = Host::from(&HostRecord::from(&host));
3330
3331        assert_eq!(
3332            restored.reasons().len(),
3333            host.reasons().len(),
3334            "a protocol that answered was lost"
3335        );
3336        assert_eq!(restored.min_rtt(), host.min_rtt(), "the fastest round trip");
3337        assert_eq!(restored.max_rtt(), host.max_rtt(), "the slowest");
3338        assert_eq!(restored.average_rtt(), host.average_rtt(), "the mean");
3339    }
3340}