openmoat_proxy/
decide.rs

1//! Which hosts and addresses the proxy may reach.
2//!
3//! A host is decided exactly as `moat guard` decides a fetch tool's URL: one
4//! `fetch` atom through openmoat-core's [`CompiledPolicy`], so `fetch` and `net`
5//! lists both apply and deny rules come first. The proxy cannot prompt, so an
6//! `ask` is refused. Cloud metadata and link-local addresses are refused
7//! whatever the policy says, by name and again after DNS resolution. Private
8//! and CGNAT addresses are refused unless an allow rule names the address.
9
10use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
11
12use openmoat_core::{AtomicAction, CompiledPolicy, Decision, Defaults, Kind, Policy, Verdict};
13
14/// Rule id for a destination refused whatever the policy says.
15pub const RULE_ADDRESS: &str = "proxy-address";
16/// Rule id for a tunnel whose TLS SNI is missing or names another host.
17pub const RULE_SNI: &str = "proxy-sni";
18/// Rule id for a request the proxy could not parse or does not serve.
19pub const RULE_REQUEST: &str = "proxy-request";
20/// Rule id for a destination that could not be resolved or reached.
21pub const RULE_UPSTREAM: &str = "proxy-upstream";
22/// Rule id for a connection refused because it could not be recorded.
23pub const RULE_AUDIT: &str = "proxy-audit";
24
25/// Metadata services reachable by name on cloud instances.
26const METADATA_NAMES: &[&str] = &["metadata.google.internal", "metadata.goog"];
27const ALIBABA_METADATA: Ipv4Addr = Ipv4Addr::new(100, 100, 100, 200);
28const AWS_METADATA_V6: Ipv6Addr = Ipv6Addr::new(0xfd00, 0xec2, 0, 0, 0, 0, 0, 0x254);
29/// RFC 6052 well-known NAT64 prefix: `64:ff9b::a.b.c.d` reaches `a.b.c.d`.
30const NAT64: [u16; 6] = [0x64, 0xff9b, 0, 0, 0, 0];
31/// Ranges on the local network (or the carrier's), each with its description.
32const PRIVATE_V4: [(Ipv4Addr, u8, &str); 5] = [
33    (
34        Ipv4Addr::new(10, 0, 0, 0),
35        8,
36        "a private address (10.0.0.0/8)",
37    ),
38    (
39        Ipv4Addr::new(172, 16, 0, 0),
40        12,
41        "a private address (172.16.0.0/12)",
42    ),
43    (
44        Ipv4Addr::new(192, 168, 0, 0),
45        16,
46        "a private address (192.168.0.0/16)",
47    ),
48    (
49        Ipv4Addr::new(100, 64, 0, 0),
50        10,
51        "a shared CGNAT address (100.64.0.0/10)",
52    ),
53    (
54        Ipv4Addr::new(198, 18, 0, 0),
55        15,
56        "a benchmarking address (198.18.0.0/15)",
57    ),
58];
59
60/// Decide whether `host`, normalised as [`Request::host`](crate::Request::host)
61/// reports it, may be reached. Only an `allow` lets the connection proceed.
62#[must_use]
63pub fn host(policy: &CompiledPolicy<'_>, host: &str) -> Decision {
64    if METADATA_NAMES
65        .iter()
66        .any(|m| host == *m || host.strip_suffix(m).is_some_and(|p| p.ends_with('.')))
67    {
68        return Decision::single(
69            Verdict::Deny,
70            RULE_ADDRESS,
71            format!("{host} is a cloud metadata service"),
72        );
73    }
74    let atom = AtomicAction::Fetch {
75        host: host.to_owned(),
76    };
77    let mut decision = policy.evaluate_atomic(&atom).unwrap_or_else(|| {
78        Decision::single(
79            Verdict::Deny,
80            RULE_REQUEST,
81            format!("no rule decided {host}"),
82        )
83    });
84    if decision.verdict == Verdict::Ask {
85        decision.verdict = Verdict::Deny;
86        decision
87            .reasons
88            .push("the proxy cannot ask, so a host that would ask is refused".to_owned());
89    }
90    decision
91}
92
93/// Why the proxy never connects to `ip`, if it does not. Checked on every
94/// resolved address, so a name the policy allows cannot be pointed at a local
95/// or metadata service (DNS rebinding).
96#[must_use]
97pub fn forbidden(ip: IpAddr) -> Option<Forbidden> {
98    match ip.to_canonical() {
99        IpAddr::V4(v4) => forbidden_v4(v4),
100        IpAddr::V6(v6) => forbidden_v6(v6),
101    }
102}
103
104/// The classes of address the proxy refuses.
105#[derive(Debug, Clone, Copy, PartialEq, Eq)]
106#[non_exhaustive]
107pub enum Forbidden {
108    /// This machine (`127.0.0.0/8`, `::1`), including the proxy itself.
109    Loopback,
110    /// Link-local (`169.254.0.0/16`, `fe80::/10`): where cloud metadata lives.
111    LinkLocal,
112    /// A cloud metadata address outside the link-local ranges.
113    Metadata,
114    /// Unspecified, broadcast, multicast or `0.0.0.0/8`: never a server.
115    NotUnicast,
116    /// Private, CGNAT, benchmarking or unique-local (`fc00::/7`): reachable
117    /// only when an allow rule names the address ([`named`]). Carries the
118    /// description naming the range.
119    Private(&'static str),
120}
121
122impl Forbidden {
123    /// A short phrase for reasons and the audit log.
124    #[must_use]
125    pub fn describe(self) -> &'static str {
126        match self {
127            Self::Loopback => "a loopback address",
128            Self::LinkLocal => "a link-local address",
129            Self::Metadata => "a cloud metadata address",
130            Self::NotUnicast => "not a unicast address",
131            Self::Private(range) => range,
132        }
133    }
134}
135
136fn forbidden_v4(ip: Ipv4Addr) -> Option<Forbidden> {
137    if ip.is_loopback() {
138        Some(Forbidden::Loopback)
139    } else if ip.is_link_local() {
140        Some(Forbidden::LinkLocal)
141    } else if ip == ALIBABA_METADATA {
142        Some(Forbidden::Metadata)
143    } else if ip.is_unspecified() || ip.is_broadcast() || ip.is_multicast() || ip.octets()[0] == 0 {
144        Some(Forbidden::NotUnicast)
145    } else {
146        PRIVATE_V4
147            .iter()
148            .find(|(net, len, _)| u32::from(ip) >> (32 - len) == u32::from(*net) >> (32 - len))
149            .map(|(_, _, range)| Forbidden::Private(range))
150    }
151}
152
153fn forbidden_v6(ip: Ipv6Addr) -> Option<Forbidden> {
154    let seg = ip.segments();
155    if ip.is_loopback() {
156        Some(Forbidden::Loopback)
157    } else if ip.is_unspecified() || ip.is_multicast() {
158        Some(Forbidden::NotUnicast)
159    } else if seg[0] & 0xffc0 == 0xfe80 {
160        Some(Forbidden::LinkLocal)
161    } else if ip == AWS_METADATA_V6 {
162        Some(Forbidden::Metadata)
163    } else if seg[..6] == NAT64 || seg[..6] == [0; 6] {
164        // NAT64 and the deprecated IPv4-compatible form carry an IPv4 address.
165        let [a, b] = seg[6].to_be_bytes();
166        let [c, d] = seg[7].to_be_bytes();
167        forbidden_v4(Ipv4Addr::new(a, b, c, d))
168    } else if seg[0] & 0xfe00 == 0xfc00 {
169        Some(Forbidden::Private("a unique local address (fc00::/7)"))
170    } else {
171        None
172    }
173}
174
175/// The part of `policy` that can open a [`Forbidden::Private`] address: its
176/// deny rules, and the allow rules' `net` and `fetch` patterns that name an
177/// address: a pattern starting with a digit or containing `:`, not starting
178/// with a glob metacharacter, and made only of what an address's text and a
179/// glob use. Everything else is denied, so a wildcard such as `*` or
180/// `*.example`, or a name such as `db.internal:5432`, never reaches the
181/// local network by DNS.
182#[must_use]
183pub fn address_policy(policy: &Policy) -> Policy {
184    let allow = policy
185        .allow
186        .iter()
187        .map(|g| {
188            let keep = |list: &[String]| {
189                list.iter()
190                    .filter(|p| names_address(p))
191                    .cloned()
192                    .collect::<Vec<_>>()
193            };
194            openmoat_core::RuleGroup {
195                id: g.id.clone(),
196                reason: g.reason.clone(),
197                net: keep(g.patterns(Kind::Net)),
198                fetch: keep(g.patterns(Kind::Fetch)),
199                ..Default::default()
200            }
201        })
202        .collect();
203    Policy {
204        defaults: Defaults::All(Verdict::Deny),
205        deny: policy.deny.clone(),
206        allow,
207        ask: Vec::new(),
208        ..policy.clone()
209    }
210}
211
212/// Whether a host pattern names an address (see [`address_policy`]).
213fn names_address(pattern: &str) -> bool {
214    !pattern.starts_with(['*', '?', '[', '{'])
215        && (pattern.starts_with(|c: char| c.is_ascii_digit()) || pattern.contains(':'))
216        && pattern
217            .chars()
218            .all(|c| c.is_ascii_hexdigit() || ".:*?[]{},!-".contains(c))
219}
220
221/// Whether `addresses` (compiled from [`address_policy`]) allows `ip`, matched
222/// in its canonical text form (`::ffff:10.0.0.5` as `10.0.0.5`).
223#[must_use]
224pub fn named(addresses: &CompiledPolicy<'_>, ip: IpAddr) -> bool {
225    let atom = AtomicAction::Fetch {
226        host: ip.to_canonical().to_string(),
227    };
228    addresses
229        .evaluate_atomic(&atom)
230        .is_some_and(|d| d.verdict == Verdict::Allow)
231}
232
233#[cfg(test)]
234mod tests;
openmoat_proxy/decide.rs

openmoat_proxy/
decide.rs
