This document is an overview of Django’s security features. It includes advice\non securing a Django-powered site.
\nThe golden rule of web application security is to never trust user-controlled\ndata. Hence, all user input should be sanitized before being used in your\napplication. See the forms documentation for\ndetails on validating user inputs in Django.
\nXSS attacks allow a user to inject client side scripts into the browsers of\nother users. This is usually achieved by storing the malicious scripts in the\ndatabase where it will be retrieved and displayed to other users, or by getting\nusers to click a link which will cause the attacker’s JavaScript to be executed\nby the user’s browser. However, XSS attacks can originate from any untrusted\nsource of data, such as cookies or web services, whenever the data is not\nsufficiently sanitized before including in a page.
\nUsing Django templates protects you against the majority of XSS attacks.\nHowever, it is important to understand what protections it provides\nand its limitations.
\nDjango templates escape specific characters\nwhich are particularly dangerous to HTML. While this protects users from most\nmalicious input, it is not entirely foolproof. For example, it will not\nprotect the following:
\n<style class={{ var }}>...</style>\nIf var is set to 'class1 onmouseover=javascript:func()', this can\nresult in unauthorized JavaScript execution, depending on how the browser\nrenders imperfect HTML. (Quoting the attribute value would fix this case.)
It is also important to be particularly careful when using is_safe with\ncustom template tags, the safe template tag, mark_safe, and when autoescape is turned off.
In addition, if you are using the template system to output something other\nthan HTML, there may be entirely separate characters and words which require\nescaping.
\nYou should also be very careful when storing HTML in the database, especially\nwhen that HTML is retrieved and displayed.
\nCSRF attacks allow a malicious user to execute actions using the credentials\nof another user without that user’s knowledge or consent.
\nDjango has built-in protection against most types of CSRF attacks, providing\nyou have enabled and used it where appropriate. However, as\nwith any mitigation technique, there are limitations. For example, it is\npossible to disable the CSRF module globally or for particular views. You\nshould only do this if you know what you are doing. There are other\nlimitations if your site has subdomains that are\noutside of your control.
\nCSRF protection works by checking for a secret in each\nPOST request. This ensures that a malicious user cannot “replay” a form POST to\nyour website and have another logged-in user unwittingly submit that form. The\nmalicious user would have to know the secret, which is user specific (using a\ncookie).
\nWhen deployed with HTTPS,\nCsrfViewMiddleware will check that the HTTP referer header is set to a\nURL on the same origin (including subdomain and port). Because HTTPS\nprovides additional security, it is imperative to ensure connections use HTTPS\nwhere it is available by forwarding insecure connection requests and using\nHSTS for supported browsers.
Be very careful with marking views with the csrf_exempt decorator unless\nit is absolutely necessary.
SQL injection is a type of attack where a malicious user is able to execute\narbitrary SQL code on a database. This can result in records\nbeing deleted or data leakage.
\nDjango’s querysets are protected from SQL injection since their queries are\nconstructed using query parameterization. A query’s SQL code is defined\nseparately from the query’s parameters. Since parameters may be user-provided\nand therefore unsafe, they are escaped by the underlying database driver.
\nDjango also gives developers power to write raw queries or execute custom sql.\nThese capabilities should be used sparingly and you should always be careful to\nproperly escape any parameters that the user can control. In addition, you\nshould exercise caution when using\nextra() and\nRawSQL.
Clickjacking is a type of attack where a malicious site wraps another site\nin a frame. This attack can result in an unsuspecting user being tricked\ninto performing unintended actions on the target site.
\nDjango contains clickjacking protection in the\nform of the X-Frame-Options middleware which in a supporting\nbrowser can prevent a site from being rendered inside a frame. It is possible\nto disable the protection on a per view basis or to configure the exact header\nvalue sent.
The middleware is strongly recommended for any site that does not need to have\nits pages wrapped in a frame by third party sites, or only needs to allow that\nfor a small section of the site.
\nIt is always better for security to deploy your site behind HTTPS. Without\nthis, it is possible for malicious network users to sniff authentication\ncredentials or any other information transferred between client and server, and\nin some cases – active network attackers – to alter data that is sent in\neither direction.
\nIf you want the protection that HTTPS provides, and have enabled it on your\nserver, there are some additional steps you may need:
\nIf necessary, set SECURE_PROXY_SSL_HEADER, ensuring that you have\nunderstood the warnings there thoroughly. Failure to do this can result\nin CSRF vulnerabilities, and failure to do it correctly can also be\ndangerous!
Set SECURE_SSL_REDIRECT to True, so that requests over HTTP\nare redirected to HTTPS.
Please note the caveats under SECURE_PROXY_SSL_HEADER. For the\ncase of a reverse proxy, it may be easier or more secure to configure the\nmain web server to do the redirect to HTTPS.
Use ‘secure’ cookies.
\nIf a browser connects initially via HTTP, which is the default for most\nbrowsers, it is possible for existing cookies to be leaked. For this reason,\nyou should set your SESSION_COOKIE_SECURE and\nCSRF_COOKIE_SECURE settings to True. This instructs the\nbrowser to only send these cookies over HTTPS connections. Note that this\nwill mean that sessions will not work over HTTP, and the CSRF protection will\nprevent any POST data being accepted over HTTP (which will be fine if you are\nredirecting all HTTP traffic to HTTPS).
Use HTTP Strict Transport Security (HSTS)
\nHSTS is an HTTP header that informs a browser that all future connections to\na particular site should always use HTTPS. Combined with redirecting requests\nover HTTP to HTTPS, this will ensure that connections always enjoy the added\nsecurity of SSL provided one successful connection has occurred. HSTS may\neither be configured with SECURE_HSTS_SECONDS,\nSECURE_HSTS_INCLUDE_SUBDOMAINS, and\nSECURE_HSTS_PRELOAD, or on the web server.
Django uses the Host header provided by the client to construct URLs in\ncertain cases. While these values are sanitized to prevent Cross Site Scripting\nattacks, a fake Host value can be used for Cross-Site Request Forgery,\ncache poisoning attacks, and poisoning links in emails.
Because even seemingly-secure web server configurations are susceptible to fake\nHost headers, Django validates Host headers against the\nALLOWED_HOSTS setting in the\ndjango.http.HttpRequest.get_host() method.
This validation only applies via get_host();\nif your code accesses the Host header directly from request.META you\nare bypassing this security protection.
For more details see the full ALLOWED_HOSTS documentation.
Additionally, Django requires you to explicitly enable support for the\nX-Forwarded-Host header (via the USE_X_FORWARDED_HOST setting)\nif your configuration requires it.
Browsers use the Referer header as a way to send information to a site\nabout how users got there. By setting a Referrer Policy you can help to\nprotect the privacy of your users, restricting under which circumstances the\nReferer header is set. See the referrer policy section of the\nsecurity middleware reference for details.
The cross-origin opener policy (COOP) header allows browsers to isolate a\ntop-level window from other documents by putting them in a different context\ngroup so that they cannot directly interact with the top-level window. If a\ndocument protected by COOP opens a cross-origin popup window, the popup’s\nwindow.opener property will be null. COOP protects against cross-origin\nattacks. See the cross-origin opener policy section of the security\nmiddleware reference for details.
Similar to the CSRF limitations requiring a site to\nbe deployed such that untrusted users don’t have access to any subdomains,\ndjango.contrib.sessions also has limitations. See the session\ntopic guide section on security for details.
If your site accepts file uploads, it is strongly advised that you limit\nthese uploads in your web server configuration to a reasonable\nsize in order to prevent denial of service (DOS) attacks. In Apache, this\ncan be easily set using the LimitRequestBody directive. You should not rely\nsolely on DATA_UPLOAD_MAX_MEMORY_SIZE\nnor FILE_UPLOAD_MAX_MEMORY_SIZE.
If you are serving your own static files, be sure that handlers like Apache’s\nmod_php, which would execute static files as code, are disabled. You\ndon’t want users to be able to execute arbitrary code by uploading and\nrequesting a specially crafted file.
Django’s media upload handling poses some vulnerabilities when that media is\nserved in ways that do not follow security best practices. Specifically, an\nHTML file can be uploaded as an image if that file contains a valid PNG\nheader followed by malicious HTML. This file will pass verification of the\nlibrary that Django uses for ImageField image\nprocessing (Pillow). When this file is subsequently displayed to a\nuser, it may be displayed as HTML depending on the type and configuration of\nyour web server.
No bulletproof technical solution exists at the framework level to safely\nvalidate all user uploaded file content, however, there are some other steps\nyou can take to mitigate these attacks:
\nOne class of attacks can be prevented by always serving user uploaded\ncontent from a distinct top-level or second-level domain. This prevents\nany exploit blocked by same-origin policy protections such as cross\nsite scripting. For example, if your site runs on example.com, you\nwould want to serve uploaded content (the MEDIA_URL setting)\nfrom something like usercontent-example.com. It’s not sufficient to\nserve content from a subdomain like usercontent.example.com.
Beyond this, applications may choose to define a list of allowable\nfile extensions for user uploaded files and configure the web server\nto only serve such files.
Form submissions containing files are not limited by\nDATA_UPLOAD_MAX_MEMORY_SIZE. Under ASGI, the entire request may be\nspooled to disk before any file size validation is performed. It is strongly\nadvised that you limit the maximum request body size in your web server\nconfiguration to prevent denial of service (DOS) attacks.
Content Security Policy (CSP) is a browser security mechanism that helps\nprotect web applications against attacks such as cross-site scripting (XSS) and\nother content injection attacks.
\nCSP allows web applications to define which sources of content are trusted,\ninstructing the browser to load, execute, or render resources only from those\nsources. This effectively creates an allowlist of content origins, reducing the\nrisk of malicious code execution.
\nKey benefits of enabling CSP include:
\nMitigating XSS attacks by blocking inline scripts and restricting external\nscript loading.
Controlling which external resources (e.g., images, fonts, stylesheets) can\nbe loaded.
Preventing unwanted framing of your site to protect against clickjacking.
Reporting violations to a specified endpoint, enabling monitoring and\ndebugging.
For configuration instructions, see the Using CSP\ndocumentation, and refer to the CSP overview for details\non directives and settings.
\nWhile CSP is a powerful security mechanism, it’s important to understand its\nlimitations and implications, particularly when used in Django:
\nPolicy exclusion risks: Avoid excluding specific paths or responses from\nCSP protection. Due to the browser’s same-origin policy, a vulnerability on\nan unprotected page (e.g., one allowing arbitrary script injection) may be\nleveraged to attack protected pages. Excluding any route can significantly\nweaken the site’s overall CSP protection.
Performance overhead: Although typically negligible, CSP adds some processing\noverhead. Nonce generation involves secure randomness for each applicable\nrequest. For high-traffic applications or resource-constrained environments,\nmeasure the performance impact accordingly.
Browser support: While CSP Levels 1 and 2 are widely supported, newer\ndirectives (CSP Level 3+) or complex policy behaviors may vary across\nbrowsers. Test your policy across the environments you intend to support.
Despite these limitations, CSP remains an important and recommended security\nlayer for web applications. Understanding its constraints will help you design\na more effective and reliable deployment.
\nWhile Django provides good security protection out of the box, it is still\nimportant to properly deploy your application and take advantage of the\nsecurity protection of the web server, operating system and other components.
\nMake sure that your Python code is outside of the web server’s root. This\nwill ensure that your Python code is not accidentally served as plain text\n(or accidentally executed).
Take care with any user uploaded files.
Django does not throttle requests to authenticate users. To protect against\nbrute-force attacks against the authentication system, you may consider\ndeploying a Django plugin or web server module to throttle these requests.
Keep your SECRET_KEY, and SECRET_KEY_FALLBACKS if in\nuse, secret.
It is a good idea to limit the accessibility of your caching system and\ndatabase using a firewall.
Take a look at the Open Web Application Security Project (OWASP) Top 10\nlist which identifies some common vulnerabilities in web applications.\nWhile Django has tools to address some of the issues, other issues must be\naccounted for in the design of your project.
Mozilla discusses various topics regarding web security. Their\npages also include security principles that apply to any system.