Skip to content

docs(security): stop presenting CORS as an XSS defence - #3086

Open
santhiprakash wants to merge 1 commit into
prometheus:mainfrom
santhiprakash:docs/security-cors-not-xss
Open

santhiprakash wants to merge 1 commit into
prometheus:mainfrom
santhiprakash:docs/security-cors-not-xss

Conversation

@santhiprakash

@santhiprakash santhiprakash commented Aug 26, 2026 •

Copy link
Copy Markdown
Contributor

Problem

docs/operating/security.md currently tells operators to set CORS headers such
as Access-Control-Allow-Origin to prevent XSS. That is incorrect: CORS
relaxes the Same-Origin Policy so a browser on another origin can read
responses; it is not an XSS defence.

Reported in #2449. Confirmed still present on current main.

Triage / Root cause

The CORS sentence is in the API Security section and presents CORS as an
XSS control. Maintainers already agreed in #2449 that CORS should not be
mentioned as a defence against XSS.

Fix

Reword the CORS sentence: set CORS if a browser app on another origin should be
allowed to read non-mutating responses; CORS is not an XSS defence.

The Java TLS and crypto/tls link changes that were previously in this branch
have been reverted so this PR stays focused on the CORS wording. They can be
proposed in separate PRs once a repo slot frees.

Issue Number

Fixes #2449

Verification

  • Read docs/operating/security.md on upstream/main — the "to prevent XSS"
    wording was still present.
  • Confirmed the branch diff now contains only the CORS paragraph change.

Notes / Risks

  • Docs-only. No Prometheus server behaviour change.
  • CORS is still documented, just not as an XSS control — operators who actually
    need cross-origin browser access still have the guidance.

@jan--f jan--f left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please keep PRs/commits focused to what the claimed change is.

@santhiprakash
santhiprakash force-pushed the docs/security-cors-not-xss branch from 793ab80 to 1ebfa1a Compare September 23, 2026 15:36
Problem: docs/operating/security.md told operators to set CORS headers
to prevent XSS. CORS relaxes the Same-Origin Policy and is not an XSS
defence (prometheus#2449).

Fix: reword the CORS sentence so it no longer presents CORS as an XSS
control.

Verification: confirmed the stale wording on the target page.
Signed-off-by: Santhi Prakash <b.santhiprakash@gmail.com>
@santhiprakash
santhiprakash force-pushed the docs/security-cors-not-xss branch from 1ebfa1a to 9422f69 Compare September 23, 2026 15:37
@santhiprakash

Copy link
Copy Markdown
Contributor Author

@jan--f Done — I reworked the branch to keep only the CORS wording change and rebased onto current main.

The previous Java TLS and crypto/tls link changes have been reverted, and the commit message / PR body are now scoped to the CORS fix only:

  • Commit: docs(security): stop presenting CORS as an XSS defence
  • PR diff:
--- a/docs/operating/security.md
+++ b/docs/operating/security.md
@@ -211,8 +211,10 @@ may wish to block such paths to prevent CSRF.
 
 For non-mutating endpoints, you may wish to set [CORS
 headers](https://fetch.spec.whatwg.org/#http-cors-protocol) such as
-`Access-Control-Allow-Origin` in your reverse proxy to prevent
-[XSS](https://en.wikipedia.org/wiki/Cross-site_scripting).
+`Access-Control-Allow-Origin` in your reverse proxy if a browser
+application on another origin should be allowed to read those
+responses. CORS relaxes the Same-Origin Policy; it is not a defence
+against [XSS](https://en.wikipedia.org/wiki/Cross-site_scripting).

CI is green and the DCO check passes.

The Java TLS and crypto/tls link points can be split into separate, focused PRs once this one is resolved.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Contrary to what the doc claims, CORS is no defence

2 participants