Skip to content

Commit 6d97607

Browse files
craig-osterhoutcraig-osterhout
authored
sbx: update policy cli (#25535)
<!--Delete sections as needed --> ## Description v0.35.0 revamps policy tooling with a new default output format for `sbx policy ls`, a new `sbx policy inspect` command, and a new `sbx policy check network` command for testing policy before running an agent. Release notes: https://github.com/docker/sandboxes/releases/tag/v0.35.0 > `sbx policy ls` now shows a concise one-row-per-policy overview by default. > Use `--wide` for the previous rule-level table (now including rule IDs), > `--json` for automation, and the new `--source`/`--decision` flags to filter. > Detailed inspection moved to the new `sbx policy inspect <policy-or-rule>` > command. Upstream changes: docker/sandboxes#3733 (policy ls revamp + policy inspect), docker/sandboxes#4018 (dhi.io HTTP in Balanced preset) ### `governance/monitoring.md` - Rewrites all `sbx policy ls` example output blocks to the new per-policy format (`POLICY`, `SOURCE`, `APPLIES TO`, `SUMMARY` columns) - Rewrites column descriptions for the new schema - Updates the org governance header from the old multi-line block format to the new single inline summary line - Adds mentions of `--wide`, `--source`, `--decision`, and `sbx policy inspect` ### `governance/local.md` - Adds a new "Testing policy" section documenting `sbx policy check network` with examples for allowed and denied targets, URL inputs, and the `--sandbox` scope flag - Updates the `sbx policy ls` reference to mention the new `--source`, `--decision`, and `--wide` filters and `sbx policy inspect` - Notes the v0.35.0 Balanced preset additions: VS Code domains, `*.blob.core.windows.net`, and `dhi.io` over HTTP ## Related issues or tickets #25532: cli ref update ## Reviews <!-- Notes for reviewers here --> <!-- List applicable reviews (optionally @tag reviewers) --> - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
1 parent 9cf407c commit 6d97607

2 files changed

Lines changed: 84 additions & 70 deletions

File tree

‎content/manuals/ai/sandboxes/governance/local.md‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -54,7 +54,9 @@ Choose a default network policy:
5454
| Locked Down | All outbound traffic is blocked, including model provider APIs (for example, `api.anthropic.com`). You must explicitly allow everything you need. |
5555

5656
The **Balanced** preset's baseline allowlist is a good starting point for most
57-
workflows. Run `sbx policy ls` to see exactly which rules it includes.
57+
workflows. Run `sbx policy ls` to see exactly which rules it includes. As of
58+
v0.35.0, the Balanced preset also allows VS Code domains, Azure Blob Storage
59+
(`*.blob.core.windows.net`), and `dhi.io` over HTTP.
5860

5961
> [!NOTE]
6062
> If your organization manages sandbox policies centrally, organization rules
@@ -111,8 +113,35 @@ To remove a sandbox-scoped rule, pass `--sandbox <name>`:
111113
$ sbx policy rm network --sandbox my-sandbox --resource api.example.com
112114
```
113115

114-
To inspect which rules are active and where they come from, use
115-
`sbx policy ls`. See [Monitoring](monitoring.md).
116+
To inspect which policies are active and where they come from, use
117+
`sbx policy ls`. Use `--source` to filter by origin (`local`, `org`, `kit`),
118+
`--decision` to filter by outcome (`allow`, `deny`), and `--wide` for
119+
rule-level detail including rule IDs. To inspect a single policy or rule in
120+
full, use `sbx policy inspect`. See [Monitoring](monitoring.md).
121+
122+
## Testing policy
123+
124+
Before running a sandbox, you can check whether the current policy would allow
125+
a network request with `sbx policy check network`:
126+
127+
```console
128+
$ sbx policy check network api.anthropic.com
129+
Allowed: api.anthropic.com
130+
131+
$ sbx policy check network blocked.example.com
132+
Denied: blocked.example.com
133+
```
134+
135+
The target can be a hostname, a `host:port` pair, an IP address, or a URL.
136+
Bare hostnames and IP addresses are evaluated against port 443. This is useful
137+
for verifying custom rules or checking what the Locked Down preset blocks
138+
before you start an agent.
139+
140+
To check policy in the context of a specific sandbox:
141+
142+
```console
143+
$ sbx policy check network --sandbox my-sandbox api.example.com
144+
```
116145

117146
### Resetting
118147

‎content/manuals/ai/sandboxes/governance/monitoring.md‎

Lines changed: 52 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -13,64 +13,59 @@ blocked or allowed.
1313

1414
## Listing rules
1515

16-
Use `sbx policy ls` to see all active rules and their current status:
16+
Use `sbx policy ls` to see all active policies and their current status:
1717

1818
```console
1919
$ sbx policy ls
20-
PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES
21-
local all default-ai-services network allow api.anthropic.com:443
22-
api.openai.com:443
23-
local all default-fs-read-allow-all filesystem:read allow **
24-
local all default-fs-write-allow-all filesystem:write allow **
25-
kit sandbox:docs kit:docs network allow api.github.com
26-
registry.npmjs.org
20+
POLICY SOURCE APPLIES TO SUMMARY
21+
local-policy local all network: 42 allow, 1 deny; filesystem read: 1 allow; filesystem write: 1 allow
22+
1b2633ea-e604-48bb-a5e6-3ac86ba383fe kit sandbox:my-sandbox network: 3 allow
2723
```
2824

2925
The columns are:
3026

31-
- `PROVENANCE`: where the rule came from. `local` is a rule from your local
32-
policy — a preset default or one you added with `sbx policy`. `kit` is a rule
33-
added by a [kit](../customize/kits.md#control-network-access). `remote` is a
34-
rule set by your organization.
35-
- `APPLIES_TO`: which sandboxes the rule applies to. `all` means the rule is
36-
global. `sandbox:<name>` means it's scoped to the named sandbox.
37-
- `POLICY/RULE`: the rule's identity. Organization rules show as
38-
`<policy> / <rule>`. Local and kit rules show the rule name.
39-
- `TYPE`: the rule domain. Network rules show as `network`. Filesystem rules
40-
show as `filesystem:read` or `filesystem:write`, depending on the access the
41-
rule controls.
42-
- `DECISION`: whether the rule allows or denies the resource.
43-
- `RESOURCES`: the hosts or patterns the rule applies to.
27+
- `POLICY`: the policy name.
28+
- `SOURCE`: where the policy came from. `local` means your local configuration
29+
— a preset or rules you added with `sbx policy`. `kit` means a
30+
[kit](../customize/kits.md#control-network-access). `org` means your
31+
organization.
32+
- `APPLIES TO`: which sandboxes the policy applies to. `all` means the policy
33+
is global. `sandbox:<name>` scopes it to a single sandbox; a profile name
34+
scopes it to sandboxes using that profile.
35+
- `SUMMARY`: a count of rules by type and decision — for example,
36+
`network: 5 allow, 1 deny`.
37+
38+
To see full rule-level detail including rule IDs and resources, pass `--wide`.
39+
To inspect a single policy or rule, use `sbx policy inspect`:
40+
41+
```console
42+
$ sbx policy inspect Balanced
43+
```
44+
45+
Use `--source` to filter by origin (`local`, `org`, or `kit`) and `--decision`
46+
to filter by outcome (`allow` or `deny`).
4447

4548
A `STATUS` column also appears when you pass `--include-inactive`; see
4649
[Showing inactive rules](#showing-inactive-rules).
4750

48-
When organization governance is active, the output starts with a `Policy rules`
49-
header showing which organization manages the policy, the sync state, and how
50-
many inactive rules are hidden:
51+
When organization governance is active, the output starts with a summary line
52+
showing which organization manages the policy, the sync state, and how many
53+
inactive rules are hidden:
5154

5255
```console
5356
$ sbx policy ls
54-
Policy rules
55-
------------
56-
Governance Managed by my-org
57-
Sync OK, last synced 08:21:01
58-
Hidden 9 inactive rules. Show with: sbx policy ls --include-inactive
59-
60-
PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES
61-
remote all default filesystem / allow home subdirectories filesystem:write allow ~/**
62-
remote all default filesystem / deny home directory filesystem:write deny ~/
63-
remote all default network / allow AI services network allow api.anthropic.com
64-
api.openai.com
65-
remote all default network / allow Docker services network allow *.docker.com
66-
*.docker.io
57+
Governance: Managed by my-org | Sync: OK, last synced 08:21:01 | Hidden: 9 inactive rules. Show with: sbx policy ls --include-inactive
58+
59+
POLICY SOURCE APPLIES TO SUMMARY
60+
default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny
61+
default network org all network: 38 allow, 4 deny
6762
```
6863

69-
The `Governance` line shows which organization manages the policy, and `Sync`
70-
confirms the daemon has pulled the latest rules. If the sync state shows an
71-
error or a stale timestamp, the daemon may not have the most recent org policy.
72-
Run `sbx policy reset` to force a fresh pull. The `Hidden` line reports how many
73-
inactive rules are suppressed and how to reveal them.
64+
`Governance` shows which organization manages the policy, and `Sync` confirms
65+
the daemon has pulled the latest rules. If the sync state shows an error or a
66+
stale timestamp, the daemon may not have the most recent org policy. Run
67+
`sbx policy reset` to force a fresh pull. `Hidden` reports how many inactive
68+
rules are suppressed and how to reveal them.
7469

7570
### Showing inactive rules
7671

@@ -81,30 +76,21 @@ example, to confirm which local rules the organization policy overrides — pass
8176

8277
```console
8378
$ sbx policy ls --include-inactive
84-
Policy rules
85-
------------
86-
Governance Managed by my-org
87-
Sync OK, last synced 08:41:06
88-
89-
PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION STATUS RESOURCES
90-
local default-fs-read-allow-all filesystem:read allow inactive — corporate policy **
91-
takes precedence and does
92-
not delegate this rule type
93-
to local policy.
94-
local default-fs-write-allow-all filesystem:write allow inactive — corporate policy **
95-
takes precedence and does
96-
not delegate this rule type
97-
to local policy.
98-
remote all default filesystem / allow home subdirectories filesystem:write allow active ~/**
99-
remote all default filesystem / deny home directory filesystem:write deny active ~/
79+
Governance: Managed by my-org | Sync: OK, last synced 08:41:06
80+
81+
POLICY SOURCE APPLIES TO SUMMARY STATUS
82+
default filesystem org all filesystem read: 2 allow; filesystem write: 7 allow, 2 deny active
83+
default network org all network: 38 allow, 4 deny active
84+
default-fs-read-allow-all local all filesystem read: 1 allow inactive
85+
default-fs-write-allow-all local all filesystem write: 1 allow inactive
10086
```
10187

102-
Inactive rules show `inactive` in the `STATUS` column, along with the reason.
103-
They have no effect while organization governance is active.
88+
Inactive policies show `inactive` in the `STATUS` column. They have no effect
89+
while organization governance is active.
10490

105-
Use `--type network` or `--type filesystem` to show only rules of that type.
106-
Without a sandbox argument, `sbx policy ls` shows every rule across all
107-
sandboxes. Pass a sandbox name to filter to global rules and rules scoped to
91+
Use `--type network` or `--type filesystem` to show only policies of that type.
92+
Without a sandbox argument, `sbx policy ls` shows every policy across all
93+
sandboxes. Pass a sandbox name to filter to global policies and those scoped to
10894
that sandbox:
10995

11096
```console
@@ -113,15 +99,14 @@ $ sbx policy ls my-sandbox
11399

114100
### Filesystem rules
115101

116-
`sbx policy ls` lists filesystem rules alongside network rules. Filesystem
102+
`sbx policy ls` lists filesystem policies alongside network policies. Filesystem
117103
rules control which host paths a sandbox can mount as a workspace. Pass
118104
`--type filesystem` to show only them:
119105

120106
```console
121107
$ sbx policy ls --type filesystem
122-
PROVENANCE APPLIES_TO POLICY/RULE TYPE DECISION RESOURCES
123-
local all default-fs-read-allow-all filesystem:read allow **
124-
local all default-fs-write-allow-all filesystem:write allow **
108+
POLICY SOURCE APPLIES TO SUMMARY
109+
local-policy local all filesystem read: 1 allow; filesystem write: 1 allow
125110
```
126111

127112
A writable workspace mount must be allowed by both a `filesystem:read` and a

0 commit comments

Comments
 (0)