Jordan Ganoff
e61adb3b1f
* docs(rfc): RFC 0012 Isolation Backend interface Introduces RFC 0012, the runtime-selectable Isolation Backend contract: a pluggable component that establishes and enforces an agent's isolation boundary across network, filesystem, syscall, and identity, while the supervisor stays the policy authority (proxy, policy, audit) and the agent's only egress. Includes the supporting topology matrix and codebase-grounding notes. Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): complete RFC 0012 contract detail and corrections Tighten RFC 0012 for review without changing its structure or tone: - Remove the undefined `BoundaryIntent` from `attach`, and state that `claim` is the only transition that binds sandbox identity, policy, agent, and resources; an attached boundary holds no claimed or untrusted workload. - Add the runtime interface definitions (`BoundaryExec`/`ExecSession`, `BoundaryPortForward`, `EventSource`) and their semantics: owned distinct stdio, PTY resize, placement-neutral exit and signals, stable repeated `wait`, validated loopback targets, and single-consumer events. - Make boundary confirmation mandatory (`MUST`) and lifetime-long, and state retry, termination, and cleanup semantics (only attach is auto-retryable; a lost `start_agent` returns the existing process; descendants are owned; `wait_terminated` and an idempotent `shutdown`). - Require trusted admission to supply the expected backend id, contract version, policy digest, and capabilities that a backend cannot lower; add the no-silent-weakening policy invariant; mark `VerifiedBoundaryDescriptor` privately constructed and distinguish envelope from contract version; make `ResourceBinding` driver-issued, bound, and non-wideable. - Make the rollout executable and forbid a silent default backend. topology-matrix: rename "sidecar proxy" to sidecar-assisted (the proxy stays with the supervisor), frame sidecar and node as composite backends, move the single-pod outer sandbox to the shared-kernel cell, and note a node enforcer alone is not `restricted`-compatible. codebase-grounding: re-pin anchors to the RFC's parentba21bb32(driver.rs and proxy.rs line numbers refreshed) and add a permalink base; correct the event wording so a denial carries `Evidence` plus request-specific L7 data. Set state: review and link PR #2048. Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): RFC 0012 cleanup Contract completion: add MediationIngress/MediatedConnection so the proxy receives connections placement-neutrally; complete the runtime types (BoundaryExitStatus/BoundarySignal, BoundaryTerminal::resize, IdentitySource Send+Sync) and a machine-readable BackendErrorKind; name the AdmittedBoundary- Requirements admission block retained by VerifiedBoundaryDescriptor; show claim_id/generation in ClaimContext; require a canonical bounded descriptor encoding; define capability comparison. Mark MediationIngress, the admission block, and claim generation as contract additions the in-pod POC does not yet implement. Security semantics: make confirmation mandatory and lifetime-long, but correct the enforcement model: Landlock/seccomp are monotonic while netns/nftables are mutable, so require the mutation authority fenced from the workload, atomic default-deny updates, and fail-closed on lease loss rather than calling the boundary irreversible. "Confirms effective enforcement", not "reads rules back". Bind Attested identity to sandbox and claim id/generation. Tighten the execution-domain invariant (admission-visible named capability + audit, whole descendant trees). Distinguish structural pre-Running ordering from dynamic post-termination rejection; note adoption must remove legacy bypass paths. Lifecycle: drop the "establishes before supervisor boot" contradiction; add shutdown to the supervisor sequence; rewrite the in-pod migration appendix (policy-free attach, netns/rules at claim/bind, agent().wait(), wait_terminated, idempotent shutdown). The RFC is implemented only after the in-pod backend passes its release gates. Topology: narrow node-enforcer claims to "network-setup capabilities off the pod"; nuance NetworkPolicy (coarse L3/L4 defense in depth, not a proxy replacement); drop the proxy-policy-reprograms-boundary claim; label the containment table a kernel-compromise ceiling. Grounding: re-pin to the RFC's parenta5161d0(process.rs and proxy.rs line numbers refreshed; others unchanged and reverified). Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): simplify isolation backend contract This removes a lot of detail to keep the RFC succinct. * removed POC and intermediate stage references The RFC should describe the end state, and not intermediate milestones or POCs. * revised based on feedback: - 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): update RFC 0012 supporting docs for sidecar topology - Repin codebase-grounding.md to8eacb477(sidecar supervisor topology, #2076); update capabilities line numbers (1534→2538, 1540→2544), init container line numbers (191→423, 993→1506, 1185→2113), and remove the stale "no native sidecars today" claim. Add openshell-network-init and openshell-supervisor-network sidecar entries and expand the rg pattern. - Add Implementation column to topology-matrix.md; mark Co-located/in-pod and Same-pod composite as implemented (original topology and #2076 respectively); remaining patterns noted as proposed. Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): fully reground RFC 0012 codebase references to8eacb477All line numbers and function names verified against the post-sidecar state of the codebase (commit8eacb477, #2076). Changes: - process.rs: ProcessHandle::spawn 440→527, netns param 446→535; drop_privileges call sites 603/700→710/812, enforcement 613/705→721/818-819; enter_netns_and_sandbox now documented at ssh.rs:1245 - CLONE_NEWNET call sites: process.rs:589→695, ssh.rs:619/1186→653/1262, supervisor_session.rs:610→735, netns/mod.rs:363→342 (226 unchanged) - CLONE_NEWNS: was one unshare at :393; now unshare at :449 and a new setns at :480 added for sidecar mount-namespace entry - nft fail-open: line 264→265, return Ok(()) range 272-277→277; note that the sidecar path (netns/mod.rs:477) requires nft and returns an error if absent, fixing the invariant bug for the sidecar topology - nft_ruleset.rs: policy accept 41→53; accept rules 43-49→56-92; reject rules now at 106+ - VM driver MASQUERADE: runtime.rs:417/436→418/437 - Agent command: main.rs:331→601; sleep infinity driver.rs:1886→2937, clarify it is set via SANDBOX_COMMAND env var - OPA evaluation: proxy.rs:1611 / evaluate_opa_tcp renamed to authorize_egress_intent at proxy.rs:1955; NetworkInput built at :2032 - openshell.proto: clarify no lifecycle Attach; note AttachSandboxProvider (provider record attachment, not isolation lifecycle) - README.md appendix: update pinned commit reference a5161d0→8eacb477 Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): address feedback and clean ups Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): preserve binary identity semantics Keep RFC 0012 focused on placing binary-aware enforcement behind the Isolation Backend contract instead of requiring a new connection-initiation capture mechanism. Define identity as trusted resolution for an accepted connection before policy evaluation, retain fail-closed attribution requirements, and document the current authorization-time procfs behavior. This preserves RFC 0002's binary gating baseline while allowing future backends to provide stronger identity resolution without changing the contract. Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com> * docs(rfc): simplify isolation backend proposal Addresses PR feedback: 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. --------- Signed-off-by: Jordan Ganoff <jordan.ganoff@docker.com>
OpenShell RFCs
Substantial changes to OpenShell should be proposed in writing before implementation begins. New features always start as a GitHub issue using the feature request template, not as an RFC pull request. RFCs drive nuanced discussions that need structured iteration, broad stakeholder input, and a durable record of the reasoning beyond what issue comments can fully capture.
An RFC provides a consistent way to collect broad feedback, build consensus, and document the decision for future contributors. An RFC is created only when maintainers decide the originating issue needs that level of design review.
Start with a GitHub issue
Before writing an RFC, you must open a GitHub issue to scope the problem, gauge interest, and get early feedback. For new features, use the feature request template. This helps:
- Validate that the problem is worth solving
- Surface potential concerns early
- Build consensus before investing in a detailed proposal
- Identify the right reviewers and stakeholders
If the ticket shows sufficient interest and maintainers decide the idea needs broad design review, they will ask for an RFC from that issue. Maintainers assign the RFC number and add the needs-rfc label in the issue before the RFC is created, preventing number clashes across branches and making pending RFC work searchable.
RFCs vs other artifacts
OpenShell has several places where design information lives. Use this guide to pick the right one:
| Artifact | Purpose | When to use |
|---|---|---|
| GitHub issue | Track and scope a bug, feature request, or rough idea | Always start here; new features use the feature request template |
Spike issue (create-spike) |
Investigate implementation feasibility for a scoped change | You need to explore the codebase and produce a buildable issue for a specific component or feature |
| RFC | Propose a cross-cutting decision that needs broad consensus | Maintainers requested an RFC from an existing issue and assigned an RFC number |
Architecture doc (architecture/) |
Document how things work today | Living reference material — updated as the system evolves |
The key distinction: spikes investigate whether and how something can be done; RFCs propose that we should do it and seek agreement on the approach. A spike may precede an RFC (to gather data) or follow one (to flesh out implementation details). When an RFC reaches implemented, its relevant content should be folded into the appropriate architecture/ docs so the living reference stays current.
When to use an RFC
Use an RFC when the discussion itself needs structure: multiple rounds of feedback, competing tradeoffs, broad stakeholder input, or a durable design record. If the important context would get lost across issue comments, an RFC is the right tool. The following are examples of when maintainers may ask for one after an issue is opened:
- An architectural or design decision for the platform
- Change to an API or command-line tool
- Change to an internal API or tool
- Add or change a company or team process
- A design for testing
RFCs don't only apply to technical ideas but overall project ideas and processes as well. If you have an idea to improve the way something is being done, you have the power to make your voice heard.
When NOT to use an RFC
Not everything needs an RFC. Skip the RFC process for:
- Bug fixes
- Small feature additions scoped to a single component (use a spike instead)
- Feature requests that can be resolved through the issue, spike, and pull request workflow
- Documentation changes
- Dependency updates
- Refactoring that doesn't change public interfaces
If a change doesn't require cross-team consensus, a GitHub issue or spike issue is the right vehicle.
RFC metadata and state
At the start of every RFC document, we include a brief amount of metadata in YAML front matter:
---
authors:
- "@username"
state: draft
links:
- https://github.com/NVIDIA/OpenShell/issues/456
- https://github.com/NVIDIA/OpenShell/pull/123
---
We track the following metadata:
- authors: The authors (and therefore owners) of an RFC. Listed as GitHub usernames.
- state: Must be one of the states discussed below.
- links: Related PRs or issues. The first link should be the originating issue where maintainers requested the RFC and assigned its number. Add entries as the RFC progresses.
- superseded_by: (optional) For RFCs in the
supersededstate, the RFC number that replaces this one (e.g.,0005).
An RFC can be in one of the following states:
| State | Description |
|---|---|
draft |
The RFC is being written and is not yet ready for formal review. |
review |
Under active discussion in a pull request. |
accepted |
The proposal has been accepted and is ready for implementation. |
rejected |
The proposal was reviewed and declined. |
implemented |
The idea has been entirely implemented. Changes would be infrequent. |
superseded |
Replaced by a newer RFC. The superseded_by field should reference the replacement. |
RFC lifecycle
1. Open a GitHub issue
Start with a GitHub issue. New features must use the feature request template and include enough design context for maintainers and contributors to evaluate the idea. Do not open an RFC PR before an issue exists.
2. Get maintainer confirmation
Maintainers decide from the issue whether an RFC is necessary. If it is, they assign the RFC number in the issue before anyone creates the RFC branch or folder, and add the needs-rfc label to the originating issue so pending RFC work is searchable. Authors should use the assigned number instead of choosing one locally.
3. Create your RFC
Each RFC lives in its own folder:
rfc/NNNN-my-feature/
README.md
(optional: diagrams, images, supporting files)
Where NNNN is the maintainer-assigned RFC number (zero-padded to 4 digits) and my-feature is a short descriptive name. The main proposal goes in README.md so GitHub renders it when browsing the folder.
To start a new RFC, copy the template folder:
cp -r rfc/0000-template rfc/NNNN-my-feature
Fill in the metadata, include the originating issue in links, and start writing. The state should be draft while you're iterating.
4. Open a pull request
When you're ready for feedback, update the state to review and open a pull request. Add the PR link to links in the metadata. Maintainers should add the rfc label to the PR and add it to the RFC board.
The PR is where discussion happens. Anyone subscribed to the repo will get a notification and can read your RFC and provide feedback.
5. Iterate and build consensus
The comments you choose to accept are up to you as the owner of the RFC, but you should remain empathetic in how you engage. For those giving feedback, be sure that all feedback is constructive.
RFCs rarely go through this process unchanged. Make edits as new commits to the PR and leave comments explaining your changes.
6. Merge the pull request
After there has been time for folks to comment, the RFC author requests merge and a maintainer approves and merges. The state should be updated from review to accepted. If the proposal is declined, the state should be set to rejected. The timing is left to the author's discretion. As a guideline, a few business days seems reasonable, but circumstances may dictate a different timeline.
When an RFC is accepted, maintainers should update any RFC board fields that track review state.
In general, RFCs shouldn't be merged if no one else has read or commented on it. If no one is reading your RFC, it's time to explicitly ask someone to give it a read!
7. Implementation
Once an RFC has been entirely implemented, its state should be moved to implemented. This represents ideas that have been fully developed. While discussion on implemented RFCs is permitted, changes would be expected to be infrequent.
Diagrams
When an RFC needs diagrams to illustrate architecture, data flow, or component interactions, use Mermaid diagrams embedded directly in the Markdown. Mermaid renders natively on GitHub and keeps diagrams version-controlled alongside the text.
```mermaid
graph LR
A[Client] --> B[Gateway]
B --> C[Sandbox]
```
Prefer Mermaid over external image files whenever possible. If a diagram is too complex for Mermaid (e.g., detailed UI mockups), commit the image to the RFC's folder alongside its README.md and reference it with a relative path.
Making changes to an RFC
After your RFC has been merged, there is always opportunity to make changes. Open a pull request with the change you would like to make. If you are not the original author, be sure to @ the original authors to make sure they see and approve of the changes.
RFC postponement
Some RFCs are marked rejected when the proposal is declined or when we want neither to think about evaluating the proposal nor about implementing it until some time in the future. Rejected RFCs may be revisited when the time is right.