You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 0cd2922
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/reference/policy-schema.mdx
+30Lines changed: 30 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -32,6 +32,36 @@ network_policies: { ... }
32
32
33
33
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.
34
34
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
+
35
65
## Version
36
66
37
67
The version field identifies which schema the policy uses:
|`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
+
76
123
## Apply a Custom Policy
77
124
78
125
Pass a policy YAML file when creating the sandbox:
Copy file name to clipboardExpand all lines: docs/sandboxes/policy-advisor.mdx
+17-1Lines changed: 17 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -87,6 +87,22 @@ Only `manual` and `auto` are accepted; typos like `autom` are rejected at config
87
87
88
88
**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.
89
89
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
+
90
106
## How It Works
91
107
92
108
When policy advisor is enabled, the sandbox supervisor turns on three agent-facing surfaces:
@@ -102,7 +118,7 @@ The loop has seven steps:
102
118
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`.
103
119
3. The agent reads the policy advisor skill, inspects the current policy, and optionally reads recent denial log lines.
104
120
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.
106
122
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.
107
123
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.
0 commit comments