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
// 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
//! # Operating system fingerprinting
//!
//! What machine is behind an address, as distinct from what service is behind a
//! port. The sibling modules answer the second question; this one answers the
//! first, from the same replies.
//!
//! ## Usable on its own
//!
//! Nothing here opens a socket, spawns a task, holds a runtime or touches the
//! scanner. A [`StackObservation`] is built by a function from bytes to a
//! value, so a caller who already has packets, a saved capture, their own raw
//! socket, a fixture, can use this without going anywhere near
//! [`scanner`](crate::scanner):
//!
//! ```
//! use zond_engine::fingerprint::os::StackObservation;
//!
//! # fn main() {
//! // An IPv4 packet carrying a TCP segment, from wherever it was captured.
//! let packet: &[u8] = &[
//! 0x45, 0x00, 0x00, 0x2c, 0xbe, 0xef, 0x40, 0x00, 0x40, 0x06, 0x00, 0x00,
//! 192, 168, 0, 1, 192, 168, 0, 100,
//! 0x00, 0x50, 0xc3, 0x50, 0, 0, 0, 1, 0, 0, 0, 2,
//! 0x60, 0x12, 0xfa, 0xf0, 0x00, 0x00, 0x00, 0x00,
//! 0x02, 0x04, 0x05, 0xb4,
//! ];
//!
//! let observed = StackObservation::from_ip_packet(packet).expect("a TCP reply");
//! assert!(observed.is_syn_ack());
//! assert_eq!(observed.mss, Some(1460));
//! assert_eq!(observed.layout_string(), "M");
//! # }
//! ```
//!
//! That decoupling is a design constraint rather than an accident, and it is
//! kept honest by the imports: this module reaches for the vocabulary in
//! [`model`](crate::model) and the header parsing in
//! [`protocols`](crate::protocols) and for nothing else. What it does *not* yet
//! buy is a smaller build, the crate still compiles its capture and its runtime
//! whatever a consumer imports, because those are unconditional dependencies.
//! Turning this into a feature that costs nothing to leave out is a change to
//! the dependency set rather than to this module, and the module is written so
//! that change is mechanical when someone wants it.
//!
//! ## Shape
//!
//! ```text
//! one reply ─▶ StackObservation ──────────────▶ classify ───┐
//! │
//! several ─┬▶ StackObservation ─┐ │
//! replies └▶ SeriesSample[] ──┴▶ SeriesClasses ─▶ classify_series ─┐
//! │ │
//! banner / hostname / hardware address ─────────────────────┐│ │
//! ▼▼ ▼
//! [OsEvidence] ─▶ resolve ─▶ OsFingerprint
//! ```
//!
//! [`identify`] is the door: it takes whatever a caller read off the wire, adds
//! the two sources a host carries about itself, resolves the combination and
//! merges the result. Every scanner in this crate goes through it.
//!
//! ## Two axes: what it runs, and what it is
//!
//! A verdict answers two questions, and a source may answer either without the
//! other. [`OsEvidence::family`](crate::model::host::OsEvidence::family) is
//! what the machine *runs*,
//! [`OsEvidence::device`](crate::model::host::OsEvidence::device) is what it
//! *is*, printer, switch, camera, and neither stands in for the other. A hop
//! counter of 255 reaches the first and never the second; an SNMP agent reading
//! `Brother NC-8700w` reaches the second and genuinely does not know the first.
//!
//! [`resolve`] settles the family by vote and everything else by agreement, so a
//! source with nothing to say about the family says nothing there rather than
//! being made to guess. That distinction is load-bearing: read as a family, a
//! model number runs against the real families on the ballot and both lose.
//!
//! ## One reply, or several
//!
//! The two entry points differ in what evidence they have, not in how they
//! score it. [`classify`] reads a single reply, which is what a scan already
//! drew for another reason and therefore costs nothing. [`classify_series`]
//! reads several replies from one host together with what their series turned
//! out to be, which costs probes and is what
//! [`OsDetection::Active`](crate::config::OsDetection) buys.
//!
//! What the second one buys is **specificity, not confidence**. A series is
//! still one stack, so it is still one piece of evidence and still bounded by
//! [`MAX_STACK_ACCURACY`]; what it adds is the three features a single reply
//! cannot carry, the identifier policy, the sequence generator and the clock,
//! and those are what a rule naming a *release* rather than a family has to
//! predicate on.
//!
//! ## What one observation can and cannot settle
//!
//! It describes **one reply**, and several of the most tempting features need
//! more than one. Whether a stack's IP identifier counts, stays at zero or is
//! random is a policy visible only across several replies; so is a clock
//! frequency, which needs two timestamps and the interval between them. Neither
//! belongs on this type, and putting either here would mean inventing a value
//! from a single sample.
//!
//! It is also **not comparable across probes**. The option layout and the
//! advertised window both depend on what the probe offered, which is measured
//! and explained on [`StackObservation`]. Two may be compared when the
//! same question was asked of both.
pub use ;
// The schema an `assets/fingerprinting/os` rule is authored against. Exported so
// a consumer writing rules of their own is held to the same shape rather than
// discovering it when one is silently dropped, exactly as the service signature
// schema is.
pub use ;
pub use ;
pub use evidence_from as hardware_evidence;
pub use evidence_from as hostname_evidence;
pub use identify;
pub use ;
pub use ;
pub use ;
pub use ;
// The capture resolver, for the service reading rather than the host one: a
// rule's `service.component.*` fields take the same `{capture:N}` templates its
// `os.*` fields do, and two resolvers would eventually disagree about one
// syntax.
pub use fill;
pub use ;