Skip to content

Commit d7f9211

Browse files
johnnygrecojohnnygreco
authored
docs(policy): refresh policy documentation and references (#3563)
* docs(policy): correct schema and default policy guidance Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): add network recipes and update command reference Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): organize lifecycle guidance and troubleshooting Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): split policy overview into concepts and management tasks Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): reorganize network recipes as a cookbook Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): restructure schema reference by field group and protocol Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): align troubleshooting, advisor, and reference pages Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): fix first policy tutorial and security guidance Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): keep overview high level and move network rules to their own page Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): focus policy management on CLI workflows and remove command reference Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): clarify policy views and sandbox deletion in management guide Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): streamline network rule concepts and examples Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct request path wildcard semantics Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): rewrite policy advisor guide for clarity Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): clarify policy advisor scope, setup, and review Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): rewrite policy prover guide for clarity Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): explain the two uses of the policy prover Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): describe policy prover uses, boundaries, and coverage Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): place prover before advisor and troubleshooting last Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): remove unsupported CI guidance from prover page Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): tighten policy prover introduction Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): move policy change behavior into management guide Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): name prover check types and note expanding coverage Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): prefix prover and advisor sidebar labels Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): streamline policy schema reference Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): place default policy before schema reference Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): fold troubleshooting into policy management guide Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct tutorial log samples and GitHub push policy steps The first policy tutorial said the 403 body begins with error, policy, and rule, but the proxy serializes the body with sorted keys. Its log samples also showed the wrong CONNECT deny reason for a sandbox without network rules, and the L7 deny sample omitted the :443 authority, the `l7` engine, and the reason tag that the shorthand formatter emits. The GitHub tutorial filtered denials with `--level warn`, which hides the INFO level OCSF policy events, and showed the retired key=value log format. Its hand-written policy also omitted /bin from the restrictive default, so `policy set` would reject the file for removing a filesystem path on a live sandbox. Start from `policy get --base` and add only the network rules. Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): improve flow and terminology across policy pages Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct network rule matching and protocol details Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): align policy management steps with CLI behavior Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct policy advisor proposal and approval details Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct policy section, default, and schema details Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): correct prover installation and coverage limits Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): recommend tls skip for server-first protocols Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): fix stale baseline path and interpreter examples Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): move policy pages under how-it-works and fix links Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): align native TCP guidance in security best practices Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): restore policy.local and policy DNS details from main Signed-off-by: Johnny Greco <jogreco@nvidia.com> * docs(policy): state exact glob matching rules Signed-off-by: Johnny Greco <jogreco@nvidia.com> --------- Signed-off-by: Johnny Greco <jogreco@nvidia.com>
1 parent 585bcf0 commit d7f9211

18 files changed

Lines changed: 1990 additions & 1927 deletions

File tree

‎docs/about/overview.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ OpenShell applies defense in depth across the following policy domains.
4242
| Process | Blocks privilege escalation and dangerous syscalls. | Locked at sandbox creation. |
4343
| Provider credentials | Resolves opaque credential placeholders only at profile-authorized endpoints. | Attachments, rotation, and revocation update at runtime; new environment variables require a new process. |
4444

45-
For details, refer to [Customize Sandbox Policies](/how-it-works/policies/overview) and [Default Policy](/how-it-works/policies/default-policy).
45+
For details, refer to [Sandbox Policies](/how-it-works/policies/overview) and [Default Policy](/how-it-works/policies/default-policy).
4646

4747
## Common Use Cases
4848

@@ -61,4 +61,4 @@ Explore these topics to go deeper:
6161

6262
- To understand the runtime architecture, refer to [Architecture](/about/architecture).
6363
- To prepare an image and launch an agent, refer to [Run Your First Agent](/about/run-your-first-agent).
64-
- To learn how OpenShell enforces policy controls across protection layers, refer to [Customize Sandbox Policies](/how-it-works/policies/overview).
64+
- To learn how OpenShell enforces policy controls across protection layers, refer to [Sandbox Policies](/how-it-works/policies/overview).

‎docs/extensibility/isolation-backends.mdx‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,6 @@ crate. `OpenShellRuntimeBackend` is implemented in
4343
| Compute driver | Placement and fencing. The driver creates runtime resources, installs the outer egress fence, and supplies a verified descriptor. |
4444
| Isolation backend | Common behavior. The backend turns the shared Rust calls into a protected session with the sandbox runtime. |
4545

