Skip to main content

rustnet_core/network/
bogon.rs

1//! Classification of an IP address into a routing/usage scope: globally
2//! routable ("public"), or one of the RFC-reserved ranges (private, loopback,
3//! link-local, multicast, documentation, etc.).
4//!
5//! Used to label remote endpoints in the UI so internal traffic is visually
6//! distinguishable from public-Internet traffic. Pure passive classification:
7//! no lookups, no I/O.
8//!
9//! The set of non-public categories is intentionally small but covers the
10//! ranges users care about when scanning a connection list. Stable-Rust
11//! `is_*` helpers on `Ipv4Addr` / `Ipv6Addr` only cover a subset, so the
12//! checks here are done with explicit bit-mask comparisons to avoid relying
13//! on unstable APIs.
14
15use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
16
17#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
18pub enum Scope {
19    Public,
20    Loopback,
21    Private,
22    LinkLocal,
23    Cgnat,
24    Multicast,
25    Broadcast,
26    Documentation,
27    Benchmarking,
28    Unspecified,
29    Reserved,
30    UniqueLocal,
31    Discard,
32    Ipv4Mapped,
33}
34
35impl Scope {
36    /// Short, all-caps tag suitable for inline display in a detail panel.
37    pub fn label(self) -> &'static str {
38        match self {
39            Scope::Public => "PUBLIC",
40            Scope::Loopback => "LOOPBACK",
41            Scope::Private => "PRIVATE",
42            Scope::LinkLocal => "LINK-LOCAL",
43            Scope::Cgnat => "CGNAT",
44            Scope::Multicast => "MULTICAST",
45            Scope::Broadcast => "BROADCAST",
46            Scope::Documentation => "DOCUMENTATION",
47            Scope::Benchmarking => "BENCHMARKING",
48            Scope::Unspecified => "UNSPECIFIED",
49            Scope::Reserved => "RESERVED",
50            Scope::UniqueLocal => "UNIQUE-LOCAL",
51            Scope::Discard => "DISCARD",
52            Scope::Ipv4Mapped => "IPV4-MAPPED",
53        }
54    }
55}
56
57pub fn classify(ip: IpAddr) -> Scope {
58    match ip {
59        IpAddr::V4(v4) => classify_v4(v4),
60        IpAddr::V6(v6) => classify_v6(v6),
61    }
62}
63
64fn classify_v4(ip: Ipv4Addr) -> Scope {
65    let octets = ip.octets();
66    let [a, b, _, _] = octets;
67
68    if ip.is_unspecified() {
69        return Scope::Unspecified;
70    }
71    if a == 127 {
72        return Scope::Loopback;
73    }
74    // RFC 1918
75    if a == 10 || (a == 172 && (16..=31).contains(&b)) || (a == 192 && b == 168) {
76        return Scope::Private;
77    }
78    if a == 169 && b == 254 {
79        return Scope::LinkLocal;
80    }
81    // RFC 6598 carrier-grade NAT: 100.64.0.0/10
82    if a == 100 && (64..=127).contains(&b) {
83        return Scope::Cgnat;
84    }
85    // Documentation: 192.0.2.0/24 (TEST-NET-1), 198.51.100.0/24 (TEST-NET-2),
86    // 203.0.113.0/24 (TEST-NET-3).
87    if (a == 192 && b == 0 && octets[2] == 2)
88        || (a == 198 && b == 51 && octets[2] == 100)
89        || (a == 203 && b == 0 && octets[2] == 113)
90    {
91        return Scope::Documentation;
92    }
93    // RFC 2544 benchmarking: 198.18.0.0/15
94    if a == 198 && (b == 18 || b == 19) {
95        return Scope::Benchmarking;
96    }
97    if octets == [255, 255, 255, 255] {
98        return Scope::Broadcast;
99    }
100    // 224.0.0.0/4 multicast
101    if (224..=239).contains(&a) {
102        return Scope::Multicast;
103    }
104    // 240.0.0.0/4 reserved (excluding the 255.255.255.255 broadcast above)
105    if a >= 240 {
106        return Scope::Reserved;
107    }
108    Scope::Public
109}
110
111fn classify_v6(ip: Ipv6Addr) -> Scope {
112    if ip.is_unspecified() {
113        return Scope::Unspecified;
114    }
115    if ip.is_loopback() {
116        return Scope::Loopback;
117    }
118    let segs = ip.segments();
119    // ::ffff:0:0/96 IPv4-mapped
120    if segs[0..5] == [0, 0, 0, 0, 0] && segs[5] == 0xffff {
121        return Scope::Ipv4Mapped;
122    }
123    // 100::/64 discard prefix (RFC 6666)
124    if segs[0] == 0x0100 && segs[1] == 0 && segs[2] == 0 && segs[3] == 0 {
125        return Scope::Discard;
126    }
127    // 2001:db8::/32 documentation
128    if segs[0] == 0x2001 && segs[1] == 0x0db8 {
129        return Scope::Documentation;
130    }
131    // ff00::/8 multicast
132    if (segs[0] >> 8) == 0xff {
133        return Scope::Multicast;
134    }
135    // fe80::/10 link-local
136    if (segs[0] & 0xffc0) == 0xfe80 {
137        return Scope::LinkLocal;
138    }
139    // fc00::/7 unique-local
140    if (segs[0] & 0xfe00) == 0xfc00 {
141        return Scope::UniqueLocal;
142    }
143    Scope::Public
144}
145
146#[cfg(test)]
147mod tests {
148    use super::*;
149
150    fn v4(s: &str) -> IpAddr {
151        IpAddr::V4(s.parse().unwrap())
152    }
153
154    fn v6(s: &str) -> IpAddr {
155        IpAddr::V6(s.parse().unwrap())
156    }
157
158    #[test]
159    fn rfc1918_10_slash_8_is_private() {
160        assert_eq!(classify(v4("10.0.0.1")), Scope::Private);
161        assert_eq!(classify(v4("10.255.255.254")), Scope::Private);
162        assert_eq!(classify(v4("10.0.0.0")), Scope::Private);
163        assert_eq!(classify(v4("10.0.0.0")).label(), "PRIVATE");
164    }
165
166    #[test]
167    fn ipv4_169_254_slash_16_is_link_local() {
168        assert_eq!(classify(v4("169.254.1.1")), Scope::LinkLocal);
169        assert_eq!(classify(v4("169.254.255.255")), Scope::LinkLocal);
170        assert_eq!(classify(v4("169.254.0.0")).label(), "LINK-LOCAL");
171        // Sibling /16 must not match.
172        assert_eq!(classify(v4("169.253.1.1")), Scope::Public);
173    }
174
175    #[test]
176    fn ipv6_fe80_slash_10_is_link_local() {
177        assert_eq!(classify(v6("fe80::1")), Scope::LinkLocal);
178        assert_eq!(
179            classify(v6("febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff")),
180            Scope::LinkLocal
181        );
182        assert_eq!(classify(v6("fe80::1")).label(), "LINK-LOCAL");
183        // fec0::/10 site-local is deprecated and outside fe80::/10.
184        assert_eq!(classify(v6("fec0::1")), Scope::Public);
185    }
186
187    // One representative per remaining category.
188
189    #[test]
190    fn ipv4_other_categories() {
191        assert_eq!(classify(v4("172.16.0.1")), Scope::Private);
192        assert_eq!(classify(v4("192.168.1.1")), Scope::Private);
193        assert_eq!(classify(v4("172.32.0.1")), Scope::Public); // outside 172.16/12
194        assert_eq!(classify(v4("127.0.0.1")), Scope::Loopback);
195        assert_eq!(classify(v4("0.0.0.0")), Scope::Unspecified);
196        assert_eq!(classify(v4("100.64.0.1")), Scope::Cgnat);
197        assert_eq!(classify(v4("100.128.0.1")), Scope::Public); // outside 100.64/10
198        assert_eq!(classify(v4("224.0.0.251")), Scope::Multicast); // mDNS
199        assert_eq!(classify(v4("239.255.255.250")), Scope::Multicast);
200        assert_eq!(classify(v4("255.255.255.255")), Scope::Broadcast);
201        assert_eq!(classify(v4("192.0.2.1")), Scope::Documentation);
202        assert_eq!(classify(v4("198.51.100.5")), Scope::Documentation);
203        assert_eq!(classify(v4("203.0.113.7")), Scope::Documentation);
204        assert_eq!(classify(v4("198.18.0.1")), Scope::Benchmarking);
205        assert_eq!(classify(v4("240.0.0.1")), Scope::Reserved);
206    }
207
208    #[test]
209    fn ipv6_other_categories() {
210        assert_eq!(classify(v6("::")), Scope::Unspecified);
211        assert_eq!(classify(v6("::1")), Scope::Loopback);
212        assert_eq!(classify(v6("ff02::1")), Scope::Multicast);
213        assert_eq!(classify(v6("fc00::1")), Scope::UniqueLocal);
214        assert_eq!(classify(v6("fd00::1")), Scope::UniqueLocal);
215        assert_eq!(classify(v6("2001:db8::1")), Scope::Documentation);
216        assert_eq!(classify(v6("100::1")), Scope::Discard);
217        assert_eq!(classify(v6("::ffff:1.2.3.4")), Scope::Ipv4Mapped);
218    }
219
220    #[test]
221    fn public_ips_are_classified_public() {
222        assert_eq!(classify(v4("1.1.1.1")), Scope::Public);
223        assert_eq!(classify(v4("8.8.8.8")), Scope::Public);
224        assert_eq!(classify(v4("93.184.216.34")), Scope::Public);
225        assert_eq!(classify(v6("2606:4700:4700::1111")), Scope::Public);
226        assert_eq!(classify(v4("1.1.1.1")).label(), "PUBLIC");
227    }
228}