feat(policy): route shared host l7 endpoints by path

Author: johntmyers

Cargo.lock

@@ -1032,7 +1032,7 @@ flowchart LR
 | `L7Protocol` | `Rest`, `Graphql`, `Sql` | Supported application protocols |
 | `TlsMode` | `Auto` (default), `Skip` | TLS handling strategy — `Auto` peeks first bytes and terminates if TLS is detected; `Skip` bypasses detection entirely |
 | `EnforcementMode` | `Audit`, `Enforce` | What to do on L7 deny (log-only vs block) |
-| `L7EndpointConfig` | `{ protocol, tls, enforcement, allow_encoded_slash, graphql_max_body_bytes }` | Per-endpoint L7 configuration |
+| `L7EndpointConfig` | `{ protocol, path, tls, enforcement, allow_encoded_slash, graphql_max_body_bytes }` | Per-endpoint L7 configuration, including optional path scoping for shared host:port APIs |
 | `L7Decision` | `{ allowed, reason, matched_rule }` | Result of L7 evaluation |
 | `L7RequestInfo` | `{ action, target, query_params, graphql }` | HTTP method, path, decoded query multimap, and optional GraphQL classification for policy evaluation |
 

architecture/sandbox.md

@@ -469,6 +469,7 @@ Each endpoint defines a network destination and, optionally, L7 inspection behav
 | `host`         | `string`   | _(required)_    | Hostname or glob pattern to match (case-insensitive). Supports wildcards (`*.example.com`). Optional when `allowed_ips` is set (see [Hostless Endpoints](#hostless-endpoints-allowed_ips-without-host)). See [Host Wildcards](#host-wildcards). |
 | `port`         | `integer`  | _(required)_    | TCP port to match. Mutually exclusive with `ports` — if both are set, `ports` takes precedence. See [Multi-Port Endpoints](#multi-port-endpoints). |
 | `ports`        | `integer[]`| `[]`            | Multiple TCP ports to match. When non-empty, the endpoint covers all listed ports. Backwards compatible with `port`. See [Multi-Port Endpoints](#multi-port-endpoints). |
+| `path`         | `string`   | `""`            | Optional HTTP path glob for L7 endpoint selection when multiple protocols share a host:port, such as `/repos/**` and `/graphql`. Empty matches all paths. |
 | `protocol`     | `string`   | `""`            | Application protocol for L7 inspection. See [Behavioral Trigger: L7 Inspection](#behavioral-trigger-l7-inspection). |
 | `tls`          | `string`   | `""` (auto)      | TLS handling mode. Absent or empty: auto-detect and terminate TLS if detected. `"skip"`: bypass TLS detection entirely. `"terminate"` and `"passthrough"` are deprecated (treated as auto). See [Behavioral Trigger: TLS Handling](#behavioral-trigger-tls-handling). |
 | `enforcement`  | `string`   | `"audit"`       | L7 enforcement mode: `"enforce"` or `"audit"`                                                                       |
@@ -739,7 +740,7 @@ flowchart LR
 
 This is the single most important behavioral trigger in the policy language. An endpoint with no `protocol` field passes traffic opaquely after the L4 (CONNECT) check. Adding `protocol: rest` or `protocol: graphql` activates per-request HTTP parsing and policy evaluation inside the proxy.
 
-**Implementation path**: After L4 CONNECT is allowed, the proxy calls `query_l7_route_snapshot()` which evaluates the Rego rule `data.openshell.sandbox.matched_endpoint_config` and records the policy generation. If an endpoint `protocol` config is returned, the proxy enters `relay_with_inspection()` instead of `copy_bidirectional()`. See `crates/openshell-sandbox/src/proxy.rs` -- `handle_tcp_connection()`.
+**Implementation path**: After L4 CONNECT is allowed, the proxy calls `query_l7_route_snapshot()` which evaluates the Rego rule `data.openshell.sandbox._matching_endpoint_configs` and records the policy generation. If one or more endpoint `protocol` configs are returned, the proxy enters path-aware L7 route selection instead of `copy_bidirectional()`. See `crates/openshell-sandbox/src/proxy.rs` -- `handle_tcp_connection()`.
 
 For L7-inspected CONNECT tunnels, the proxy binds endpoint config and the per-tunnel policy engine clone to the policy generation observed at tunnel setup. If a live policy reload advances the generation, the relay closes the existing keep-alive tunnel before forwarding another request. HTTP passthrough tunnels without endpoint `protocol` use the same generation guard for parsed requests even though they do not evaluate L7 OPA rules. Clients should reconnect so the next request is evaluated under the current policy.
 

architecture/security-policy.md

@@ -89,6 +89,8 @@ struct NetworkPolicyRuleDef {
 struct NetworkEndpointDef {
     #[serde(default, skip_serializing_if = "String::is_empty")]
     host: String,
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    path: String,
     /// Single port (backwards compat). Mutually exclusive with `ports`.
     /// Uses `u16` to reject invalid values >65535 at parse time.
     #[serde(default, skip_serializing_if = "is_zero")]
@@ -245,6 +247,7 @@ fn to_proto(raw: PolicyFile) -> SandboxPolicy {
                         };
                         NetworkEndpoint {
                             host: e.host,
+                            path: e.path,
                             port: normalized_ports.first().copied().unwrap_or(0),
                             ports: normalized_ports,
                             protocol: e.protocol,
@@ -409,6 +412,7 @@ fn from_proto(policy: &SandboxPolicy) -> PolicyFile {
                         };
                         NetworkEndpointDef {
                             host: e.host.clone(),
+                            path: e.path.clone(),
                             port,
                             ports,
                             protocol: e.protocol.clone(),
@@ -1392,6 +1396,34 @@ network_policies:
         assert_eq!(ep.port, 443);
     }
 
+    #[test]
+    fn round_trip_preserves_endpoint_path() {
+        let yaml = r#"
+version: 1
+network_policies:
+  test:
+    name: test
+    endpoints:
+      - host: api.example.com
+        port: 443
+        path: "/graphql"
+        protocol: graphql
+        rules:
+          - allow:
+              operation_type: query
+    binaries:
+      - { path: /usr/bin/curl }
+"#;
+        let proto1 = parse_sandbox_policy(yaml).expect("parse failed");
+        let yaml_out = serialize_sandbox_policy(&proto1).expect("serialize failed");
+        let proto2 = parse_sandbox_policy(&yaml_out).expect("re-parse failed");
+
+        let ep1 = &proto1.network_policies["test"].endpoints[0];
+        let ep2 = &proto2.network_policies["test"].endpoints[0];
+        assert_eq!(ep1.path, "/graphql");
+        assert_eq!(ep1.path, ep2.path);
+    }
+
     #[test]
     fn round_trip_preserves_multi_port() {
         let yaml = r"

crates/openshell-policy/src/lib.rs

@@ -389,6 +389,9 @@ fn merge_endpoint(
     if existing.host.is_empty() {
         existing.host.clone_from(&incoming.host);
     }
+    if existing.path.is_empty() {
+        existing.path.clone_from(&incoming.path);
+    }
 
     merge_endpoint_ports(existing, incoming);
     let existing_protocol = existing.protocol.clone();
@@ -508,6 +511,9 @@ fn endpoints_overlap(left: &NetworkEndpoint, right: &NetworkEndpoint) -> bool {
     if !left.host.eq_ignore_ascii_case(&right.host) {
         return false;
     }
+    if left.path != right.path {
+        return false;
+    }
 
     let left_ports = canonical_ports(left);
     let right_ports = canonical_ports(right);

crates/openshell-policy/src/merge.rs

@@ -67,6 +67,7 @@ serde = { workspace = true }
 serde_json = { workspace = true }
 serde_yml = { workspace = true }
 apollo-parser = { workspace = true }
+glob = { workspace = true }
 
 # Logging
 tracing = { workspace = true }

crates/openshell-sandbox/Cargo.toml

@@ -179,7 +179,7 @@ default allow_request = false
 _policy_allows_l7(policy) if {
 	some ep
 	ep := policy.endpoints[_]
-	endpoint_matches_request(ep, input.network)
+	endpoint_matches_l7_request(ep, input.network, input.request)
 	request_allowed_for_endpoint(input.request, ep)
 }
 
@@ -207,7 +207,7 @@ default deny_request = false
 _policy_denies_l7(policy) if {
 	some ep
 	ep := policy.endpoints[_]
-	endpoint_matches_request(ep, input.network)
+	endpoint_matches_l7_request(ep, input.network, input.request)
 	request_denied_for_endpoint(input.request, ep)
 }
 
@@ -250,6 +250,16 @@ request_denied_for_endpoint(request, endpoint) if {
 	graphql_deny_rule_matches_operation(op, deny_rule, endpoint)
 }
 
+# A GraphQL endpoint path is authoritative once it matches. If the parsed
+# GraphQL request is malformed, hash-only without a trusted registry entry, or
+# contains an operation outside the GraphQL allow rules, a broader REST rule on
+# the same host:port must not allow it through.
+request_denied_for_endpoint(request, endpoint) if {
+	endpoint.protocol == "graphql"
+	is_object(request.graphql)
+	not graphql_request_allowed(request, endpoint)
+}
+
 # Deny query matching: fail-closed semantics.
 # If no query rules on the deny rule, match unconditionally (any query params).
 # If query rules present, trigger the deny if ANY value for a configured key
@@ -314,7 +324,7 @@ request_deny_reason := reason if {
 	input.request
 	deny_request
 	graphql_request_has_operations(input.request)
-	reason := "GraphQL operation blocked by deny rule"
+	reason := "GraphQL operation blocked by endpoint policy"
 }
 
 request_deny_reason := reason if {
@@ -632,6 +642,21 @@ endpoint_matches_request(ep, network) if {
 	ep.ports[_] == network.port
 }
 
+endpoint_matches_l7_request(ep, network, request) if {
+	endpoint_matches_request(ep, network)
+	endpoint_path_matches_request(ep, request)
+}
+
+endpoint_path_matches_request(ep, request) if {
+	object.get(ep, "path", "") == ""
+}
+
+endpoint_path_matches_request(ep, request) if {
+	path := object.get(ep, "path", "")
+	path != ""
+	path_matches(request.path, path)
+}
+
 # An endpoint has extended config if it specifies L7 protocol, allowed_ips,
 # or an explicit tls mode (e.g. tls: skip).
 endpoint_has_extended_config(ep) if {

crates/openshell-sandbox/data/sandbox-policy.rego

@@ -61,6 +61,9 @@ pub enum EnforcementMode {
 #[derive(Debug, Clone)]
 pub struct L7EndpointConfig {
     pub protocol: L7Protocol,
+    /// Optional endpoint-level HTTP path glob used to select between L7
+    /// protocols that share the same host:port.
+    pub path: String,
     pub tls: TlsMode,
     pub enforcement: EnforcementMode,
     /// Maximum GraphQL request body bytes to buffer for inspection.
@@ -142,13 +145,41 @@ pub fn parse_l7_config(val: &regorus::Value) -> Option<L7EndpointConfig> {
 
     Some(L7EndpointConfig {
         protocol,
+        path: get_object_str(val, "path").unwrap_or_default(),
         tls,
         enforcement,
         graphql_max_body_bytes,
         allow_encoded_slash,
     })
 }
 
+impl L7EndpointConfig {
+    pub fn matches_path(&self, path: &str) -> bool {
+        endpoint_path_matches(&self.path, path)
+    }
+
+    pub fn path_specificity(&self) -> usize {
+        if self.path.is_empty() {
+            0
+        } else {
+            self.path.chars().filter(|c| *c != '*').count()
+        }
+    }
+}
+
+pub fn endpoint_path_matches(pattern: &str, path: &str) -> bool {
+    if pattern.is_empty() || pattern == "**" || pattern == "/**" {
+        return true;
+    }
+    if pattern == path {
+        return true;
+    }
+    if let Some(prefix) = pattern.strip_suffix("/**") {
+        return path == prefix || path.starts_with(&format!("{prefix}/"));
+    }
+    glob::Pattern::new(pattern).is_ok_and(|glob| glob.matches(path))
+}
+
 /// Parse the `tls` field from an endpoint config, independent of L7 protocol.
 ///
 /// Used to check for `tls: skip` even on L4-only endpoints (no `protocol`
@@ -352,6 +383,7 @@ pub fn validate_l7_policies(data_json: &serde_json::Value) -> (Vec<String>, Vec<
                 .and_then(|v| v.as_array())
                 .is_some_and(|a| !a.is_empty());
             let host = ep.get("host").and_then(|v| v.as_str()).unwrap_or("");
+            let endpoint_path = ep.get("path").and_then(|v| v.as_str()).unwrap_or("");
 
             // Read ports from either "ports" array or scalar "port".
             let ports: Vec<u64> = ep.get("ports").and_then(|v| v.as_array()).map_or_else(
@@ -366,6 +398,17 @@ pub fn validate_l7_policies(data_json: &serde_json::Value) -> (Vec<String>, Vec<
             );
             let loc = format!("{name}.endpoints[{i}]");
 
+            if !endpoint_path.is_empty() {
+                if !endpoint_path.starts_with('/') && endpoint_path != "**" {
+                    errors.push(format!(
+                        "{loc}: endpoint path must start with '/' or be '**', got '{endpoint_path}'"
+                    ));
+                }
+                if let Some(warning) = check_glob_syntax(endpoint_path) {
+                    warnings.push(format!("{loc}.path: {warning}"));
+                }
+            }
+
             // Validate host wildcard patterns.
             if host.contains('*') {
                 if host == "*" || host == "**" {