rfc-0012: Isolation Backend interface

[jganoff]

Note

This RFC is a draft and open for feedback.

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.

[russellb]

Concrete grounding for this row: the cni-sidecar topology (#2606) implements exactly this shape — a node CNI DaemonSet establishes standing enforcement (egress-redirect nftables in the pod netns at CNI ADD), while network mediation stays co-located as the in-pod network sidecar. Might be worth citing it here the way the two rows above cite #2076, since it's the first real instance of "a node helper establishes some controls" and it surfaces the confirmation/loss-detection questions I've flagged on the README.

[russellb]

This is the one place cni-sidecar can't satisfy as written. The standing enforcement is node-installed nft/iptables state, and reading it back to detect loss requires NET_ADMIN — which this topology deliberately withholds from the pod. We tried an in-pod self-verify in #2606 and had to drop it: nft list/iptables -L return EPERM in the unprivileged sidecar, which fail-closed the check and crash-looped every healthy pod. (Your own codebase-grounding.md — the "reading it back does not prove 'only the proxy can egress'" row — makes a related point that reading rules is weak evidence anyway.)

For a node-delegated backend, detection and termination realistically live out of pod, on the node helper's reconcile cadence. Could the invariant explicitly allow, for delegated backends: (a) loss-detection that is periodic with a documented bound rather than in-band/instantaneous, and (b) termination effected by a control-plane or node actor rather than the in-pod supervisor? As written, the RFC's flagship "delegated backend" example can't claim conformance.

[russellb]

Same root issue as invariant 6, at confirmation time. cni-sidecar confirms standing enforcement via an out-of-pod gate (the CNI labels its node openshell.ai/cni-ready, the gateway pins a required nodeAffinity, and a wait-cni-coverage init container blocks the pod until the node acks coverage) — the in-pod component cannot self-confirm. Line 187 ("how a backend confirms its Ready conditions is implementation-specific") plus the helper-coordination language mostly covers this in spirit, but the normative "the backend has confirmed" reads in-band. A sentence explicitly blessing a provisioning-time / out-of-pod confirmation signal would remove the ambiguity.

[russellb]

Worth acknowledging cluster-scoped gating for node backends. cni-sidecar's node component is shared infrastructure whose "is this pod enforced at all" decision depends on cluster-scoped namespace registration — pods in unregistered namespaces are passed through without enforcement (a deliberate blast-radius guard). The per-netns rules keep invariant 5's per-boundary isolation intact, but a strict reading of "no silent weakening" collides with that pass-through unless an admitted cni-sidecar sandbox is guaranteed to be in a registered namespace before it runs. We hold that coupling (registration marker + wait-cni-coverage), so we stay conformant — but the contract should note that a delegated node backend may gate enforcement on cluster-scoped registration, with conformance resting on the admission↔registration coupling.

[russellb]

Minor modeling note for delegated topologies: cni-sidecar runs two in-pod processes — the network sidecar (network mediation + policy authority + gateway session) and the process-supervisor (network-only; owns start_agent/exec), coupled over a control socket so they live and die together. That maps fine onto the RFC's NetworkMediationIngress vs RunningBoundary split as one logical supervisor composed of two processes, but the singular "one logical supervisor" phrasing invites the question. A clause confirming the logical supervisor may span multiple coupled processes would help.