Skip to content

Commit 0cd2922

Browse files
committed
test(policy): add managed maximum golden flow
Signed-off-by: Alexander Watson <[email protected]>
1 parent a2e1af5 commit 0cd2922

11 files changed

Lines changed: 466 additions & 21 deletions

File tree

‎architecture/security-policy.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,32 @@ before the child process starts.
9696
Gateway-global policy can override sandbox-scoped policy. Use it sparingly
9797
because it changes the effective access model for every sandbox on the gateway.
9898

99+
## Managed Maximum
100+
101+
A gateway can own one optional managed maximum policy. The maximum is a ceiling,
102+
not an active sandbox policy: each sandbox starts with a narrower base policy,
103+
and the gateway proves the fully composed base and provider-derived policy before
104+
creation or any authority-changing update. With no maximum configured, policy
105+
creation, updates, providers, and proposals keep their existing unmanaged behavior.
106+
107+
The maximum extends the normal policy YAML with an ID, version, allowed/default
108+
`ask` or `auto` modes, and optional `review.required` annotations. The same
109+
admission operation protects sandbox creation, provider attachment, direct policy
110+
updates, and proposal merges. The initial implementation checks filesystem paths
111+
plus L4 and REST network authority. Explicit denies take precedence; other
112+
protocols and unsupported authority fields fail closed. Providers without a
113+
resolvable policy profile also fail closed because their credential-bearing
114+
reach cannot be included in the proof. Managed maximums initially require
115+
single-replica SQLite storage; PostgreSQL/HA needs database-backed coordination
116+
before it can preserve the proof-to-commit boundary across gateway replicas.
117+
118+
The sandbox's selected permission mode is fixed at creation. `ask` holds new
119+
agent-proposed authority for review. `auto` applies only the requested delta that
120+
fits the maximum's auto-eligible region; review-marked authority remains pending.
121+
Authenticated direct edits are approval of that exact edit but remain bounded.
122+
Every merge recomputes the candidate from live policy and provider state before
123+
persistence, so a stored proposal or approval is evidence rather than authority.
124+
99125
## Policy Advisor
100126

101127
The policy advisor pipeline turns observed denials into draft policy
@@ -123,6 +149,11 @@ through the proposal loop instead of treating the denial as terminal.
123149
never `safe`. The opt-in gate preserves OpenShell's default-deny
124150
posture: with no setting at either scope, every proposal lands in
125151
`pending` for human review, even when the prover sees no findings.
152+
For a sandbox governed by a managed maximum, its immutable `ask` or `auto`
153+
permission mode replaces this unmanaged approval gate. Outside or unsupported
154+
proposals are rejected before persistence, review-marked proposals stay
155+
pending, and eligible `auto` proposals are revalidated against live state at
156+
merge time.
126157
4. **Implicit supersede.** On any successful submission, the gateway scans
127158
the sandbox's pending chunks for matches on `(host, port, binary)` and
128159
auto-rejects the older ones with reason `"superseded by chunk X"`. This

‎docs/reference/policy-schema.mdx‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,36 @@ network_policies: { ... }
3232

3333
Static fields are set at sandbox creation time. Changing them requires destroying and recreating the sandbox. Dynamic fields can be updated on a running sandbox with `openshell policy update` for incremental merges or `openshell policy set` for full replacement, and take effect without restarting.
3434

