cageforge_policy/network/
model.rs

1// SPDX-License-Identifier: Apache-2.0
2
3use std::net::SocketAddr;
4use std::path::PathBuf;
5
6use globset::GlobMatcher;
7
8/// Network restrictions passed to a platform backend or network proxy.
9#[derive(Debug, Clone, PartialEq, Eq)]
10pub struct NetworkPolicy {
11    pub(super) mode: NetworkMode,
12    pub(super) domain_mode: DomainMode,
13    pub(super) unix_socket_mode: UnixSocketMode,
14    pub(super) local_network_access: LocalNetworkAccess,
15    pub(super) domains: Vec<DomainRule>,
16    pub(super) unix_sockets: Vec<UnixSocketRule>,
17}
18
19/// A normalized hostname or literal together with the exact addresses a
20/// backend resolved for one connection attempt.
21#[derive(Debug, Clone, PartialEq, Eq)]
22pub struct ResolvedNetworkTarget {
23    pub(super) domain: String,
24    pub(super) addresses: Vec<SocketAddr>,
25}
26
27/// A normalized domain pattern and its access decision.
28#[derive(Debug, Clone)]
29pub struct DomainRule {
30    pub(super) pattern: String,
31    pub(super) access: DomainAccess,
32    pub(super) matcher: DomainMatcher,
33}
34
35/// A Unix socket path and its access decision.
36#[derive(Debug, Clone)]
37pub struct UnixSocketRule {
38    pub(super) path: PathBuf,
39    pub(super) access: DomainAccess,
40}
41
42/// The result of checking the exact address a backend is about to connect to.
43#[derive(Debug, PartialEq, Eq, Hash)]
44pub enum ConnectionAuthorization {
45    /// The address passed local policy and belongs to the resolution snapshot.
46    Allowed(AuthorizedSocketAddr),
47    /// The local policy rejects the connection.
48    Denied,
49    /// Another trusted boundary owns connection enforcement.
50    ExternallyEnforced,
51}
52
53/// A socket address that has passed the exact resolved-target check.
54#[derive(Debug, PartialEq, Eq, Hash)]
55pub struct AuthorizedSocketAddr(pub(super) SocketAddr);
56
57#[derive(Debug, Clone)]
58pub(super) enum DomainMatcher {
59    Any,
60    Full(GlobMatcher),
61    Suffix {
62        labels: Vec<GlobMatcher>,
63        include_apex: bool,
64    },
65}
66
67/// The result of evaluating a complete network policy.
68#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
69pub enum NetworkDecision {
70    /// The local policy allows the destination.
71    Allow,
72    /// The local policy denies the destination.
73    Deny,
74    /// A trusted external boundary owns enforcement for the destination.
75    ExternallyEnforced,
76}
77
78/// Whether a domain or socket is allowed or denied.
79#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
80pub enum DomainAccess {
81    /// Permit the destination.
82    Allow,
83    /// Deny the destination.
84    Deny,
85}
86
87/// Controls access to loopback, private, link-local, and otherwise
88/// non-public IP addresses reached through a domain.
89#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
90pub enum LocalNetworkAccess {
91    /// Reject non-public destinations unless the caller explicitly opts in.
92    Deny,
93    /// Permit non-public destinations after the ordinary domain policy allows.
94    Allow,
95}
96
97/// Default behavior for Unix socket rules when no rule matches.
98#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
99pub enum UnixSocketMode {
100    /// Reject every Unix socket path.
101    Disabled,
102    /// Allow Unix socket paths by default and apply matching rules as restrictions.
103    Enabled,
104    /// Reject Unix socket paths by default and allow only matching allow rules.
105    Restricted,
106}
107
108/// Default behavior for domain rules when no rule matches.
109#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
110pub enum DomainMode {
111    /// Reject every domain.
112    Disabled,
113    /// Allow domains by default and apply matching rules as restrictions.
114    Enabled,
115    /// Reject domains by default and allow only matching allow rules.
116    Restricted,
117}
118
119/// The enforcement ownership for network access.
120#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
121pub enum NetworkMode {
122    /// Outbound command networking is disabled unless a rule is explicitly used
123    /// by a backend that supports an allowlist.
124    Disabled,
125    /// Outbound command networking is enabled.
126    Enabled,
127    /// Another trusted component is responsible for enforcement.
128    External,
129}
cageforge_policy/network/model.rs

cageforge_policy/network/
model.rs
