Files
OpenShell/docs/observability
krishicks a24340beba feat(auth): emit OCSF events for gateway authorization denials (#4728)
When the gateway refuses a caller that has already authenticated, it
now emits an OCSF API Activity event. The caller gets exactly the same
error as before. The event records:

- Who: the principal (user, mTLS operator, sandbox, or gateway peer).
- What: the gRPC method, plus the sandbox or workspace that was
  refused when there is one.
- Why: a reason such as cross_sandbox, missing_role or
  not_workspace_member.
- Correlation: the caller's address and request ID, the same fields
  the authentication events carry.

That covers the denials made centrally by the router and the shared
guards, plus the checks inside handlers that have no shared guard: a
sandbox naming another sandbox (in either sandbox-name resolver), a
non-user caller refused by mutation admission, a sandbox sending a
config update it isn't allowed to, and a non-admin granting the
workspace admin role. Denials raised in the mutation admission worker,
which runs in a spawned task, keep the request's context.

When a sandbox credential is refused for calling a method it may not
call, touching another sandbox, or acting across workspaces, the
gateway also emits a High-severity Detection Finding. It carries the
same correlation_uid as the denial event. A real supervisor never makes
these requests, so a finding means the credential is probably being
misused. Two cases are recorded without a finding: a method the
gateway doesn't recognize (unknown_method), so a newer supervisor
doesn't look like a compromised one, and a supervisor whose own sandbox
was deleted mid-request, which is refused but isn't misuse.

The shorthand line names the refused sandbox or workspace, for example
sandbox:<id>, so operators reading console logs can see the target
without JSONL or OTLP export.

To support this, the OCSF crate's Actor can now hold a user instead of
a process, and the API Activity builder gained the fields gateway
events need. Supervisor inference events come out unchanged. Gateway
events declare the container profile only when they concern a sandbox,
as MXC findings do. The OCSF
1.8.0 resource_details schema is vendored so the refused sandbox or
workspace goes in the standard resources field.

Refs #2912

Signed-off-by: Kris Hicks <khicks@nvidia.com>
2026-10-20 15:49:14 +00:00
..