Skip to content

Commit 0743b22

Browse files
committed
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>
1 parent 977fa46 commit 0743b22

2 files changed

Lines changed: 23 additions & 20 deletions

File tree

‎docs/get-started/tutorials/first-network-policy.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,7 @@ openshell logs demo --since 5m --source sandbox
8787
You see a line like:
8888

8989
```text
90-
[1775014132.690] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(64) -> api.github.com:443 [policy:- engine:opa] [reason:no matching policy]
90+
[1775014132.690] [sandbox] [OCSF ] [ocsf] NET:OPEN [MED] DENIED /usr/bin/curl(64) -> api.github.com:443 [policy:- engine:opa] [reason:network connections not allowed by policy]
9191
```
9292

9393
Every denied connection is logged with the destination, the binary that attempted it, and the reason. Nothing gets out silently.
@@ -158,10 +158,10 @@ curl -s -X POST https://api.github.com/repos/octocat/hello-world/issues \
158158
-d '{"title":"oops"}'
159159
```
160160

161-
The proxy returns a `403` response with a JSON body. The body begins with fields like these, followed by details about the denied request:
161+
The proxy returns a `403` response with a JSON body that includes fields like these, along with details about the denied request:
162162

163163
```text
164-
{"error":"policy_denied","policy":"github_api","rule":"POST /repos/octocat/hello-world/issues",...}
164+
{...,"error":"policy_denied",...,"policy":"github_api",...,"rule":"POST /repos/octocat/hello-world/issues",...}
165165
```
166166

167167
The connection succeeded because `api.github.com` is allowed, but the proxy inspected the HTTP method and returned `403`. `POST` is not in the `read-only` preset. An agent with this policy can read code from GitHub but cannot create issues, push commits, or modify anything.
@@ -175,7 +175,7 @@ openshell logs demo --since 5m --source sandbox
175175
```
176176

177177
```text
178-
[1775014140.412] [sandbox] [OCSF ] [ocsf] HTTP:POST [MED] DENIED POST http://api.github.com/repos/octocat/hello-world/issues [policy:github_api engine:opa]
178+
[1775014140.412] [sandbox] [OCSF ] [ocsf] HTTP:POST [MED] DENIED POST http://api.github.com:443/repos/octocat/hello-world/issues [policy:github_api engine:l7] [reason:L7_REQUEST deny POST api.github.com:443/repos/octocat/hello-world/issues reason=POST /repos/octocat/hello-world/issues not permitted by policy]
179179
```
180180

181181
Policy events are INFO-level log records regardless of their severity, so do not filter them out with `--level warn`. In production, export these events to your SIEM for a complete audit trail of every request your agent makes. Refer to [Logging](/observability/logging) for the event format.

‎docs/get-started/tutorials/github-sandbox.mdx‎

Lines changed: 19 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -107,34 +107,41 @@ not grant the missing network authority.
107107
In terminal 2, inspect recent sandbox logs:
108108

109109
```shell
110-
openshell logs github-demo --level warn --since 5m
110+
openshell logs github-demo --since 5m --source sandbox
111111
```
112112

113113
You should see a denial for a request resembling this one:
114114

115115
```text
116-
action=deny dst_host=github.com dst_port=443 binary=/usr/bin/git l7_action=POST l7_target=/<org>/<repo>.git/git-receive-pack
116+
[1775014140.412] [sandbox] [OCSF ] [ocsf] HTTP:POST [MED] DENIED POST http://github.com:443/<org>/<repo>.git/git-receive-pack [policy:_provider_my_github engine:l7] [reason:L7_REQUEST deny POST github.com:443/<org>/<repo>.git/git-receive-pack reason=POST /<org>/<repo>.git/git-receive-pack not permitted by policy]
117117
```
118118

119+
`_provider_my_github` is the rule that OpenShell composes from the attached
120+
`my-github` provider. Policy events are INFO-level log records, so do not filter
121+
them out with `--level warn`.
122+
119123
You can also run `openshell term` to inspect policy decisions in the terminal
120124
dashboard.
121125

122126
## Create a Repository-Scoped Policy
123127

124-
Create `github-push.yaml`. Replace `<org>` and `<repo>`, and adjust `binaries`
125-
to match your image:
128+
`policy set` replaces the complete base policy, so start from the sandbox's
129+
current one. In terminal 2, print it:
126130

127-
```yaml
128-
version: 1
131+
```shell
132+
openshell policy get github-demo --base
133+
```
129134

130-
filesystem_policy:
131-
include_workdir: true
132-
read_only: [/usr, /lib, /proc, /dev/urandom, /etc, /var/log]
133-
read_write: [/tmp, /dev/null]
135+
The command prints revision details followed by the policy. Save only the policy
136+
YAML as `github-push.yaml`. Keep its filesystem, Landlock, and process settings
137+
unchanged, because OpenShell rejects removed filesystem paths and changed
138+
Landlock or process settings on a running sandbox.
134139

135-
landlock:
136-
compatibility: best_effort
140+
Add these entries under `network_policies`, creating the section if it is
141+
missing. Replace `<org>` and `<repo>`, and adjust `binaries` to match your
142+
image:
137143

144+
```yaml
138145
network_policies:
139146
github_repository_push:
140147
name: github-repository-push
@@ -178,10 +185,6 @@ repository. The second lets `gh` use REST operations scoped to the same
178185
repository. The attached GitHub provider continues to supply credential
179186
placement and its broader read-only rules.
180187

181-
The filesystem and Landlock sections preserve the fallback policy's static
182-
settings because `policy set` replaces the complete user-authored base policy.
183-
Process identity remains omitted so the compute driver can select it.
184-
185188
## Apply the Policy
186189

187190
Apply the policy and wait for the new revision to load:

0 commit comments

Comments
 (0)