camel_api/ssrf.rs
1//! SSRF (Server-Side Request Forgery) defense helpers.
2//!
3//! Canonical IP-classification logic shared by every outbound HTTP client
4//! in the workspace. Centralising this prevents drift between crates
5//! (e.g. one allowing ULA, another not) and makes the rule set auditable
6//! in one place.
7//!
8//! Blocking policy:
9//! - IPv4: private, loopback, link-local, broadcast, multicast, unspecified, 0.0.0.0/8,
10//! CGN (100.64.0.0/10), benchmark (198.18.0.0/15), reserved future-use (240.0.0.0/4)
11//! - IPv6: loopback, multicast, unspecified, ULA (fc00::/7), link-local (fe80::/10),
12//! deprecated site-local (fec0::/10)
13//!
14//! Public, routable addresses always return `false`. Domain-name validation
15//! is the caller's responsibility — this helper operates on `IpAddr`.
16
17use std::net::IpAddr;
18
19/// SSRF validation policy for outbound HTTP clients.
20///
21/// `PublicHttpsOnly` is the default and enforces HTTPS + public IPs only.
22/// `AllowInternal` relaxes both: permits private/loopback IPs and permits
23/// HTTP scheme **only when all resolved IPs are internal**. Public IPs
24/// over HTTP remain blocked to prevent cleartext credentials to the internet.
25#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
26#[non_exhaustive]
27pub enum SsrfPolicy {
28 #[default]
29 PublicHttpsOnly,
30 AllowInternal,
31}
32
33impl SsrfPolicy {
34 /// Returns `true` when internal/private addresses are permitted.
35 pub fn allows_internal(self) -> bool {
36 matches!(self, Self::AllowInternal)
37 }
38}
39
40/// Returns `true` if `ip` belongs to a network that must NOT be reached
41/// by an outbound HTTP client in this workspace.
42///
43/// Blocks:
44///
45/// - **IPv4**: private (RFC 1918), loopback (127.0.0.0/8), link-local
46/// (169.254.0.0/16 — cloud metadata), broadcast (255.255.255.255),
47/// multicast (224.0.0.0/4), unspecified (0.0.0.0), the entire
48/// `0.0.0.0/8` block (first octet 0), carrier-grade NAT
49/// (100.64.0.0/10 — RFC 6598), network interconnect benchmark
50/// (198.18.0.0/15 — RFC 2544), and the reserved future-use
51/// `240.0.0.0/4` block (RFC 1112).
52/// - **IPv6**: loopback (::1), multicast (ff00::/8), unspecified (::),
53/// unique-local (fc00::/7), link-local (fe80::/10), and deprecated
54/// site-local (fec0::/10 — RFC 3879).
55/// IPv4-mapped IPv6 (`::ffff:a.b.c.d`) inherits the classification of
56/// the embedded IPv4 — required to close the DNS-rebinding bypass where
57/// a public AAAA record maps to a private IPv4 in v4-mapped form.
58///
59/// Public, routable addresses (e.g. 8.8.8.8, 2001:4860:4860::8888) return `false`.
60pub fn is_ssrf_blocked_ip(ip: &IpAddr) -> bool {
61 match ip {
62 IpAddr::V4(v4) => {
63 v4.is_private()
64 || v4.is_loopback()
65 || v4.is_link_local()
66 || v4.is_broadcast()
67 || v4.is_multicast()
68 || v4.is_unspecified()
69 || v4.octets()[0] == 0
70 // CGN 100.64.0.0/10 (RFC 6598) — carrier-grade NAT range,
71 // commonly used as shared address space inside ISPs and
72 // occasionally leaked to internal networks.
73 || (v4.octets()[0] == 100
74 && (v4.octets()[1] >= 64 && v4.octets()[1] <= 127))
75 // Network interconnect benchmark 198.18.0.0/15 (RFC 2544) —
76 // reserved for benchmarking; never appears on the public
77 // internet, only on lab equipment that an attacker could
78 // pivot through.
79 || (v4.octets()[0] == 198
80 && (v4.octets()[1] == 18 || v4.octets()[1] == 19))
81 // Reserved future-use 240.0.0.0/4 (RFC 1112) — covers
82 // 240.0.0.0..255.255.255.254. Currently unallocated;
83 // blocking prevents any surprise assignment from becoming
84 // an SSRF target.
85 || v4.octets()[0] >= 240
86 }
87 IpAddr::V6(v6) => {
88 v6.is_loopback()
89 || v6.is_multicast()
90 || v6.is_unspecified()
91 // ULA fc00::/7 — covers both fc00::/8 and fd00::/8
92 || (v6.segments()[0] & 0xfe00) == 0xfc00
93 // Link-local fe80::/10
94 || (v6.segments()[0] & 0xffc0) == 0xfe80
95 // Deprecated site-local fec0::/10 (RFC 3879). Replaced by
96 // ULA but still routable in some legacy networks.
97 || (v6.segments()[0] & 0xffc0) == 0xfec0
98 // IPv4-mapped IPv6: recurse into the embedded IPv4 to
99 // close the rebinding bypass.
100 || v6
101 .to_ipv4_mapped()
102 .map(|v4| {
103 v4.is_private()
104 || v4.is_loopback()
105 || v4.is_link_local()
106 || v4.is_broadcast()
107 || v4.is_multicast()
108 || v4.is_unspecified()
109 || v4.octets()[0] == 0
110 || (v4.octets()[0] == 100
111 && (v4.octets()[1] >= 64 && v4.octets()[1] <= 127))
112 || (v4.octets()[0] == 198
113 && (v4.octets()[1] == 18 || v4.octets()[1] == 19))
114 || v4.octets()[0] >= 240
115 })
116 .unwrap_or(false)
117 }
118 }
119}
120
121#[cfg(test)]
122mod tests {
123 use super::*;
124 use std::net::Ipv4Addr;
125
126 fn v4(s: &str) -> IpAddr {
127 IpAddr::V4(s.parse::<Ipv4Addr>().expect("valid ipv4")) // allow-unwrap
128 }
129
130 fn v6(s: &str) -> IpAddr {
131 IpAddr::V6(s.parse().expect("valid ipv6")) // allow-unwrap
132 }
133
134 // ---- IPv4: blocked ranges ----
135
136 #[test]
137 fn blocks_rfc1918_10() {
138 assert!(is_ssrf_blocked_ip(&v4("10.0.0.1")));
139 assert!(is_ssrf_blocked_ip(&v4("10.255.255.255")));
140 }
141
142 #[test]
143 fn blocks_rfc1918_172_16() {
144 assert!(is_ssrf_blocked_ip(&v4("172.16.1.10")));
145 assert!(is_ssrf_blocked_ip(&v4("172.31.255.254")));
146 }
147
148 #[test]
149 fn blocks_rfc1918_192_168() {
150 assert!(is_ssrf_blocked_ip(&v4("192.168.1.1")));
151 assert!(is_ssrf_blocked_ip(&v4("192.168.0.0")));
152 }
153
154 #[test]
155 fn blocks_loopback_v4() {
156 assert!(is_ssrf_blocked_ip(&v4("127.0.0.1")));
157 assert!(is_ssrf_blocked_ip(&v4("127.255.255.254")));
158 }
159
160 #[test]
161 fn blocks_link_local_v4() {
162 // 169.254/16 — cloud metadata endpoints
163 assert!(is_ssrf_blocked_ip(&v4("169.254.169.254")));
164 assert!(is_ssrf_blocked_ip(&v4("169.254.1.1")));
165 }
166
167 #[test]
168 fn blocks_broadcast_v4() {
169 assert!(is_ssrf_blocked_ip(&v4("255.255.255.255")));
170 }
171
172 #[test]
173 fn blocks_multicast_v4() {
174 assert!(is_ssrf_blocked_ip(&v4("224.0.0.1")));
175 assert!(is_ssrf_blocked_ip(&v4("239.255.255.255")));
176 }
177
178 #[test]
179 fn blocks_unspecified_v4() {
180 assert!(is_ssrf_blocked_ip(&v4("0.0.0.0")));
181 }
182
183 #[test]
184 fn blocks_zero_octet_v4() {
185 // 0.0.0.0/8 — first octet 0, but not the unspecified address
186 assert!(is_ssrf_blocked_ip(&v4("0.1.2.3")));
187 assert!(is_ssrf_blocked_ip(&v4("0.255.255.255")));
188 }
189
190 #[test]
191 fn blocks_cgn_v4() {
192 // CGN 100.64.0.0/10 (RFC 6598) — first octet 100, second 64..=127
193 assert!(is_ssrf_blocked_ip(&v4("100.64.0.0")));
194 assert!(is_ssrf_blocked_ip(&v4("100.100.100.100")));
195 assert!(is_ssrf_blocked_ip(&v4("100.127.255.255")));
196 // 100.63 and 100.128 are NOT CGN
197 assert!(!is_ssrf_blocked_ip(&v4("100.63.255.255")));
198 assert!(!is_ssrf_blocked_ip(&v4("100.128.0.0")));
199 }
200
201 #[test]
202 fn blocks_benchmark_v4() {
203 // Benchmark 198.18.0.0/15 (RFC 2544) — second octet 18 or 19
204 assert!(is_ssrf_blocked_ip(&v4("198.18.0.0")));
205 assert!(is_ssrf_blocked_ip(&v4("198.18.255.255")));
206 assert!(is_ssrf_blocked_ip(&v4("198.19.255.255")));
207 // 198.17 and 198.20 are NOT benchmark
208 assert!(!is_ssrf_blocked_ip(&v4("198.17.255.255")));
209 assert!(!is_ssrf_blocked_ip(&v4("198.20.0.0")));
210 }
211
212 #[test]
213 fn blocks_reserved_v4() {
214 // Reserved 240.0.0.0/4 — first octet >= 240
215 assert!(is_ssrf_blocked_ip(&v4("240.0.0.0")));
216 assert!(is_ssrf_blocked_ip(&v4("241.1.2.3")));
217 assert!(is_ssrf_blocked_ip(&v4("250.100.200.50")));
218 // broadcast 255.255.255.255 already covered by is_broadcast
219 assert!(is_ssrf_blocked_ip(&v4("255.255.255.255")));
220 // 239.x is the top of multicast (224.0.0.0/4), NOT reserved —
221 // multicast is still blocked, but via a different rule.
222 assert!(is_ssrf_blocked_ip(&v4("239.255.255.255")));
223 // 100.x is CGN, blocked, not reserved
224 assert!(is_ssrf_blocked_ip(&v4("100.100.100.100")));
225 }
226
227 // ---- IPv4: allowed ranges ----
228
229 #[test]
230 fn allows_public_dns_v4() {
231 assert!(!is_ssrf_blocked_ip(&v4("8.8.8.8")));
232 assert!(!is_ssrf_blocked_ip(&v4("1.1.1.1")));
233 }
234
235 #[test]
236 fn allows_public_edge_v4() {
237 // 172.15 and 172.32 are NOT RFC-1918 (only 172.16/12 is)
238 assert!(!is_ssrf_blocked_ip(&v4("172.15.255.255")));
239 assert!(!is_ssrf_blocked_ip(&v4("172.32.0.0")));
240 }
241
242 // ---- IPv6: blocked ranges ----
243
244 #[test]
245 fn blocks_loopback_v6() {
246 assert!(is_ssrf_blocked_ip(&v6("::1")));
247 }
248
249 #[test]
250 fn blocks_unspecified_v6() {
251 assert!(is_ssrf_blocked_ip(&v6("::")));
252 }
253
254 #[test]
255 fn blocks_multicast_v6() {
256 assert!(is_ssrf_blocked_ip(&v6("ff02::1")));
257 assert!(is_ssrf_blocked_ip(&v6("ff00::1")));
258 }
259
260 #[test]
261 fn blocks_ula_fc_v6() {
262 assert!(is_ssrf_blocked_ip(&v6("fc00::1")));
263 assert!(is_ssrf_blocked_ip(&v6("fc00:1234:abcd::1")));
264 }
265
266 #[test]
267 fn blocks_ula_fd_v6() {
268 assert!(is_ssrf_blocked_ip(&v6("fd00::1")));
269 assert!(is_ssrf_blocked_ip(&v6("fd12:3456:789a::1")));
270 }
271
272 #[test]
273 fn blocks_link_local_v6() {
274 assert!(is_ssrf_blocked_ip(&v6("fe80::1")));
275 // fe80::/10 covers fe80..febf
276 assert!(is_ssrf_blocked_ip(&v6("febf:ffff::1")));
277 // febf + 1 is site-local, which is also blocked (separate test below)
278 }
279
280 #[test]
281 fn blocks_site_local_v6() {
282 // fec0::/10 (RFC 3879) — deprecated site-local, but still
283 // routable in some legacy networks.
284 assert!(is_ssrf_blocked_ip(&v6("fec0::1")));
285 assert!(is_ssrf_blocked_ip(&v6("feff:ffff::1")));
286 // febf is link-local, blocked by the fe80::/10 rule
287 assert!(is_ssrf_blocked_ip(&v6("febf::1")));
288 // ff00::/8 is multicast, already blocked
289 assert!(is_ssrf_blocked_ip(&v6("ff00::1")));
290 }
291
292 // ---- IPv6: allowed ranges ----
293
294 #[test]
295 fn allows_public_dns_v6() {
296 assert!(!is_ssrf_blocked_ip(&v6("2001:4860:4860::8888")));
297 }
298
299 #[test]
300 fn allows_public_documentation_v6() {
301 assert!(!is_ssrf_blocked_ip(&v6("2001:db8::1")));
302 }
303
304 // ---- SsrfPolicy ----
305
306 #[test]
307 fn ssrf_policy_default_is_public_https_only() {
308 assert_eq!(SsrfPolicy::default(), SsrfPolicy::PublicHttpsOnly);
309 }
310
311 #[test]
312 fn ssrf_policy_allows_internal() {
313 assert!(!SsrfPolicy::PublicHttpsOnly.allows_internal());
314 assert!(SsrfPolicy::AllowInternal.allows_internal());
315 }
316}