Skip to content

Tweak configuration docs #146

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 28, 2021
Merged

Tweak configuration docs #146

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
183 changes: 118 additions & 65 deletions docs/configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,107 +7,157 @@ Configuring django-csp
Content-Security-Policy_ is a complicated header. There are many values
you may need to tweak here.

.. note::
Note when a setting requires a tuple or list. Since Python strings
are iterable, you may get very strange policies and errors.

It's worth reading the latest CSP spec and making sure you understand it
It's worth reading the latest CSP spec_ and making sure you understand it
before configuring django-csp.

.. note::
Many settings require a ``tuple`` or ``list``. You may get very strange
policies and even errors when mistakenly configuring them as a ``string``.


Policy Settings
===============

These settings affect the policy in the header. The defaults are in
*italics*.
These settings affect the policy in the header. The defaults are in *italics*.

.. note::
The "special" source values of ``'self'``, ``'unsafe-inline'``,
``'unsafe-eval'``, ``'none'`` and hash-source (``'sha256-...'``) must be quoted! e.g.:
``CSP_DEFAULT_SRC = ("'self'",)``. Without quotes they will not work
as intended.
``'unsafe-eval'``, ``'none'`` and hash-source (``'sha256-...'``) 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. A tuple or list of
values, e.g. ``("'self'", 'cdn.example.net')``. *'self'*
Set the ``default-src`` directive. A ``tuple`` or ``list`` of values,
e.g.: ``("'self'", 'cdn.example.net')``. *["'self'"]*

``CSP_SCRIPT_SRC``
Set the ``script-src`` directive. A tuple or list. *None*
Set the ``script-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_SCRIPT_SRC_ATTR``
Set the ``script-src-attr`` directive. A tuple or list. *None*
Set the ``script-src-attr`` directive. A ``tuple`` or ``list``. *None*

``CSP_SCRIPT_SRC_ELEM``
Set the ``script-src-elem`` directive. A tuple or list. *None*
Set the ``script-src-elem`` directive. A ``tuple`` or ``list``. *None*

``CSP_IMG_SRC``
Set the ``img-src`` directive. A tuple or list. *None*
Set the ``img-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_OBJECT_SRC``
Set the ``object-src`` directive. A tuple or list. *None*
Set the ``object-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_PREFETCH_SRC``
Set the ``prefetch-src`` directive. A tuple or list. *None*
Set the ``prefetch-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_MEDIA_SRC``
Set the ``media-src`` directive. A tuple or list. *None*
Set the ``media-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_FRAME_SRC``
Set the ``frame-src`` directive. A tuple or list. *None*
Set the ``frame-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_FONT_SRC``
Set the ``font-src`` directive. A tuple or list. *None*
Set the ``font-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_CONNECT_SRC``
Set the ``connect-src`` directive. A tuple or list. *None*
Set the ``connect-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_STYLE_SRC``
Set the ``style-src`` directive. A tuple or list. *None*
Set the ``style-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_STYLE_SRC_ATTR``
Set the ``style-src-attr`` directive. A tuple or list. *None*
Set the ``style-src-attr`` directive. A ``tuple`` or ``list``. *None*

``CSP_STYLE_SRC_ELEM``
Set the ``style-src-elem`` directive. A tuple or list. *None*
Set the ``style-src-elem`` directive. A ``tuple`` or ``list``. *None*

``CSP_BASE_URI``
Set the ``base-uri`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``base-uri`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_CHILD_SRC``
Set the ``child-src`` directive. A tuple or list. *None*
Set the ``child-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_FRAME_ANCESTORS``
Set the ``frame-ancestors`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``frame-ancestors`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_NAVIGATE_TO``
Set the ``navigate-to`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``navigate-to`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_FORM_ACTION``
Set the ``FORM_ACTION`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``FORM_ACTION`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_SANDBOX``
Set the ``sandbox`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``sandbox`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_REPORT_URI``
Set the ``report-uri`` directive. A tuple or list. Each URI can be a
full or relative URI. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``report-uri`` directive. A ``tuple`` or ``list`` of URIs.
Each URI can be a full or relative URI. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_REPORT_TO``
Set the ``report-to`` directive. A string describing a reporting group. *None*
Note: This doesn't use default-src as a fall-back.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 this isn't a src list so we can remove this comment about the fallback

Set the ``report-to`` directive. A ``string`` describing a reporting
group. *None*

See Section 1.2: https://w3c.github.io/reporting/#group

