Refs #36532 - Added CSP view decorators. #19680

robhudson · 2025-07-28T17:15:01Z

Trac ticket number

ticket-36532

Branch description

This adds view decorators for adjusting the CSP configuration per-view.

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.
I have added or updated relevant tests.
I have added or updated relevant docs, including release notes if applicable.
I have attached screenshots in both light and dark modes for any UI changes.

nessita

Amazing start, thank you @robhudson! 🌟

I added an initial comment regarding API design, once we settled that I'll go deeper in tests and docs.

nessita · 2025-07-31T15:08:07Z

django/middleware/csp.py

-        for header, config in [
-            (CSP.HEADER_ENFORCE, settings.SECURE_CSP),
-            (CSP.HEADER_REPORT_ONLY, settings.SECURE_CSP_REPORT_ONLY),
+        for config, header, disabled in [


Small nitpick, could we keep the previous order, adding the disabled at the end?

Suggested change

for config, header, disabled in [

for header, config, disabled in [

I switched it to match the order it is being used in the conditional within this loop. This wasn't an arbitrary change I just felt it read better with the 3 conditionals after following the same order.

That order could be discussed too, but I feel like config makes sense first. The header not in response and the not disabled could be swapped with the assumption that using the decorators would happen more often than a custom header set in the view.

I'm open to however you'd like to tweak these but thought I'd share my thought process.

nessita · 2025-07-31T15:09:27Z

django/views/decorators/csp.py

+from asgiref.sync import iscoroutinefunction
+
+
+def csp_override(config, enforced=True, report_only=True):


Did you consider providing two independent decorators? perhaps this is a nicer API?
What I like is that there is a clear separation of concerns, and if both config need tweak, both decorators can be used. What's unclear is whether we could reuse code between the two definitions... I'm torn about code dup with the benefit of clear separation vs DRY and an arguably less clean API.

I'm inclined to split them given that we have two separated settings for these. What do you think?

Suggested change

def csp_override(config, enforced=True, report_only=True):

def csp_override(config):

def decorator(view_func):

@wraps(view_func)

async def _wrapped_async_view(request, *args, **kwargs):

response = await view_func(request, *args, **kwargs)

response._csp_config = config

return response

@wraps(view_func)

def _wrapped_sync_view(request, *args, **kwargs):

response = view_func(request, *args, **kwargs)

response._csp_config = config

return response

# Determine whether to wrap as async or sync function

if iscoroutinefunction(view_func):

return _wrapped_async_view

return _wrapped_sync_view

return decorator

def csp_override_report_only(config):

def decorator(view_func):

@wraps(view_func)

async def _wrapped_async_view(request, *args, **kwargs):

response = await view_func(request, *args, **kwargs)

response._csp_config_ro = config

return response

@wraps(view_func)

def _wrapped_sync_view(request, *args, **kwargs):

response = view_func(request, *args, **kwargs)

response._csp_config_ro = config

return response

# Determine whether to wrap as async or sync function

if iscoroutinefunction(view_func):

return _wrapped_async_view

return _wrapped_sync_view

return decorator

It was slightly mentioned in the original PR here:
#18215 (review)

It's hard to think of what the most common use case would be. For disabling the CSP on a view altogether I would imagine it would be more common to want to disable both the enforced and report-only. So having a single decorator makes that nice, otherwise you'd have to stack 2 decorators.

For the overrides I'm not sure. You may be overriding the CSP for the report-only header perhaps, but then why not use the setting? It's likely you'd want to override both as well I imagine since there's something in the view + template that needs the override and needs to override both.

I do think there's a valid argument that they are separate headers so they should be separate decorators. But I also think the context of the view + template typically sharing the same needs for both headers also sways the argument a bit towards being a single decorator.

Curious what your further thoughts are.

Thank you for your follow up comments. I've been thinking about this and I have also chatted with Sarah to get a third maintainer's perspective. Since the comment is long and relevant for future readers, I will post as a PR-level comment instead of a diff-level comments since the latter are easier to miss.

nessita · 2025-07-31T15:47:42Z

docs/releases/6.0.txt

@@ -70,6 +70,10 @@ The resulting ``Content-Security-Policy`` header would be set to:

    default-src 'self'; script-src 'self' 'nonce-SECRET'; img-src 'self' https:

+Per-view policy customization with can be achieved via the


Suggested change

Per-view policy customization with can be achieved via the

Per-view policy customization can be achieved via the

nessita · 2025-08-08T16:41:54Z

Notes about CSP decorators design.

(This summary has been written with the assistance of AI to ensure all POVs are included and phrased with as much clarity as possible.)

There have been ongoing conversations about whether to use combined or separate decorators for CSP enforcement and report_only overrides. Rob shared his perspective, which I carefully considered, and also consulted with Sarah to gather a Fellows-wide perspective. The summary of that discussion and conclusions is detailed below.

Rob pointed out that disabling CSP entirely on a view likely involves both enforced and report_only headers, so a single decorator simplifies that use case. For overriding policies, he feels that since view and template contexts usually share the same needs for both headers, a single decorator is often more practical. However, he acknowledged that the headers are separate concerns, which supports having distinct decorators in alignment with having two separated settings.

After discussing with Sarah, we considered the trade-offs between having a single csp_override decorator with boolean flags for enforced and report_only, versus separate decorators for enforced and report_only overrides.

Pros of the unified decorator:

Fewer decorators to remember or import.
Single decorator call can override both headers when they share the same config.

Cons/concerns:

The default behavior considering both booleans being True means a simple call might unintentionally override both enforced and report_only policies, which could lead to subtle security or debugging issues if the user only intended to override one.
When a user wants to override only the report_only policy (which is common for testing new policies or policy changes), they must explicitly set enforced=False to avoid overriding the enforced header, adding some cognitive overhead.
Since enforced and report_only policies are configured independently in settings, having separate decorators better reflects this separation and reduces the chance of user error.

Other points:

We intentionally do not validate CSP directives in middleware or decorators. An invalid report_only config, like missing report-uri, won't error in Django but may cause browser issues or defeat the purpose of the report_only CSP. Similarly, using the same config for both headers can also add report_only-only directives (e.g., report-uri) to the enforced header, potentially causing problems or unexpected results.

This makes it important to keep overrides clear and explicit by using separate decorators for enforced and report_only policies, avoiding misconfiguration.

Using two decorators can still allows for simpler and safer usage in typical cases, e.g.:

@csp_override(config1)
@csp_override_report_only(config2)
def my_view(request):
    ...

even if the config is the same:

my_policy = {...}

@csp_override(my_policy)
@csp_override_report_only({**my_policy, "report-uri": "/csp-report-endpoint/"})
def my_view(request):
    ...

Because of the above, the suggestion is to split csp_override into two decorators: one for enforced and one for report_only overrides, for clarity, reduced chance of accidental overrides, and better alignment with the independent settings and typical usage patterns. The boolean flags approach is workable but has subtle usability risks.

Thanks again for your work on this! Happy to discuss further or help with refactoring if desired.

robhudson force-pushed the add-csp-decorators branch 4 times, most recently from e8b5379 to a12f683 Compare July 30, 2025 16:02

Refs #36532 - Added CSP view decorators.

901752b

robhudson force-pushed the add-csp-decorators branch from a12f683 to 901752b Compare July 30, 2025 17:19

robhudson changed the title ~~Refs #15727 - Added CSP view decorators.~~ Refs #36532 - Added CSP view decorators. Jul 30, 2025

nessita reviewed Jul 31, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Refs #36532 - Added CSP view decorators. #19680

Refs #36532 - Added CSP view decorators. #19680

Uh oh!

robhudson commented Jul 28, 2025 •

edited

Loading

Uh oh!

nessita left a comment

Uh oh!

nessita Jul 31, 2025

Uh oh!

robhudson Aug 3, 2025

Uh oh!

nessita Jul 31, 2025

Uh oh!

robhudson Aug 3, 2025

Uh oh!

nessita Aug 8, 2025

Uh oh!

nessita Jul 31, 2025

Uh oh!

nessita commented Aug 8, 2025

Uh oh!

Uh oh!

	for config, header, disabled in [
	for header, config, disabled in [

		from asgiref.sync import iscoroutinefunction


		def csp_override(config, enforced=True, report_only=True):

-def csp_override(config, enforced=True, report_only=True):
+def csp_override(config):
+    def decorator(view_func):
+        @wraps(view_func)
+        async def _wrapped_async_view(request, *args, **kwargs):
+            response = await view_func(request, *args, **kwargs)
+            response._csp_config = config
+            return response
+        @wraps(view_func)
+        def _wrapped_sync_view(request, *args, **kwargs):
+            response = view_func(request, *args, **kwargs)
+            response._csp_config = config
+            return response
+        # Determine whether to wrap as async or sync function
+        if iscoroutinefunction(view_func):
+            return _wrapped_async_view
+        return _wrapped_sync_view
+    return decorator
+def csp_override_report_only(config):
+    def decorator(view_func):
+        @wraps(view_func)
+        async def _wrapped_async_view(request, *args, **kwargs):
+            response = await view_func(request, *args, **kwargs)
+            response._csp_config_ro = config
+            return response
+        @wraps(view_func)
+        def _wrapped_sync_view(request, *args, **kwargs):
+            response = view_func(request, *args, **kwargs)
+            response._csp_config_ro = config
+            return response
+        # Determine whether to wrap as async or sync function
+        if iscoroutinefunction(view_func):
+            return _wrapped_async_view
+        return _wrapped_sync_view
+    return decorator

		@@ -70,6 +70,10 @@ The resulting ``Content-Security-Policy`` header would be set to:

		default-src 'self'; script-src 'self' 'nonce-SECRET'; img-src 'self' https:

		Per-view policy customization with can be achieved via the

	Per-view policy customization with can be achieved via the
	Per-view policy customization can be achieved via the

Uh oh!

Refs #36532 - Added CSP view decorators. #19680

Are you sure you want to change the base?

Refs #36532 - Added CSP view decorators. #19680

Uh oh!

Conversation

robhudson commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Trac ticket number

Branch description

Checklist

Uh oh!

nessita left a comment

Choose a reason for hiding this comment

Uh oh!

nessita Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

robhudson Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

nessita Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

robhudson Aug 3, 2025

Choose a reason for hiding this comment

Uh oh!

nessita Aug 8, 2025

Choose a reason for hiding this comment

Uh oh!

nessita Jul 31, 2025

Choose a reason for hiding this comment

Uh oh!

nessita commented Aug 8, 2025

Notes about CSP decorators design.

Uh oh!

Uh oh!

robhudson commented Jul 28, 2025 •

edited

Loading