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
// 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 you got it.
//! 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.
//!
//! ## 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 RuleDb;
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 ;
pub use ;