Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Way more doc updates.

  • Loading branch information...
commit 9ab236fb172ba3eaa5563c79c861becd078d2b82 1 parent 6d2c32b
James Socol authored
View
84 README.rst
@@ -12,87 +12,3 @@ documentation is available on ReadTheDocs_.
.. _GitHub: https://github.com/mozilla/django-csp
.. _Issues: https://github.com/mozilla/django-csp/issues
.. _ReadTheDocs: http://django-csp.readthedocs.org/
-
-
-Using Django-CSP
-================
-
-Django-CSP is configured entirely in Django's settings. Almost all the
-arguments take a tuple of possible values (cf the spec). Only the
-``default-src`` directive has a default value (``'self'``). All others are
-ignored unless specified.
-
-
-
-
-The Settings
-------------
-
-These settings take a tuple of values. For simplicity, the special values
-``'self'``, ``'unsafe-inline'``, and ``'unsafe-eval'`` must contain
-the single quotes. See the spec for allowed use of the ``*`` wildcard::
-
- CSP_DEFAULT_SRC
- CSP_IMG_SRC
- CSP_SCRIPT_SRC
- CSP_STYLE_SRC
- CSP_OBJECT_SRC
- CSP_MEDIA_SRC
- CSP_FRAME_SRC
- CSP_FONT_SRC
- CSP_CONNECT_SRC
- CSP_SANDBOX
-
-The following settings take only a URI, not a tuple::
-
- CSP_REPORT_URI
-
-You can disable CSP for specific url prefixes with the
-``CSP_EXCLUDE_URL_PREFIXES`` setting. For example, to exclude the django admin
-(which uses inline Javascript) with the standard urlconf::
-
- CSP_EXCLUDE_URL_PREFIXES = ('/admin',)
-
-
-
-
-Report-Only Mode
-----------------
-
-Content Security Policy supports a *report-only* mode that will send
-violation reports but not enforce the policy in the browser. This allows you
-to test a site for compliance without potentially breaking anything for your
-users.
-
-To activate report-only mode, simply turn on ``CSP_REPORT_ONLY`` in
-settings::
-
- CSP_REPORT_ONLY = True
-
-
-Modifying the Policy
-====================
-
-Right now, the only way to modify the policy is with the ``@csp_exempt``
-decorator::
-
- from csp.decorators import csp_exempt
-
- @csp_exempt
- def myview(request):
- return HttpResponse()
-
-This will prevent the ``CSPMiddleware`` from sending any CSP headers from this
-view.
-
-
-TODO
-====
-
-* ``@csp_patch`` decorator that will allow you to patch a policy for a specific
- view. Will be... complicated.
-* ``@csp_override`` decorator that allows you to replace a policy for a
- specific view.
-
-.. [#] Strictly speaking, ``csp`` only needs to be in your installed apps
- if you plan to use the report feature.
View
22 docs/changing.rst
@@ -0,0 +1,22 @@
+.. _changing-chapter:
+
+================
+Changing the CSP
+================
+
+django-csp includes decorators to enable you to change the policy on a
+per-view basis.
+
+
+``@csp_exempt``
+===============
+
+To stop CSP headers from being sent at all, wrap a view with
+``@csp_exempt``::
+
+ from csp.decorators import csp_exempt
+
+ @csp_exempt
+ def myview(request):
+ # ...
+ return render(request, ...)
View
48 docs/configuration.rst
@@ -7,7 +7,7 @@ Configuring django-csp
Content-Security-Policy_ is a complicated header. There are many values
you may need to tweak here.
-.. note:
+.. note::
Note when a setting requires a tuple or list. Since Python strings
are iterable, you may get very strange policies and errors.
@@ -18,15 +18,53 @@ before configuring django-csp.
Policy Settings
===============
-These settings affect the policy in the header.
+These settings affect the policy in the header. The defaults are in
+*italics*.
-.. note:
+.. note::
The "special" source values of ``'self'``, ``'unsafe-inline'``,
``'unsafe-eval'``, and ``'none'`` must be quoted! e.g.:
``CSP_DEFAULT_SRC = ("'self'",)``. Without quotes they will not work
as intended.
-:``CSP_DEFAULT_SRC``:
- Set the ``default-src`` directive.
+``CSP_DEFAULT_SRC``
+ Set the ``default-src`` directive. A tuple or list of
+ values, e.g. ``("'self'", 'cdn.example.net')``. *'self'*
+``CSP_IMG_SRC``
+ Set the ``img-src`` directive. A tuple or list. *None*
+``CSP_OBJECT_SRC``
+ Set the ``object-src`` directive. A tuple or list. *None*
+``CSP_MEDIA_SRC``
+ Set the ``media-src`` directive. A tuple or list. *None*
+``CSP_FRAME_SRC``
+ Set the ``frame-src`` directive. A tuple or list. *None*
+``CSP_FONT_SRC``
+ Set the ``font-src`` directive. A tuple or list. *None*
+``CSP_CONNECT_SRC``
+ Set the ``connect-src`` directive. A tuple or list. *None*
+``CSP_STYLE_SRC``
+ Set the ``style-src`` directive. A tuple or list. *None*
+``CSP_SANDBOX``
+ Set the ``sandbox`` directive. A tuple or list. *None*
+``CSP_REPORT_URI``
+ Set the ``report-uri`` directive. A **string** with a full or
+ relative URI.
+
+
+Other Settings
+==============
+
+These settings control the behavior of django-csp. Defaults are in
+*italics*.
+
+``CSP_REPORT_ONLY``
+ Send "report-only" headers instead of real headers. See the spec_
+ and the chapter on `reports <reports-chapter>`_ for more info. A
+ boolean. *False*
+``CSP_EXCLUDE_URL_PREFIXES``
+ A **tuple** of URL prefixes. URLs beginning with any of these will
+ not get the CSP headers. *('/admin',)*
+
.. _Content-Security-Policy: http://www.w3.org/TR/CSP/
+.. _spec: Content-Security-Policy_
View
3  docs/index.rst
@@ -7,7 +7,7 @@
django-csp
==========
-Django-CSP adds Content-Security-Policy_ headers and a CSP report
+django-csp adds Content-Security-Policy_ headers and a CSP report
processing facility to Django.
:Version: |release|
@@ -23,6 +23,7 @@ Contents:
installation
configuration
reports
+ changing
View
34 docs/reports.rst
@@ -0,0 +1,34 @@
+.. _reports-chapter:
+
+=====================
+CSP Violation Reports
+=====================
+
+When something on a page violates the Content-Security-Policy, and the
+policy defines a ``report-uri`` directive, the user agent may POST a
+report_. Reports are JSON blobs containing information about how the
+policy was violated.
+
+django-csp includes a view to accept and process these reports, or you
+can write your own, if you need to process them differently.
+
+The built-in report view is largely inspired by Sentry_, with all due
+credit.
+
+
+How reports are processed
+=========================
+
+When a report is POSTed to django-csp, a new instance of a ``Report``
+object is created which stores the details of the report. django-csp
+will try to determine if it has ever seen this report before.
+
+If the report is new, a new ``Group`` will be created and an email will
+be sent to the addresses in the ``ADMINS`` list.
+
+If the report is filed into an existing ``Group``, the report will be
+stored but no new group will be created and no email will be sent.
+
+
+.. _report: http://www.w3.org/TR/CSP/#sample-violation-report
+.. _Sentry: http://getsentry.com/
Please sign in to comment.
Something went wrong with that request. Please try again.