Security in Django

This document is an overview of Django’s security features. It includes adviceon securing a Django-powered site.

Cross site scripting (XSS) protection

XSS attacks allow a user to inject client side scripts into the browsers ofother users. This is usually achieved by storing the malicious scripts in thedatabase where it will be retrieved and displayed to other users, or by gettingusers to click a link which will cause the attacker’s JavaScript to be executedby the user’s browser. However, XSS attacks can originate from any untrustedsource of data, such as cookies or Web services, whenever the data is notsufficiently sanitized before including in a page.

Using Django templates protects you against the majority of XSS attacks.However, it is important to understand what protections it providesand its limitations.

Django templates escape specific characterswhich are particularly dangerous to HTML. While this protects users from mostmalicious input, it is not entirely foolproof. For example, it will notprotect the following:

<style class={{ var }}>...</style>

If var is set to 'class1 onmouseover=javascript:func()', this can resultin unauthorized JavaScript execution, depending on how the browser rendersimperfect HTML. (Quoting the attribute value would fix this case.)

It is also important to be particularly careful when using is_safe withcustom 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 otherthan HTML, there may be entirely separate characters and words which requireescaping.

You should also be very careful when storing HTML in the database, especiallywhen that HTML is retrieved and displayed.

Cross site request forgery (CSRF) protection

CSRF attacks allow a malicious user to execute actions using the credentialsof another user without that user’s knowledge or consent.

Django has built-in protection against most types of CSRF attacks, providing youhave enabled and used it where appropriate. However, as withany mitigation technique, there are limitations. For example, it is possible todisable the CSRF module globally or for particular views. You should only dothis if you know what you are doing. There are other limitations if your site has subdomains that are outside of yourcontrol.

CSRF protection works by checking for a secret in eachPOST request. This ensures that a malicious user cannot “replay” a form POST toyour website and have another logged in user unwittingly submit that form. Themalicious user would have to know the secret, which is user specific (using acookie).

When deployed with HTTPS,CsrfViewMiddleware will check that the HTTP referer header is set to aURL on the same origin (including subdomain and port). Because HTTPSprovides additional security, it is imperative to ensure connections use HTTPSwhere it is available by forwarding insecure connection requests and usingHSTS for supported browsers.

Be very careful with marking views with the csrf_exempt decorator unlessit is absolutely necessary.

SQL injection protection

SQL injection is a type of attack where a malicious user is able to executearbitrary SQL code on a database. This can result in recordsbeing deleted or data leakage.

Django’s querysets are protected from SQL injection since their queries areconstructed using query parameterization. A query’s SQL code is definedseparately from the query’s parameters. Since parameters may be user-providedand therefore unsafe, they are escaped by the underlying database driver.

Django also gives developers power to write raw queries or execute custom sql.These capabilities should be used sparingly and you should always be careful toproperly escape any parameters that the user can control. In addition, youshould exercise caution when using extra()and RawSQL.

Clickjacking protection

Clickjacking is a type of attack where a malicious site wraps another sitein a frame. This attack can result in an unsuspecting user being trickedinto performing unintended actions on the target site.

Django contains clickjacking protection inthe form of theX-Frame-Options middlewarewhich in a supporting browser can prevent a site from being rendered insidea frame. It is possible to disable the protection on a per view basisor to configure the exact header value sent.

The middleware is strongly recommended for any site that does not need to haveits pages wrapped in a frame by third party sites, or only needs to allow thatfor a small section of the site.

SSL/HTTPS

It is always better for security to deploy your site behind HTTPS. Withoutthis, it is possible for malicious network users to sniff authenticationcredentials or any other information transferred between client and server, andin some cases – active network attackers – to alter data that is sent ineither direction.

If you want the protection that HTTPS provides, and have enabled it on yourserver, there are some additional steps you may need:

• If necessary, set SECURE_PROXY_SSL_HEADER, ensuring that you haveunderstood the warnings there thoroughly. Failure to do this can resultin CSRF vulnerabilities, and failure to do it correctly can also bedangerous!

• Set SECURE_SSL_REDIRECT to True, so that requests over HTTPare redirected to HTTPS.

Please note the caveats under SECURE_PROXY_SSL_HEADER. For thecase of a reverse proxy, it may be easier or more secure to configure themain Web server to do the redirect to HTTPS.

• Use ‘secure’ cookies.

If a browser connects initially via HTTP, which is the default for mostbrowsers, it is possible for existing cookies to be leaked. For this reason,you should set your SESSION_COOKIE_SECURE andCSRF_COOKIE_SECURE settings to True. This instructs the browserto only send these cookies over HTTPS connections. Note that this will meanthat sessions will not work over HTTP, and the CSRF protection will preventany POST data being accepted over HTTP (which will be fine if you areredirecting all HTTP traffic to HTTPS).

