<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Security in Django — Django 1.6.7 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.6.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="top" title="Django 1.6.7 documentation" href="../index.html" />
<link rel="up" title="Using Django" href="index.html" />
<link rel="next" title="Serializing Django objects" href="serialization.html" />
<link rel="prev" title="Porting to Python 3" href="python3.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.6.7 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="python3.html" title="Porting to Python 3">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="serialization.html" title="Serializing Django objects">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-security">
<div class="section" id="s-security-in-django">
<span id="security-in-django"></span><h1>Security in Django<a class="headerlink" href="#security-in-django" title="Permalink to this headline">¶</a></h1>
<p>This document is an overview of Django’s security features. It includes advice
on securing a Django-powered site.</p>
<div class="section" id="s-cross-site-scripting-xss-protection">
<span id="s-cross-site-scripting"></span><span id="cross-site-scripting-xss-protection"></span><span id="cross-site-scripting"></span><h2>Cross site scripting (XSS) protection<a class="headerlink" href="#cross-site-scripting-xss-protection" title="Permalink to this headline">¶</a></h2>
<p>XSS attacks allow a user to inject client side scripts into the browsers of
other users. This is usually achieved by storing the malicious scripts in the
database where it will be retrieved and displayed to other users, or by getting
users to click a link which will cause the attacker’s JavaScript to be executed
by the user’s browser. However, XSS attacks can originate from any untrusted
source of data, such as cookies or Web services, whenever the data is not
sufficiently sanitized before including in a page.</p>
<p>Using Django templates protects you against the majority of XSS attacks.
However, it is important to understand what protections it provides
and its limitations.</p>
<p>Django templates <a class="reference internal" href="templates.html#automatic-html-escaping"><em>escape specific characters</em></a>
which are particularly dangerous to HTML. While this protects users from most
malicious input, it is not entirely foolproof. For example, it will not
protect the following:</p>
<div class="highlight-html+django"><pre><style class={{ var }}>...</style></pre>
</div>
<p>If <tt class="docutils literal"><span class="pre">var</span></tt> is set to <tt class="docutils literal"><span class="pre">'class1</span> <span class="pre">onmouseover=javascript:func()'</span></tt>, this can result
in unauthorized JavaScript execution, depending on how the browser renders
imperfect HTML.</p>
<p>It is also important to be particularly careful when using <tt class="docutils literal"><span class="pre">is_safe</span></tt> with
custom template tags, the <a class="reference internal" href="../ref/templates/builtins.html#std:templatefilter-safe"><tt class="xref std std-tfilter docutils literal"><span class="pre">safe</span></tt></a> template tag, <a class="reference internal" href="../ref/utils.html#module-django.utils.safestring" title="django.utils.safestring: Functions and classes for working with strings that can be displayed safely without further escaping in HTML."><tt class="xref py py-mod docutils literal"><span class="pre">mark_safe</span></tt></a>, and when autoescape is turned off.</p>
<p>In addition, if you are using the template system to output something other
than HTML, there may be entirely separate characters and words which require
escaping.</p>
<p>You should also be very careful when storing HTML in the database, especially
when that HTML is retrieved and displayed.</p>
</div>
<div class="section" id="s-cross-site-request-forgery-csrf-protection">
<span id="cross-site-request-forgery-csrf-protection"></span><h2>Cross site request forgery (CSRF) protection<a class="headerlink" href="#cross-site-request-forgery-csrf-protection" title="Permalink to this headline">¶</a></h2>
<p>CSRF attacks allow a malicious user to execute actions using the credentials
of another user without that user’s knowledge or consent.</p>
<p>Django has built-in protection against most types of CSRF attacks, providing you
have <a class="reference internal" href="../ref/contrib/csrf.html#using-csrf"><em>enabled and used it</em></a> where appropriate. However, as with
any mitigation technique, there are limitations. For example, it is possible to
disable the CSRF module globally or for particular views. You should only do
this if you know what you are doing. There are other <a class="reference internal" href="../ref/contrib/csrf.html#csrf-limitations"><em>limitations</em></a> if your site has subdomains that are outside of your
control.</p>
<p><a class="reference internal" href="../ref/contrib/csrf.html#how-csrf-works"><em>CSRF protection works</em></a> by checking for a nonce in each
POST request. This ensures that a malicious user cannot simply “replay” a form
POST to your Web site and have another logged in user unwittingly submit that
form. The malicious user would have to know the nonce, which is user specific
(using a cookie).</p>
<p>When deployed with <a class="reference internal" href="#security-recommendation-ssl"><em>HTTPS</em></a>,
<tt class="docutils literal"><span class="pre">CsrfViewMiddleware</span></tt> will check that the HTTP referer header is set to a
URL on the same origin (including subdomain and port). Because HTTPS
provides additional security, it is imperative to ensure connections use HTTPS
where it is available by forwarding insecure connection requests and using
HSTS for supported browsers.</p>
<p>Be very careful with marking views with the <tt class="docutils literal"><span class="pre">csrf_exempt</span></tt> decorator unless
it is absolutely necessary.</p>
</div>
<div class="section" id="s-sql-injection-protection">
<span id="s-id1"></span><span id="sql-injection-protection"></span><span id="id1"></span><h2>SQL injection protection<a class="headerlink" href="#sql-injection-protection" title="Permalink to this headline">¶</a></h2>
<p>SQL injection is a type of attack where a malicious user is able to execute
arbitrary SQL code on a database. This can result in records
being deleted or data leakage.</p>
<p>By using Django’s querysets, the resulting SQL will be properly escaped by
the underlying database driver. However, Django also gives developers power to
write <a class="reference internal" href="db/sql.html#executing-raw-queries"><em>raw queries</em></a> or execute
<a class="reference internal" href="db/sql.html#executing-custom-sql"><em>custom sql</em></a>. These capabilities should be used
sparingly and you should always be careful to properly escape any parameters
that the user can control. In addition, you should exercise caution when using
<a class="reference internal" href="../ref/models/querysets.html#django.db.models.query.QuerySet.extra" title="django.db.models.query.QuerySet.extra"><tt class="xref py py-meth docutils literal"><span class="pre">extra()</span></tt></a>.</p>
</div>
<div class="section" id="s-clickjacking-protection">
<span id="clickjacking-protection"></span><h2>Clickjacking protection<a class="headerlink" href="#clickjacking-protection" title="Permalink to this headline">¶</a></h2>
<p>Clickjacking is a type of attack where a malicious site wraps another site
in a frame. This attack can result in an unsuspecting user being tricked
into performing unintended actions on the target site.</p>
<p>Django contains <a class="reference internal" href="../ref/clickjacking.html#clickjacking-prevention"><em>clickjacking protection</em></a> in
the form of the
<a class="reference internal" href="../ref/middleware.html#django.middleware.clickjacking.XFrameOptionsMiddleware" title="django.middleware.clickjacking.XFrameOptionsMiddleware"><tt class="xref py py-mod docutils literal"><span class="pre">X-Frame-Options</span> <span class="pre">middleware</span></tt></a>
which in a supporting browser can prevent a site from being rendered inside
a frame. It is possible to disable the protection on a per view basis
or to configure the exact header value sent.</p>
<p>The middleware is strongly recommended for any site that does not need to have
its pages wrapped in a frame by third party sites, or only needs to allow that
for a small section of the site.</p>
</div>
<div class="section" id="s-ssl-https">
<span id="s-security-recommendation-ssl"></span><span id="ssl-https"></span><span id="security-recommendation-ssl"></span><h2>SSL/HTTPS<a class="headerlink" href="#ssl-https" title="Permalink to this headline">¶</a></h2>
<p>It is always better for security, though not always practical in all cases, to
deploy your site behind HTTPS. Without this, it is possible for malicious
network users to sniff authentication credentials or any other information
transferred between client and server, and in some cases – <strong>active</strong> network
attackers – to alter data that is sent in either direction.</p>
<p>If you want the protection that HTTPS provides, and have enabled it on your
server, there are some additional steps you may need:</p>
<ul>
<li><p class="first">If necessary, set <a class="reference internal" href="../ref/settings.html#std:setting-SECURE_PROXY_SSL_HEADER"><tt class="xref std std-setting docutils literal"><span class="pre">SECURE_PROXY_SSL_HEADER</span></tt></a>, ensuring that you have
understood the warnings there thoroughly. Failure to do this can result
in CSRF vulnerabilities, and failure to do it correctly can also be
dangerous!</p>
</li>
<li><p class="first">Set up redirection so that requests over HTTP are redirected to HTTPS.</p>
<p>This could be done using a custom middleware. Please note the caveats under
<a class="reference internal" href="../ref/settings.html#std:setting-SECURE_PROXY_SSL_HEADER"><tt class="xref std std-setting docutils literal"><span class="pre">SECURE_PROXY_SSL_HEADER</span></tt></a>. For the case of a reverse proxy, it may be
easier or more secure to configure the main Web server to do the redirect to
HTTPS.</p>
</li>
<li><p class="first">Use ‘secure’ cookies.</p>
<p>If a browser connects initially via HTTP, which is the default for most
browsers, it is possible for existing cookies to be leaked. For this reason,
you should set your <a class="reference internal" href="../ref/settings.html#std:setting-SESSION_COOKIE_SECURE"><tt class="xref std std-setting docutils literal"><span class="pre">SESSION_COOKIE_SECURE</span></tt></a> and
<a class="reference internal" href="../ref/settings.html#std:setting-CSRF_COOKIE_SECURE"><tt class="xref std std-setting docutils literal"><span class="pre">CSRF_COOKIE_SECURE</span></tt></a> settings to <tt class="docutils literal"><span class="pre">True</span></tt>. This instructs the browser
to only send these cookies over HTTPS connections. Note that this will mean
that sessions will not work over HTTP, and the CSRF protection will prevent
any POST data being accepted over HTTP (which will be fine if you are
redirecting all HTTP traffic to HTTPS).</p>
</li>
<li><p class="first">Use HTTP Strict Transport Security (HSTS)</p>
<p>HSTS is an HTTP header that informs a browser that all future connections
to a particular site should always use HTTPS. Combined with redirecting
requests over HTTP to HTTPS, this will ensure that connections always enjoy
the added security of SSL provided one successful connection has occurred.
HSTS is usually configured on the web server.</p>
</li>
</ul>
</div>
<div class="section" id="s-host-header-validation">
<span id="s-host-headers-virtual-hosting"></span><span id="host-header-validation"></span><span id="host-headers-virtual-hosting"></span><h2>Host header validation<a class="headerlink" href="#host-header-validation" title="Permalink to this headline">¶</a></h2>
<p>Django uses the <tt class="docutils literal"><span class="pre">Host</span></tt> header provided by the client to construct URLs in
certain cases. While these values are sanitized to prevent Cross Site Scripting
attacks, a fake <tt class="docutils literal"><span class="pre">Host</span></tt> value can be used for Cross-Site Request Forgery,
cache poisoning attacks, and poisoning links in emails.</p>
<p>Because even seemingly-secure web server configurations are susceptible to fake
<tt class="docutils literal"><span class="pre">Host</span></tt> headers, Django validates <tt class="docutils literal"><span class="pre">Host</span></tt> headers against the
<a class="reference internal" href="../ref/settings.html#std:setting-ALLOWED_HOSTS"><tt class="xref std std-setting docutils literal"><span class="pre">ALLOWED_HOSTS</span></tt></a> setting in the
<a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><tt class="xref py py-meth docutils literal"><span class="pre">django.http.HttpRequest.get_host()</span></tt></a> method.</p>
<p>This validation only applies via <a class="reference internal" href="../ref/request-response.html#django.http.HttpRequest.get_host" title="django.http.HttpRequest.get_host"><tt class="xref py py-meth docutils literal"><span class="pre">get_host()</span></tt></a>;
if your code accesses the <tt class="docutils literal"><span class="pre">Host</span></tt> header directly from <tt class="docutils literal"><span class="pre">request.META</span></tt> you
are bypassing this security protection.</p>
<p>For more details see the full <a class="reference internal" href="../ref/settings.html#std:setting-ALLOWED_HOSTS"><tt class="xref std std-setting docutils literal"><span class="pre">ALLOWED_HOSTS</span></tt></a> documentation.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Previous versions of this document recommended configuring your web server to
ensure it validates incoming HTTP <tt class="docutils literal"><span class="pre">Host</span></tt> headers. While this is still
recommended, in many common web servers a configuration that seems to
validate the <tt class="docutils literal"><span class="pre">Host</span></tt> header may not in fact do so. For instance, even if
Apache is configured such that your Django site is served from a non-default
virtual host with the <tt class="docutils literal"><span class="pre">ServerName</span></tt> set, it is still possible for an HTTP
request to match this virtual host and supply a fake <tt class="docutils literal"><span class="pre">Host</span></tt> header. Thus,
Django now requires that you set <a class="reference internal" href="../ref/settings.html#std:setting-ALLOWED_HOSTS"><tt class="xref std std-setting docutils literal"><span class="pre">ALLOWED_HOSTS</span></tt></a> explicitly rather
than relying on web server configuration.</p>
</div>
<p>Additionally, as of 1.3.1, Django requires you to explicitly enable support for
the <tt class="docutils literal"><span class="pre">X-Forwarded-Host</span></tt> header (via the <a class="reference internal" href="../ref/settings.html#std:setting-USE_X_FORWARDED_HOST"><tt class="xref std std-setting docutils literal"><span class="pre">USE_X_FORWARDED_HOST</span></tt></a>
setting) if your configuration requires it.</p>
</div>
<div class="section" id="s-session-security">
<span id="session-security"></span><h2>Session security<a class="headerlink" href="#session-security" title="Permalink to this headline">¶</a></h2>
<p>Similar to the <a class="reference internal" href="../ref/contrib/csrf.html#csrf-limitations"><em>CSRF limitations</em></a> requiring a site to
be deployed such that untrusted users don’t have access to any subdomains,
<a class="reference internal" href="http/sessions.html#module-django.contrib.sessions" title="django.contrib.sessions: Provides session management for Django projects."><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.sessions</span></tt></a> also has limitations. See <a class="reference internal" href="http/sessions.html#topics-session-security"><em>the session
topic guide section on security</em></a> for details.</p>
</div>
<div class="section" id="s-user-uploaded-content">
<span id="s-user-uploaded-content-security"></span><span id="user-uploaded-content"></span><span id="user-uploaded-content-security"></span><h2>User-uploaded content<a class="headerlink" href="#user-uploaded-content" title="Permalink to this headline">¶</a></h2>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Consider <a class="reference internal" href="../howto/static-files/deployment.html#staticfiles-from-cdn"><em>serving static files from a cloud service or CDN</em></a> to avoid some of these issues.</p>
</div>
<ul>
<li><p class="first">If your site accepts file uploads, it is strongly advised that you limit
these uploads in your Web server configuration to a reasonable
size in order to prevent denial of service (DOS) attacks. In Apache, this
can be easily set using the <a class="reference external" href="http://httpd.apache.org/docs/2.2/mod/core.html#limitrequestbody">LimitRequestBody</a> directive.</p>
</li>
<li><p class="first">If you are serving your own static files, be sure that handlers like Apache’s
<tt class="docutils literal"><span class="pre">mod_php</span></tt>, which would execute static files as code, are disabled. You don’t
want users to be able to execute arbitrary code by uploading and requesting a
specially crafted file.</p>
</li>
<li><p class="first">Django’s media upload handling poses some vulnerabilities when that media is
served in ways that do not follow security best practices. Specifically, an
HTML file can be uploaded as an image if that file contains a valid PNG
header followed by malicious HTML. This file will pass verification of the
libraries that Django uses for <a class="reference internal" href="../ref/models/fields.html#django.db.models.ImageField" title="django.db.models.ImageField"><tt class="xref py py-class docutils literal"><span class="pre">ImageField</span></tt></a> image
processing (PIL or Pillow). When this file is subsequently displayed to a
user, it may be displayed as HTML depending on the type and configuration of
your web server.</p>
<p>No bulletproof technical solution exists at the framework level to safely
validate all user uploaded file content, however, there are some other steps
you can take to mitigate these attacks:</p>
<ol class="arabic simple">
<li>One class of attacks can be prevented by always serving user uploaded
content from a distinct top-level or second-level domain. This prevents
any exploit blocked by <a class="reference external" href="http://en.wikipedia.org/wiki/Same-origin_policy">same-origin policy</a> protections such as cross
site scripting. For example, if your site runs on <tt class="docutils literal"><span class="pre">example.com</span></tt>, you
would want to serve uploaded content (the <a class="reference internal" href="../ref/settings.html#std:setting-MEDIA_URL"><tt class="xref std std-setting docutils literal"><span class="pre">MEDIA_URL</span></tt></a> setting)
from something like <tt class="docutils literal"><span class="pre">usercontent-example.com</span></tt>. It’s <em>not</em> sufficient to
serve content from a subdomain like <tt class="docutils literal"><span class="pre">usercontent.example.com</span></tt>.</li>
<li>Beyond this, applications may choose to define a whitelist of allowable
file extensions for user uploaded files and configure the web server
to only serve such files.</li>
</ol>
</li>
</ul>
</div>
<div class="section" id="s-additional-security-topics">
<span id="s-id2"></span><span id="additional-security-topics"></span><span id="id2"></span><h2>Additional security topics<a class="headerlink" href="#additional-security-topics" title="Permalink to this headline">¶</a></h2>
<p>While Django provides good security protection out of the box, it is still
important to properly deploy your application and take advantage of the
security protection of the Web server, operating system and other components.</p>
<ul class="simple">
<li>Make sure that your Python code is outside of the Web server’s root. This
will ensure that your Python code is not accidentally served as plain text
(or accidentally executed).</li>
<li>Take care with any <a class="reference internal" href="../ref/models/fields.html#file-upload-security"><em>user uploaded files</em></a>.</li>
<li>Django does not throttle requests to authenticate users. To protect against
brute-force attacks against the authentication system, you may consider
deploying a Django plugin or Web server module to throttle these requests.</li>
<li>Keep your <a class="reference internal" href="../ref/settings.html#std:setting-SECRET_KEY"><tt class="xref std std-setting docutils literal"><span class="pre">SECRET_KEY</span></tt></a> a secret.</li>
<li>It is a good idea to limit the accessibility of your caching system and
database using a firewall.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Security in Django</a><ul>
<li><a class="reference internal" href="#cross-site-scripting-xss-protection">Cross site scripting (XSS) protection</a></li>
<li><a class="reference internal" href="#cross-site-request-forgery-csrf-protection">Cross site request forgery (CSRF) protection</a></li>
<li><a class="reference internal" href="#sql-injection-protection">SQL injection protection</a></li>
<li><a class="reference internal" href="#clickjacking-protection">Clickjacking protection</a></li>
<li><a class="reference internal" href="#ssl-https">SSL/HTTPS</a></li>
<li><a class="reference internal" href="#host-header-validation">Host header validation</a></li>
<li><a class="reference internal" href="#session-security">Session security</a></li>
<li><a class="reference internal" href="#user-uploaded-content">User-uploaded content</a></li>
<li><a class="reference internal" href="#additional-security-topics">Additional security topics</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="python3.html">Porting to Python 3</a></li>
<li>Next: <a href="serialization.html">Serializing Django objects</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.6.7 documentation</a>
<ul><li><a href="index.html">Using Django</a>
<ul><li>Security in Django</li></ul>
</li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/topics/security.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Sep 26, 2014</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="python3.html" title="Porting to Python 3">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="serialization.html" title="Serializing Django objects">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
