From 27a922f14f5284cdf7a5b56d9eed4ea01e376c88 Mon Sep 17 00:00:00 2001 From: alangou Date: Tue, 10 Nov 2026 15:38:32 +0100 Subject: [PATCH] docs(security): clarify audit behavior and runtime guarantees Signed-off-by: Adrien Langou --- docs/about/architecture.mdx | 9 +++++---- docs/how-it-works/providers/google.mdx | 12 +++++++----- docs/how-it-works/providers/profiles.mdx | 5 ++++- 3 files changed, 16 insertions(+), 10 deletions(-) diff --git a/docs/about/architecture.mdx b/docs/about/architecture.mdx index 320ed9d700..8a53f1ce90 100644 --- a/docs/about/architecture.mdx +++ b/docs/about/architecture.mdx @@ -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. diff --git a/docs/how-it-works/providers/google.mdx b/docs/how-it-works/providers/google.mdx index 6d5b0c1256..f7f9e1c5f6 100644 --- a/docs/how-it-works/providers/google.mdx +++ b/docs/how-it-works/providers/google.mdx @@ -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 @@ -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, @@ -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 diff --git a/docs/how-it-works/providers/profiles.mdx b/docs/how-it-works/providers/profiles.mdx index 94d668751d..39799e0f45 100644 --- a/docs/how-it-works/providers/profiles.mdx +++ b/docs/how-it-works/providers/profiles.mdx @@ -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