zond-engine 0.15.0

The core networking library powering Zond. Raw packet injection, protocol parsing, service and OS fingerprinting, and asynchronous network scanning.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
// Copyright (c) 2026 Erik Lening (hollowpointer) and Contributors
//
// This file is part of Zond Engine, licensed under the GNU Affero General
// Public License, version 3 or later. See the LICENSE file for details, or
// <https://www.gnu.org/licenses/agpl-3.0.html>.
//
// SPDX-License-Identifier: AGPL-3.0-or-later

//! # Ports, and what was found behind them
//!
//! A [`Port`] is one transport endpoint on one host, and everything a scan
//! learned about it. That covers three separate questions, kept in three
//! separate types so that a scan answering one of them does not have to pretend
//! it answered the rest:
//!
//! | Question | Type |
//! |---|---|
//! | Is anything there? | [`PortState`], with [`discovery`]'s account of the packet that decided it |
//! | What is it? | [`Service`], refined as better evidence arrives |
//! | How is it protected? | [`Security`], for an endpoint that negotiated TLS |
//!
//! Each is an `Option`, and an absent one means the question was not answered
//! rather than answered negatively. A port scan that has not run service
//! detection leaves [`Port::service`] empty rather than recording a service
//! named "unknown", because a later pass has to tell what it has yet to look at
//! apart from what it looked at and could not identify.
//!
//! ## Merging is how a port is built
//!
//! No single probe fills a `Port` in. Techniques run in sequence, a connect
//! fallback may repeat what a raw scan already asked, and service detection
//! arrives afterwards. [`Port::merge`] folds one probe's account into another,
//! and the rules it merges by are the substance of this module. [`Service`] and
//! [`Security`] carry their own, since each knows what makes one of its findings
//! better than another; a [`Discovery`] is taken or discarded whole, because it
//! is the account of a single packet and half of one explains nothing.
//!
//! They agree on one thing: a tie keeps what is already recorded. Two probes
//! that learned the same amount are equally good sources, and preferring the
//! later one would make a report depend on which probe happened to finish
//! last.
//!
//! ## Which ports to ask about in the first place
//!
//! [`PortSet`] is what a caller asked for, and [`catalog`] is what this crate
//! answers when they asked for nothing: a ranked list of the ports most likely
//! to be listening, from which [`PortSet::top_tcp`] takes a prefix. It is a
//! deliberate opinion rather than a neutral default, and the module says where
//! the opinion comes from.

pub mod catalog;
pub mod discovery;
pub mod security;
pub mod service;
pub mod set;

pub use catalog::{TCP_BY_PREVALENCE, UDP_BY_PREVALENCE};
pub use discovery::{Discovery, ScanResponse};
pub use security::{CertificateInfo, Security};
pub use service::Service;
pub use set::{PortSet, PortSetParseError};

use std::collections::BTreeMap;

use crate::model::finding::{ClaimId, Finding, MAX_FINDINGS_PER_SUBJECT};

/// Supported transport layer protocols.
///
/// Ordered so that a set of protocols has one canonical rendering, which is what
/// keeps two scans of the same targets producing byte-identical reports.
///
/// A variant exists here only once a scanner can speak it. A protocol nobody
/// can probe still forces every `match` over this enum to invent an answer for
/// a case that never arises, and those invented answers fail quietly. Adding one
/// is a deliberate act, and the compiler names every site that has to decide
/// something about it.
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum Protocol {
    /// TCP. Probed by every technique in
    /// [`TcpScanTechnique`](crate::model::technique::TcpScanTechnique), and the
    /// only protocol the unprivileged connect fallback can speak.
    Tcp,
    /// UDP. Answered by a service that recognises the payload sent to it, by an
    /// ICMP port unreachable, or most often by nothing at all. That last case is
    /// why silence here means [`PortState::OpenFiltered`] rather than open.
    Udp,
    /// SCTP. Probed with an INIT chunk, which a listener answers by accepting
    /// the association and a stack with nothing there refuses outright, so both
    /// verdicts come from a single exchange the way a SYN scan's do.
    ///
    /// Carries Diameter, S1AP and M3UA, which is why a mobile core is the place
    /// a scan that asks about TCP and UDP alone reports an empty host.
    Sctp,
}

