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    // A deferred host (ADR-025) is refused too: the agent's permission flow never sees
85    // the proxy's connections.
86    if matches!(decision.verdict, Verdict::Ask | Verdict::Defer) {
87        decision.verdict = Verdict::Deny;
88        decision
89            .reasons
90            .push("the proxy cannot ask, so a host the hook would ask for or leave to the agent is refused".to_owned());
91    }
92    decision
93}
94
95/// Why the proxy never connects to `ip`, if it does not. Checked on every
96/// resolved address, so a name the policy allows cannot be pointed at a local
97/// or metadata service (DNS rebinding).
98#[must_use]
99pub fn forbidden(ip: IpAddr) -> Option<Forbidden> {
100    match ip.to_canonical() {
101        IpAddr::V4(v4) => forbidden_v4(v4),
102        IpAddr::V6(v6) => forbidden_v6(v6),
103    }
104}
105
106/// The classes of address the proxy refuses.
107#[derive(Debug, Clone, Copy, PartialEq, Eq)]
108#[non_exhaustive]
109pub enum Forbidden {
110    /// This machine (`127.0.0.0/8`, `::1`), including the proxy itself.
111    Loopback,
112    /// Link-local (`169.254.0.0/16`, `fe80::/10`): where cloud metadata lives.
113    LinkLocal,
114    /// A cloud metadata address outside the link-local ranges.
115    Metadata,
116    /// Unspecified, broadcast, multicast or `0.0.0.0/8`: never a server.
117    NotUnicast,
118    /// Private, CGNAT, benchmarking or unique-local (`fc00::/7`): reachable
119    /// only when an allow rule names the address ([`named`]). Carries the
120    /// description naming the range.
121    Private(&'static str),
122}
123
124impl Forbidden {
125    /// A short phrase for reasons and the audit log.
126    #[must_use]
127    pub fn describe(self) -> &'static str {
128        match self {
129            Self::Loopback => "a loopback address",
130            Self::LinkLocal => "a link-local address",
131            Self::Metadata => "a cloud metadata address",
132            Self::NotUnicast => "not a unicast address",
133            Self::Private(range) => range,
134        }
135    }
136}
137
138fn forbidden_v4(ip: Ipv4Addr) -> Option<Forbidden> {
139    if ip.is_loopback() {
140        Some(Forbidden::Loopback)
141    } else if ip.is_link_local() {
142        Some(Forbidden::LinkLocal)
143    } else if ip == ALIBABA_METADATA {
144        Some(Forbidden::Metadata)
145    } else if ip.is_unspecified() || ip.is_broadcast() || ip.is_multicast() || ip.octets()[0] == 0 {
146        Some(Forbidden::NotUnicast)
147    } else {
148        PRIVATE_V4
149            .iter()
150            .find(|(net, len, _)| u32::from(ip) >> (32 - len) == u32::from(*net) >> (32 - len))
151            .map(|(_, _, range)| Forbidden::Private(range))
152    }
153}
154
155fn forbidden_v6(ip: Ipv6Addr) -> Option<Forbidden> {
156    let seg = ip.segments();
157    if ip.is_loopback() {
158        Some(Forbidden::Loopback)
159    } else if ip.is_unspecified() || ip.is_multicast() {
160        Some(Forbidden::NotUnicast)
161    } else if seg[0] & 0xffc0 == 0xfe80 {
162        Some(Forbidden::LinkLocal)
163    } else if ip == AWS_METADATA_V6 {
164        Some(Forbidden::Metadata)
165    } else if seg[..6] == NAT64 || seg[..6] == [0; 6] {
166        // NAT64 and the deprecated IPv4-compatible form carry an IPv4 address.
167        let [a, b] = seg[6].to_be_bytes();
168        let [c, d] = seg[7].to_be_bytes();
169        forbidden_v4(Ipv4Addr::new(a, b, c, d))
170    } else if seg[0] & 0xfe00 == 0xfc00 {
171        Some(Forbidden::Private("a unique local address (fc00::/7)"))
172    } else {
173        None
174    }
175}
176
177/// The part of `policy` that can open a [`Forbidden::Private`] address: its
178/// deny rules, and the allow rules' `net` and `fetch` patterns that name an
179/// address: a pattern starting with a digit or containing `:`, not starting
180/// with a glob metacharacter, and made only of what an address's text and a
181/// glob use. Everything else is denied, so a wildcard such as `*` or
182/// `*.example`, or a name such as `db.internal:5432`, never reaches the
183/// local network by DNS.
184#[must_use]
185pub fn address_policy(policy: &Policy) -> Policy {
186    let allow = policy
187        .allow
188        .iter()
189        .map(|g| {
190            let keep = |list: &[String]| {
191                list.iter()
192                    .filter(|p| names_address(p))
193                    .cloned()
194                    .collect::<Vec<_>>()
195            };
196            openmoat_core::RuleGroup {
197                id: g.id.clone(),
198                reason: g.reason.clone(),
199                net: keep(g.patterns(Kind::Net)),
200                fetch: keep(g.patterns(Kind::Fetch)),
201                ..Default::default()
202            }
203        })
204        .collect();
205    Policy {
206        defaults: Defaults::All(Verdict::Deny),
207        deny: policy.deny.clone(),
208        allow,
209        ask: Vec::new(),
210        ..policy.clone()
211    }
212}
213
214/// Whether a host pattern names an address (see [`address_policy`]).
215fn names_address(pattern: &str) -> bool {
216    !pattern.starts_with(['*', '?', '[', '{'])
217        && (pattern.starts_with(|c: char| c.is_ascii_digit()) || pattern.contains(':'))
218        && pattern
219            .chars()
220            .all(|c| c.is_ascii_hexdigit() || ".:*?[]{},!-".contains(c))
221}
222
223/// Whether `addresses` (compiled from [`address_policy`]) allows `ip`, matched
224/// in its canonical text form (`::ffff:10.0.0.5` as `10.0.0.5`).
225#[must_use]
226pub fn named(addresses: &CompiledPolicy<'_>, ip: IpAddr) -> bool {
227    let atom = AtomicAction::Fetch {
228        host: ip.to_canonical().to_string(),
229    };
230    addresses
231        .evaluate_atomic(&atom)
232        .is_some_and(|d| d.verdict == Verdict::Allow)
233}
234
235#[cfg(test)]
236mod tests;
openmoat_proxy/decide.rs

openmoat_proxy/
decide.rs