• Use HTTP Strict Transport Security (HSTS)

HSTS is an HTTP header that informs a browser that all future connectionsto a particular site should always use HTTPS. Combined with redirectingrequests over HTTP to HTTPS, this will ensure that connections always enjoythe added security of SSL provided one successful connection has occurred.HSTS may either be configured with SECURE_HSTS_SECONDS,SECURE_HSTS_INCLUDE_SUBDOMAINS, and SECURE_HSTS_PRELOAD,or on the Web server.

Host header validation

Django uses the Host header provided by the client to construct URLs incertain cases. While these values are sanitized to prevent Cross Site Scriptingattacks, a fake Host value can be used for Cross-Site Request Forgery,cache poisoning attacks, and poisoning links in emails.

Because even seemingly-secure web server configurations are susceptible to fakeHost headers, Django validates Host headers against theALLOWED_HOSTS setting in thedjango.http.HttpRequest.get_host() method.

This validation only applies via get_host();if your code accesses the Host header directly from request.META youare bypassing this security protection.

For more details see the full ALLOWED_HOSTS documentation.

Warning

Previous versions of this document recommended configuring your web server toensure it validates incoming HTTP Host headers. While this is stillrecommended, in many common web servers a configuration that seems tovalidate the Host header may not in fact do so. For instance, even ifApache is configured such that your Django site is served from a non-defaultvirtual host with the ServerName set, it is still possible for an HTTPrequest to match this virtual host and supply a fake Host header. Thus,Django now requires that you set ALLOWED_HOSTS explicitly ratherthan relying on web server configuration.

Additionally, Django requires you to explicitly enable support for theX-Forwarded-Host header (via the USE_X_FORWARDED_HOST setting)if your configuration requires it.

Referrer policy

Browsers use the Referer header as a way to send information to a siteabout how users got there. By setting a Referrer Policy you can help toprotect the privacy of your users, restricting under which circumstances theReferer header is set. See the referrer policy section of thesecurity middleware reference for details.

Session security

Similar to the CSRF limitations requiring a site tobe deployed such that untrusted users don’t have access to any subdomains,django.contrib.sessions also has limitations. See the sessiontopic guide section on security for details.

User-uploaded content

Note

Consider serving static files from a cloud service or CDN to avoid some of these issues.

• If your site accepts file uploads, it is strongly advised that you limitthese uploads in your Web server configuration to a reasonablesize in order to prevent denial of service (DOS) attacks. In Apache, thiscan be easily set using the LimitRequestBody directive.

• If you are serving your own static files, be sure that handlers like Apache’smod_php, which would execute static files as code, are disabled. You don’twant users to be able to execute arbitrary code by uploading and requesting aspecially crafted file.

• Django’s media upload handling poses some vulnerabilities when that media isserved in ways that do not follow security best practices. Specifically, anHTML file can be uploaded as an image if that file contains a valid PNGheader followed by malicious HTML. This file will pass verification of thelibrary that Django uses for ImageField imageprocessing (Pillow). When this file is subsequently displayed to auser, it may be displayed as HTML depending on the type and configuration ofyour web server.

No bulletproof technical solution exists at the framework level to safelyvalidate all user uploaded file content, however, there are some other stepsyou can take to mitigate these attacks:

• One class of attacks can be prevented by always serving user uploadedcontent from a distinct top-level or second-level domain. This preventsany exploit blocked by same-origin policy protections such as crosssite scripting. For example, if your site runs on example.com, youwould want to serve uploaded content (the MEDIA_URL setting)from something like usercontent-example.com. It’s not sufficient toserve content from a subdomain like usercontent.example.com.
• Beyond this, applications may choose to define a whitelist of allowablefile extensions for user uploaded files and configure the web serverto only serve such files.

Additional security topics

While Django provides good security protection out of the box, it is stillimportant to properly deploy your application and take advantage of thesecurity protection of the Web server, operating system and other components.

• Make sure that your Python code is outside of the Web server’s root. Thiswill ensure that your Python code is not accidentally served as plain text(or accidentally executed).
• Take care with any user uploaded files.
• Django does not throttle requests to authenticate users. To protect againstbrute-force attacks against the authentication system, you may considerdeploying a Django plugin or Web server module to throttle these requests.
• Keep your SECRET_KEY a secret.
• It is a good idea to limit the accessibility of your caching system anddatabase using a firewall.
• Take a look at the Open Web Application Security Project (OWASP) Top 10list which identifies some common vulnerabilities in web applications. WhileDjango has tools to address some of the issues, other issues must beaccounted for in the design of your project.