diff --git a/develop-docs/sdk/expected-features/data-handling.mdx b/develop-docs/sdk/expected-features/data-handling.mdx index 1baa2c467d275..ce3ff617af9e3 100644 --- a/develop-docs/sdk/expected-features/data-handling.mdx +++ b/develop-docs/sdk/expected-features/data-handling.mdx @@ -13,13 +13,21 @@ In the event that API returns data considered PII, we guard that behind a flag c This is an option in the SDK called [_send-default-pii_](https://docs.sentry.io/platforms/python/configuration/options/#send-default-pii) and is **disabled by default**. That means that data that is naturally sensitive is not sent by default. -Some examples of data guarded by this flag: +Certain sensitive data must never be sent through SDK instrumentation, regardless of any configuration: + +- HTTP Headers: The keys of known sensitive headers are added, while their values must be replaced with `"[Filtered]"`. + - The SDK performs a **partial, case-insensitive match** against the following headers to determine if they are sensitive: `["auth", "token", "secret", "password", "passwd", "pwd", "key", "jwt", "bearer", "sso", "saml", "crsf", "xsrf", "credentials"]` + +SDKs should only replace sensitive data with `"[Filtered]"` when the data is gathered automatically through instrumentation. +If a user explicitly provides data (for example, by setting a request object on the scope), the SDK must not modify it. + +Some examples of data guarded by `send_default_pii: false`: - When attaching data of HTTP requests and/or responses to events - - Request Body: "raw" HTTP bodies (bodies which cannot be parsed as JSON or formdata) are removed - - HTTP Headers: known sensitive headers such as `Authorization` or `Cookie` are removed too. + - Request Body: "raw" HTTP bodies (bodies which cannot be parsed as JSON or FormData) are removed + - HTTP Headers: header values, containing information about the user are replaced with `"[Filtered]"` - _Note_ that if a user explicitly sets a request on the scope, nothing is stripped from that request. The above rules only apply to integrations that come with the SDK. -- User-specific information (e.g. the current user ID according to the used web-framework) is not sent at all. +- User-specific information (e.g. the current user ID according to the used web-framework) is not collected and therefore not sent at all. - On desktop applications - The username logged in the device is not included. This is often a person's name. - The machine name is not included, for example `Bruno's laptop` @@ -33,6 +41,21 @@ Before sending events to Sentry, the SDKs should invokes callbacks. That allows - [`before-send` and `event-processors`](/sdk/miscellaneous/unified-api/#static-api) can be used to register a callback with custom logic to remove sensitive data. +### Cookies + +Since `Cookie` and `Set-Cookie` headers can contain a mix of sensitive and non-sensitive data, SDKs should parse the cookie header and filter values on a per-key basis, depending on the SDK setting and the sensitivity of the cookie value. +In case, the SDK cannot parse each cookie key-value pair, the entire cookie header must be replaced with `"[Filtered]"`. An unfiltered, raw cookie header value must never be sent. + +This selective filtering prevents capturing sensitive data while retaining harmless contextual information for debugging. +For example, a sensitive session cookie's value is replaced with "[Filtered]", but a non-sensitive theme cookie can be sent as-is. + +When attached as span attributes, the results should be as follows: + +- `http.request.header.cookie.user_session: "[Filtered]"` +- `http.request.header.cookie.theme: "dark-mode"` +- `http.request.header.set_cookie.theme: "light-mode"` +- `http.request.header.cookie: "[Filtered]"` (Used as a fallback if the cookie header cannot be parsed) + ### Application State App state can be critical to help developers reproduce bugs. For that reason, SDKs often collect app state and append to events through auto instrumentation. diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 2e6372a2b8a14..e87e880249a61 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -361,7 +361,7 @@ The HTTP Client integration should have 3 configuration options: - If the language has a `Range` type, it should be used instead of `HttpStatusCodeRange`. - `failedRequestTargets` defaults to (`.*`), this configuration option accepts a `List` of `String` that may be Regular expressions as well, similar to tracePropagationTargets. - The SDK will only capture HTTP Client errors if the HTTP Request URL is a match for any of the `failedRequestsTargets`. -- sensitive `headers` should only be set if `sendDefaultPii` is enabled, e.g. `Cookie` and `Set-Cookie`. +- While the keys of sensitive HTTP headers (e.g. `Authorization` and `Cookie`) are included, their values must be replaced with `"[Filtered]"` (also see Data Handling: Sensitive Data). The HTTP Client integration should capture error events with the following properties: