docs(rfc): add Policy subsystem (RFC 0005)

[dvavili]

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).

• builtin driver (the default) — today's in-process, store-backed policy path, unchanged.
• Third-party driver — implements a PolicyDriver gRPC 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.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[github-actions]

All contributors have signed the DCO ✍️ ✅
_{Posted by the DCO Assistant Lite bot.}

[dvavili]

I have read the DCO document and I hereby sign the DCO.

[dvavili]

recheck

[dvavili]

I have read the Contributor Agreement including DCO and I hereby sign the Contributor Agreement and DCO

[drew]

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.

[dvavili]

The comment in the earlier thread here should apply for this case as well. The hook mechanism should be agnostic to the requirements of the enterprise and clean separation as discussed.

[johntmyers]

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.

[johntmyers]

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?

[drew]

Definitely. I think we'll need to enforce specific gateway settings from some sort of enterprise/it managed authority.

[dvavili]

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.

We are narrowing in on this design to have a hook to GetPolicy from any Openshell component that requires it. Note that policy signature verification is just one use-case that this model unlocks. We should keep the requirements of the external Policy Provider service out of gateway. So, instead of thinking it as a hook to sign/attest the policy - it's a general adapter that fetches an enterprise policy for the sandbox. What the adapter does - policy-sign-verification, support multi-tenancy, and so on - can then be catered to the requirements of the enterprise itself and not as an opinionated flow in Openshell.

[dvavili]

Regarding the Gateway configuration being something that needs to governed - it's a good point. I'd imagine that this is something that an out-of-band operator responsible for the deployment can leverage to pull gateway's config from a governed source. We could certainly use a similar hook mechanism to fetch the config from a governed location.

[drew]

@dvavili, I'd like to clarify this

So, instead of thinking it as a hook to sign/attest the policy - it's a general adapter that fetches an enterprise policy for the sandbox. What the adapter does - policy-sign-verification, support multi-tenancy, and so on - can then be catered to the requirements of the enterprise itself and not as an opinionated flow in Openshell.

In our conversation earlier today, you said that OpenShell itself would have to verify the policy signature using the signing_key_id. Are you saying that's not the case, and the general adapter would do this instead?

[drew]

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.