From f86bdf80bed0fb350271ac86b748965f7d73555d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Tue, 20 Oct 2026 16:45:45 +0000 Subject: [PATCH] docs(website): sync dev docs from a24340bebaa9ee173725ce87c48011d2cc2cacd9 --- fern/.docs-snapshots.yml | 6 +++--- fern/pages-dev/observability/logging.mdx | 8 ++++++++ .../observability/ocsf-json-export.mdx | 17 +++++++++++++++++ 3 files changed, 28 insertions(+), 3 deletions(-) diff --git a/fern/.docs-snapshots.yml b/fern/.docs-snapshots.yml index 7c2019ad6..e5df43fc7 100644 --- a/fern/.docs-snapshots.yml +++ b/fern/.docs-snapshots.yml @@ -1,8 +1,8 @@ snapshots: dev: - source-ref: 92f3a41b7c1be980ca2ee922a6ca4b01d97a1d2e - source-sha: 92f3a41b7c1be980ca2ee922a6ca4b01d97a1d2e - version: 0.1.5.dev82 + source-ref: a24340bebaa9ee173725ce87c48011d2cc2cacd9 + source-sha: a24340bebaa9ee173725ce87c48011d2cc2cacd9 + version: 0.1.5.dev83 latest: source-ref: 5a7728c304b5528e954e9ae900cf21f84e1a12b1 source-sha: 5a7728c304b5528e954e9ae900cf21f84e1a12b1 diff --git a/fern/pages-dev/observability/logging.mdx b/fern/pages-dev/observability/logging.mdx index acf9ce14d..ce7cab1ee 100644 --- a/fern/pages-dev/observability/logging.mdx +++ b/fern/pages-dev/observability/logging.mdx @@ -61,6 +61,7 @@ OpenShell maps sandbox events to these OCSF classes: | `PROC:` | Process Activity | 1007 | Process start, exit, timeout, signal failures | | `FINDING:` | Detection Finding | 2004 | Security findings (nonce replay, proxy bypass, unsafe policy) | | `AUTH:` | Authentication | 3002 | Gateway authentication failures | +| `API:` | API Activity | 6003 | Inference calls, gateway authorization denials | | `CONFIG:` | Device Config State Change | 5019 | Policy load/reload, Landlock, TLS setup, provider and settings changes | | `LIFECYCLE:` | Application Lifecycle | 6002 | Sandbox supervisor start, SSH server ready | @@ -99,6 +100,7 @@ endpoint, use `EVENT` rather than a network or lifecycle event. - HTTP: `METHOD url` with the HTTP method and target - SSH: peer address and authentication type - Authentication: the principal as `type:id`, or `unknown` when none was established, and the peer address when known +- Authorization denial: the principal as `type:id` and the peer address when known, with the refused sandbox or workspace in the context - Process: `name(pid)` with exit code or command line - Config: description of what changed - Finding: quoted title with the stable finding type, optional confidence, and source-specific context attributes when available @@ -113,6 +115,12 @@ A gateway request rejected because it presented no credential: OCSF AUTH:LOGON [LOW] DENIED unknown [op:/openshell.v1.OpenShell/ListSandboxes reason:missing_credential] ``` +A sandbox credential used to read another sandbox's configuration: + +```text +OCSF API:OTHER [MED] DENIED sandbox:5d1c2e7a-0b3f-4c8e-9a61-7f2d4b6e8c10 from 10.42.0.7:51234 [op:/openshell.v1.OpenShell/GetSandboxConfig sandbox:9a3e61b0-4c2d-4f7e-8b15-2d6c0e9f7a43 reason:cross_sandbox] +``` + An allowed HTTPS connection: ```text diff --git a/fern/pages-dev/observability/ocsf-json-export.mdx b/fern/pages-dev/observability/ocsf-json-export.mdx index aa00b90d8..593ed88e8 100644 --- a/fern/pages-dev/observability/ocsf-json-export.mdx +++ b/fern/pages-dev/observability/ocsf-json-export.mdx @@ -39,6 +39,22 @@ The gateway emits an Authentication (`class_uid: 3002`) event when it rejects a These events never include presented credentials, other request headers, or verification error text. +The gateway emits an API Activity (`class_uid: 6003`) event with Medium severity when its method, role, scope, sandbox, workspace, or operator checks refuse an authenticated caller. `actor.user` identifies the principal: its `type` is `User`, `Admin` for an mTLS operator, `Sandbox`, or `Gateway Peer`, and `uid` is the subject, sandbox ID, or gateway replica ID. `api.operation` names the gRPC method, and `resources` names the sandbox or workspace that was refused, when one applies, by `uid` for a sandbox ID or by `name` otherwise. `status_detail` holds the reason category: + +| Reason | Meaning | +|---|---| +| `method_not_permitted` | The principal type may not call the method, or may not call it with these arguments. | +| `unknown_method` | The gateway does not recognize the method, for example one added in a newer client. | +| `missing_role` | The caller lacks the OIDC role the method requires. | +| `missing_scope` | The caller's token lacks the scope the method requires. | +| `cross_sandbox` | A sandbox principal referenced a sandbox other than its own, by ID or by name. | +| `not_workspace_member` | The caller is not a member of the workspace. | +| `insufficient_workspace_role` | The caller's workspace role is below the one the operation requires. | +| `platform_admin_required` | The operation spans workspaces or assigns the workspace admin role. | +| `operator_required` | The operation requires a verified mTLS operator. | + +When a sandbox principal is refused with `method_not_permitted`, `cross_sandbox`, or `platform_admin_required`, the gateway also emits a High-severity Detection Finding (`class_uid: 2004`) with `finding_info.uid` `sandbox-authorization-boundary`. Supervisors never make these requests, so the sandbox's credential may be compromised. Both events carry the same `metadata.correlation_uid`. Some methods answer a refused request with "not found" so callers cannot probe for resources; the event still records the denial. + Without JSONL enabled, gateway OCSF events still appear as shorthand in console output, subject to the diagnostic log filter. Events associated with a sandbox also appear in its gateway log stream; gateway-wide events have no sandbox association. ## Enable Sandbox JSON Export @@ -268,6 +284,7 @@ The `class_uid` field identifies the event type: | 3002 | Authentication | `AUTH:` | | 5019 | Device Config State Change | `CONFIG:` | | 6002 | Application Lifecycle | `LIFECYCLE:` | +| 6003 | API Activity | `API:` | HTTP Activity records include request or response details. Rejections that have parsed a request, including early credential-binding failures, include safe