Content Security Policy (CSP) is a web security standard that helps prevent\ncontent injection attacks by restricting the sources from which content can be\nloaded. It plays an important role in a comprehensive security strategy.
\nFor configuration instructions in a Django project, see the Using CSP documentation. For an HTTP guide about CSP, see the MDN Guide on\nCSP.
\nThe Content-Security-Policy specification\ndefines two complementary headers:
\nContent-Security-Policy: Enforces the CSP policy, blocking content that\nviolates the defined directives.
Content-Security-Policy-Report-Only: Reports CSP violations without\nblocking content, allowing for non-intrusive testing.
Each policy is composed of one or more directives and their values, which\ntogether instruct the browser on how to handle specific types of content.
\nWhen the ContentSecurityPolicyMiddleware is\nenabled, Django automatically builds and attaches the appropriate headers to\neach response based on the configured settings, unless\nthey have already been set by another layer.
The ContentSecurityPolicyMiddleware is\nconfigured using the following settings:
SECURE_CSP: defines the enforced Content Security Policy.
SECURE_CSP_REPORT_ONLY: defines a report-only Content Security\nPolicy.
When a CSP violation occurs, browsers typically log details to the developer\nconsole, providing immediate feedback during development. To also receive these\nreports programmatically, the policy must include a reporting directive\nsuch as report-uri that specifies where violation data should be sent.
Django supports configuring these directives via the\nSECURE_CSP_REPORT_ONLY settings, but reports will only be issued by\nthe browser if the policy explicitly includes a valid reporting directive.
Django does not provide built-in functionality to receive, store, or process\nviolation reports. To collect and analyze them, you must implement your own\nreporting endpoint or integrate with a third-party monitoring service.
\nDjango provides predefined constants representing common CSP source expression\nkeywords such as 'self', 'none', and 'unsafe-inline'. These\nconstants are intended for use in the directive values defined in the settings.
They are available through the CSP enum, and using\nthem is recommended over raw strings. This helps avoid common mistakes such as\ntypos, improper quoting, or inconsistent formatting, and ensures compliance\nwith the CSP specification.
Enum providing standardized constants for common CSP source expressions.
\nRepresents 'none'. Blocks loading resources for the given directive.
Represents 'report-sample'. Instructs the browser to include a sample\nof the violating code in reports. Note that this may expose sensitive\ndata.
Represents 'self'. Allows loading resources from the same origin\n(same scheme, host, and port).
Represents 'strict-dynamic'. Allows execution of scripts loaded by a\ntrusted script (e.g., one with a valid nonce or hash), without needing\n'unsafe-inline'.
Represents 'unsafe-eval'. Allows use of eval() and similar\nJavaScript functions. Strongly discouraged.
Represents 'unsafe-hashes'. Allows inline event handlers and some\njavascript: URIs when their content hashes match a policy rule.\nRequires CSP Level 3+.
Represents 'unsafe-inline'. Allows execution of inline scripts,\nstyles, and javascript: URLs. Generally discouraged, especially for\nscripts.
Represents 'wasm-unsafe-eval'. Permits compilation and execution of\nWebAssembly code without enabling 'unsafe-eval' for scripts.
Django-specific placeholder value ("<CSP_NONCE_SENTINEL>") used in\nscript-src or style-src directives to activate nonce-based CSP.\nThis string is replaced at runtime by the\nContentSecurityPolicyMiddleware with a\nsecure, random nonce that is generated for each request. See detailed\nexplanation in Nonce usage.
Django provides decorators to control the Content Security Policy headers on a\nper-view basis. These allow overriding or disabling the enforced or report-only\npolicy for specific views, providing fine-grained control when the global\nsettings are not sufficient. Applying these overrides fully replaces the base\nCSP: they do not merge with existing rules. They can be used alongside the\nconstants defined in CSP.
Overrides the Content-Security-Policy header for the decorated view\nusing directives in the same format as the SECURE_CSP setting.
The config argument must be a mapping with the desired CSP directives.\nIf config is an empty mapping ({}), no CSP enforcement header will\nbe added to the response returned by that view, effectively disabling CSP\nfor that view.
Examples:
\nfrom django.http import HttpResponse\nfrom django.utils.csp import CSP\nfrom django.views.decorators.csp import csp_override\n\n\n@csp_override(\n {\n "default-src": [CSP.SELF],\n "img-src": [CSP.SELF, "data:"],\n }\n)\ndef my_view(request):\n return HttpResponse("Custom Content-Security-Policy header applied")\n\n\n@csp_override({})\ndef my_other_view(request):\n return HttpResponse("No Content-Security-Policy header added")\nOverrides the Content-Security-Policy-Report-Only header for the\ndecorated view using directives in the same format as the\nSECURE_CSP_REPORT_ONLY setting.
Like csp_override(), the config argument must be a mapping with\nthe desired CSP directives. If config is an empty mapping ({}), no\nCSP report-only header will be added to the response returned by that view,\neffectively disabling report-only CSP for that view.
Examples:
\nfrom django.http import HttpResponse\nfrom django.utils.csp import CSP\nfrom django.views.decorators.csp import csp_report_only_override\n\n\n@csp_report_only_override(\n {\n "default-src": [CSP.SELF],\n "img-src": [CSP.SELF, "data:"],\n "report-uri": "https://mysite.com/csp-report/",\n }\n)\ndef my_view(request):\n return HttpResponse("Custom Content-Security-Policy-Report-Only header applied")\n\n\n@csp_report_only_override({})\ndef my_other_view(request):\n return HttpResponse("No Content-Security-Policy-Report-Only header added")\nThe examples above assume function-based views. For class-based views, see the\nguide for decorating class-based views.
\nA CSP nonce («number used once») is a unique, random value generated per HTTP\nresponse. Django supports nonces as a secure way to allow specific inline\n<script> or <style> elements to execute without relying on\n'unsafe-inline'.
Nonces are enabled by including the special placeholder\nNONCE in the relevant directive(s) of your\nCSP settings, such as script-src or style-src.\nWhen present, the\nContentSecurityPolicyMiddleware\nwill generate a nonce and insert the corresponding nonce-<value> source\nexpression into the CSP header.
To use this nonce in templates, the\ncsp() context processor needs to be\nenabled. It adds a csp_nonce variable to the template context.
For inline <script> and <style> elements, include the nonce directly\nusing the context variable:
<script nonce="{{ csp_nonce }}">\n // This inline JavaScript will be allowed.\n</script>\nFor external <script src="..."> and <link rel="stylesheet"> elements,\nuse the csp_nonce_attr template tag:
<script src="/path/to/script.js" {% csp_nonce_attr %}></script>\n<link rel="stylesheet" href="/path/to/style.css" {% csp_nonce_attr %}>\nTo render a Media object’s assets with the nonce\napplied, pass the object to the csp_nonce_attr template tag:
{% csp_nonce_attr form.media %}\nThe browser will only execute inline elements that include a nonce=<value>\nattribute matching the one specified in the Content-Security-Policy (or\nContent-Security-Policy-Report-Only) header. This mechanism provides\nfine-grained control over which inline code is allowed to run.
If a template includes the CSP nonce but the policy does not include\nNONCE, the HTML will include a nonce attribute,\nbut the header will lack the required source expression. In this case, the\nbrowser will block the inline script or style (or report it for report-only\nconfigurations).
Django’s nonce generation is lazy: the middleware only generates a nonce if\n{{ csp_nonce }} is accessed during template rendering. This avoids\nunnecessary work for pages that do not use nonces.
However, because nonces must be unique per request, extra care is needed when\nusing full-page caching (e.g., Django’s cache middleware, CDN caching). Serving\ncached responses with previously generated nonces may result in reuse across\nusers and requests. Although such responses may still appear to work (since the\nnonce in the CSP header and HTML content match), reuse defeats the purpose of\nthe nonce and weakens security.
\nTo ensure nonce-based policies remain effective:
\nAvoid caching full responses that include {{ csp_nonce }} or\ncsp_nonce_attr.
If caching is necessary, use a strategy that injects a fresh nonce on each\nrequest, or consider refactoring your application to avoid inline scripts and\nstyles altogether.