docs(rfc): add Policy subsystem (RFC 0005)#1728
Conversation
Proposes a Policy subsystem on the gateway that delegates where policy comes from to a driver: a first-party builtin driver (the default, in-process store-backed path) or a third-party driver over a PolicyDriver gRPC contract. Third-party drivers follow the out-of-tree model — operator-run, with the gateway connecting to a provided UDS. The change is additive and opt-in per deployment. Signed-off-by: Divya Vavili <dvavili@nvidia.com>
dvavili
requested review from
a team,
derekwaynecarr,
maxamillion and
mrunalp
as code owners
|
All contributors have signed the DCO ✍️ ✅ |
|
I have read the DCO document and I hereby sign the DCO. |
|
recheck |
|
I have read the Contributor Agreement including DCO and I hereby sign the Contributor Agreement and DCO |
| - **Handle.** The opaque token a driver returns when it binds a runtime context; the per-sandbox reference for fetching the projection, releasing state, and audit correlation. | ||
| - **Surface (`surface_id`).** The policy schema a projection targets, e.g. `openshell.sandbox.v1`. | ||
|
|
||
| ### The `PolicyDriver` contract |
There was a problem hiding this comment.
This might want to extend to Provider Profiles as well (https://docs.nvidia.com/openshell/latest/sandboxes/providers-v2). Provider profiles embed network policies so when v2 is enabled, the effective policy for any given sandbox is constructed JIT when the sandbox requests it. So I'd imagine this contract should extend to also support provider profile signing as well.
|
|
||
| ### The `PolicyDriver` contract | ||
|
|
||
| A third-party driver implements one gRPC service — `PolicyDriver` (versioned `openshell.policy.driver.v1`), the same kind of contract compute, credentials, and identity drivers already define ([RFC 0001](https://github.com/NVIDIA/OpenShell/blob/8bf667f377d567e4c7638db8ca70ce13ecdeb0da/rfc/0001-core-architecture/README.md)). Four RPCs: |
There was a problem hiding this comment.
If I understand this RFC correctly, policies bodies are no longer stored on the gateway. Is that right?
If so, is there a way to keep the policy itself stored on the gateway, but then delegate signing and attestation infrastructure to some PolicySigningDriver/PolicyGovernanceDriver instead?
I think that is going to be a cleaner boundary for the driver interface and better match how our other drivers work.
| Introduce a **Policy subsystem** on the gateway. Like compute, credentials, and identity ([RFC 0001](https://github.com/NVIDIA/OpenShell/blob/8bf667f377d567e4c7638db8ca70ce13ecdeb0da/rfc/0001-core-architecture/README.md)), the subsystem owns the policy semantics and delegates *where policy comes from* to a **driver**: | ||
|
|
||
| - A **first-party `builtin` driver** *(the default, used when no driver socket is configured)* — today's store-backed path, unchanged: ships with the gateway and is satisfied in-process. | ||
| - A **third-party driver** implements the `PolicyDriver` gRPC contract and runs as an **operator-managed process**; the gateway connects to a UDS the operator provides. The gateway does not launch or supervise it — the same out-of-tree model proposed for compute drivers in [#1703](https://github.com/NVIDIA/OpenShell/pull/1703) (the `--compute-driver-socket` flag). How the driver is packaged, where it sources policy (including fronting a remote backend), and how its socket is secured are all the operator's, invisible to the gateway. |
There was a problem hiding this comment.
Policy (and by extension, provider v2 profiles) objects in our database are constructed in a very specific way for sandbox operations. The gateway does JIT construction of a sandbox's effective running policy, we have our policy prover also that needs JIT access to policy data as well.
I would lean towards ensuring the OpenShell db is still the system of record for all sandbox operations.
Other patterns to explore:
- Could the third party service replicate approved objects into OpenShell so all operations still use the OpenShell DB?
- Is there a more narrow hook we can put into OpenShell specific around signature attestation? So you could still use existing OpenShell APIs to import policies and provider profiles but the Gateway (or Driver) can do the signature verification.
There was a problem hiding this comment.
Now I'm wondering if Gateway configuration would also need to be something that potentially needs to governed, especially with certain knobs for volume mounts. Thoughts @drew?
There was a problem hiding this comment.
Definitely. I think we'll need to enforce specific gateway settings from some sort of enterprise/it managed authority.
| Policy in OpenShell is store-backed and gateway-owned: user-authored, validated, persisted, and composed inside the gateway. That works when one party owns both OpenShell and policy. Some policy ecosystems do not fit that shape — **enterprise deployment models in particular require strict attestation and independent auditability**: | ||
|
|
||
| - Policy is authored and signed by a central authority in a separate trust domain. | ||
| - What a sandbox enforces must be tamper-evident even against a compromised gateway. |
There was a problem hiding this comment.
Can you expand on what these threat vectors look like. Some examples would be good. How is a gateway compromised, and what can an attacker do once the gateway is owned? What does a policy provider outside the gateway trust domain protect against.
4 participants
Summary
Proposes RFC 0005 — Policy Subsystem: promote policy to a first-class gateway subsystem that delegates where policy comes from to a driver, mirroring the subsystem-and-driver model RFC 0001 defines for the gateway (and implements today for compute).
builtindriver (the default) — today's in-process, store-backed policy path, unchanged.PolicyDrivergRPC contract and runs as an operator-managed process the gateway connects to over a UDS. The gateway does not launch or supervise it.The change is additive and opt-in per deployment. Enforcement stays the gateway's: projections are verified against a trust store (authentic), admitted all-or-nothing (complete), and gated against mutation (unaltered). A driver's internals — packaging, policy sourcing, remote backends, trust establishment — are out of scope; OpenShell consumes only the projected
SandboxPolicy.Scoping issue: #1713. Related: RFC 0001, RFC 0002, #1703.
DCO: the commit is signed off.