diff --git a/content/manuals/ai/sandboxes/configuration/credentials.md b/content/manuals/ai/sandboxes/configuration/credentials.md index 3ab366955e1..47cdfe403f6 100644 --- a/content/manuals/ai/sandboxes/configuration/credentials.md +++ b/content/manuals/ai/sandboxes/configuration/credentials.md @@ -440,7 +440,9 @@ the kit handles the wiring; you only provide the value. ### Set a custom secret Custom secrets are global by default. Pass `--sandbox` to scope one to a -specific sandbox. +specific sandbox. Values must be at least eight characters long, including +values returned by dynamic sources. Existing shorter values aren't substituted +and must be replaced with longer values. To read the value from standard input, set `API_KEY` in your host environment and pipe it with `--value-stdin`: @@ -449,6 +451,7 @@ and pipe it with `--value-stdin`: $ printf '%s' "$API_KEY" | sbx secret set-custom \ --host api.example.com \ --env API_KEY \ + --header X-Api-Key \ --value-stdin ``` @@ -464,9 +467,58 @@ to enter the value at a prompt instead. `--value-stdin` can't be combined with Inside the sandbox, `API_KEY` is set to a generated placeholder (for example, `sbx-cs-`). When a sandboxed process sends a request to any of the -configured hosts and the placeholder appears in an HTTP request header, the -proxy replaces it with the real value. Replacement applies only to HTTP request -headers, not request bodies. The agent never sees the real secret. +configured hosts over HTTPS and the placeholder appears in a request header +configured for that secret, the proxy replaces it with the real value. +Replacement applies only to those request headers, not request bodies. + +### Choose request headers + +Use `--header` to name the header your service reads. Repeat the flag to bind +the secret to more than one header. In other headers, the placeholder is sent +unchanged. + +Without `--header`, local custom secrets, including existing secrets without +header bindings, use the headers listed in +[`secret.custom.defaultHeaders`](settings.md#secretcustomdefaultheaders). +If your service uses another header, bind it explicitly. + +Cloud custom secrets use `Authorization` by default instead; see +[cloud credentials](../cloud/credentials.md). + +To change a secret's header bindings, find its placeholder with +`sbx secret ls`, then update only its headers: + +```console +$ sbx secret set-custom --placeholder --header X-Custom-Key +``` + +For a sandbox-scoped secret, include `--sandbox `. This keeps +the value, hosts, environment variable, and dynamic source unchanged. Setting +the secret again without `--header` preserves its existing header bindings. +Alternatively, change the default-header setting for all secrets that follow it. + +Header names are case-insensitive. The CLI rejects invalid names and headers +controlled by the proxy, such as `Host` and `Content-Length`. + +### When a service returns a secret + +A service might include a secret in its response, for example in an error +message that repeats the request headers. When the proxy inserts a custom +secret into a request, it checks the response headers and body and masks +matching secret values before returning the response to the sandbox. It +recognizes the original value and JSON-escaped, percent-encoded, and base64 +forms. + +This filtering cannot guarantee that a secret stays hidden. It doesn't inspect +WebSocket messages or recognize every way a service could transform a secret, +such as splitting it across separate fields. Filtering applies only when the +proxy inserted a custom secret into the request. + +Masking a secret can change the response format and make it unreadable by the +client. + +For these requests, the proxy returns `502 Bad Gateway` instead of forwarding +partial responses (`206`) or responses with unsupported content encodings. ### List custom secrets @@ -488,6 +540,9 @@ Add `--sandbox` to list only matching secrets stored for a specific sandbox: $ sbx secret ls --host api.example.com --sandbox my-sandbox ``` +The header column shows explicit bindings or `(default)` for secrets that +follow the default-header setting. + ### Target multiple hosts Repeat `--host` to cover multiple domains with the same secret — useful when diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index 83be65bba68..6332212317b 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -469,6 +469,31 @@ timestamp from a timestamp authority instead of a transparency log timestamp. Leave this at `false` when your signing workflow uses the public transparency log. It has no effect on signatures verified with a public key. +### Custom secrets + +#### secret.custom.defaultHeaders {.wrap-anywhere} + +{{< setting-metadata type="JSON" + default="[\"Authorization\",\"X-Api-Key\",\"Api-Key\",\"X-Auth-Token\",\"Private-Token\",\"X-Goog-Api-Key\",\"DD-API-KEY\"]" >}} + +Choose the request headers into which the proxy substitutes local custom +secrets stored without explicit header bindings. The value is a JSON array of +HTTP header names. For example, restrict these secrets to `Authorization`: + +```console +$ sbx settings set secret.custom.defaultHeaders '["Authorization"]' +``` + +The array replaces the whole list. Set it to `[]` to require explicit +`sbx secret set-custom --header` bindings: secrets that follow the defaults +aren't substituted into any header. Explicit bindings and cloud custom secrets +aren't affected. See [choose request headers](credentials.md#choose-request-headers) +for binding commands and headers the proxy rejects. + +Changes apply to existing local sandboxes without a restart. If the setting +can't be read or contains an invalid list, secrets that depend on it aren't +substituted until a valid setting can be read again. + ### Model server #### model.server.enabled {.wrap-anywhere}