zond_engine/model/host/protocol.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//! # Which IP protocols a host's stack accepts
10//!
11//! One layer below ports: which protocols the host's stack takes delivery of. GRE, ESP,
12//! OSPF and IPIP have no ports, so a TCP and UDP scan reports a tunnel endpoint or a
13//! router as an empty host.
14//!
15//! It also reads a firewall's protocol policy, usually shorter and more revealing than
16//! its port policy: a host with every TCP port closed that answers for protocol 47 is
17//! one end of a tunnel.
18//!
19//! ## Separate from ports
20//!
21//! The protocol numbers include the transports themselves
22//! ([`Protocol::Tcp`](crate::model::port::Protocol::Tcp) is 6,
23//! [`Udp`](crate::model::port::Protocol::Udp) 17,
24//! [`Sctp`](crate::model::port::Protocol::Sctp) 132), and a protocol number has none of
25//! a [`Port`](crate::model::port::Port)'s service or TLS data. So this is a fact about
26//! the host, kept beside [`Filtering`](super::Filtering).
27
28/// What a scan established about a host accepting one IP protocol.
29///
30/// Ordered from least to most definitive, so [`Host::merge`](super::Host) promotes by
31/// comparison.
32///
33/// As with [`PortState`](crate::model::port::PortState), a packet outranks silence:
34/// [`Blocked`](Self::Blocked) sits above [`OpenOrNoReply`](Self::OpenOrNoReply).
35#[non_exhaustive]
36#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
37pub enum IpProtocolState {
38 /// No probe was sent, so nothing was established either way.
39 ///
40 /// A protocol the scan named but never reached. The counterpart of
41 /// [`PortState::Unasked`](crate::model::port::PortState::Unasked).
42 Unasked,
43
44 /// A probe was sent and nothing came back.
45 ///
46 /// The ordinary verdict: most protocols answer nothing even where the host speaks
47 /// them, so silence cannot tell acceptance from a filter.
48 OpenOrNoReply,
49
50 /// Something in the path refused the protocol, by an ICMP unreachable that
51 /// was not a protocol unreachable: administratively prohibited, or a
52 /// communication filter.
53 ///
54 /// A statement about the path; the host may speak the protocol.
55 Blocked,
56
57 /// The host's own stack said it does not speak this protocol, by an ICMP
58 /// protocol unreachable (RFC 792 type 3 code 2, RFC 4443 type 1 code 4).
59 ///
60 /// The host's own negative verdict, which proves it is there.
61 Closed,
62
63 /// The host answered in the protocol that was asked about.
64 ///
65 /// Only reachable for a protocol whose answers this build can recognise and
66 /// capture; see [`IpProtocolScan`](crate::scanner::strategy::protocols) for
67 /// which those are and why silence is the usual answer for the rest.
68 Open,
69}
70
71impl IpProtocolState {
72 /// Every state, in declaration order, which is least definitive first and is
73 /// the order this type's [`Ord`] ranks by.
74 ///
75 /// Read by the check holding the exported schema to what this build can write.
76 pub const ALL: &'static [Self] = &[
77 Self::Unasked,
78 Self::OpenOrNoReply,
79 Self::Blocked,
80 Self::Closed,
81 Self::Open,
82 ];
83
84 /// Whether the host is known to take delivery of the protocol.
85 pub fn is_accepted(&self) -> bool {
86 matches!(self, IpProtocolState::Open)
87 }
88
89 /// Whether anything at all was established.
90 ///
91 /// False only for [`Unasked`](Self::Unasked), a fact about the scan.
92 pub fn is_established(&self) -> bool {
93 !matches!(self, IpProtocolState::Unasked)
94 }
95}
96
97/// The IANA name for a protocol number, where it has one worth printing.
98///
99/// A short list of the numbers a scan is likely to find something at; others render as
100/// the number.
101///
102/// Lowercase, matching the registry's own keyword column and
103/// [`record::wire`](crate::record::wire)'s convention for a name on the wire.
104pub const fn ip_protocol_name(number: u8) -> Option<&'static str> {
105 Some(match number {
106 1 => "icmp",
107 2 => "igmp",
108 4 => "ipv4",
109 6 => "tcp",
110 17 => "udp",
111 41 => "ipv6",
112 47 => "gre",
113 50 => "esp",
114 51 => "ah",
115 58 => "ipv6-icmp",
116 89 => "ospfigp",
117 103 => "pim",
118 112 => "vrrp",
119 132 => "sctp",
120 136 => "udplite",
121 137 => "mpls-in-ip",
122 _ => return None,
123 })
124}
125
126// ╔════════════════════════════════════════════╗
127// ║ ████████╗███████╗███████╗████████╗███████╗ ║
128// ║ ╚══██╔══╝██╔════╝██╔════╝╚══██╔══╝██╔════╝ ║
129// ║ ██║ █████╗ ███████╗ ██║ ███████╗ ║
130// ║ ██║ ██╔══╝ ╚════██║ ██║ ╚════██║ ║
131// ║ ██║ ███████╗███████║ ██║ ███████║ ║
132// ║ ╚═╝ ╚══════╝╚══════╝ ╚═╝ ╚══════╝ ║
133// ╚════════════════════════════════════════════╝
134
135#[cfg(test)]
136mod tests {
137 use super::*;
138
139 /// A later probe that learned less does not lower the state.
140 #[test]
141 fn the_states_rank_by_how_much_they_establish() {
142 assert!(IpProtocolState::Unasked < IpProtocolState::OpenOrNoReply);
143 assert!(IpProtocolState::OpenOrNoReply < IpProtocolState::Blocked);
144 assert!(IpProtocolState::Blocked < IpProtocolState::Closed);
145 assert!(IpProtocolState::Closed < IpProtocolState::Open);
146 }
147
148 /// Silence does not count as acceptance.
149 #[test]
150 fn silence_is_not_acceptance() {
151 assert!(!IpProtocolState::OpenOrNoReply.is_accepted());
152 assert!(IpProtocolState::OpenOrNoReply.is_established());
153 assert!(IpProtocolState::Open.is_accepted());
154 }
155
156 /// The one state that is about the scan rather than the host.
157 #[test]
158 fn a_protocol_nobody_asked_about_establishes_nothing() {
159 assert!(!IpProtocolState::Unasked.is_established());
160 for &state in IpProtocolState::ALL {
161 assert_eq!(
162 state.is_established(),
163 state != IpProtocolState::Unasked,
164 "{state:?}"
165 );
166 }
167 }
168
169 /// Names come from the registry; unlisted numbers have none.
170 #[test]
171 fn a_number_is_named_only_where_the_registry_names_it() {
172 assert_eq!(ip_protocol_name(47), Some("gre"));
173 assert_eq!(ip_protocol_name(6), Some("tcp"));
174 assert_eq!(ip_protocol_name(253), None, "an experimental number");
175 assert_eq!(
176 ip_protocol_name(0),
177 None,
178 "the hop-by-hop header is not one"
179 );
180 }
181}