impl Protocol {
    /// Every transport this build can probe, in declaration order.
    ///
    /// The enum is `#[non_exhaustive]`, so nothing outside the crate can write
    /// an exhaustive list of its own and nothing inside should: a transport
    /// added without a name on the wire, or without a place in the exported
    /// schema, is a port that survives a scan and cannot be written down. The
    /// export conformance suite reads this and the schema's own list and fails
    /// unless they hold the same names.
    pub const ALL: [Protocol; 3] = [Self::Tcp, Self::Udp, Self::Sctp];

    /// What a written port specification puts in front of this protocol's
    /// ports: nothing for TCP, `u:` for UDP, `s:` for SCTP.
    ///
    /// Read by both halves of [`PortSet`]'s spelling, so the prefix a caller
    /// writes and the one a report renders cannot come apart.
    pub const fn spec_prefix(self) -> &'static str {
        match self {
            Self::Tcp => "",
            Self::Udp => "u:",
            Self::Sctp => "s:",
        }
    }
}

/// What a scan established about a port.
///
/// Ordered from least definitive to most, so that [`Port::merge`] promotes by an
/// ordinary comparison and two probes that disagree resolve to whichever learned
/// more.
///
/// The ordering ranks evidence, not how alarming a state is. `Open` outranks
/// `Closed` because a SYN+ACK settles the question where a RST from a filtered
/// path does not, and the two ambiguous states sit below the states they are
/// ambiguous between. `Unasked` is beneath all of them because it is the absence
/// of evidence rather than a weak grade of it.
///
/// Which reply produces which state depends on the probe that drew it, since a
/// RST means a closed port to a SYN and an unfiltered path to an ACK. That
/// mapping lives in
/// [`TcpScanTechnique`](crate::model::technique::TcpScanTechnique).
#[non_exhaustive]
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum PortState {
    /// No probe was sent, so nothing was established either way.
    ///
    /// Every state below is a reading of an answer or of a silence that followed
    /// a question. This one is what a port says when the question was never put:
    /// a scan that ran out of wall clock with targets still queued, a
    /// host that spent
    /// [`ZondConfig::host_timeout`](crate::config::ZondConfig::host_timeout)
    /// before the scan reached this port, a probe the operating system refused
    /// to send.
    ///
    /// Such a port stays on the record rather than being left off the host,
    /// because a truncated port list and a complete one look identical and the
    /// count agrees with itself either way. Before this state existed the only
    /// way to keep it was to file it under whatever the scan read silence as,
    /// which put a port nobody looked at beside ports that were probed and
    /// stayed quiet. A comparison then read the pair as a port that had changed.
    ///
    /// Being the bottom of the ordering, it never overrides anything:
    /// [`Port::merge`] folding a probed record onto an unasked one keeps the
    /// probe's verdict.
    Unasked,

    /// Closed or filtered, and the probe cannot say which. What an idle scan
    /// concludes when the target's IP ID did not advance.
    ClosedFiltered,

    /// Something dropped the probe. The lowest state a scan will record from
    /// silence alone, and only for the techniques every live stack would have
    /// answered. See
    /// [`silence_means`](crate::model::technique::TcpScanTechnique::silence_means).
    Filtered,

    /// The probe reached the host's stack and nothing dropped it on the way,
    /// but whether anything is listening was not asked. What an ACK scan
    /// establishes.
    Unfiltered,

    /// Nothing is listening. A RST answering a SYN says so outright.
    Closed,

    /// Open, or silently dropped. The honest verdict for a probe whose positive
    /// result *is* silence: a bare FIN that an open port is required to ignore,
    /// or a UDP payload no service recognised.
    OpenFiltered,

    /// Something is listening and accepted the connection attempt. Only a SYN
    /// draws the SYN+ACK that establishes this.
    ///
    /// The SYN need not have been this scan's. A listener reading a segment off
    /// the wire sees the same handshake completed for somebody else, which
    /// establishes the same thing and in one respect more, since what was
    /// accepted was a real client rather than a knock. What it does not establish
    /// is that this machine could reach the endpoint: the peer and the path were
    /// somebody else's.
    ///
    /// [`Discovery::reason`](discovery::Discovery::reason) is what tells the two
    /// apart, and it is worth reading before acting on an open port from a
    /// merged report.
    Open,
}

