Skip to content

The django-csp 4.x refactor

Published: at 08:00 PM

Ensuring robust web security is a fundamental concern for any web application, and a Content Security Policy (CSP) is a powerful tool in mitigating risks like Cross-Site Scripting (XSS) and data injection attacks. As a Python developer working extensively with Django, I’ve recently undertaken a significant refactor of the django-csp library — a third-party tool designed to streamline the implementation of CSP headers in Django projects.

In this post, I’ll share the journey behind this refactor, exploring the motivations and the improvements to the django-csp 4.0 release.

Before we dive into the details of the recent refactor, let’s refresh ourselves on what Content Security Policy (CSP) is and why it is important.

Overview of CSP

Content Security Policy (CSP) is a critical security standard designed to prevent various types of attacks, such as Cross-Site Scripting (XSS) and data injection attacks, by restricting the sources from which content can be loaded on a web page. In today’s web landscape, security is paramount, and CSP provides a robust layer of defense by allowing developers to specify approved content sources. This significantly reduces the risk of malicious content being executed on your site. For example, XSS attacks, which CSP helps mitigate, account for a large portion of web security incidents.

CSP works by defining policies that control the loading of resources on a web page. These policies are delivered via HTTP headers or <meta> tags in HTML. A typical CSP header might look like this:

Content-Security-Policy: default-src 'self'; script-src 'self'

This policy specifies that, by default, only resources from the same origin (‘self’) are allowed, and scripts can only be loaded from the same origin or from This mechanism not only helps in preventing the execution of malicious scripts but also in enforcing strict content policies to safeguard the web application.

Overview of django-csp

The django-csp library is designed to simplify the implementation of CSP in Django applications. django-csp integrates with Django’s settings allowing developers to configure their CSP policies directly in the file, making the management of security policies straightforward and centralized. By defining the CSP directives in the settings, such as specifying approved sources for scripts, styles, and other resources, developers can easily tailor the security policy to meet the specific needs of their application. Once configured, django-csp uses middleware to automatically add the appropriate CSP headers to every response generated by the Django application. This approach ensures that the security policies are consistently enforced across all responses.

State of the django-csp Project

The django-csp project began in 2010, making it a 14-year-old project that has seen various maintainers over its lifetime. During this period, the Content Security Policy (CSP) specification itself has evolved significantly, progressing from version 1 to version 3. This evolution reflects the growing and changing needs of web security practices.

The project eventually found itself without a maintainer and the need for a dedicated maintainer who actively uses django-csp in their work became apparent. This person would be motivated to keep the project up-to-date and also have firsthand experience with its practical applications and limitations.

Motivation for the Refactor

There was a growing interest in integrating parts of the django-csp codebase into Django core. However, a critical blocking issue was the inability to support both an enforced CSP header and a report-only header simultaneously, due to the limitations in the existing settings configuration.

This limitation was a significant roadblock for many users who needed the capability to deploy CSP policies in a report-only mode alongside enforced policies. The existing codebase didn’t allow for this dual-header configuration, making it difficult to test and monitor CSP policies without fully enforcing them, which is a best practice for gradually tightening security measures.

Goals of the Refactor

The primary goal of the refactor was to address these issues and modernize the settings configuration to better align with Django core’s common settings. My aims are to:


I am actively working on django-csp. The above changes were merged in django-csp PR 219. The main branch and upcoming release are backwards incompatible. 😨 As such, it will require re-configuring your Django project’s settings upon upgrade. I’ve written a django-csp 4.0 migration guide that will hopefully help walk through the changes.

Assuming Django core would like to add native CSP support, it would be ideal if both Django and the django-csp package shared the same configuration. To that end, I’ve opened a pull request proposing the addition of CSP to Django, with the hope that the configuration can be solidified before the release of django-csp 4.0. If the settings configuration can be aligned, it would ease the transition for projects currently utilizing django-csp when they eventually migrate to Django’s built-in CSP capabilities.

To achieve this alignment, the django-csp project may release a series of alpha versions. This iterative development approach will allow for continuous refinement and ensure that the final solution meets the needs of the broader community.

During the iterative development process, community involvement is highly desired. I encourage interested developers to actively participate by testing the alpha versions and providing feedback on their experience. Identifying potential bugs or areas for improvement during these early releases will be helpful in shaping the final solution. Your input and insights will ensure that it addresses the real-world needs and challenges faced by developers using django-csp. 🙏