Skip to content

Commit 4288256

Browse files
refactor(policy): extract shared L7 endpoint validation
Move 9 L7 endpoint semantic checks into a shared validate_l7_endpoint_semantics() function in openshell-policy. Both profile lint (openshell-providers) and the runtime validator (openshell-supervisor-network) now call the shared function via a lightweight L7EndpointFields field bag, eliminating duplication and preventing the two implementations from drifting apart. Update server test fixtures that used protocol without rules or access, which the shared validator now correctly rejects. Fixes NVIDIA#1714 Signed-off-by: Grace Smith <[email protected]>
1 parent 9a4f8a8 commit 4288256

8 files changed

Lines changed: 658 additions & 136 deletions

File tree

‎Cargo.lock‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
Lines changed: 389 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,389 @@
1+
// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2+
// SPDX-License-Identifier: Apache-2.0
3+
4+
//! Shared L7 endpoint semantic validation.
5+
//!
6+
//! Both profile lint (`openshell-providers`) and the runtime policy
7+
//! validator (`openshell-supervisor-network`) call
8+
//! [`validate_l7_endpoint_semantics`] to enforce the same constraints on
9+
//! L7 endpoint field combinations, preventing drift between lint-time
10+
//! and runtime checks.
11+
12+
/// Known L7 inspection protocols.
13+
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
14+
pub enum L7Protocol {
15+
Rest,
16+
Websocket,
17+
Graphql,
18+
Sql,
19+
JsonRpc,
20+
Mcp,
21+
}
22+
23+
impl L7Protocol {
24+
/// Parse a protocol string into a known variant.
25+
pub fn parse(s: &str) -> Option<Self> {
26+
match s.to_ascii_lowercase().as_str() {
27+
"rest" => Some(Self::Rest),
28+
"websocket" => Some(Self::Websocket),
29+
"graphql" => Some(Self::Graphql),
30+
"sql" => Some(Self::Sql),
31+
"json-rpc" => Some(Self::JsonRpc),
32+
"mcp" => Some(Self::Mcp),
33+
_ => None,
34+
}
35+
}
36+
37+
/// Returns `true` for protocols in the JSON-RPC family (`json-rpc`,
38+
/// `mcp`).
39+
pub fn is_jsonrpc_family(self) -> bool {
40+
matches!(self, Self::JsonRpc | Self::Mcp)
41+
}
42+
}
43+
44+
/// Fields extracted from an endpoint definition needed for L7 semantic
45+
/// validation. Both profile lint and the runtime validator construct this
46+
/// from their own data representation.
47+
#[allow(clippy::struct_excessive_bools)]
48+
pub struct L7EndpointFields<'a> {
49+
/// Protocol string as authored (e.g. `"rest"`, `"mcp"`). Empty
50+
/// string means no L7 protocol was specified.
51+
pub protocol: &'a str,
52+
53+
/// Access preset string (e.g. `"read-only"`, `"full"`). Empty string
54+
/// means no access preset.
55+
pub access: &'a str,
56+
57+
/// `true` when the endpoint has a non-empty rules list.
58+
pub has_rules: bool,
59+
60+
/// `true` when the endpoint has a non-empty `deny_rules` list.
61+
pub has_deny_rules: bool,
62+
63+
/// `true` when rules are present (non-empty) but would deny all
64+
/// traffic because every entry lacks an allow clause.
65+
pub rules_would_deny_all: bool,
66+
67+
/// Value of `mcp.allow_all_known_mcp_methods` (defaults to `false`).
68+
pub allow_all_known_mcp_methods: bool,
69+
}
70+
71+
/// Validate the semantic consistency of an L7 endpoint's field
72+
/// combination.
73+
///
74+
/// Returns a list of error message strings. An empty list means the
75+
/// endpoint passes validation. Messages are bare — callers prepend
76+
/// their own location context.
77+
pub fn validate_l7_endpoint_semantics(ep: &L7EndpointFields<'_>) -> Vec<String> {
78+
let mut errors = Vec::new();
79+
let protocol = ep.protocol;
80+
let l7_protocol = if protocol.is_empty() {
81+
None
82+
} else {
83+
L7Protocol::parse(protocol)
84+
};
85+
let jsonrpc_family = l7_protocol.is_some_and(L7Protocol::is_jsonrpc_family);
86+
let is_mcp = l7_protocol == Some(L7Protocol::Mcp);
87+
let is_jsonrpc = l7_protocol == Some(L7Protocol::JsonRpc);
88+
89+
// 1. Unknown protocol
90+
if !protocol.is_empty() && l7_protocol.is_none() {
91+
errors.push(format!(
92+
"unknown protocol '{protocol}' (expected rest, websocket, graphql, sql, json-rpc, or mcp)"
93+
));
94+
}
95+
96+
// 2. rules + access mutually exclusive
97+
if ep.has_rules && !ep.access.is_empty() {
98+
errors.push("rules and access are mutually exclusive".to_string());
99+
}
100+
101+
// 3. JSON-RPC family cannot use access presets
102+
if jsonrpc_family && !ep.access.is_empty() {
103+
if is_mcp {
104+
errors.push(format!(
105+
"protocol {protocol} does not support access presets; \
106+
use rules/deny_rules or set mcp.allow_all_known_mcp_methods: true \
107+
for an allow-all MCP policy"
108+
));
109+
} else {
110+
errors.push(format!(
111+
"protocol {protocol} does not support access presets; \
112+
use explicit rules with allow.method such as \"*\""
113+
));
114+
}
115+
}
116+
117+
// 4. json-rpc requires explicit rules
118+
if is_jsonrpc && !ep.has_rules {
119+
errors.push(format!(
120+
"protocol {protocol} requires explicit rules with allow.method"
121+
));
122+
}
123+
124+
// 5. Non-MCP, non-JSON-RPC protocol requires rules or access (JSON-RPC's
125+
// dedicated message is emitted by rule 4).
126+
if !protocol.is_empty() && !is_mcp && !is_jsonrpc && !ep.has_rules && ep.access.is_empty() {
127+
errors.push("protocol requires rules or access to define allowed traffic".to_string());
128+
}
129+
130+
// 6. MCP requires rules when allow_all_known_mcp_methods is false
131+
if is_mcp && !ep.has_rules && ep.access.is_empty() && !ep.allow_all_known_mcp_methods {
132+
errors.push(
133+
"protocol mcp requires rules when mcp.allow_all_known_mcp_methods is false".to_string(),
134+
);
135+
}
136+
137+
// 7. Rules would deny all traffic
138+
if ep.rules_would_deny_all {
139+
errors.push(
140+
"rules would deny all traffic (no allow clause found). \
141+
Use `access: full` or add allow clauses to rules."
142+
.to_string(),
143+
);
144+
}
145+
146+
// 8. deny_rules require protocol
147+
if ep.has_deny_rules && protocol.is_empty() {
148+
errors.push("deny_rules require protocol (L7 inspection must be enabled)".to_string());
149+
}
150+
151+
// 9. deny_rules require base allow set
152+
if ep.has_deny_rules && !is_mcp && !ep.has_rules && ep.access.is_empty() {
153+
errors.push("deny_rules require rules or access to define the base allow set".to_string());
154+
}
155+
156+
errors
157+
}
158+
159+
#[cfg(test)]
160+
mod tests {
161+
use super::*;
162+
163+
fn valid_rest_endpoint() -> L7EndpointFields<'static> {
164+
L7EndpointFields {
165+
protocol: "rest",
166+
access: "read-only",
167+
has_rules: false,
168+
has_deny_rules: false,
169+
rules_would_deny_all: false,
170+
allow_all_known_mcp_methods: false,
171+
}
172+
}
173+
174+
#[test]
175+
fn valid_endpoint_produces_no_errors() {
176+
let errors = validate_l7_endpoint_semantics(&valid_rest_endpoint());
177+
assert!(errors.is_empty(), "expected no errors, got: {errors:?}");
178+
}
179+
180+
#[test]
181+
fn rejects_unknown_protocol() {
182+
let ep = L7EndpointFields {
183+
protocol: "ftp",
184+
access: "",
185+
has_rules: false,
186+
has_deny_rules: false,
187+
rules_would_deny_all: false,
188+
allow_all_known_mcp_methods: false,
189+
};
190+
let errors = validate_l7_endpoint_semantics(&ep);
191+
assert!(errors.iter().any(|e| e.contains("unknown protocol")));
192+
}
193+
194+
#[test]
195+
fn rejects_rules_and_access_together() {
196+
let ep = L7EndpointFields {
197+
protocol: "rest",
198+
access: "full",
199+
has_rules: true,
200+
has_deny_rules: false,
201+
rules_would_deny_all: false,
202+
allow_all_known_mcp_methods: false,
203+
};
204+
let errors = validate_l7_endpoint_semantics(&ep);
205+
assert!(errors.iter().any(|e| e.contains("mutually exclusive")));
206+
}
207+
208+
#[test]
209+
fn rejects_jsonrpc_with_access_presets() {
210+
let ep = L7EndpointFields {
211+
protocol: "json-rpc",
212+
access: "full",
213+
has_rules: false,
214+
has_deny_rules: false,
215+
rules_would_deny_all: false,
216+
allow_all_known_mcp_methods: false,
217+
};
218+
let errors = validate_l7_endpoint_semantics(&ep);
219+
assert!(
220+
errors
221+
.iter()
222+
.any(|e| e.contains("does not support access presets"))
223+
);
224+
}
225+
226+
#[test]
227+
fn rejects_mcp_with_access_presets() {
228+
let ep = L7EndpointFields {
229+
protocol: "mcp",
230+
access: "full",
231+
has_rules: false,
232+
has_deny_rules: false,
233+
rules_would_deny_all: false,
234+
allow_all_known_mcp_methods: false,
235+
};
236+
let errors = validate_l7_endpoint_semantics(&ep);
237+
assert!(
238+
errors
239+
.iter()
240+
.any(|e| e.contains("allow_all_known_mcp_methods"))
241+
);
242+
}
243+
244+
#[test]
245+
fn rejects_jsonrpc_without_rules() {
246+
let ep = L7EndpointFields {
247+
protocol: "json-rpc",
248+
access: "",
249+
has_rules: false,
250+
has_deny_rules: false,
251+
rules_would_deny_all: false,
252+
allow_all_known_mcp_methods: false,
253+
};
254+
let errors = validate_l7_endpoint_semantics(&ep);
255+
assert!(errors.iter().any(|e| e.contains("requires explicit rules")));
256+
}
257+
258+
#[test]
259+
fn rejects_protocol_without_rules_or_access() {
260+
let ep = L7EndpointFields {
261+
protocol: "rest",
262+
access: "",
263+
has_rules: false,
264+
has_deny_rules: false,
265+
rules_would_deny_all: false,
266+
allow_all_known_mcp_methods: false,
267+
};
268+
let errors = validate_l7_endpoint_semantics(&ep);
269+
assert!(
270+
errors
271+
.iter()
272+
.any(|e| e.contains("protocol requires rules or access"))
273+
);
274+
}
275+
276+
#[test]
277+
fn rejects_mcp_without_rules_when_allow_all_false() {
278+
let ep = L7EndpointFields {
279+
protocol: "mcp",
280+
access: "",
281+
has_rules: false,
282+
has_deny_rules: false,
283+
rules_would_deny_all: false,
284+
allow_all_known_mcp_methods: false,
285+
};
286+
let errors = validate_l7_endpoint_semantics(&ep);
287+
assert!(errors.iter().any(|e| e.contains("mcp requires rules when")));
288+
}
289+
290+
#[test]
291+
fn accepts_mcp_with_allow_all_true() {
292+
let ep = L7EndpointFields {
293+
protocol: "mcp",
294+
access: "",
295+
has_rules: false,
296+
has_deny_rules: false,
297+
rules_would_deny_all: false,
298+
allow_all_known_mcp_methods: true,
299+
};
300+
let errors = validate_l7_endpoint_semantics(&ep);
301+
assert!(errors.is_empty(), "expected no errors, got: {errors:?}");
302+
}
303+
304+
#[test]
305+
fn rejects_rules_that_deny_all() {
306+
let ep = L7EndpointFields {
307+
protocol: "rest",
308+
access: "",
309+
has_rules: false,
310+
has_deny_rules: false,
311+
rules_would_deny_all: true,
312+
allow_all_known_mcp_methods: false,
313+
};
314+
let errors = validate_l7_endpoint_semantics(&ep);
315+
assert!(errors.iter().any(|e| e.contains("would deny all traffic")));
316+
}
317+
318+
#[test]
319+
fn rejects_deny_rules_without_protocol() {
320+
let ep = L7EndpointFields {
321+
protocol: "",
322+
access: "",
323+
has_rules: false,
324+
has_deny_rules: true,
325+
rules_would_deny_all: false,
326+
allow_all_known_mcp_methods: false,
327+
};
328+
let errors = validate_l7_endpoint_semantics(&ep);
329+
assert!(
330+
errors
331+
.iter()
332+
.any(|e| e.contains("deny_rules require protocol"))
333+
);
334+
}
335+
336+
#[test]
337+
fn rejects_deny_rules_without_allow_base() {
338+
let ep = L7EndpointFields {
339+
protocol: "rest",
340+
access: "",
341+
has_rules: false,
342+
has_deny_rules: true,
343+
rules_would_deny_all: false,
344+
allow_all_known_mcp_methods: false,
345+
};
346+
let errors = validate_l7_endpoint_semantics(&ep);
347+
assert!(
348+
errors
349+
.iter()
350+
.any(|e| e.contains("deny_rules require rules or access"))
351+
);
352+
}
353+
354+
#[test]
355+
fn no_protocol_no_errors() {
356+
let ep = L7EndpointFields {
357+
protocol: "",
358+
access: "",
359+
has_rules: false,
360+
has_deny_rules: false,
361+
rules_would_deny_all: false,
362+
allow_all_known_mcp_methods: false,
363+
};
364+
let errors = validate_l7_endpoint_semantics(&ep);
365+
assert!(errors.is_empty(), "expected no errors, got: {errors:?}");
366+
}
367+
368+
#[test]
369+
fn l7_protocol_parse_known_variants() {
370+
assert_eq!(L7Protocol::parse("rest"), Some(L7Protocol::Rest));
371+
assert_eq!(L7Protocol::parse("websocket"), Some(L7Protocol::Websocket));
372+
assert_eq!(L7Protocol::parse("graphql"), Some(L7Protocol::Graphql));
373+
assert_eq!(L7Protocol::parse("sql"), Some(L7Protocol::Sql));
374+
assert_eq!(L7Protocol::parse("json-rpc"), Some(L7Protocol::JsonRpc));
375+
assert_eq!(L7Protocol::parse("mcp"), Some(L7Protocol::Mcp));
376+
assert_eq!(L7Protocol::parse("unknown"), None);
377+
assert_eq!(L7Protocol::parse(""), None);
378+
}
379+
380+
#[test]
381+
fn l7_protocol_jsonrpc_family() {
382+
assert!(L7Protocol::JsonRpc.is_jsonrpc_family());
383+
assert!(L7Protocol::Mcp.is_jsonrpc_family());
384+
assert!(!L7Protocol::Rest.is_jsonrpc_family());
385+
assert!(!L7Protocol::Websocket.is_jsonrpc_family());
386+
assert!(!L7Protocol::Graphql.is_jsonrpc_family());
387+
assert!(!L7Protocol::Sql.is_jsonrpc_family());
388+
}
389+
}

0 commit comments

Comments
 (0)