Fixed #15727 -- Added Content Security Policy (CSP) support. #18215

robhudson · 2024-05-30T21:40:54Z

Trac ticket number

ticket-15727

Branch description

This adds CSP support for both the enforced header and report-only header.

There are a number of TODO notes within this PR that I'm looking for feedback on.

Checklist

This PR targets the main branch.
The commit message is written in past tense, mentions the ticket number, and ends with a period.
I have checked the "Has patch" ticket flag in the Trac system (was already set from prior efforts.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.

django/middleware/security.py

docs/spelling_wordlist

django/middleware/security.py

docs/ref/middleware.txt

robhudson · 2024-10-04T23:33:54Z

I refactored the code today after review from Adam.

The middleware is now its own middleware, not part of SecurityMiddleware
Decorators were added. See comment above looking for feedback.
I removed the docs for now but will continue to work on them.

What's left:

Documentation
A context processor test
Possibly a security check to warn if the CSP settings are empty that no CSP headers will be sent
Possibly review what views may need to be exempted from CSP
Possibly review what views want to set their own CSP, but this could come in later commits

robhudson · 2024-11-09T21:21:49Z

I'm going to set this as ready for review. I think it's feature complete for a first that includes the middleware to set the CSP headers, a couple decorators to fine tune the CSP policy for views, and a context processor for accessing the nonce easily.

Inline there are a few TODO comments for further discussion. Feel free to add Github comments on those.

sarahboyce

Hi @robhudson - I think you've not had a review as the PR was not in the review queue (see "Patches that need review" within Reviewing patches)
That's because this ticket currently has "Needs documentation" marked as "yes"

Can you add a release note to Django 5.2, add a couple .. versionadded:: 5.2 notes, and then mark "Needs documentation" as "no" in the ticket so it appears in the review queue?

docs/ref/csp.txt

docs/ref/settings.txt

docs/ref/csp.txt

sarahboyce

Thank you @robhudson - I added initial comments

docs/ref/csp.txt

django/middleware/csp.py

sarahboyce · 2024-12-13T13:51:24Z

django/middleware/csp.py

I think it makes sense to have a security warning, this is a recommendation
We can do that in a separate commit/PR

django/middleware/csp.py

docs/ref/settings.txt

django/views/decorators/csp.py

docs/ref/csp.txt

tests/middleware/test_csp.py

This adds a bullet point about policy exclusion risks. This also orders these points by what I consider highest risk to lowest.

* Reorganizes top-level sections for a more intuitive flow. * Clarifies differences between SECURE_CSP and SECURE_CSP_REPORT_ONLY, including which headers they affect. * Adds detailed information on using nonces in CSP policies.

sarahboyce · 2025-04-09T13:06:21Z

docs/ref/middleware.txt

+   Can be placed near the bottom, but ensure any middleware that accesses ``request.csp_nonce`` is
+   positioned after it, so the nonce is properly included in the response header.


Suggested change

Can be placed near the bottom, but ensure any middleware that accesses ``request.csp_nonce`` is

positioned after it, so the nonce is properly included in the response header.

Before any middleware that accesses ``request.csp_nonce``.

Is there any middle-ware it should be after? Or it doesn't matter if it was first?

Looking at the default list of middleware for a new project, I don't see anything that would affect it being first, since it just reads the settings and writes the header. The only tricky bit is if a nonce is used during content creation will affect whether the nonce is included in the header. So if there's a middleware that updates content in some way related to the nonce (unusual), that middleware would need to go after the CSP middleware.

docs/ref/csp.txt

docs/ref/settings.txt

sarahboyce · 2025-04-09T13:31:41Z

docs/ref/csp.txt

+* Third-party Integration Complexity: If your application relies heavily on
+  third-party scripts or services, implementing a strict CSP can be challenging
+  and may require careful configuration and ongoing maintenance.


I'm not sure we need to document this one

docs/ref/csp.txt

sarahboyce · 2025-04-09T13:36:30Z

docs/ref/csp.txt

I agree let's move this as a subheading within the CSP section for security

sarahboyce · 2025-04-09T13:41:35Z

docs/ref/csp.txt

@@ -0,0 +1,459 @@
+.. _content-security-policy:


I think what should keep in this reference docs:

the CSP enum

the decorators

I think there should be a "how-to" guide which has the

Using CSP (perhaps linking to the decorators or some decorators stuff pulled in)

Nonce Usage

I think the some of the "Limitations and Considerations" should be moved to the CSP security topic
The settings information should mostly be covered by the settings docs

To give some background as to "why", this is within our reference docs and includes quite a bit of how-to and explanation which would normally be within either a how-to or topic. We get feedback that our reference docs are too verbose so we need to try and put stuff in the right places

Point for @nessita, in the how-to doc it would be worth having an example of something that would be blocked (in order to say/show how you can "see" it/test it/understand it while playing out with it)

Leaning towards using a topic rather than a how-to

I think it should be a how-to, like the CSRF one. It'll need to include the how to content on configuring the middleware and using the decorators.

adamchainz

Thank you for your Continuous Sustained Persistence (C.S.P.) here Rob.

I have a few comments here. The only thing I'd change on the design at this point is dropping the DIRECTIVES key, per the below.

django/middleware/csp.py

adamchainz · 2025-04-10T17:47:52Z

django/middleware/csp.py

+        # In DEBUG mode, exclude CSP headers for specific status codes that
+        # trigger the debug view.
+        exempted_status_codes = {
+            http_client.NOT_FOUND,
+            http_client.INTERNAL_SERVER_ERROR,
+        }
+        if settings.DEBUG and response.status_code in exempted_status_codes:
+            return response


FYI, I opened a ticket on the debug view not being CSP-friendly a long time ago: https://code.djangoproject.com/ticket/33180

After this PR is merged, we can work toward using nonces in the debug views, and maybe this workaround can then be dropped.

django/middleware/csp.py

adamchainz · 2025-04-10T23:15:01Z

docs/ref/csp.txt

@@ -0,0 +1,459 @@
+.. _content-security-policy:


I think it should be a how-to, like the CSRF one. It'll need to include the how to content on configuring the middleware and using the decorators.

adamchainz · 2025-04-10T23:19:37Z

docs/ref/csp.txt

The DIRECTIVES key allows room for future CSP wide configuration that aren't directive specific to keep policy logic separate from middleware behavior.

I'm feeling some YAGNI looking at the DIRECTIVES sub-key. I would rather we dropped to just a dict of directives.

The concerns you listed (NONCE_GENERATOR, POLICY_OVERRIDES, and "extensibility") can already be addressed in other ways, such as overriding the middleware or using decorators.

Meanwhile, a sub-key DIRECTIVES prevents the setting from mapping cleanly to the header contents, while analogous security header settings, such as SECURE_REFERRER_POLICY, do. (Although they contain simple string values.) So, having a "just in case" substructure feels slightly less Django-ey.

If we do end up with something else to change beyond the policy directives, we could add another setting or document how to subclass the middleware and swap out the appropriate method. The latter is likely to be preferable for fairly niche features.

adamchainz · 2025-04-11T12:44:03Z

docs/releases/6.0.txt

 What's new in Django 6.0
 ========================

+Content Security Policy (CSP) Support


We don't title-case headings

Suggested change

Content Security Policy (CSP) Support

Content Security Policy (CSP) support

(This comment applies to all titles in the updated docs here.)

adamchainz · 2025-04-11T12:46:13Z

docs/releases/6.0.txt

+Django 6.0 introduces built-in :ref:`Content Security Policy (CSP)
+<security-csp>` support, making it easier to protect your application against
+various types of content injection attacks. CSP helps you specify which content
+sources are allowed to be loaded by the browser.


Suggested change

Django 6.0 introduces built-in :ref:`Content Security Policy (CSP)

<security-csp>` support, making it easier to protect your application against

various types of content injection attacks. CSP helps you specify which content

sources are allowed to be loaded by the browser.

The new built-in :ref:`Content Security Policy (CSP) <security-csp>` support

makes it easier to protect your application against content injection attacks.

CSP is a security standard that allows you to specify which resources browsers

are allowed to load.

We don't normally say "Django " throughout the release notes. Also, I edited for brevity clarity.

adamchainz · 2025-04-11T12:46:41Z

docs/releases/6.0.txt

+* :setting:`SECURE_CSP` for the enforced policy
+* :setting:`SECURE_CSP_REPORT_ONLY` for the report-only policy
+
+Here's an an example of a basic CSP config::


Suggested change

Here's an an example of a basic CSP config::

Here's an an example of a basic CSP configuration::

Use full words wherever possible.

- remove constants and unnecessary comments - use secrets.token_urlsafe for nonce - use HTTPStatus - refactor decorator header check loop - refactor build_policy loop - support sets as CSP setting value

robhudson · 2025-04-12T20:47:50Z

I've addressed all the code-specific feedback discussed so far. My next steps are:

Documentation reorganization: I'll move implementation details from the reference guide into the how-to documentation, keeping ref/csp.txt focused on the technical API specification.

Breaking down the PR: As suggested, I'll split this into smaller, more manageable chunks:

First PR: Middleware with nonce support only (including context processor)
Follow-up PR: CSP Decorators

Update: Since the context processor is for the nonce and the how-to would show configuring the context processor to use in the templates to define where the nonce goes, that will go with the first PR. The follow up will then only be the decorator.

adamchainz · 2025-04-15T22:50:58Z

django/core/checks/security/csp.py

+
+
+@register(Tags.security)
+def check_csp_directives(app_configs, **kwargs):


Suggested change

def check_csp_directives(app_configs, **kwargs):

def check_csp_settings(app_configs, **kwargs):

I think, since we dropped DIRECTIVES

adamchainz · 2025-04-15T22:52:33Z

django/core/checks/security/csp.py

+    "Each enabled CSP setting (SECURE_CSP, SECURE_CSP_REPORT_ONLY) must be a "
+    "dictionary.",


Can we put the setting name in the message? Otherwise, it leaves the user hunting for where the mistake may be. I'm thinking of complex settings configurations where production has a report-only policy separate from some base configuration.

adamchainz · 2025-04-15T22:53:24Z

django/core/checks/security/csp.py

+        # Only validate if the setting is explicitly set (not None or empty dict)
+        if setting_value:
+            if not isinstance(setting_value, dict):
+                errors.append(W026)


Maybe we can do the below, so we still trigger a warning for an empty list and similar falsey values?

Suggested change

# Only validate if the setting is explicitly set (not None or empty dict)

if setting_value:

if not isinstance(setting_value, dict):

errors.append(W026)

if setting_value is not None and not isinstance(setting_value, dict):

errors.append(W026)

robhudson · 2025-04-19T18:04:31Z

A new PR has been filed at #19393

The new PR:

splits this into a smaller reviewable chunk focusing on the middleware and adjacent components.
squashes the commits.
addresses the requested changes to the docs (adding a howto, etc).

robhudson force-pushed the add-csp branch from fbd1a11 to 8164f4a Compare May 30, 2024 22:43

robhudson commented May 30, 2024

View reviewed changes

django/middleware/security.py Outdated Show resolved Hide resolved

robhudson force-pushed the add-csp branch 6 times, most recently from ea4116b to 8edd4a7 Compare August 31, 2024 22:26

adamchainz reviewed Sep 24, 2024

View reviewed changes

docs/spelling_wordlist Outdated Show resolved Hide resolved

django/middleware/security.py Outdated Show resolved Hide resolved

docs/ref/middleware.txt Outdated Show resolved Hide resolved

robhudson force-pushed the add-csp branch 2 times, most recently from a698389 to 62196e7 Compare October 4, 2024 18:56

robhudson force-pushed the add-csp branch 3 times, most recently from e6bd8cd to f53f30e Compare October 18, 2024 23:50

robhudson mentioned this pull request Oct 22, 2024

Upstream changes in django core mozilla/django-csp#135

Open

robhudson force-pushed the add-csp branch 2 times, most recently from d978052 to 40e9097 Compare October 24, 2024 23:15

robhudson force-pushed the add-csp branch from 40e9097 to 39459bc Compare November 9, 2024 20:16

robhudson marked this pull request as ready for review November 9, 2024 21:21

sarahboyce reviewed Dec 11, 2024

View reviewed changes

docs/ref/csp.txt Outdated Show resolved Hide resolved

docs/ref/settings.txt Outdated Show resolved Hide resolved

docs/ref/settings.txt Outdated Show resolved Hide resolved

shangxiao reviewed Dec 12, 2024

View reviewed changes

docs/ref/csp.txt Outdated Show resolved Hide resolved

sarahboyce reviewed Dec 13, 2024

View reviewed changes

RealOrangeOne reviewed Dec 13, 2024

View reviewed changes

docs/ref/csp.txt Outdated Show resolved Hide resolved

docs/ref/csp.txt Outdated Show resolved Hide resolved

docs/ref/csp.txt Outdated Show resolved Hide resolved

tests/middleware/test_csp.py Outdated Show resolved Hide resolved

robhudson force-pushed the add-csp branch 4 times, most recently from 8fe7c1d to d30fab2 Compare December 21, 2024 17:51

robhudson force-pushed the add-csp branch from 77e89b4 to 28ada1c Compare December 31, 2024 01:07

robhudson added 18 commits April 8, 2025 15:31

Rework CSP limitations section

8651045

This adds a bullet point about policy exclusion risks. This also orders these points by what I consider highest risk to lowest.

Word wrap at 80

5977740

Add a CSP section to the 5.2 release notes

338c7fe

Exclude CSP headers from debug views

2aa49bc

Move constants to django.conf

4322d0f

Refactor CSP docs after PR reviews

24c3d4c

* Reorganizes top-level sections for a more intuitive flow. * Clarifies differences between SECURE_CSP and SECURE_CSP_REPORT_ONLY, including which headers they affect. * Adds detailed information on using nonces in CSP policies.

Update CSP middleware with suggestions from @pauloxnet

62e7507

Update middleware tests after previous change

25dc3b6

Rename @csp_exempt to @csp_disabled

24f59c6

Include warning with decorators

727959e

Refactor comprehensive CSP example to be cleaner

191c711

Update versionadded to 6.0 🤞

07a9667

Replace singleton NONCE with a string

e02192d

Add light checks for CSP settings

de7e8ac

Move CSP header constants to middleware

84dcf99

Move CSP constants to middleware/constants.py

b3dcf6b

Document the CSP constants

f7af616

Replace _make_nonce wrapper with LazyNonce

3139cad

robhudson force-pushed the add-csp branch from f62ef7e to 3139cad Compare April 8, 2025 23:09

sarahboyce reviewed Apr 9, 2025

View reviewed changes

adamchainz suggested changes Apr 10, 2025

View reviewed changes

adamchainz reviewed Apr 11, 2025

View reviewed changes

robhudson added 2 commits April 12, 2025 12:13

middleware refactoring based on review feedback

9d7183f

- remove constants and unnecessary comments - use secrets.token_urlsafe for nonce - use HTTPStatus - refactor decorator header check loop - refactor build_policy loop - support sets as CSP setting value

flatten CSP settings dict by removing DIRECTIVES

dae58c3

adamchainz reviewed Apr 15, 2025

View reviewed changes

robhudson closed this Apr 19, 2025

nessita mentioned this pull request Jun 18, 2025

Fixed #15727 -- Added Content-Security-Policy support. #19393

Merged

5 tasks

robhudson mentioned this pull request Aug 3, 2025

Refs #36532 - Added CSP view decorators. #19680

Merged

6 tasks

		Can be placed near the bottom, but ensure any middleware that accesses ``request.csp_nonce`` is
		positioned after it, so the nonce is properly included in the response header.

	Can be placed near the bottom, but ensure any middleware that accesses ``request.csp_nonce`` is
	positioned after it, so the nonce is properly included in the response header.
	Before any middleware that accesses ``request.csp_nonce``.

	Content Security Policy (CSP) Support
	Content Security Policy (CSP) support

	Here's an an example of a basic CSP config::
	Here's an an example of a basic CSP configuration::



		@register(Tags.security)
		def check_csp_directives(app_configs, **kwargs):

	def check_csp_directives(app_configs, **kwargs):
	def check_csp_settings(app_configs, **kwargs):

		"Each enabled CSP setting (SECURE_CSP, SECURE_CSP_REPORT_ONLY) must be a "
		"dictionary.",

Uh oh!

Fixed #15727 -- Added Content Security Policy (CSP) support. #18215

Fixed #15727 -- Added Content Security Policy (CSP) support. #18215

Uh oh!

Conversation

robhudson commented May 30, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trac ticket number

Branch description

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

robhudson commented Oct 4, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

robhudson commented Nov 9, 2024

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sarahboyce left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sarahboyce Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adamchainz left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

robhudson commented May 30, 2024 •

edited

Loading

robhudson commented Oct 4, 2024 •

edited

Loading

sarahboyce Apr 9, 2025 •

edited

Loading

robhudson commented Apr 12, 2025 •

edited

Loading