impl PortState {
    /// Every state a port can be recorded in, in declaration order, which is
    /// least definitive first and is the order this type's [`Ord`] ranks by.
    ///
    /// Here for the reason [`Protocol::ALL`] gives, and read by the gate holding
    /// the exported schema to what this build can write.
    ///
    /// It was written in neither the declaration's order nor any other, with
    /// `Filtered` before `ClosedFiltered` and `Closed` before `Unfiltered`. The
    /// gate compares names as a set and did not care, so nothing said so; a
    /// caller rendering a legend from it would have got them in an order the
    /// type says is wrong. `model`'s own test now holds every `ALL` to its
    /// enum's declaration order.
    pub const ALL: [PortState; 7] = [
        Self::Unasked,
        Self::ClosedFiltered,
        Self::Filtered,
        Self::Unfiltered,
        Self::Closed,
        Self::OpenFiltered,
        Self::Open,
    ];
}

/// One transport endpoint on one host, and everything a scan learned about it.
///
/// The number and protocol identify it; everything else is a finding, and is
/// absent until something establishes it. See the module documentation for what
/// the four optional halves each answer and why they are kept apart.
#[must_use]
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Port {
    /// The 16-bit port number.
    number: u16,

    /// The transport protocol this endpoint is reached over.
    protocol: Protocol,

    /// What a probe established about it.
    state: PortState,

    /// What is listening, and how sure the identification is.
    service: Option<Service>,

    /// What a TLS handshake negotiated, for an endpoint that completed one.
    security: Option<Security>,

    /// The packet that settled [`state`](Self::state), and what it carried.
    discovery: Option<Discovery>,

    /// What a detection concluded was wrong with this endpoint, keyed on the
    /// claim so that the same finding reached twice records once.
    ///
    /// The per-port findings, such as a vulnerable service or a weak
    /// configuration on the thing listening here, as distinct from the cross-host
    /// findings a [`Host`](crate::model::host::Host) carries. Bounded by
    /// [`MAX_FINDINGS_PER_SUBJECT`], and folded through [`Finding::corroborate`]
    /// when a detection re-fires.
    findings: BTreeMap<ClaimId, Finding>,
}

impl Port {
    /// A port in `state`, with nothing yet established about what is behind it.
    pub fn new(number: u16, protocol: Protocol, state: PortState) -> Self {
        Self {
            number,
            protocol,
            state,
            service: None,
            security: None,
            discovery: None,
            findings: BTreeMap::new(),
        }
    }

    /// The 16-bit port number.
    pub fn number(&self) -> u16 {
        self.number
    }

    /// The transport this endpoint is reached over.
    pub fn protocol(&self) -> Protocol {
        self.protocol
    }

    /// What a probe established about this port.
    pub fn state(&self) -> PortState {
        self.state
    }

    /// Raises the recorded state to `state`, if that is more definitive.
    ///
    /// Promotes and never lowers, on the same ordering [`merge`](Self::merge)
    /// uses. A second probe that learned less about a port does not get to
    /// unlearn what the first established.
    pub fn set_state(&mut self, state: PortState) {
        self.state = std::cmp::max(self.state, state);
    }

