Skip to content

Commit 0cfe443

Browse files
committed
fix(policy): reject unknown endpoint security modes
Closes NVIDIA#3046 Validate TLS, enforcement, and access values across policy and provider profile ingress, and prevent runtime parsing from falling back to audit for unknown enforcement values. Signed-off-by: Krzysztof Malczuk <[email protected]>
1 parent 5b9daab commit 0cfe443

8 files changed

Lines changed: 188 additions & 14 deletions

File tree

‎architecture/security-policy.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -199,6 +199,10 @@ connection metadata agrees. When request paths overlap, a path endpoint with a
199199
higher specificity rank deterministically overrides broader request-processing
200200
metadata. Equally specific overlapping endpoints must agree.
201201

202+
Endpoint `tls`, `enforcement`, `access`, and `protocol` strings are validated
203+
before persistence or activation. The supervisor also refuses unknown endpoint
204+
modes defensively; an unrecognized enforcement value never falls back to audit.
205+
202206
Gateway mutation paths validate the complete effective candidate before
203207
persistence when the affected sandbox scope is known. Direct replacements,
204208
incremental merges and approvals, provider attachment, and profile fanout reject

‎crates/openshell-policy/src/l7_validate.rs‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -107,6 +107,30 @@ mod agent_transport_tests {
107107
}
108108
}
109109

110+
/// Validate the security-sensitive endpoint fields whose public representation
111+
/// is currently a string. Empty values preserve the documented defaults.
112+
pub fn validate_endpoint_modes(tls: &str, enforcement: &str, access: &str) -> Vec<String> {
113+
let mut errors = Vec::new();
114+
115+
if !matches!(tls, "" | "skip" | "terminate" | "passthrough") {
116+
errors.push(format!(
117+
"unknown tls value '{tls}' (expected skip, terminate, or passthrough)"
118+
));
119+
}
120+
if !matches!(enforcement, "" | "enforce" | "audit") {
121+
errors.push(format!(
122+
"unknown enforcement value '{enforcement}' (expected enforce or audit)"
123+
));
124+
}
125+
if !matches!(access, "" | "read-only" | "read-write" | "full") {
126+
errors.push(format!(
127+
"unknown access value '{access}' (expected read-only, read-write, or full)"
128+
));
129+
}
130+
131+
errors
132+
}
133+
110134
/// Fields extracted from an endpoint definition needed for L7 semantic
111135
/// validation. Both profile lint and the runtime validator construct this
112136
/// from their own data representation.
@@ -250,6 +274,27 @@ mod tests {
250274
assert!(errors.is_empty(), "expected no errors, got: {errors:?}");
251275
}
252276

