mjamivandJohn Myers
528fb29147
* fix(sandbox): allow first-label L7 host wildcards * 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. * chore: update mise lockfile * test(server): tolerate serialized inference upserts --------- Co-authored-by: John Myers <9696606+johntmyers@users.noreply.github.com>
5.7 KiB
Security Policy
OpenShell policy defines what a sandboxed agent can access. The policy is enforced inside each sandbox by kernel controls, process setup, and the local policy proxy. The gateway stores and delivers policy, but it does not make per-request egress decisions.
For the field-by-field YAML reference, use Policy Schema Reference.
Policy Areas
| Area | Enforcement |
|---|---|
| Filesystem | Landlock restricts read-only and read-write paths. |
| Process | The supervisor launches the agent as an unprivileged user with reduced capabilities. |
| Network | The proxy evaluates destination, port, calling binary, and optional L7 rules. |
| Inference | inference.local is configured through gateway inference settings, not OPA network policy. |
| Runtime settings | Typed settings are delivered with policy and can be global or sandbox scoped. |
Filesystem and process policy are startup-time controls. Network policy is dynamic and can be hot-reloaded when the new policy validates successfully.
Network Decisions
Ordinary network traffic follows this order:
- Force traffic through the sandbox proxy with namespace and seccomp controls.
- Identify the calling binary and compare its trusted identity.
- Reject hard-blocked destinations, including unsafe internal IP ranges unless explicitly allowed.
- Match the destination and binary against network policy blocks.
- Apply optional HTTP/L7 rules for endpoints that enable protocol inspection.
- Allow, deny, audit, or log according to the matched policy.
Explicit deny and hardening checks win over allow rules. If no rule matches, the request is denied.
Host Wildcards
Network endpoint host patterns accept a * wildcard inside the first DNS
label only. The OPA runtime matches with a . label boundary, so a wildcard
never spans dots. The validator enforces the same boundary so that policy load
fails fast instead of silently mismatching at the proxy.
| Pattern | Accepted | Example match | Notes |
|---|---|---|---|
*.example.com |
Yes | api.example.com |
Single first label of any value. |
**.example.com |
Yes | a.b.example.com |
Recursive wildcard as the entire first label. |
*-aiplatform.googleapis.com |
Yes | us-central1-aiplatform.googleapis.com |
Intra-label wildcard inside the first DNS label. |
* or ** |
No | — | Matches every host. |
*.com, **.com |
No | — | TLD wildcards (labels <= 2). |
foo.*.example.com |
No | — | Wildcard outside the first DNS label. |
foo**.example.com |
No | — | Recursive ** mixed inside a label; allowed only as the entire first label. |
Validation rejects the disallowed patterns at policy load time with a message that names the offending host. Exact hosts and IP addresses do not use this path.
TLS and L7 Inspection
For HTTP endpoints that need request-level controls, the proxy can terminate TLS with the sandbox's ephemeral CA and inspect method/path or protocol-specific metadata before forwarding. The proxy also supports credential injection on terminated HTTP streams when policy allows the endpoint.
Raw streams and long-lived response bodies are connection scoped. Policy
reloads affect the next connection or the next parsed HTTP request; they do not
rewrite bytes already being relayed. HTTP upgrades switch to raw relay by
default. A protocol: rest endpoint can opt in to
websocket_credential_rewrite for client-to-server WebSocket text messages
after an allowed 101 upgrade; server-to-client traffic and all other upgraded
protocols remain raw passthrough.
Live Updates
The gateway stores policy revisions and exposes effective sandbox configuration. The supervisor polls for config revisions and attempts to load new dynamic policy into the in-process OPA engine.
If a new policy fails validation or loading, the supervisor reports the failure and keeps the last-known-good policy. Static controls, such as filesystem allowlists and process identity, require a new sandbox because they are applied before the child process starts.
Gateway-global policy can override sandbox-scoped policy. Use it sparingly because it changes the effective access model for every sandbox on the gateway.
Policy Advisor
The policy advisor pipeline turns observed denials into draft policy recommendations:
- The sandbox aggregates denied network events.
- A mechanistic mapper proposes minimal endpoint, binary, or rule additions.
- The gateway validates and stores draft recommendations.
- A human or admin workflow approves or rejects drafts.
- Approved drafts merge into the target sandbox policy.
Proposals intentionally omit allowed_ips. If a proposed rule targets a host
that resolves to a private IP, the proxy's runtime SSRF classification blocks
the connection. The operator must then add an explicit allowed_ips entry to
permit it — a two-step flow that keeps SSRF protection on by default.
The advisor should propose narrow additions and preserve explicit-deny behavior. It is a workflow aid, not an automatic permission grant.
Security Logging
Sandbox events that represent observable behavior use OCSF structured logs:
| Event | OCSF class |
|---|---|
| Network and proxy decisions | Network or HTTP activity |
| SSH authentication and relay activity | SSH activity |
| Process lifecycle | Process activity |
| Policy and settings changes | Configuration state change |
| Security findings | Detection finding |
Use plain tracing for internal plumbing such as retries, debug state, and intermediate steps where the final observable event is logged separately.
Never log secrets, credentials, bearer tokens, or query parameters in OCSF messages. OCSF JSONL output may be shipped to external systems.