    /// What is listening, if anything identified it.
    pub fn service(&self) -> Option<&Service> {
        self.service.as_ref()
    }

    /// Returns the high-level service name (e.g. `"ssh"`), if one was
    /// identified.
    ///
    /// The name alone, for a caller rendering a column of them.
    /// [`service`](Self::service) has the version, product and confidence that
    /// say how much the name is worth.
    pub fn service_name(&self) -> Option<&str> {
        self.service.as_ref().map(|s| s.name())
    }

    /// Records a service identification, replacing any already held.
    ///
    /// A caller refining an identification rather than replacing it should
    /// merge into [`service`](Self::service) instead; see [`Service::merge`].
    pub fn set_service(&mut self, service: Service) {
        self.service = Some(service);
    }

    /// What a TLS handshake negotiated here, if one completed.
    pub fn security(&self) -> Option<&Security> {
        self.security.as_ref()
    }

    /// Records what a handshake negotiated, replacing anything already held.
    pub fn set_security(&mut self, security: Security) {
        self.security = Some(security);
    }

    /// The account of the packet that settled this port's state, if there is
    /// one. An unprivileged connect attempt produces none.
    pub fn discovery(&self) -> Option<&Discovery> {
        self.discovery.as_ref()
    }

    /// Builder form of [`set_service`](Self::set_service).
    pub fn with_service(mut self, service: Service) -> Self {
        self.service = Some(service);
        self
    }

    /// Builder form of [`set_security`](Self::set_security).
    pub fn with_security(mut self, security: Security) -> Self {
        self.security = Some(security);
        self
    }

    /// Attaches the account of the packet that settled this port's state.
    pub fn with_discovery(mut self, discovery: Discovery) -> Self {
        self.discovery = Some(discovery);
        self
    }

    /// This port's findings, in a stable order.
    ///
    /// What is wrong with the service listening here. Ordered by claim, so two
    /// runs that found the same things render them the same way.
    pub fn findings(&self) -> impl Iterator<Item = &Finding> {
        self.findings.values()
    }

    /// Records a finding about this port, and reports whether it was new
    /// information: a claim not seen before, or a stronger reading of one that
    /// was.
    ///
    /// A finding reached again folds into the one on record through
    /// [`Finding::corroborate`] rather than accumulating. The ceiling
    /// ([`MAX_FINDINGS_PER_SUBJECT`]) turns away only a genuinely new claim.
    pub fn add_finding(&mut self, finding: Finding) -> bool {
        let claim = finding.claim_id();

        let full = self.findings.len() >= MAX_FINDINGS_PER_SUBJECT;

        match self.findings.get_mut(&claim) {
            Some(existing) => existing.corroborate(finding),
            None if full => false,
            None => {
                self.findings.insert(claim, finding);
                true
            }
        }
    }

