Skip to content

docs(security): clarify audit behavior and runtime guarantees #5452

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
alangou wants to merge 1 commit into
base: main
Choose a base branch
from
+16 −10
Draft

docs(security): clarify audit behavior and runtime guarantees #5452

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 5 additions & 4 deletions docs/about/architecture.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,10 +195,11 @@ tokens that last for the life of the sandbox run.

### What the agent can see

The agent shares its side of the boundary with the **sandbox**, so
the **sandbox** holds nothing worth stealing: no gateway signing key, no
gateway JWT, and no provider credentials. It can verify that it's talking to
the right **supervisor**, but it can't impersonate one.
The agent shares its container or guest with the trusted **sandbox** runtime.
The runtime holds no gateway signing key, gateway JWT, or provider credentials.
It still protects its TLS private key and enforcement state from the agent.
It can verify that it's talking to the right **supervisor**, but it can't
impersonate one.

If the **supervisor** disconnects, the **sandbox** freezes the agent. The same
**supervisor** process can reconnect and resume it within the recovery window.
Expand Down
12 changes: 7 additions & 5 deletions docs/how-it-works/providers/google.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,7 @@ The `google-cloud` provider gives sandboxes native GCP credentials so
any Google Cloud SDK works out of the box — Cloud Storage, BigQuery, Drive,
Maps, Discovery Engine, or any other GCP API. A GCE metadata server emulator
on loopback provides credential placeholders that the
sandbox proxy resolves to real tokens at request time. The sandbox process
never holds a real GCP credential.
sandbox proxy resolves to real tokens at request time.

## Quick Start

Expand Down Expand Up @@ -131,7 +130,7 @@ When a sandbox starts with the `google-cloud` provider attached:
2. The sandbox relays HTTP requests to the reserved `127.0.0.1:8174`
metadata endpoint over its authenticated supervisor connection. The
supervisor emulates the GCE instance metadata API and serves credential
placeholders to GCP SDKs. Real access tokens remain in the supervisor.
placeholders to GCP SDKs. The emulator does not return real access tokens.
3. When the SDK makes an API call, it sends the placeholder in the
`Authorization` header. The sandbox proxy TLS-terminates the
outbound connection, resolves the placeholder to the real token,
Expand All @@ -143,8 +142,11 @@ When a sandbox starts with the `google-cloud` provider attached:
Configuration values (`project_id`, `region`, `service_account_email`)
are **visible in plain text** inside the sandbox — they appear as
environment variables and are served by the metadata endpoint. These are
non-secret identifiers, not credentials. Access tokens are never exposed;
only placeholders reach the sandbox process.
non-secret identifiers, not credentials. The metadata endpoint returns
placeholders in place of access tokens. Credential injection does not
automatically scrub tokens from upstream responses. See
[How Credential Injection Works](/how-it-works/providers/overview#how-credential-injection-works)
for credential delivery and response-handling limits.

The emulator supports Linux sandboxes using the Docker, Podman, Kubernetes,
and VM runtimes. Windows/MXC does not provide this metadata endpoint. SDKs must
Expand Down
5 changes: 4 additions & 1 deletion docs/how-it-works/providers/profiles.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,9 +71,12 @@ A request can use a static credential only when all of these checks pass:
| The calling binary and destination are allowed. | Effective sandbox network policy. |
| The host, port, and canonical request path match the credential binding. | Provider profile endpoints, or an explicit sandbox policy binding for an endpointless profile. |
| The request location matches declared placement, the default `Authorization` header, or an explicit body/WebSocket rewrite policy. | The credential's `auth_style` and its header, query parameter, or path template. |
| The HTTP method, path, or protocol operation is allowed when L7 inspection is configured. | Effective sandbox network policy. |
| The HTTP method, path, or protocol operation is allowed when L7 inspection uses `enforcement: enforce`. | Effective sandbox network policy. |
| The credential has not expired. | Provider credential expiry metadata. |

With `enforcement: audit`, request-rule violations are logged and forwarded.
Credential binding, placement, and expiry checks still apply.

Network policy and credential binding serve different purposes. Network policy
authorizes traffic. A credential binding authorizes use of one provider
instance's credentials at an admitted endpoint. A credential binding cannot
Expand Down
Loading