Ticket #14201: 14201-security.diff

docs/index.txt

@@ -185 +185 @@
     * :doc:`Messages <ref/contrib/messages>`
     * :doc:`Pagination <topics/pagination>`
     * :doc:`Redirects <ref/contrib/redirects>`
+    * :doc:`Security <topics/security>`
     * :doc:`Serialization <topics/serialization>`
     * :doc:`Sessions <topics/http/sessions>`
     * :doc:`Signals <topics/signals>`

docs/topics/db/sql.txt

@@ -13 +13 @@
 __ `performing raw queries`_
 __ `executing custom SQL directly`_
 
+.. _executing-raw-queries:
+
 Performing raw queries
 ======================
 
@@ -190 +192 @@
 
 __ http://en.wikipedia.org/wiki/SQL_injection
 
+.. _executing-custom-sql:
+
 Executing custom SQL directly
 =============================
 

docs/topics/index.txt

@@ -23 +23 @@
    i18n/index
    logging
    pagination
+   security
    serialization
    settings
    signals

docs/topics/security.txt

@@ +1 @@
+=====================
+Security in Django
+=====================
+
+This document will show you the security features of Django as well
+as give some advice about securing a Django site.
+
+.. _cross-site-scripting:
+
+Cross site scripting (XSS) protection
+=====================================
+
+.. highlightlang:: html+django
+
+XSS attacks allow a user to inject client side scripts into the
+browsers of other users. This is usually acheived by storing the malicious
+scripts to the database where it will be retrieved and displayed to other users
+or to get users to click a link containing variables containing scripts that 
+will be rendered by the user's browser. However, XSS attacks can originate 
+from any untrusted source of data such as cookies or web services. 
+
+Using Django templates protects you against the majority of XSS attacks. 
+However, it is important to understand what protections it provides
+and its limitations.
+
+Django templates :ref:`escape specific characters <automatic-html-escaping>`
+which are particularly dangerous to HTML. While this protects users from most
+malications input, it is not entirely foolproof. For example, it will not 
+protect the following:
+
+.. code-block:: html+django
+
+    <style class={{ var }}>...</style>
+
+If ``var`` is set to ``'class1 onmouseover=javascript:func()'``, this can
+result in unauthorized javascript execution depending on how the browser
+renders imperfect HTML.
+
+It is also important to be particularly careful when using ``is_safe``
+with custom template tags, the :ttag:`safe` template tag and with 
+:mod:`mark_safe <django.utils.safestring>`.
+
+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. 
+
+You should also be very careful when storing HTML to the database especially
+when that HTML will be retrieved and displayed.
+
+Cross site request forgery (CSRF) protection
+============================================
+
+CSRF attacks allow a malicious user to execute actions using the credentials
+of another user without that user's knowledge or consent.
+
+Django has built-in :ref:`protection <using-csrf>`
+against most types of CSRF attacks. 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 :ref:`limitations <csrf-limitations>` if your 
+site has subdomains that are outside of your control.
+
+:ref:`CSRF protection works <how-csrf-works>` by inserting some random data
+- a cryptographic nonce - into each POST request. This ensures that a 
+malicious user cannot simply "replay" a form POST to your website and have
+another logged in user unwittingly submit that form. The malicious user would
+have to know the nonce which is user specific and expires after a short time.
+
+Be very careful with marking views with the ``csrf_exempt`` decorator unless
+it is absolutely necessary.
+
+SQL injection protection
+========================
+
+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. 
+
+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 :ref:`raw queries <executing-raw-queries>` or execute 
+:ref:`custom sql <executing-custom-sql>`. 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
+:meth:`extra() <django.db.models.query.QuerySet.extra>`.
+
+
+Clickjacking protection
+=======================
+
+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.
+
+Django contains :ref:`clickjacking protection <clickjacking-prevention>` in
+the form of the 
+:mod:`X-Frame-Options middleware <django.middleware.clickjacking.XFrameOptionsMiddleware>`
+which in a supporting browser can prevent a site from being rendered inside
+of a frame. It is possible to disable the protection on a per view basis
+or to allow frames from the same origin.
+
+The middleware is strongly recommended for any site that does not use frames
+or uses frames for only a small section of the site.
+
+.. _additional-security-topics:
+
+Additional security topics
+==========================
+
+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.
+
+* 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.
+* If security is particularly important, it is a good idea to deploy the
+  :mod:`admin site <django.contrib.admin>` behind HTTPS. Without this, it is 
+  possible for malicious users to sniff authentication credentials if the
+  admin site is accessed from an insecure network connection. You may also
+  want to take a look at the :setting:`SESSION_COOKIE_SECURE` setting.
+* 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.
+* If your site accepts file uploads, it is strongly advised that you limit
+  the 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 LimitRequestBody_ directive.
+* Keep your :setting:`SECRET_KEY` a secret.
+* It is a good idea to limit the accessibility of your caching system and
+  database using a firewall.
+
+.. _LimitRequestBody: http://httpd.apache.org/docs/2.2/mod/core.html#limitrequestbody
+

docs/ref/clickjacking.txt

@@ -26 +26 @@
 user visits the attacker site and clicks "I Like Ponies" he will inadvertently
 click on the online store's "Buy Now" button and unknowingly purchase the item.
 
+.. _clickjacking-prevention:
+
 Preventing clickjacking
 =======================
 

docs/ref/contrib/csrf.txt

@@ -21 +21 @@
 .. _Cross Site Request Forgeries: http://www.squarefree.com/securitytips/web-developers.html#CSRF
 .. _9.1.1 Safe Methods, HTTP 1.1, RFC 2616: http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html
 
+.. _using-csrf:
+
 How to use it
 =============
 
@@ -182 +184 @@
 own view for handling this condition.  To do this, simply set the
 :setting:`CSRF_FAILURE_VIEW` setting.
 
+.. _how-csrf-works:
+
 How it works
 ============