35+
## Managed Maximum Extensions
36+
37+
`openshell policy maximum set` accepts the same policy shape with one additional top-level
38+
`metadata` block. These fields identify a gateway-owned ceiling and are not valid in ordinary
39+
sandbox policy files.
40+
41+
| Field | Type | Required | Description |
42+
|---|---|---|---|
43+
| `metadata.policy_id` | string | Yes | Stable administrator-chosen identity for the maximum. |
44+
| `metadata.version` | integer | Yes | Positive version. Replacing the same policy ID requires a larger version. |
45+
| `metadata.allowed_modes` | list | Yes | Non-empty set containing `ask`, `auto`, or both. |
46+
| `metadata.default_mode` | string | Yes | Mode used when sandbox creation omits `--permission-mode`; must appear in `allowed_modes`. |
47+
| `metadata.audit_label` | string | No | Operator label copied into managed admission audit events. |
48+
49+
An endpoint or an allow payload can include a managed-only review annotation:
50+
51+
```yaml showLineNumbers={false}
52+
review:
53+
required: true
54+
reason: "write changes external state"
55+
```
56+
57+
Endpoint-level review applies to all authority on that endpoint. Allow-level review applies only to
58+
the matching REST method/path region. Review metadata changes auto-approval eligibility; it does
59+
not remove the authority from the maximum.
60+
61+
The initial managed containment surface models filesystem paths, L4 host/port/binary access, and
62+
REST method/path access. `deny_rules` remove REST authority before containment. GraphQL, MCP, and
63+
other endpoint controls fail closed in managed mode instead of being silently ignored.
64+
3565
## Version
3666

3767
The version field identifies which schema the policy uses:

‎docs/sandboxes/policies.mdx‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,53 @@ User-specified paths in your policy YAML are not pre-filtered. If you list a pat
7373

7474
This distinction means baseline system paths degrade gracefully while user-specified paths surface configuration errors.
7575