    /// Folds another probe's account of this same endpoint into this one.
    ///
    /// The state rises to whichever of the two is the more definitive and never
    /// falls. Service and security details fold by their own confidence rules,
    /// and findings accumulate, a claim on both sides corroborating rather than
    /// landing twice. The discovery record follows the state: only a probe that
    /// raised the verdict replaces it, so a tie leaves the account already on
    /// record in place.
    ///
    /// # Panics
    ///
    /// In debug builds, if `other` describes a different endpoint. A number
    /// names one endpoint per transport, so merging TCP/53 into UDP/53 produces
    /// a record of neither. [`Host`](crate::model::host::Host) keys on both and
    /// cannot reach this; a caller merging by hand can.
    pub fn merge(&mut self, other: Port) {
        debug_assert_eq!(
            (self.number, self.protocol),
            (other.number, other.protocol),
            "merging two different endpoints into one record"
        );

        // Destructured rather than reached through `other.…`, so a field added
        // to this struct is a compile error here and not a value that quietly
        // stops being folded.
        let Port {
            // The endpoint, which the assertion above has just established is
            // this one's.
            number: _,
            protocol: _,
            state,
            service,
            security,
            discovery,
            findings,
        } = other;

        // Taken before the state moves, because the telemetry below has to be
        // judged against what it actually had to beat.
        let previous_state = self.state;

        self.state = std::cmp::max(self.state, state);

        if let Some(service) = service {
            match &mut self.service {
                Some(recorded) => recorded.merge(service),
                None => self.service = Some(service),
            }
        }

        if let Some(security) = security {
            match &mut self.security {
                Some(recorded) => recorded.merge(security),
                None => self.security = Some(security),
            }
        }

        // The telemetry explains the state, so it follows the state. A probe
        // that upgraded this port carries the account of why it is now Open,
        // and that account replaces whatever explained the weaker verdict; a
        // probe that did not upgrade it explains a verdict this port no longer
        // holds, and the RTT and TTL of a `NoResponse` say nothing about a port
        // something has since answered on.
        //
        // A tie keeps the incumbent, which is the rule every other merge in
        // this module follows. Two probes reaching the same verdict are equally
        // good accounts of it, and preferring the later one would make the
        // recorded telemetry depend on which probe happened to finish last.
        //
        // A port with no telemetry at all takes whatever is offered: an
        // explanation of a weaker verdict still beats none.
        if discovery.is_some() && (state > previous_state || self.discovery.is_none()) {
            self.discovery = discovery;
        }

        // A claim missing from one record is a detection that did not run there,
        // not a retraction, so a fold adds and never removes; a claim on both
        // corroborates through `add_finding`.
        for finding in findings.into_values() {
            self.add_finding(finding);
        }
    }
}

// ╔════════════════════════════════════════════╗
// ║ ████████╗███████╗███████╗████████╗███████╗ ║
// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
// ║    ██║   █████╗  ███████╗   ██║   ███████╗ ║
// ║    ██║   ██╔══╝  ╚════██║   ██║   ╚════██║ ║
// ║    ██║   ███████╗███████║   ██║   ███████║ ║
// ║    ╚═╝   ╚══════╝╚══════╝   ╚═╝   ╚══════╝ ║
// ╚════════════════════════════════════════════╝

#[cfg(test)]
mod tests {
    use super::*;

    /// A second probe that learned more replaces the verdict; one that learned
    /// less does not. The ordering on [`PortState`] is what decides, so these
    /// pin the three promotions a scan actually performs.
    #[test]
    fn a_probe_that_learned_more_raises_the_verdict() {
        // Filtered -> Open
        let mut p1 = Port::new(80, Protocol::Tcp, PortState::Filtered);
        p1.merge(Port::new(80, Protocol::Tcp, PortState::Open));
        assert_eq!(p1.state(), PortState::Open);

        // OpenFiltered -> Open
        let mut p2 = Port::new(53, Protocol::Udp, PortState::OpenFiltered);
        p2.merge(Port::new(53, Protocol::Udp, PortState::Open));
        assert_eq!(p2.state(), PortState::Open);

        // Unfiltered -> Closed
        let mut p3 = Port::new(443, Protocol::Tcp, PortState::Unfiltered);
        p3.merge(Port::new(443, Protocol::Tcp, PortState::Closed));
        assert_eq!(p3.state(), PortState::Closed);
    }

    /// Telemetry explains a verdict, so a probe that did not improve the
    /// verdict does not get to rewrite the account of it. Two probes reaching
    /// the same state are equally good accounts, and preferring the later one
    /// makes the record depend on which probe happened to finish last.
    #[test]
    fn a_tie_keeps_the_telemetry_already_on_record() {
        let mut first = Port::new(22, Protocol::Tcp, PortState::Open)
            .with_discovery(Discovery::new(ScanResponse::TcpSynAck).with_ttl(64));
        let second = Port::new(22, Protocol::Tcp, PortState::Open)
            .with_discovery(Discovery::new(ScanResponse::TcpSynAck).with_ttl(128));

        first.merge(second);

        assert_eq!(
            first.discovery().expect("telemetry survives").ttl(),
            Some(64)
        );
    }

