Skip to content

Commit 7ebc2e6

Browse files
committed
docs(sandbox): document L7 host wildcard contract + add OPA runtime tests
- Add Host Wildcards section to architecture/security-policy.md describing accepted (first-label *, **, intra-label *-X) and rejected (bare, TLD, non-first-label, recursive-in-label) forms, and noting that wildcards never cross '.' boundaries. - Expand the policy-schema.mdx 'host' field description to reflect the same contract instead of only mentioning '*.example.com'. - Add OPA runtime tests asserting '*-aiplatform.googleapis.com' matches 'us-central1-aiplatform.googleapis.com' and does not match 'us-central1.aiplatform.googleapis.com' (cross-dot boundary). Locks validator/runtime alignment for intra-label wildcards.
1 parent 0f045e6 commit 7ebc2e6

3 files changed

Lines changed: 85 additions & 1 deletion

File tree

‎architecture/security-policy.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,27 @@ Ordinary network traffic follows this order:
3636
Explicit deny and hardening checks win over allow rules. If no rule matches, the
3737
request is denied.
3838

39+
## Host Wildcards
40+
41+
Network endpoint `host` patterns accept a `*` wildcard inside the first DNS
42+
label only. The OPA runtime matches with a `.` label boundary, so a wildcard
43+
never spans dots. The validator enforces the same boundary so that policy load
44+
fails fast instead of silently mismatching at the proxy.
45+
46+
| Pattern | Accepted | Example match | Notes |
47+
|---|---|---|---|
48+
| `*.example.com` | Yes | `api.example.com` | Single first label of any value. |
49+
| `**.example.com` | Yes | `a.b.example.com` | Recursive wildcard as the entire first label. |
50+
| `*-aiplatform.googleapis.com` | Yes | `us-central1-aiplatform.googleapis.com` | Intra-label wildcard inside the first DNS label. |
51+
| `*` or `**` | No | — | Matches every host. |
52+
| `*.com`, `**.com` | No | — | TLD wildcards (`labels <= 2`). |
53+
| `foo.*.example.com` | No | — | Wildcard outside the first DNS label. |
54+
| `foo**.example.com` | No | — | Recursive `**` mixed inside a label; allowed only as the entire first label. |
55+
56+
Validation rejects the disallowed patterns at policy load time with a message
57+
that names the offending host. Exact hosts and IP addresses do not use this
58+
path.
59+
3960
## TLS and L7 Inspection
4061

4162
For HTTP endpoints that need request-level controls, the proxy can terminate TLS

‎crates/openshell-sandbox/src/opa.rs‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3739,6 +3739,69 @@ network_policies:
37393739
assert!(!decision.allowed, "Wildcard host on wrong port should deny");
37403740
}
37413741

3742+
#[test]
3743+
fn wildcard_host_intra_label_matches() {
3744+
// First-label intra-label wildcard: `*` matches the variable prefix
3745+
// within a single DNS label. Locks validator/runtime alignment for
3746+
// the pattern accepted by `validate_host_wildcard`.
3747+
let data = r#"
3748+
network_policies:
3749+
intra_label:
3750+
name: intra_label
3751+
endpoints:
3752+
- { host: "*-aiplatform.googleapis.com", port: 443 }
3753+
binaries:
3754+
- { path: /usr/bin/curl }
3755+
"#;
3756+
let engine = OpaEngine::from_strings(TEST_POLICY, data).unwrap();
3757+
let input = NetworkInput {
3758+
host: "us-central1-aiplatform.googleapis.com".into(),
3759+
port: 443,
3760+
binary_path: PathBuf::from("/usr/bin/curl"),
3761+
binary_sha256: "unused".into(),
3762+
ancestors: vec![],
3763+
cmdline_paths: vec![],
3764+
};
3765+
let decision = engine.evaluate_network(&input).unwrap();
3766+
assert!(
3767+
decision.allowed,
3768+
"*-aiplatform.googleapis.com should match us-central1-aiplatform.googleapis.com: {}",
3769+
decision.reason
3770+
);
3771+
}
3772+
3773+
#[test]
3774+
fn wildcard_host_intra_label_does_not_cross_dot() {
3775+
// `glob.match(..., ["."])` treats `.` as a label boundary that `*`
3776+
// cannot cross. `*-aiplatform.googleapis.com` must not match a host
3777+
// whose first label is `us-central1` and where `aiplatform` is a
3778+
// separate label.
3779+
let data = r#"
3780+
network_policies:
3781+
intra_label:
3782+
name: intra_label
3783+
endpoints:
3784+
- { host: "*-aiplatform.googleapis.com", port: 443 }
3785+
binaries:
3786+
- { path: /usr/bin/curl }
3787+
"#;
3788+
let engine = OpaEngine::from_strings(TEST_POLICY, data).unwrap();
3789+
let input = NetworkInput {
3790+
host: "us-central1.aiplatform.googleapis.com".into(),
3791+
port: 443,
3792+
binary_path: PathBuf::from("/usr/bin/curl"),
3793+
binary_sha256: "unused".into(),
3794+
ancestors: vec![],
3795+
cmdline_paths: vec![],
3796+
};
3797+
let decision = engine.evaluate_network(&input).unwrap();
3798+
assert!(
3799+
!decision.allowed,
3800+
"*-aiplatform.googleapis.com must NOT match us-central1.aiplatform.googleapis.com \
3801+
(would cross a `.` boundary)"
3802+
);
3803+
}
3804+
37423805
#[test]
37433806
fn wildcard_host_multi_port() {
37443807
let data = r#"

‎docs/reference/policy-schema.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ Each endpoint defines a reachable destination and optional inspection rules.
152152

153153
| Field | Type | Required | Description |
154154
|---|---|---|---|
155-
| `host` | string | Yes | Hostname or IP address. Supports wildcards: `*.example.com` matches any subdomain. |
155+
| `host` | string | Yes | Hostname or IP address. Supports a `*` wildcard inside the first DNS label only: `*.example.com`, `**.example.com`, and intra-label patterns like `*-aiplatform.googleapis.com` are accepted; bare `*`/`**`, TLD wildcards (`*.com`), and wildcards outside the first label are rejected at load time. |
156156
| `port` | integer | Yes | TCP port number. |
157157
| `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`. |
158158
| `protocol` | string | No | Set to `rest` for HTTP method/path inspection or `graphql` for GraphQL operation inspection. Omit for TCP passthrough. |

0 commit comments

Comments
 (0)