rfc-0012: Isolation Backend interface

[jganoff]

Summary

Adds RFC 0012 for the Isolation Backend, a proposed pluggable component that establishes and enforces an agent's isolation boundary.

OpenShell runs untrusted agent code inside an isolation boundary: the network, filesystem, syscall, and identity constraints that decide what the agent can reach and what can reach it. Building that boundary takes privilege, and today that privilege lives inside the agent's own container, beside the code it is meant to confine. That blocks restricted and multi-tenant clusters, whose Pod Security Standards reject the capability set the in-pod setup needs.

This RFC proposes making the boundary a pluggable component, the Isolation Backend, that separates the privileged work that builds the boundary from the supervisor that operates it as the policy authority (proxy, policy, audit) and the agent's only egress. The supervisor drives any backend through one runtime contract, so the privileged setup can move out of the agent's container (a sidecar, a separate pod, a microVM, a node component, and eventually outside the agent's kernel) without changing how the supervisor operates it. Each placement is a new backend, not a new supervisor.

Feedback especially welcome on: the lifecycle state boundaries and what each one guarantees, the provenance-based identity and attestation model, and the resource-binding split between the backend and the compute driver.

Related to #1737.

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[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.}

[jganoff]

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

[drew]

I'd be interested to see if we can support MXC using this interface, #2071.

[ericcurtin]

@maxamillion @derekwaynecarr @mrunalp thoughts?

[jganoff]

@TaylorMutch thanks for the review and discussion last week. Based on our discussion, I've made the following changes:

• Introduced topology nomenclature to align with how we've been talking about this in other conversations
• Simplified the explanation in the proposal section
• Clarified binary identity
• Simplified the initial contract to require the minimal interface necessary to satisfy all known topologies
• Confirmed this will work with the proposed mxc (RFC 0013) proposal: docs(rfc): add RFC 0013 native Windows support via MXC #2071 (cc @drew )
• Confirmed this will work with warm pooling (though I haven't built a POC for it yet)

I've also updated my POC implementation for the current in-pod supervisor topology to align with these updates.

Please let me know what you all think!

[github-actions]

This pull request has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity.

[russellb]

Reviewed this against the in-progress cni-sidecar supervisor topology (#2606), which moves nftables installation from an in-pod NET_ADMIN init container to a node CNI DaemonSet. It lines up well with this RFC — it's a concrete instance of the "Delegated backend components" row, and the direction (privilege out of the agent container, one supervisor operating the boundary) is exactly what we built toward.

Most of my notes are inline. The substantive one is invariant 6: as written it assumes the backend can detect standing-enforcement loss at runtime, which a node-delegated backend structurally can't do from inside the pod. I think the contract needs a small amount of give for delegated backends there and in the Ready/confirmation wording; everything else is either a clean fit or a mechanical reshape on our side.

[jganoff]

@drew @russellb I pushed commit 6f892f5 with a broader revision based on the review feedback and subsequent design discussions. The update intends to simplify the mental model and normative contract, clarify the responsibilities of the logical supervisor and isolation backend, and explicitly covers delegated and multi-process topologies. It also aligns descriptor, lifecycle, network-mediation, binary-identity, and failure semantics throughout.

Please let me know how your testing goes with this and if there's any other changes you'd like to see.

[jganoff]

I realized I had inadvertently changed the contract for how binary identity is resolved, and that shouldn't be part of RFC 0012. 86dc3f2 preserves RFC 0002's binary gating baseline while allowing future backends to provide stronger identity resolution without changing the contract.

[mayawang]

We're planning to implement RFC 12 for Agent Substrate, which lands as a delegated backend: a thin in-process implementation carrying its own transport, with delegation staying topology-private.

My question is what conformance can cover for that shape. It's specified per backend and topology, so a delegated topology does get tested. What I can't tell is how much of its behavior the suite reaches. If the transport inside the topology is backend-private, the tests exercise the in-process trait while the load-bearing part happens over a link they never cross, and two delegated backends could pass the same suite while behaving differently in ways it stays silent on.

So the concrete question: does conformance for a delegated topology stop at the trait boundary, or is there a point where the delegated transport becomes versioned contract surface? The alternatives section says

A transport-bearing surface is not precluded: it is versioned contract surface, added when a concrete delegated backend requires it.

We may well be that concrete backend, so it would help to know what "requires" means in practice: a backend that can't be built without it, or one where conformance coverage argues for it. If it's the second, we can bring the specifics from our side rather than leave it abstract.

Happy to write it up as a proposal if that's more useful than a question.

[drew]

We're planning to implement RFC 12 for Agent Substrate, which lands as a delegated backend: a thin in-process implementation carrying its own transport, with delegation staying topology-private.

My question is what conformance can cover for that shape. It's specified per backend and topology, so a delegated topology does get tested. What I can't tell is how much of its behavior the suite reaches. If the transport inside the topology is backend-private, the tests exercise the in-process trait while the load-bearing part happens over a link they never cross, and two delegated backends could pass the same suite while behaving differently in ways it stays silent on.

So the concrete question: does conformance for a delegated topology stop at the trait boundary, or is there a point where the delegated transport becomes versioned contract surface? The alternatives section says

A transport-bearing surface is not precluded: it is versioned contract surface, added when a concrete delegated backend requires it.

We may well be that concrete backend, so it would help to know what "requires" means in practice: a backend that can't be built without it, or one where conformance coverage argues for it. If it's the second, we can bring the specifics from our side rather than leave it abstract.

Happy to write it up as a proposal if that's more useful than a question.

@mayawang if it's not too much trouble a proposal would be great. We have an initial prototype of this RFC starting here, #3151. We could quickly prototype your proposal against that PR to make sure we have everything we need in the interface.

You might also be interested in this doc, https://docs.google.com/document/d/11iR15xUgncckT50aBsDQgDVfCWrUU3nIh6Woc8IYaxI/edit?tab=t.0#heading=h.bwtw9rv4ec9q. We discussed this at our last community call and it outlines how we want to think about a concrete implementation (#3151) of the RFC for our existing drivers.

We also have an initial set of conformance tests here, https://github.com/NVIDIA/OpenShell/tree/main/crates/openshell-conformance. Our conformance tests will let you standup a OpenShell deployment in any specific configuration. Once that deployment is available we can run tests against that configuration. I would expect this to be a good starting point to ensure that the substrate implementation is conformant.

If you notice anything missing in the conformance tests we should be able to include additional tests as well.

[jganoff]

Thanks, @drew and @mayawang. I removed the implementation plan and codebase grounding, renamed the forwarding primitive to BoundaryLoopbackConnector, and clarified that conformance tests exercise the deployed topology, including delegated components and their transport. Let me know if that addresses the concern @mayawang.

I'd like to leave the TCP/DNS interface details open for implementation work (see comment above).

[mayawang]

Thanks, @drew and @mayawang. I removed the implementation plan and codebase grounding, renamed the forwarding primitive to BoundaryLoopbackConnector, and clarified that conformance tests exercise the deployed topology, including delegated components and their transport. Let me know if that addresses the concern @mayawang.

I'd like to leave the TCP/DNS interface details open for implementation work (see comment above).

Yes, that covers it. "Exercises each backend in its deployed topology, including delegated components and their transport" is the part I couldn't tell from the earlier text, and it settles the question: the suite crosses the delegated link, so what's left is which behaviors it asserts rather than where it stops. Thanks for making it explicit.

No view from me on the TCP/DNS lanes. Leaving them to implementation work seems reasonable.

One thing I'll take to #2941 rather than here, flagging it so it isn't a surprise. Our boundary is a gVisor sandbox, and SandboxConfirmEvidence::validate in the interface crate requires seccomp user notification plus a Landlock ABI, neither of which the sentry implements, so we can't reach Ready regardless of what we build. Nothing in the merged RFC asks for either, and the kernel-relationship table already contemplates a userspace application kernel, so I read it as a mismatch in the crate rather than anything in your text. Drew offered to prototype a proposal against #3151, so I'll write it up there.