    /// A probe that lost the state comparison still explains something, and a
    /// port holding no telemetry at all has nothing to lose by taking it.
    #[test]
    fn a_port_with_no_telemetry_adopts_a_weaker_probes() {
        let mut open = Port::new(22, Protocol::Tcp, PortState::Open);
        let filtered = Port::new(22, Protocol::Tcp, PortState::Filtered)
            .with_discovery(Discovery::new(ScanResponse::NoResponse));

        open.merge(filtered);

        assert_eq!(open.state(), PortState::Open, "the weaker state loses");
        assert_eq!(
            open.discovery().expect("adopted").reason(),
            &ScanResponse::NoResponse,
            "but its account of itself is better than none"
        );
    }

    /// Nothing established outranks nothing at all, in both directions, so a
    /// sitting that never reached a port cannot undo what an earlier one learned
    /// about it and cannot invent anything either.
    #[test]
    fn an_unasked_port_loses_to_every_verdict() {
        for verdict in PortState::ALL {
            if verdict == PortState::Unasked {
                continue;
            }
            assert!(
                PortState::Unasked < verdict,
                "{verdict:?} does not outrank a port nobody probed"
            );
        }

        let mut probed = Port::new(22, Protocol::Tcp, PortState::Closed);
        probed.merge(Port::new(22, Protocol::Tcp, PortState::Unasked));
        assert_eq!(
            probed.state(),
            PortState::Closed,
            "a later sitting that never asked unlearned the first one's answer"
        );

        let mut unasked = Port::new(22, Protocol::Tcp, PortState::Unasked);
        unasked.merge(Port::new(22, Protocol::Tcp, PortState::Closed));
        assert_eq!(unasked.state(), PortState::Closed);
    }

    /// The telemetry explains the verdict, so replacing the verdict replaces the
    /// account of it. The RTT and TTL of a `NoResponse` say nothing about a port
    /// something has since answered on.
    #[test]
    fn telemetry_follows_the_verdict_it_explains() {
        let disc_filtered = Discovery::new(ScanResponse::NoResponse);
        let mut p_filtered =
            Port::new(22, Protocol::Tcp, PortState::Filtered).with_discovery(disc_filtered.clone());

        let disc_open = Discovery::new(ScanResponse::TcpSynAck);
        let p_open =
            Port::new(22, Protocol::Tcp, PortState::Open).with_discovery(disc_open.clone());

        // Merging should upgrade the state AND the telemetry reason
        p_filtered.merge(p_open);

        assert_eq!(p_filtered.state(), PortState::Open);
        assert_eq!(
            p_filtered.discovery().unwrap().reason(),
            &ScanResponse::TcpSynAck
        );
    }

    fn a_finding(detection_id: &str) -> Finding {
        use crate::model::confidence::Confidence;
        use crate::model::finding::{DetectionClass, DetectionId, Severity, Version};
        Finding::new(
            DetectionId::new(detection_id, Version::new(1, 0, 0), "hash").unwrap(),
            "A port finding",
            Severity::High,
            Confidence::Certain,
            DetectionClass::ActiveBenign,
        )
        .unwrap()
    }

    #[test]
    fn a_merge_keeps_both_ports_findings() {
        // The silent failure: a merge that folds state and service but forgets
        // findings reports a clean port that had one.
        let mut base = Port::new(443, Protocol::Tcp, PortState::Open);
        base.add_finding(a_finding("det-a"));

        let mut other = Port::new(443, Protocol::Tcp, PortState::Open);
        other.add_finding(a_finding("det-b"));

        base.merge(other);

        assert_eq!(
            base.findings().count(),
            2,
            "a merge must not drop the other's findings"
        );
    }
}