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

cageforge_policy/network/
model.rs
