Skip to content

docs(sensitive-data): Overhaul docs around HTTP headers #15616

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

Open
wants to merge 6 commits into
base: master
Choose a base branch
from
+28 −5
Open

docs(sensitive-data): Overhaul docs around HTTP headers #15616

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
93abbcf
docs(sensitive-data): Overhaul docs around HTTP headers
s1gr1d Nov 24, 2025
40b6461
review suggestions, cookie addition
s1gr1d Nov 25, 2025
0a6327d
add set-cookie
s1gr1d Nov 25, 2025
a1645ee
add pwd
s1gr1d Nov 25, 2025
fa41ef3
Update develop-docs/sdk/expected-features/data-handling.mdx
s1gr1d Nov 25, 2025
7885c84
make sentence more clear
s1gr1d Nov 25, 2025
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
30 changes: 26 additions & 4 deletions develop-docs/sdk/expected-features/data-handling.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 been sent by the SDK, regardless of any config:

- 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", "key", "jwt", "bearer", "sso", "saml", "crsf", "xsrf", "credentials"]`
Copy link

@cursor cursor bot Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: CSRF misspelled as CRSF in sensitive header list

The sensitive header matching list includes "crsf" instead of "csrf". Since SDKs perform partial case-insensitive matching against this list to filter sensitive headers, the misspelling means headers containing csrf won't be detected and filtered. This allows CSRF tokens to be sent unfiltered to Sentry, exposing sensitive security credentials that should always be replaced with "[Filtered]".

Fix in Cursor Fix in Web

Copy link
Member

@cleptric cleptric Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- The SDK performs a **partial, case-insensitive match** against the following headers to determine if they are sensitive: `["auth", "token", "secret", "password", "passwd", "key", "jwt", "bearer", "sso", "saml", "crsf", "xsrf", "credentials"]`
- The SDK performs a **partial, case-insensitive match** against the following headers to determine if they are sensitive: `["auth", "token", "secret", "password", "passwd", "key", "jwt", "bearer", "sso", "saml", "csrf", "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.
Comment on lines +20 to +30
Copy link

@sentry sentry bot Nov 25, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bug: Contradictory guidance on HTTP header filtering leads to inconsistent SDK implementations.
Severity: CRITICAL | Confidence: High

🔍 Detailed Analysis

The documentation provides contradictory guidance on HTTP header filtering, specifically regarding the send_default_pii setting. Statement 1 (lines 16-19) mandates unconditional filtering for HTTP headers, while Statement 2 (lines 24-30) describes conditional filtering based on send_default_pii. Furthermore, Statement 3 (lines 44-57) treats cookies (which are HTTP headers) as conditionally filtered. This inconsistency will lead to divergent SDK implementations, where some SDKs might always filter headers, and others might filter them conditionally, resulting in inconsistent data handling across platforms.

💡 Suggested Fix

Clarify whether HTTP header filtering, including cookies, is always unconditional or if it depends on the send_default_pii setting. Ensure all related sections provide a unified and unambiguous rule.

🤖 Prompt for AI Agent 
Review the code at the location below. A potential bug has been identified by an AI
agent.
Verify if this is a real issue. If it is, propose a fix; if not, explain why it's not
valid.

Location: develop-docs/sdk/expected-features/data-handling.mdx#L16-L30

Potential issue: The documentation provides contradictory guidance on HTTP header
filtering, specifically regarding the `send_default_pii` setting. Statement 1 (lines
16-19) mandates unconditional filtering for HTTP headers, while Statement 2 (lines
24-30) describes conditional filtering based on `send_default_pii`. Furthermore,
Statement 3 (lines 44-57) treats cookies (which are HTTP headers) as conditionally
filtered. This inconsistency will lead to divergent SDK implementations, where some SDKs
might always filter headers, and others might filter them conditionally, resulting in
inconsistent data handling across platforms.

Did we get this right? 👍 / 👎 to inform future reviews.
Reference ID: 3516138

- 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`
Expand All @@ -33,6 +41,20 @@ 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 cookies 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.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.
Expand Down
2 changes: 1 addition & 1 deletion develop-docs/sdk/expected-features/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <Link to="/sdk/telemetry/traces/#tracepropagationtargets">tracePropagationTargets</Link>.
- 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. `Cookie` and `Set-Cookie`) are included, their values must be replaced with `"[Filtered]"` (also see <Link to="/sdk/expected-features/data-handling/#sensitive-data">Data Handling: Sensitive Data</Link>).

The HTTP Client integration should capture error events with the following properties:

Expand Down
Loading