46-
For how `openshell-sandbox` enforces the boundary, refer to
47-
[Sandbox](/about/architecture/sandbox). For driver-specific workload behavior,
48-
refer to [Runtimes](/how-it-works/sandboxes/runtimes).
46+
For how `openshell-sandbox` enforces the boundary, refer to [Inside the Sandbox
47+
Boundary](/about/architecture#inside-the-sandbox-boundary). For driver-specific
48+
workload behavior, refer to [Runtimes](/how-it-works/sandboxes/runtimes).

‎docs/how-it-works/inference.mdx‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -34,17 +34,18 @@ curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/providers/nvi
3434
```
3535

3636
In `nvidia-native.yaml`, change `id` to `nvidia-native`, give the profile a
37-
distinct `display_name`, and set `binaries` to the paths that may call the API.
38-
Keep the credential and endpoint definitions you intend to grant. For a Python
39-
workload, the edited fields can look like:
37+
distinct `display_name`, and set `binaries` to the executables that may call the
38+
API, as described in [Binary
39+
Matching](/how-it-works/policies/network-rules#binary-matching). Keep the
40+
credential and endpoint definitions you intend to grant. For a Python workload,
41+
the edited fields can look like:
4042

4143
```yaml
4244
id: nvidia-native
4345
display_name: NVIDIA Native API
4446
binaries:
45-
- /usr/bin/python3
46-
- /usr/bin/python3.13
47-
- /usr/local/bin/python
47+
- /usr/bin/python3.*
48+
- /usr/local/bin/python3.*
4849
- /sandbox/.venv/**
4950
```
5051
@@ -316,5 +317,5 @@ headers, model selection, request shape, streaming, and timeout behavior.
316317

317318
- [Profiles](/how-it-works/providers/profiles)
318319
- [Providers](/how-it-works/providers/overview)
319-
- [Customize Sandbox Policies](/how-it-works/policies/overview)
320+
- [Sandbox Policies](/how-it-works/policies/overview)
320321
- [Google](/how-it-works/providers/google#vertex-ai)

‎docs/how-it-works/policies/advisor.mdx‎

Lines changed: 204 additions & 176 deletions
Large diffs are not rendered by default.

‎docs/how-it-works/policies/default-policy.mdx‎

Lines changed: 101 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,122 @@
11
---
22
# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
33
# SPDX-License-Identifier: Apache-2.0
4-
title: "Default Policy Reference"
4+
title: "Default Policy and Baseline Paths"
55
sidebar-title: "Default Policy"
6-
description: "Breakdown of the built-in default policy applied when you create an OpenShell sandbox without a custom policy."
7-
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Policy"
8-
position: 2
6+
description: "The restrictive fallback policy used when a sandbox has no explicit or embedded policy, and the baseline paths OpenShell adds to sandbox policies."
7+
keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Security, Policy, Landlock, Filesystem"
8+
position: 6
99
---
1010

11-
When you create a sandbox without `--policy`, OpenShell applies a restrictive built-in fallback. The policy comes from the OpenShell runtime and does not depend on the selected workload image.
11+
This reference describes the restrictive policy OpenShell uses when a sandbox
12+
has no other policy, and the filesystem paths that OpenShell adds to sandbox
13+
policies at runtime.
1214

13-
## Filesystem Access
15+
## When the Default Applies
1416

15-
The fallback includes the sandbox working directory and grants read-only access to standard runtime paths:
17+
OpenShell uses the restrictive default only when no global policy is active, the
18+
sandbox has no saved policy, and its image contains no policy. Creating a
19+
sandbox without `--policy` does not by itself mean the default is active,
20+
because the image or `OPENSHELL_SANDBOX_POLICY` can supply one. An invalid image
21+
policy keeps the workload from starting until you repair it. It does not select
22+
the default. Refer to [Where the Active Policy Comes
23+
From](/how-it-works/policies/overview#where-the-active-policy-comes-from) for
24+
the complete selection order.
1625

26+
## Default Filesystem Access
27+
28+
The default policy includes the sandbox working directory as read-write and
29+
grants read-only access to these paths:
30+
31+
- `/bin`
1732
- `/usr`
1833
- `/lib`
1934
- `/proc`
2035
- `/dev/urandom`
2136
- `/etc`
2237
- `/var/log`
2338

24-
It grants read-write access to `/tmp` and `/dev/null`. Landlock enforcement uses `best_effort` compatibility so OpenShell can use the strongest ABI available on the host while retaining its mandatory baseline protections.
39+
It grants read-write access to `/tmp` and `/dev/null`. Landlock user-policy
40+
compatibility is `best_effort`.
41+
42+
## Default Network Access
43+
44+
The default policy defines no network rules or middleware, so all outbound
45+
network access is denied. Attached providers can still add network rules to the
46+
effective policy. To see them, compare the base and effective policies, as
47+
described in [Inspect the Selected Policy](#inspect-the-selected-policy).
48+
49+
## Default Process Identity
50+
51+
The default policy leaves process identity to the compute driver. Docker and
52+
Podman run the workload as the image's `USER` when it names a non-root user, and
53+
as UID and GID 1000 when the image declares no user. They reject an image whose
54+
user is root unless the policy you pass when you create the sandbox sets a
55+
non-root `run_as_user`. Kubernetes and VM sandboxes run as the identity
56+
configured for their driver.
57+
58+
## Baseline Filesystem Paths
59+
60+
Sandbox processes that use the network need system paths for shared libraries,
61+
DNS resolution, and CA certificates. When the effective policy contains at least
62+
one network rule, including a provider-contributed rule, OpenShell adds these
63+
baseline paths to the sandbox's filesystem policy at startup:
64+
65+
| Access | Paths |
66+
|---|---|
67+
| Read-only | `/usr`, `/lib`, `/etc`, `/app`, `/var/log`, `/proc`, `/dev/urandom` |
68+
| Read-write | `/tmp`, `/dev/null` |
69+
70+
OpenShell adds a baseline path only when it is available and your policy does
71+
not already list it, so list the paths your workload needs, such as `/app`, in
72+
your policy. OpenShell never changes the access of a path you list, so a
73+
baseline read-write path that you list as read-only stays read-only. If the
74+
policy has no `filesystem_policy` section, OpenShell creates one with
75+
`include_workdir: true`.
76+
77+
The sandbox saves the enriched filesystem policy as a new revision, so the
78+
added paths appear in `openshell policy get --base`. OpenShell can reject a
79+
replacement policy that removes filesystem paths, so keep the added paths when
80+
you replace the complete policy.
81+
82+
The runtime also grants the workload read-only access to the sandbox's TLS CA
83+
certificates under `/run/openshell-supervisor-ca`. This grant is not saved in
84+
the sandbox's policy.
85+
86+
### GPU Sandboxes
87+
88+
On the Docker and VM compute drivers, a sandbox that requests a GPU receives
89+
additional paths when the corresponding GPU device is present:
90+
91+
| Access | Paths |
92+
|---|---|
93+
| Read-only | `/run/nvidia-persistenced`, `/usr/lib/wsl` |
94+
| Read-write | `/dev/nvidiactl`, `/dev/nvidia-uvm`, `/dev/nvidia-uvm-tools`, `/dev/nvidia-modeset`, `/dev/dxg`, numbered `/dev/nvidia<N>` device nodes, and `/proc` |
95+
96+
CUDA writes thread names under `/proc` during initialization, so GPU enrichment
97+
moves `/proc` from read-only to read-write. OpenShell adds each path only when
98+
it exists in the workload. These paths apply at runtime and are not saved in
99+
the sandbox's policy.
100+
101+
### Protected Paths
25102

26-
## Network Access
103+
On Docker, Podman, Kubernetes, and VM sandboxes, a mandatory Landlock baseline
104+
protects the private `/.openshell` directory and requires Landlock ABI v3. Your
105+
filesystem policy is applied on top of that baseline and can narrow access, but
106+
it cannot expose `/.openshell`. The `best_effort` compatibility setting does not
107+
disable this protection or allow a kernel without ABI v3.
27108

28-
The fallback defines no network policies or provider-derived endpoints, so outbound network access is denied. Attach a provider or apply a custom policy that names the required endpoints and executable paths before running a networked agent.
109+
## Inspect the Selected Policy
29110

30-
## Process Identity
111+
To see which policy a sandbox uses, print its base and effective policies.
112+
While a global policy is active, both commands show the global policy:
31113

32-
The fallback leaves process identity selection to the compute driver. Docker and Podman honor a non-root OCI `USER`; when an image declares no user, they use numeric UID and GID `1000`. Kubernetes and MicroVM drivers apply their configured non-root identities.
114+
```shell
115+
openshell policy get <sandbox> --base
116+
openshell policy get <sandbox> --full
117+
```
33118

34-
Use `openshell policy get <sandbox> --full` to inspect the effective policy. Refer to [Customize Sandbox Policies](/how-it-works/policies/overview) to replace the fallback.
119+
Neither view includes the paths that OpenShell grants only at runtime, such as
120+
the CA certificate and GPU paths. To confirm what a running sandbox enforces,
121+
check the revision status with `openshell policy list <sandbox>` and test
122+
requests.

0 commit comments

Comments
 (0)