76+
## Managed Maximum Policies
77+
78+
A gateway administrator can configure one managed maximum policy that bounds every sandbox on
79+
the gateway. The maximum is a ceiling: it does not become the sandbox's active policy and does not
80+
grant runtime access by itself. OpenShell proves the sandbox policy plus attached provider policy
81+
against the maximum before creation and before any authority-changing update.
82+
83+
Configure the maximum before creating sandboxes:
84+
85+
```shell
86+
openshell policy maximum set --policy ./maximum.yaml --yes
87+
openshell policy maximum get --full
88+
openshell sandbox create --policy ./base.yaml --permission-mode auto
89+
```
90+
91+
The maximum uses normal policy YAML plus a top-level `metadata` block. It can also mark an endpoint
92+
or individual allow rule with `review.required: true`. Its `allowed_modes` and `default_mode` select
93+
how agent proposals inside the boundary behave:
94+
95+
| Mode | Auto-eligible proposal | Review-required proposal | Outside or unsupported proposal |
96+
|---|---|---|---|
97+
| `ask` | Keep pending for a reviewer. | Keep pending for a reviewer. | Reject before persistence. |
98+
| `auto` | Apply after live-state revalidation. | Keep pending for a reviewer. | Reject before persistence. |
99+
100+
An authenticated direct policy edit is approval of that exact change, but it must still fit inside
101+
the maximum. Sandbox creation rejects review-required starting authority. Provider attachment and
102+
provider-derived policy are part of the same composed candidate. Credential values are never
103+
included in decision logs.
104+
105+
The initial managed containment surface supports filesystem paths plus L4 and REST network
106+
authority. Explicit deny rules take precedence. GraphQL, MCP, and endpoint behavior that the
107+
containment prover does not model fail closed in managed mode. Unmanaged gateways keep their
108+
existing behavior. An attached provider must have a resolvable policy profile so the gateway can
109+
include its credential-bearing reach in the proof.
110+
111+
The maximum can be replaced or deleted only when no sandboxes exist, and it cannot coexist with a
112+
gateway-global policy override. This initial implementation requires single-replica SQLite storage;
113+
the gateway rejects managed maximum configuration with PostgreSQL/HA storage until admission uses
114+
database-backed coordination:
115+
116+
```shell
117+
openshell policy maximum delete --yes
118+
```
119+
120+
See the runnable [managed maximum examples](https://github.com/NVIDIA/OpenShell/tree/main/examples/managed-maximum-policies)
121+
for REST read-auto/write-review behavior.
122+
76123
## Apply a Custom Policy
77124

78125
Pass a policy YAML file when creating the sandbox:

‎docs/sandboxes/policy-advisor.mdx‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,22 @@ Only `manual` and `auto` are accepted; typos like `autom` are rejected at config
8787

8888
**Audit trail.** Every auto-approval emits a `CONFIG:APPROVED` event with `auto=true`, `source=<mechanistic|agent_authored>`, `prover_delta=empty`, and `resolved_from=<gateway|sandbox|default>` so operators can reconstruct why a given approval ran without human review.
8989

90+
### Managed Permission Modes
91+
92+
When the gateway has a [managed maximum policy](/sandboxes/policies#managed-maximum-policies),
93+
`--permission-mode ask|auto` selects the sandbox's immutable managed mode. Omit the flag to use the
94+
maximum's default. This mode replaces `proposal_approval_mode` for that sandbox:
95+
96+
- `ask` keeps every in-boundary authority expansion pending.
97+
- `auto` immediately applies only expansions inside the maximum's auto-eligible region.
98+
- Authority marked `review.required` stays pending in either mode.
99+
- Outside, explicitly denied, or unsupported proposals are returned in `rejection_reasons` and do
100+
not enter the draft queue.
101+
102+
OpenShell reruns containment against the live sandbox policy and provider state immediately before
103+
an auto or human-approved proposal is merged. The stored proposal and earlier decision explain what
104+
happened; they do not authorize a stale candidate.
105+
90106
## How It Works
91107

92108
When policy advisor is enabled, the sandbox supervisor turns on three agent-facing surfaces:
@@ -102,7 +118,7 @@ The loop has seven steps:
102118
2. For inspected REST traffic, OpenShell returns a structured `403` body with fields such as `layer`, `host`, `port`, `binary`, `method`, `path`, `rule_missing`, `agent_guidance`, and `next_steps`.
103119
3. The agent reads the policy advisor skill, inspects the current policy, and optionally reads recent denial log lines.
104120
4. The agent submits one or more `addRule` proposals to `http://policy.local/v1/proposals`.
105-
5. The gateway stores accepted proposals as pending draft chunks for the sandbox and runs the [policy prover](#what-auto-approval-checks) against the proposed delta.
121+
5. The gateway runs admission against the proposed delta. Unmanaged sandboxes store accepted proposals as draft chunks and use the security-finding prover below. Managed sandboxes first reject proposals outside their configured maximum.
106122
6. Under `auto` mode, proposals with an empty prover delta are approved immediately and skipped past human review. Under `manual` mode (the default), every proposal — and under `auto` mode, every proposal with a prover finding — lands in the draft inbox for a developer to approve or reject.
107123
7. The agent waits on `/v1/proposals/{chunk_id}/wait` until a decision is available. Approved proposals hot-reload into the sandbox; rejected proposals return `rejection_reason` and `validation_result` so the agent can revise.
108124

‎e2e/rust/e2e-vm.sh‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -124,8 +124,8 @@ GATEWAY_PID_FILE="${RUN_STATE_DIR}/gateway.pid"
124124
GATEWAY_ARGS_FILE="${RUN_STATE_DIR}/gateway.args"
125125
GATEWAY_CONFIG="${RUN_STATE_DIR}/gateway.toml"
126126
GATEWAY_DB="${RUN_STATE_DIR}/gateway.db"
127-
JWT_DIR="${RUN_STATE_DIR}/jwt"
128127
PKI_DIR="${RUN_STATE_DIR}/pki"
128+
JWT_DIR="${PKI_DIR}/jwt"
129129
GATEWAY_NAME="openshell-e2e-vm-${HOST_PORT}"
130130

131131
# ── Cleanup (trap) ───────────────────────────────────────────────────
@@ -194,7 +194,6 @@ echo "==> Starting openshell-gateway on 127.0.0.1:${HOST_PORT} (state: ${RUN_STA
194194
# host-loopback proxy carries the connection while keeping the endpoint aligned
195195
# with package-managed gateway certificates. gvproxy's bare gateway IP
196196
# (192.168.127.1) does NOT forward arbitrary host ports.
197-
e2e_generate_gateway_jwt "${JWT_DIR}"
198197
e2e_generate_pki "${GATEWAY_BIN}" "${PKI_DIR}"
199198

200199
cat >"${GATEWAY_CONFIG}" <<EOF

0 commit comments

Comments
 (0)