``CSP_MANIFEST_SRC``
Set the ``manifest-src`` directive. A tuple or list. *None*
Set the ``manifest-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_WORKER_SRC``
Set the ``worker-src`` directive. A tuple or list. *None*
Set the ``worker-src`` directive. A ``tuple`` or ``list``. *None*

``CSP_PLUGIN_TYPES``
Set the ``plugin-types`` directive. A tuple or list. *None*
Note: This doesn't use default-src as a fall-back.
Set the ``plugin-types`` directive. A ``tuple`` or ``list``. *None*

Note: This doesn't use ``default-src`` as a fall-back.

``CSP_REQUIRE_SRI_FOR``
Set the ``require-sri-for`` directive. A tuple or list. *None*
Valid values: ``script``, ``style``, or both. See: require-sri-for-known-tokens_
Note: This doesn't use default-src as a fall-back.
Set the ``require-sri-for`` directive. A ``tuple`` or ``list``. *None*

Valid values: a ``list`` containing ``'script'``, ``'style'``, or both.

See: require-sri-for-known-tokens_

``CSP_UPGRADE_INSECURE_REQUESTS``
Include ``upgrade-insecure-requests`` directive. A boolean. *False*
Include ``upgrade-insecure-requests`` directive. A ``boolean``. *False*

See: upgrade-insecure-requests_

``CSP_REQUIRE_TRUSTED_TYPES_FOR``
Include ``reuire-trusted-types-for`` directive. A tuple or list. *None*
Valid values: ``'script'``
Note: This doesn't use default-src as a fall-back.
Include ``require-trusted-types-for`` directive.
A ``tuple`` or ``list``. *None*

Valid values: ``["'script'"]``

``CSP_TRUSTED_TYPES``
Include ``trusted-types`` directive. A tuple of list. *This header is empty by default*
Valid values: a list of allowed policy names that may include ``default`` and/or ``'allow-duplicates'``
Note: This doesn't use default-src as a fall-back.
Include ``trusted-types`` directive.
A ``tuple`` or ``list``. *None*

Valid values: a ``list`` of allowed policy names that may include
``default`` and/or ``'allow-duplicates'``

``CSP_BLOCK_ALL_MIXED_CONTENT``
Include ``block-all-mixed-content`` directive. A boolean. *False*
Include ``block-all-mixed-content`` directive. A ``boolean``. *False*

See: block-all-mixed-content_

``CSP_INCLUDE_NONCE_IN``
Include dynamically generated nonce in all listed directives, e.g. ``CSP_INCLUDE_NONCE_IN=['script-src']`` will add ``'nonce-<b64-value>'`` to the ``script-src`` directive. A tuple or list. *None*
Include dynamically generated nonce in all listed directives.
A ``tuple`` or ``list``, e.g.: ``CSP_INCLUDE_NONCE_IN = ['script-src']``
will add ``'nonce-<b64-value>'`` to the ``script-src`` directive.
*['default-src']*

Note: The nonce value will only be generated if ``request.csp_nonce``
is accessed during the request/response cycle.


Changing the Policy
Expand All @@ -124,22 +174,25 @@ 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 :ref:`reports <reports-chapter>` for more info. A
boolean. *False*
Send "report-only" headers instead of real headers.
A ``boolean``. *False*

See the spec_ and the chapter on :ref:`reports <reports-chapter>` for
more info.

``CSP_EXCLUDE_URL_PREFIXES``
A **tuple** of URL prefixes. URLs beginning with any of these will
not get the CSP headers. *()*
A ``tuple`` (*not* a ``list``) of URL prefixes. URLs beginning with any
of these will not get the CSP headers. *()*

.. warning::

Excluding any path on your site will eliminate the benefits of CSP
everywhere on your site. The typical browser security model for
JavaScript considers all paths alike. A Cross-Site Scripting flaw
on, e.g., `excluded-page/` can therefore be leveraged to access everything
on the same origin.
on, e.g., ``excluded-page/`` can therefore be leveraged to access
everything on the same origin.

.. _Content-Security-Policy: http://www.w3.org/TR/CSP/
.. _Content-Security-Policy: https://www.w3.org/TR/CSP/
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

.. _Content-Security-Policy-L3: https://w3c.github.io/webappsec-csp/
.. _spec: Content-Security-Policy_
.. _require-sri-for-known-tokens: https://w3c.github.io/webappsec-subresource-integrity/#opt-in-require-sri-for
Expand Down