ai-gov: http and path policies - #26060
craig-osterhout wants to merge 1 commit into
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
| approval behaves and what satisfies it, see | ||
| [Approval-required access](network.md#approval-required-access). | ||
|
|
||
| Before you turn it on, note that you shouldn't combine an approval requirement |
There was a problem hiding this comment.
This needs updating - this should no longer be the case. Approvals should now support both network-level and HTTP-level rules.
## Description Document HTTP method and path rules for local policy. A local network rule can match specific HTTP methods and URL paths on a destination. No org/admin updates in this update. Supersedes #26060 without ask policies. | Page | What changed | | --- | --- | | [`concepts.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/concepts/) | Method, destination, and path syntax, plus how HTTP and network rules combine. Nested under Network rules, since an HTTP rule is a network rule with a method and path. Notes that L7 evaluation needs the sandbox HTTP proxy, so a connection it can't inspect is blocked rather than evaluated | | [`network.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/access-controls/network/) | Introduces the capability and routes to the local CLI | | [`local.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/access-controls/local/) | `--method` and `--path` how-to, split out from the existing rule management. Path must be canonical, and each rule takes one path. Troubleshooting entry for a method or path blocked on an allowed host | | [`monitoring.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/monitor-and-enforce/monitoring/) | `--type http` listing with the method and path columns, and the `(L4)` and `(L7)` labels in the summary | | [`_index.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/access-controls/) & [`_index.md`](https://deploy-preview-26162--docsdocker.netlify.app/ai/sandboxes/governance/) | Network bullet notes that a local policy rule can match a host, or an HTTP method and path | ## Related issues or tickets ENGDOCS-3373 ## Reviews - [ ] Technical review - [ ] Editorial review - [ ] Product review --------- Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
derekmisler
left a comment
derekmisler
left a comment
There was a problem hiding this comment.
left 1 issue, 3 questions, and 3 nitpicks inline. the stale "don't combine approval with HTTP rules" guidance in organization.md is the one to check first, it isn't reconciled with network.md/concepts.md and chrispatrick already flagged it as outdated.
| approval behaves and what satisfies it, see | ||
| [Approval-required access](network.md#approval-required-access). | ||
|
|
||
| Before you turn it on, note that you shouldn't combine an approval requirement |
There was a problem hiding this comment.
issue: the "don't combine approval with HTTP rules" guidance looks outdated per chrispatrick's unresolved comment, and it isn't reconciled with network.md or concepts.md
i think this paragraph is stale: chrispatrick flagged it on this PR (no reply yet) saying approvals now support both network-level and HTTP-level rules, and the restriction only lives here (nothing in network.md#approval-required-access or the concepts.md HTTP evaluation table mentions it, so the two pages already tell a slightly different story). why it matters: an admin who reads this will split their HTTP rules into a separate no-approval policy for no reason, and it's a product-behavior claim on the exact feature this PR documents. probably confirm with eng and either drop the paragraph or replace it with what approval actually does for an HTTP rule (does the developer get asked per destination and then the method/path carve-outs apply on top?). btw if any version of this survives, drop the "note that" filler and state it positively ("Keep HTTP rules in a policy that doesn't require approval" already does that).
| | Destination | A host, with an optional port | | ||
| | Path | An absolute path pattern, such as `/api/**` | | ||
|
|
||
| A CIDR range isn't a valid HTTP destination. Use a network rule to cover one. |
There was a problem hiding this comment.
question (non-blocking): concepts.md says only CIDR ranges are invalid HTTP destinations, but local.md also excludes plain IP addresses; which is it, and does the org composer match?
concepts.md (the page every other page links to for "the full matching table") only rules out CIDR ranges, but local.md says a local HTTP rule takes a hostname and that IP addresses also need a plain network rule. why it matters: someone reading only concepts.md will reasonably try 10.0.0.5 as an HTTP destination. does the org composer accept a bare IP in the HTTP Destination field? if not, i'd say "A host name" in the Destination row and change this sentence to cover both ("An IP address or CIDR range isn't a valid HTTP destination. Use a network rule to cover one."); if the composer does accept IPs, note the surface difference the same way you already do for methods two lines down.
|
|
||
| ### HTTP method and path rules | ||
|
|
||
| Add `--method` to an allow or deny rule to match specific HTTP methods on a |
There was a problem hiding this comment.
question (non-blocking): how do you give one CLI rule more than one path pattern? concepts.md says "one or more paths" but the CLI section only ever shows a single --path
concepts.md says an HTTP rule names "one or more paths" and the composer has a plural Path patterns list, but every CLI example here passes a single --path, and the text explains comma lists for --method only. why it matters: a reader replicating a two-path org rule locally has no idea whether to repeat --path, comma-separate it, or add two rules. can you add one sentence (and ideally an example) saying which it is? if the CLI is one path per rule, say that explicitly so the mismatch with the composer is intentional.
| ```console | ||
| $ sbx policy ls | ||
| POLICY SOURCE APPLIES TO SUMMARY | ||
| local-policy local all network: 2 allow (L4), 1 deny (L7) |
There was a problem hiding this comment.
question (non-blocking): the SUMMARY example doesn't show how the (L4)/(L7) labels look when the same decision has rules at both layers
the example happens to have all allows at L4 and the one deny at L7, so it never shows what happens when one decision spans both layers (say 2 L4 allows plus 1 L7 allow). why it matters: "labels each part" reads as one label per decision, and a reader can't tell if the real output is 3 allow, 2 allow (L4), 1 allow (L7), or something else. probably worth swapping the sample for a mixed one, or adding a sentence on how a split count renders (non-blocking, small completeness gap).
|
|
||
| A CIDR range isn't a valid HTTP destination. Use a network rule to cover one. | ||
|
|
||
| A rule that names no method matches every method. The methods you can select |
There was a problem hiding this comment.
nitpick (super non-blocking): "a rule that names no method matches every method" doesn't match either surface, where you always pick a method or ANY/any (*)
i don't think a method-less rule exists on either surface: local.md says a path without a method is rejected (you pass ANY), and the composer has any (*) pre-selected. why it matters: a CLI reader could take this as permission to run sbx policy allow network host --path /foo and get a rejection. maybe rephrase to "Every rule names at least one method; ANY on the CLI or any (*) in the composer means every method (with the caveat below)." and let the next sentence carry the per-surface difference (super non-blocking).
| organization. | ||
| 1. In the left-hand navigation, expand **AI Platform** and select | ||
| **Network access**. | ||
| 1. Select the policy, then choose **Edit**. |
There was a problem hiding this comment.
nitpick (super non-blocking): "choose Edit" where the rest of the list uses "select" for buttons
every other UI step in this list and file uses "select" for a control ("select Save changes", "select Add rule"); one "choose" for a button reads like a different author. why it matters: the docs style guide standardizes on "select" for UI actions, and consistency inside one numbered list is the cheapest place to keep it.
| 1. Select the policy, then choose **Edit**. | |
| 1. Select the policy, then select **Edit**. |
| Configure them in either place: | ||
|
|
||
| - Organization policies, in the network rule composer in Docker Home. Set the | ||
| rule **Type** to **HTTP**, then choose the methods and path patterns. See |
There was a problem hiding this comment.
nitpick (super non-blocking): "choose the methods and path patterns" vs "select" everywhere else for the same composer
same composer is described in organization.md with "select the methods the rule applies to", so "choose" here is the odd one out. why it matters: "select" is the standard verb for UI actions in the docs style guide (super non-blocking).
| rule **Type** to **HTTP**, then choose the methods and path patterns. See | |
| rule **Type** to **HTTP**, then select the methods and path patterns. See |
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Signed-off-by: Craig Osterhout <craig.osterhout@docker.com>
f8def90 to
c959171
Compare
This branch has not been deployed
3 participants
Description
Document HTTP method and path rules for organization policies. An organization
network rule can match specific HTTP methods and URL paths on a destination.
Local policy support shipped in #26162, so this PR covers
the organization side.
organization.md--method ANY. Note that HTTP rules are evaluated per requestnetwork.mdconcepts.mdlocal.md--pathtakes one path per rulemonitoring.mdSUMMARYcolumn counts one decision with entries at both layers_index.md&_index.mdRelated issues or tickets
ENGDOCS-3373
Reviews