277+
#[test]
278+
fn endpoint_modes_reject_unknown_values() {
279+
let errors = validate_endpoint_modes("skp", "enforc", "read-wirte");
280+
281+
assert_eq!(errors.len(), 3);
282+
assert!(errors[0].contains("unknown tls value 'skp'"));
283+
assert!(errors[1].contains("unknown enforcement value 'enforc'"));
284+
assert!(errors[2].contains("unknown access value 'read-wirte'"));
285+
}
286+
287+
#[test]
288+
fn endpoint_modes_accept_documented_values_and_defaults() {
289+
for tls in ["", "skip", "terminate", "passthrough"] {
290+
for enforcement in ["", "enforce", "audit"] {
291+
for access in ["", "read-only", "read-write", "full"] {
292+
assert!(validate_endpoint_modes(tls, enforcement, access).is_empty());
293+
}
294+
}
295+
}
296+
}
297+
253298
#[test]
254299
fn rejects_unknown_protocol() {
255300
let ep = L7EndpointFields {

‎crates/openshell-policy/src/lib.rs‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ pub use compose::{
3838
is_provider_rule_name, provider_rule_name, strip_provider_rule_names,
3939
};
4040
pub use l7_validate::{
41-
L7EndpointFields, L7Protocol, agent_authored_transport_rejection,
41+
L7EndpointFields, L7Protocol, agent_authored_transport_rejection, validate_endpoint_modes,
4242
validate_explicit_tcp_additional_fields, validate_l7_endpoint_semantics,
4343
};
4444
pub use merge::{
@@ -1852,6 +1852,11 @@ fn validate_sandbox_policy_with_mcp_presence(
18521852
.unwrap_or(false),
18531853
};
18541854
let mut l7_errors = validate_l7_endpoint_semantics(&fields);
1855+
l7_errors.extend(validate_endpoint_modes(
1856+
&ep.tls,
1857+
&ep.enforcement,
1858+
&ep.access,
1859+
));
18551860
let mut explicit_tcp_fields = Vec::new();
18561861
if !ep.enforcement.is_empty() {
18571862
explicit_tcp_fields.push("enforcement");
@@ -2445,6 +2450,36 @@ network_policies:
24452450
assert!(policy.filesystem.is_none());
24462451
}
24472452

2453+
#[test]
2454+
fn validation_rejects_unknown_security_sensitive_endpoint_values() {
2455+
let policy = parse_sandbox_policy(
2456+
r"
2457+
version: 1
2458+
network_policies:
2459+
github_api:
2460+
endpoints:
2461+
- host: api.github.com
2462+
port: 443
2463+
protocol: rest
2464+
tls: skp
2465+
enforcement: enforc
2466+
access: read-wirte
2467+
",
2468+
)
2469+
.expect("the string-backed protobuf shape accepts syntactically valid YAML");
2470+
2471+
let violations = validate_sandbox_policy(&policy).expect_err("values must be rejected");
2472+
let message = violations
2473+
.iter()
2474+
.map(ToString::to_string)
2475+
.collect::<Vec<_>>()
2476+
.join("\n");
2477+
2478+
assert!(message.contains("unknown tls value 'skp'"));
2479+
assert!(message.contains("unknown enforcement value 'enforc'"));
2480+
assert!(message.contains("unknown access value 'read-wirte'"));
2481+
}
2482+
24482483
#[test]
24492484
fn process_identity_omission_survives_yaml_round_trip() {
24502485
let policy = parse_sandbox_policy("version: 1\nprocess:\n run_as_user: \"1234\"\n")

‎crates/openshell-providers/src/profiles.rs‎

Lines changed: 40 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ use openshell_core::proto::{
1414
};
1515
use openshell_core::secrets::uses_reserved_revision_namespace;
1616
use openshell_policy::{
17-
L7EndpointFields, L7Protocol, validate_explicit_tcp_additional_fields,
17+
L7EndpointFields, L7Protocol, validate_endpoint_modes, validate_explicit_tcp_additional_fields,
1818
validate_l7_endpoint_semantics,
1919
};
2020
use serde::{Deserialize, Deserializer, Serialize, Serializer, de};
@@ -2335,6 +2335,16 @@ pub fn validate_profile_set(
23352335
msg,
23362336
));
23372337
}
2338+
for msg in
2339+
validate_endpoint_modes(&endpoint.tls, &endpoint.enforcement, &endpoint.access)
2340+
{
2341+
diagnostics.push(ProfileValidationDiagnostic::error(
2342+
source,
2343+
profile_id,
2344+
format!("endpoints[{index}]"),
2345+
msg,
2346+
));
2347+
}
23382348
for msg in validate_explicit_tcp_additional_fields(
23392349
&endpoint.protocol,
23402350
&additional_l7_profile_fields(endpoint),
@@ -5921,6 +5931,35 @@ credentials:
59215931

59225932
// -- L7 endpoint semantic validation (shared with runtime) ----------------
59235933

5934+
#[test]
5935+
fn validate_rejects_unknown_security_sensitive_endpoint_values() {
5936+
let profile = parse_profile_yaml(
5937+
r"
5938+
id: invalid-modes
5939+
display_name: Invalid modes
5940+
endpoints:
5941+
- host: api.example.com
5942+
port: 443
5943+
protocol: rest
5944+
tls: skp
5945+
enforcement: enforc
5946+
access: read-wirte
5947+
",
5948+
)
5949+
.expect("string values should parse before semantic validation");
5950+
5951+
let diagnostics = validate_profile_set(&[("profile.yaml".to_string(), profile)]);
5952+
let message = diagnostics
5953+
.iter()
5954+
.map(|diagnostic| diagnostic.message.as_str())
5955+
.collect::<Vec<_>>()
5956+
.join("\n");
5957+
5958+
assert!(message.contains("unknown tls value 'skp'"));
5959+
assert!(message.contains("unknown enforcement value 'enforc'"));
5960+
assert!(message.contains("unknown access value 'read-wirte'"));
5961+
}
5962+
59245963
#[test]
59255964
fn validate_rejects_protocol_without_rules_or_access() {
59265965
let profile = parse_profile_yaml(

‎crates/openshell-server/src/grpc/validation.rs‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2031,6 +2031,35 @@ mod tests {
20312031
assert!(err.message().contains("TLD wildcard"));
20322032
}
20332033

2034+
#[test]
2035+
fn validate_policy_safety_reports_unknown_enforcement() {
2036+
use openshell_core::proto::{NetworkEndpoint, NetworkPolicyRule};
2037+
2038+
let mut policy = openshell_policy::restrictive_default_policy();
2039+
policy.network_policies.insert(
2040+
"github_api".into(),
2041+
NetworkPolicyRule {
2042+
name: "github-api-readonly".into(),
2043+
endpoints: vec![NetworkEndpoint {
2044+
host: "api.github.com".into(),
2045+
port: 443,
2046+
protocol: "rest".into(),
2047+
enforcement: "enforc".into(),
2048+
access: "read-only".into(),
2049+
..Default::default()
2050+
}],
2051+
..Default::default()
2052+
},
2053+
);
2054+
2055+
let err = validate_policy_safety(&policy).unwrap_err();
2056+
2057+
assert_eq!(err.code(), Code::InvalidArgument);
2058+
assert!(err.message().contains("endpoint 0"));
2059+
assert!(err.message().contains("unknown enforcement value 'enforc'"));
2060+
assert!(err.message().contains("expected enforce or audit"));
2061+
}
2062+
20342063
#[test]
20352064
fn validate_policy_safety_rejects_invalid_middleware_before_acceptance() {
20362065
use openshell_core::proto::{MiddlewareEndpointSelector, NetworkMiddlewareConfig};

‎crates/openshell-supervisor-network/src/l7/mod.rs‎

Lines changed: 29 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,8 @@ pub(crate) mod websocket;
2424
use openshell_core::mcp::McpProtocolVersion;
2525
pub use openshell_policy::L7Protocol;
2626
use openshell_policy::{
27-
L7EndpointFields, validate_explicit_tcp_additional_fields, validate_l7_endpoint_semantics,
27+
L7EndpointFields, validate_endpoint_modes, validate_explicit_tcp_additional_fields,
28+
validate_l7_endpoint_semantics,
2829
};
2930

3031
pub(crate) fn build_credential_endpoint_mismatch_finding(
@@ -183,9 +184,16 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
183184
let protocol_val = get_object_str(val, "protocol")?;
184185
let protocol = L7Protocol::parse(&protocol_val)?;
185186

186-
let tls = match get_object_str(val, "tls").as_deref() {
187-
Some("skip") => TlsMode::Skip,
188-
Some("terminate") => {
187+
let tls_value = get_object_str(val, "tls").unwrap_or_default();
188+
let enforcement_value = get_object_str(val, "enforcement").unwrap_or_default();
189+
let access_value = get_object_str(val, "access").unwrap_or_default();
190+
if !validate_endpoint_modes(&tls_value, &enforcement_value, &access_value).is_empty() {
191+
return None;
192+
}
193+
194+
let tls = match tls_value.as_str() {
195+
"skip" => TlsMode::Skip,
196+
"terminate" => {
189197
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
190198
.activity(openshell_ocsf::ActivityId::Other)
191199
.severity(openshell_ocsf::SeverityId::Medium)
@@ -197,7 +205,7 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
197205
openshell_ocsf::ocsf_emit!(event);
198206
TlsMode::Auto
199207
}
200-
Some("passthrough") => {
208+
"passthrough" => {
201209
let event = openshell_ocsf::NetworkActivityBuilder::new(openshell_ocsf::ctx::ctx())
202210
.activity(openshell_ocsf::ActivityId::Other)
203211
.severity(openshell_ocsf::SeverityId::Medium)
@@ -209,12 +217,14 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
209217
openshell_ocsf::ocsf_emit!(event);
210218
TlsMode::Auto
211219
}
212-
_ => TlsMode::Auto,
220+
"" => TlsMode::Auto,
221+
_ => unreachable!("endpoint modes were validated above"),
213222
};
214223

215-
let enforcement = match get_object_str(val, "enforcement").as_deref() {
216-
Some("enforce") => EnforcementMode::Enforce,
217-
_ => EnforcementMode::Audit,
224+
let enforcement = match enforcement_value.as_str() {
225+
"enforce" => EnforcementMode::Enforce,
226+
"" | "audit" => EnforcementMode::Audit,
227+
_ => unreachable!("endpoint modes were validated above"),
218228
};
219229

220230
let allow_encoded_slash = get_object_bool(val, "allow_encoded_slash").unwrap_or(false);
@@ -1845,6 +1855,16 @@ mod tests {
18451855
assert_eq!(config.enforcement, EnforcementMode::Audit);
18461856
}
18471857

1858+
#[test]
1859+
fn parse_l7_config_rejects_unknown_enforcement() {
1860+
let val = regorus::Value::from_json_str(
1861+
r#"{"protocol": "rest", "enforcement": "enforc", "access": "read-only", "host": "api.example.com", "port": 443}"#,
1862+
)
1863+
.unwrap();
1864+
1865+
assert!(parse_l7_config(&val).is_none());
1866+
}
1867+
18481868
#[test]
18491869
fn parse_credential_signing_sigv4() {
18501870
let val = regorus::Value::from_json_str(

‎docs/providers/profiles.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -436,6 +436,8 @@ environment value under the actual environment variable key.
436436

437437
`endpoints` contains the same endpoint object shape as sandbox network policy. A profile can use access presets, protocol-specific allow rules, deny rules, WebSocket credential rewriting, request body credential rewriting, GraphQL fields, and SSRF IP allowlists. Because profile credentials are not mapped to individual endpoints, OpenShell conservatively treats every endpoint in a profile that declares credentials as credentialed. Such endpoints require L7 inspection and cannot use `tls: skip` unless the profile explicitly sets `allow_uninspected_credentials: true`.
438438

439+
Profile validation rejects unknown `tls`, `enforcement`, and `access` values before the profile can contribute policy to a sandbox.
440+
439441
`binaries` contains the executable paths allowed to reach the profile endpoints when the profile contributes policy to a sandbox. Write each binary as a scalar path. OpenShell also accepts the transitional object form `- path: /usr/bin/example` and exports it as a scalar. The removed `harness` property is rejected; delete it from profiles created before 0.1.0.
440442

441443
`inference_capable` is informational metadata that marks profiles intended for

‎docs/reference/policy-schema.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -166,9 +166,9 @@ Each endpoint defines a reachable destination and optional inspection rules.
166166
| `port` | integer | Yes | TCP port number. |
167167
| `path` | string | No | Optional HTTP path glob used to select between L7 endpoints that share the same host and port. Empty means all paths. Use this when REST and GraphQL live under the same host, such as `/repos/**` and `/graphql`. |
168168
| `protocol` | string | No | Set to `tcp` with a valid DNS hostname to allow native TCP clients through policy DNS and transparent capture without payload inspection. Omit the field for L4 passthrough through an explicit proxy, including legacy hostless `allowed_ips` endpoints. Set to `rest` for HTTP method/path inspection, `websocket` for RFC 6455 upgrade and client text-message inspection, `graphql` for GraphQL-over-HTTP operation inspection, `mcp` for MCP Streamable HTTP request inspection, or `json-rpc` for generic JSON-RPC-over-HTTP method inspection. WebSocket endpoints can also use GraphQL operation rules for GraphQL-over-WebSocket traffic. Provider-credentialed endpoints require an inspected protocol unless `allow_uninspected_credentials` is explicitly set. |
169-
| `tls` | string | No | TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it for inspected HTTPS traffic, so this field is optional in most cases. Set to `skip` to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols. Provider-credentialed endpoints reject `tls: skip` unless `allow_uninspected_credentials` is explicitly set. The values `terminate` and `passthrough` are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior. |
170-
| `enforcement` | string | No | `enforce` actively blocks disallowed requests. `audit` logs violations but allows traffic through. |
171-
| `access` | string | No | Access preset. One of `read-only`, `read-write`, or `full`. Mutually exclusive with `rules`. Not valid on `protocol: mcp` or `protocol: json-rpc`; MCP uses explicit rules unless `mcp.allow_all_known_mcp_methods: true` enables the endpoint method profile, and JSON-RPC always uses explicit rules. |
169+
| `tls` | string | No | TLS handling mode. The proxy auto-detects TLS by peeking the first bytes of each connection and terminates it for inspected HTTPS traffic, so this field is optional in most cases. Set to `skip` to disable auto-detection for edge cases such as client-certificate mTLS or non-standard protocols. Provider-credentialed endpoints reject `tls: skip` unless `allow_uninspected_credentials` is explicitly set. The values `terminate` and `passthrough` are deprecated and log a warning; they are still accepted for backward compatibility but have no effect on behavior. Other values are rejected before activation. |
170+
| `enforcement` | string | No | `enforce` actively blocks disallowed requests. `audit` logs violations but allows traffic through. Other values are rejected before activation rather than interpreted as audit mode. |
171+
| `access` | string | No | Access preset. One of `read-only`, `read-write`, or `full`; other values are rejected before activation. Mutually exclusive with `rules`. Not valid on `protocol: mcp` or `protocol: json-rpc`; MCP uses explicit rules unless `mcp.allow_all_known_mcp_methods: true` enables the endpoint method profile, and JSON-RPC always uses explicit rules. |
172172
| `rules` | list of allow rule objects | No | Fine-grained protocol-specific allow rules. Mutually exclusive with `access`. |
173173
| `deny_rules` | list of deny rule objects | No | L7 deny rules that block specific requests even when allowed by `access` or `rules`. Deny rules take precedence over allow rules. |
174174
| `allowed_ips` | list of string | No | CIDR or IP allowlist for SSRF override. Exact user-declared hostname endpoints may resolve to RFC 1918 private addresses without this field, but wildcard, hostless, and policy-advisor-proposed endpoints still require `allowed_ips` for private resolved IPs. A hostless allowlist is valid only for the legacy proxy path and cannot be combined with `protocol: tcp`. Entries overlapping loopback (`127.0.0.0/8`), link-local (`169.254.0.0/16`), or unspecified (`0.0.0.0`) are rejected at load time. |

0 commit comments

Comments
 (0)