[vishwa-raman]

Summary

Implements RFC 0020 (#4564): a sandbox policy can be written in Cedar instead of YAML, chosen once per sandbox and enforced by Cedar alone. YAML sandboxes are unchanged. Draft while the RFC is under review; it is otherwise complete and verified.

Cedar comes from ai-openshell/cedar, the project's own Cedar in the OpenShell CNCF workspace, pinned by commit. OpenShell iterates on policy-language features there with the Cedar team (delimited like today, tracked upstream as cedar-policy/rfcs#115), and does not depend on those features reaching the upstream Cedar release.

Related Issue

Closes #4411

Changes

• openshell-policy-cedar-schema and openshell-policy-cedar: the canonical schema, strict validation, load-time analysis (Landlock grants, inspected endpoints and paths, policy DNS eligibility, native TCP, address ranges, binary aliases and globs, query keys), evaluation with audit and staged policies, and the token-grant compiler for provider rules.
• Proto: additive SandboxPolicy fields cedar_policy_source, provider_credential_rules (gateway-managed), and endpoint_settings.
• CLI, gateway, and supervisor: .cedar policies, the --middleware file (middleware, endpoint settings, process identity), one shared validation, format-switch rejection, and a PolicyEngine that is OPA or Cedar; a Cedar sandbox builds no OPA engine and shares only typed Rust data with the YAML path.
• Parity harness pairing YAML and Cedar policies through both engines: 2,909 cases on Linux, 2,904 agreeing, 5 deliberate differences; Cedar versions of every example and e2e policy with POLICY_FORMAT=cedar in their scripts; the e2e/cedar suite and its CI matrix entry.
• Documentation: docs/how-it-works/policies/cedar.mdx, the middleware configuration page, and the crate README.

Testing

• Checks appropriate to the affected code and behavior pass (fmt, clippy -D warnings, cargo deny, mise run pre-commit; unit tests on macOS and Linux; Windows cross-compile of the supervisor network crate; Go SDK CI)
• Unit tests added/updated
• E2E tests added/updated (mise run e2e:cedar, 26 checks)

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (RFC 0020 in docs(rfc): propose Cedar as an alternate sandbox policy language #4564)

🤖 Generated with Claude Code

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

[vishwa-raman]

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

[vishwa-raman]

/ok to test d9df6d3

[vishwa-raman]

/ok to test dd2c70d

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-4565.docs.buildwithfern.com/openshell

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. rust-sdk — No explicit risk acceptance found

raw::proto::SandboxPolicy grew cedar_policy_source, provider_credential_rules, and endpoint_settings, whereas the baseline generated struct ended at network_middlewares.

• Impact: Existing Rust consumers using exhaustive struct literals or patterns for SandboxPolicy no longer compile.
• Action: Defer the fields to a minor train or provide a source-compatible SDK representation and actionable migration guidance for exhaustive literals and patterns.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

2. go-sdk — No explicit risk acceptance found

Zero-valued types.SandboxPolicy JSON gains CedarPolicySource, ProviderCredentialRules, and EndpointSettings because the new exported fields have no omitempty tags.

• Impact: Consumers persisting, snapshotting, or validating encoding/json output receive three unexpected keys even when they do not use Cedar.
• Action: Add json:",omitempty" to the three new curated fields or implement compatible JSON marshaling so omitted Cedar fields preserve baseline output.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

3. typescript-sdk — No explicit risk acceptance found

Regenerating the exported SandboxPolicy type adds required cedarPolicySource, providerCredentialRules, and endpointSettings properties to the baseline six-field message shape.

• Impact: Existing consumers that directly construct object literals typed as the exported SandboxPolicy fail TypeScript compilation until all three properties are supplied.
• Action: Defer the fields to a minor train or export a compatibility SandboxPolicy type with the new members optional from both SDK entry points.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

Review details

• Execution: complete
• Candidate: PR #4565 (876eec79b98c26dee4f4bed7e78ffe84c951d1cb)
• Baseline: c06ba109c63ccc9cdab5c1ad604f208ef5c2f1d7 (c06ba109c63ccc9cdab5c1ad604f208ef5c2f1d7)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[github-actions]

Label test:e2e applied for dd2c70d. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway, sandbox, and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[vishwa-raman]

Compatibility risk acceptance for the SandboxPolicy additions (cedar_policy_source, provider_credential_rules, endpoint_settings):

1. rust-sdk: accepted. The fields are additive proto fields, the evolution pattern proto/README.md prescribes; consumers using exhaustive struct literals or patterns on raw::proto::SandboxPolicy need to add the three fields or use ..Default::default().
2. go-sdk: accepted. The curated domain types carry no JSON tags on any field, so zero-valued output has always listed every field; the three new keys follow that existing shape.
3. typescript-sdk: accepted. The generated SandboxPolicy type gains three required properties, as every additive message field does; consumers constructing literals should spread create(SandboxPolicySchema) or supply the fields.

These fields are the wire representation of RFC 0020 (#4564) and cannot be deferred without deferring the feature.

[vishwa-raman]

/ok to test 55b998e

[vishwa-raman]

/ok to test 486f456

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. rust-sdk — Risk explicitly accepted

raw::proto::SandboxPolicy grew cedar_policy_source, provider_credential_rules, and endpoint_settings; the baseline generated struct ended at network_middlewares.

• Impact: Existing Rust consumers using exhaustive struct literals or patterns for SandboxPolicy no longer compile.

• Action: Material update: the PR author now accepts the risk, but v0.1.5 must defer these fields to v0.2.0 or provide a source-compatible representation and migration guidance.

• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

• Acceptance: comment

2. go-sdk — Risk explicitly accepted

Zero-valued types.SandboxPolicy JSON now includes CedarPolicySource, ProviderCredentialRules, and EndpointSettings because the new exported fields lack omitempty tags.

• Impact: Consumers persisting, snapshotting, or validating encoding/json output receive three new keys even when Cedar is unused.

• Action: Material update: the PR author now accepts the risk, but v0.1.5 must omit zero-valued Cedar fields through omitempty tags or compatible custom JSON marshaling.

• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

• Acceptance: comment

3. typescript-sdk — Risk explicitly accepted

Regenerating the exported SandboxPolicy message adds required cedarPolicySource, providerCredentialRules, and endpointSettings properties to the baseline six-field type.

• Impact: Existing consumers directly constructing object literals typed as SandboxPolicy fail TypeScript compilation until they supply the new properties.

• Action: Material update: the PR author now accepts the risk, but v0.1.5 must defer these fields to v0.2.0 or export a compatibility type with optional new properties and migration guidance.

• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

• Acceptance: comment

Review details

• Execution: complete
• Candidate: PR #4565 (f64069741c9bbdcc8b3856a04ffed5557b82b25e)
• Baseline: b2069a267c7c8c7cb9a8b652792167dab886cd83 (b2069a267c7c8c7cb9a8b652792167dab886cd83)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[vishwa-raman]

/ok to test 4cdee2a

[vishwa-raman]

/ok to test 77f4818

[johnnygreco]

@vishwa-raman — aggregated panel review of commit 77f4818d5c1dbbab3e605f3ffc910f28e008f67b.

I recommend changes before merge and splitting this PR into four PRs. The panel found six code defects and one required documentation update. I verified and deduplicated these through source and caller tracing; the failure scenarios below were not executed locally.

1. Gateway validation can allocate approximately 10 GB from a 200 KB policy.
   Host-overlap analysis allocates a matrix proportional to both hostname lengths before comparing them. Two 100,000-character endpoint literals fit within the gateway’s 262,144-byte policy limit but trigger roughly ten billion Boolean elements. Neither ordinary Cedar endpoint parsing nor the pinned Cedar parser rejects these lengths. A caller authorized to submit sandbox policies could exhaust gateway memory before a sandbox starts. Bound hostname lengths and overlap-analysis work, and use direct comparison for literal hosts. Host-overlap allocation

2. An older gateway silently interprets Cedar policy as YAML.
   The new CLI sends version: 1, with Cedar restrictions carried exclusively in a new protobuf field. A pre-Cedar gateway discards that field and accepts an empty YAML policy. Attached providers then contribute their usual YAML access grants—even when the submitted Cedar policy forbids that access. Previously, the CLI rejected Cedar input. Add fail-closed capability/version negotiation and a mixed-version regression test. The existing stable_placeholder capability check provides a precedent. Cedar policy construction

3. Ordinary resource conditions can bypass GraphQL path restrictions.
   The helper detecting resource.protocol also returns true for resource.port and resource.host: it recursively reaches their underlying resource variable. Consequently, a general REST permit can survive the filtering intended to make a query-only GraphQL path authoritative, allowing mutations. Wildcard-host permits naturally trigger this because they contain host/port conditions. Stop traversal at attribute accesses and add exact-host and wildcard-host regressions. Attribute traversal

4. Cedar loses the sandbox-wide WebSocket buffering limit.
   Each Cedar tunnel receives a fresh assembly budget. YAML shares one budget across tunnels and reloads, limiting concurrent message assemblies to 32. With Cedar, many connections can each buffer fragmented messages up to the per-message limit without contending for that aggregate bound, potentially exhausting supervisor memory. Store one budget on the Cedar engine and clone it across both upgrade paths and reloads. Per-tunnel budget construction

5. Staged policies can deny otherwise allowed traffic.
   Staged evaluation errors propagate after the enforced decision has already allowed a request. Additionally, staged rules contribute query keys to enforcement’s combination budget: adding a staged rule reading two keys can make 65 × 64 values exceed the 4,096-combination limit and deny previously allowed traffic. This contradicts the documented promise that staged policies do not change decisions. Separate enforced query analysis and evaluation from staged diagnostics, preserving the enforced result when staging fails. Staged evaluation

6. Cedar MCP endpoints disappear from connection diagnostics.
   Cedar endpoint configurations lack endpoint_id, so the observer ignores them. Gateway and supervisor inventories also enumerate only network_policies, which valid Cedar policies leave empty. Corresponding YAML endpoints report successful and failed exchanges; Cedar users lose the documented tool-server status and troubleshooting information. Derive consistent endpoint identities and inventories from Cedar inspection metadata across all three layers. Cedar endpoint construction

7. Public agent skills prescribe a broken Cedar editing workflow.
   The CLI skill exports every policy to current-policy.yaml, delegates YAML network_policies generation, then submits that file. Cedar output fails that workflow through parsing or format-switch rejection. Update the CLI and policy-generation skills to preserve the format and handle the separate middleware file. This is a companion update required by AGENTS.md’s Skill Maintenance rule. Existing editing instructions

I recommend this split because the PR combines an existing-engine refactor, a new language implementation, feature activation, and example expansion. Those have different review and rollback boundaries.

PR	Scope	Required validation
1. Shared runtime refactor	Extract endpoint types, policy data, middleware selection, and binary resolution while retaining YAML behavior.	Existing YAML regressions and policy-hash compatibility.
2. Standalone Cedar engine	Schema, validation, analysis, evaluator, provider-rule compiler, dependency pin, and packaging changes. Keep public Cedar submission disabled.	Engine tests, bounded-input checks, and focused semantic regressions.
3. Complete feature integration	Proto/SDK, CLI, gateway validation/composition, supervisor enforcement, filesystem handling, credentials, reload, diagnostics, docs, and skills.	Core parity coverage, Cedar/MCP E2E, mixed-version rejection, and credential attachment/reload tests.
4. Remaining examples	Additional demo conversions, governance smoke support, and example-specific tests.	Relevant example smoke tests and policy comparisons.

PRs 1 and 2 can be reviewed independently; PR 3 depends on both. Keep Cedar acceptance and its complete enforcement path together. Splitting CLI, gateway, and supervisor activation into independently enabled changes would create unsafe intermediate states. Tests needed to establish safe enforcement belong with their implementation.

The verification review also identified two limits worth addressing:

• One wildcard parity fixture pairs wildcard YAML inspection with Cedar inspection of only api.example.com, then probes only that host. Correct the fixture and exercise a second host through the relay. The reported parity count establishes agreement on selected probes.
• The new Cedar E2E creates no attached provider, while credential parity primarily checks owner selection. Add an E2E covering attachment without access, permitted credential injection, denial without injection, and credential reload.

The panel comprised independent reviews of Cedar semantics, runtime enforcement, authoring/control-plane integration, and the full parity/example corpus, followed by an independent semantic recheck. No additional concrete filesystem widening, token-grant authorization defect, or YAML regression survived verification. New-gateway/old-supervisor compatibility remains unverified.

Reviewed head 77f4818d5, against merge base 6546691d5; the recorded main tip was a4c848adb. Reproduce with git diff 6546691d5 77f4818d5. No uncommitted work was included, and the workspace remained unchanged.

Local diff and syntax checks passed. At review time, exact-head branch CI had passed Rust tests on Linux/macOS and Go/TypeScript SDK checks; integration CI had passed Cedar and MCP-Cedar E2E. Other runtime jobs were still running at the last review check. Rust/Cargo was unavailable locally, so the new failure scenarios still need executable regression tests. Review status: findings.

[johnnygreco]

/ok to test cd26841

[johnnygreco]

/ok to test 32c4ff5

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

2. rust-sdk — No explicit risk acceptance found

raw::proto::HealthResponse and GetSandboxConfigRequest gain the public supports_cedar_policy field.

• Impact: Rust consumers using exhaustive literals or patterns for either generated message no longer compile, although generated server traits and ordinary high-level client callers are unchanged.
• Action: Defer these fields to a minor release or provide source-compatible Rust representations with migration guidance for exhaustive construction and matching.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

5. typescript-sdk — No explicit risk acceptance found

The raw generated HealthResponse and GetSandboxConfigRequest types gain the required supportsCedarPolicy property.

• Impact: Direct consumers constructing either exported exact message type fail TypeScript compilation, while RPC callers using MessageInitShape remain unaffected.
• Action: Defer these properties to a minor release or export source-compatible message types with optional additions and migration guidance.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

Review details

• Execution: complete
• Candidate: PR #4565 (7aad01fd8475285aad4133c7f7d1d67562a6613a)
• Baseline: b58e24c9dabd6d4bcf2b7186592d3ad50646541b (b58e24c9dabd6d4bcf2b7186592d3ad50646541b)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[johnnygreco]

/ok to test 3253a33

[johnnygreco]

/ok to test b81bd1e

[github-actions]

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

6. cli — No explicit risk acceptance found

--policy and OPENSHELL_SANDBOX_POLICY previously parsed every path as YAML, but now parse any .cedar filename as Cedar.

• Impact: Existing valid YAML policies named with a .cedar suffix fail Cedar validation during sandbox creation or policy set.
• Action: Keep existing .cedar YAML files on the YAML path and select Cedar explicitly, or defer extension dispatch to a minor release with rename guidance.
• PR: feat(policy): support Cedar as an alternate sandbox policy language #4565

Review details

• Execution: complete
• Candidate: PR #4565 (86ec20ab25128cffd45304d516ad1ba107c9d47c)
• Baseline: b58e24c9dabd6d4bcf2b7186592d3ad50646541b (b58e24c9dabd6d4bcf2b7186592d3ad50646541b)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[johnnygreco]

/ok to test 2995fb5

[vishwa-raman]

/ok to test 1bd37b1