Skip to content

Commit 517738e

Browse files
author
Jaap Roes
committed
Tweak configuration docs
* Change formatting and some wording for readability sake * Make defaults reflect the actual default values * Fix some typos
1 parent 3659ddc commit 517738e

File tree

1 file changed

+116
-65
lines changed

1 file changed

+116
-65
lines changed

‎docs/configuration.rst‎

Lines changed: 116 additions & 65 deletions
Original file line numberDiff line numberDiff line change
@@ -7,107 +7,155 @@ Configuring django-csp
77
Content-Security-Policy_ is a complicated header. There are many values
88
you may need to tweak here.
99

10-
.. note::
11-
Note when a setting requires a tuple or list. Since Python strings
12-
are iterable, you may get very strange policies and errors.
13-
14-
It's worth reading the latest CSP spec and making sure you understand it
10+
It's worth reading the latest CSP spec_ and making sure you understand it
1511
before configuring django-csp.
1612

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

1818
Policy Settings
1919
===============
2020

21-
These settings affect the policy in the header. The defaults are in
22-
*italics*.
21+
These settings affect the policy in the header. The defaults are in *italics*.
2322

2423
.. note::
2524
The "special" source values of ``'self'``, ``'unsafe-inline'``,
26-
``'unsafe-eval'``, ``'none'`` and hash-source (``'sha256-...'``) must be quoted! e.g.:
27-
``CSP_DEFAULT_SRC = ("'self'",)``. Without quotes they will not work
28-
as intended.
25+
``'unsafe-eval'``, ``'none'`` and hash-source (``'sha256-...'``) must be
26+
quoted! e.g.: ``CSP_DEFAULT_SRC = ("'self'",)``. Without quotes they will
27+
not work as intended.
2928

3029
``CSP_DEFAULT_SRC``
31-
Set the ``default-src`` directive. A tuple or list of
32-
values, e.g. ``("'self'", 'cdn.example.net')``. *'self'*
30+
Set the ``default-src`` directive. A ``tuple`` or ``list`` of values,
31+
e.g.: ``("'self'", 'cdn.example.net')``. *["'self'"]*
32+
3333
``CSP_SCRIPT_SRC``
34-
Set the ``script-src`` directive. A tuple or list. *None*
34+
Set the ``script-src`` directive. A ``tuple`` or ``list``. *None*
35+
3536
``CSP_SCRIPT_SRC_ATTR``
36-
Set the ``script-src-attr`` directive. A tuple or list. *None*
37+
Set the ``script-src-attr`` directive. A ``tuple`` or ``list``. *None*
38+
3739
``CSP_SCRIPT_SRC_ELEM``
38-
Set the ``script-src-elem`` directive. A tuple or list. *None*
40+
Set the ``script-src-elem`` directive. A ``tuple`` or ``list``. *None*
41+
3942
``CSP_IMG_SRC``
40-
Set the ``img-src`` directive. A tuple or list. *None*
43+
Set the ``img-src`` directive. A ``tuple`` or ``list``. *None*
44+
4145
``CSP_OBJECT_SRC``
42-
Set the ``object-src`` directive. A tuple or list. *None*
46+
Set the ``object-src`` directive. A ``tuple`` or ``list``. *None*
47+
4348
``CSP_PREFETCH_SRC``
44-
Set the ``prefetch-src`` directive. A tuple or list. *None*
49+
Set the ``prefetch-src`` directive. A ``tuple`` or ``list``. *None*
50+
4551
``CSP_MEDIA_SRC``
46-
Set the ``media-src`` directive. A tuple or list. *None*
52+
Set the ``media-src`` directive. A ``tuple`` or ``list``. *None*
53+
4754
``CSP_FRAME_SRC``
48-
Set the ``frame-src`` directive. A tuple or list. *None*
55+
Set the ``frame-src`` directive. A ``tuple`` or ``list``. *None*
56+
4957
``CSP_FONT_SRC``
50-
Set the ``font-src`` directive. A tuple or list. *None*
58+
Set the ``font-src`` directive. A ``tuple`` or ``list``. *None*
59+
5160
``CSP_CONNECT_SRC``
52-
Set the ``connect-src`` directive. A tuple or list. *None*
61+
Set the ``connect-src`` directive. A ``tuple`` or ``list``. *None*
62+
5363
``CSP_STYLE_SRC``
54-
Set the ``style-src`` directive. A tuple or list. *None*
64+
Set the ``style-src`` directive. A ``tuple`` or ``list``. *None*
65+
5566
``CSP_STYLE_SRC_ATTR``
56-
Set the ``style-src-attr`` directive. A tuple or list. *None*
67+
Set the ``style-src-attr`` directive. A ``tuple`` or ``list``. *None*
68+
5769
``CSP_STYLE_SRC_ELEM``
58-
Set the ``style-src-elem`` directive. A tuple or list. *None*
70+
Set the ``style-src-elem`` directive. A ``tuple`` or ``list``. *None*
71+
5972
``CSP_BASE_URI``
60-
Set the ``base-uri`` directive. A tuple or list. *None*
61-
Note: This doesn't use default-src as a fall-back.
73+
Set the ``base-uri`` directive. A ``tuple`` or ``list``. *None*
74+
75+
Note: This doesn't use ``default-src`` as a fall-back.
76+
6277
``CSP_CHILD_SRC``
63-
Set the ``child-src`` directive. A tuple or list. *None*
78+
Set the ``child-src`` directive. A ``tuple`` or ``list``. *None*
79+
6480
``CSP_FRAME_ANCESTORS``
65-
Set the ``frame-ancestors`` directive. A tuple or list. *None*
66-
Note: This doesn't use default-src as a fall-back.
81+
Set the ``frame-ancestors`` directive. A ``tuple`` or ``list``. *None*
82+
83+
Note: This doesn't use ``default-src`` as a fall-back.
84+
6785
``CSP_NAVIGATE_TO``
68-
Set the ``navigate-to`` directive. A tuple or list. *None*
69-
Note: This doesn't use default-src as a fall-back.
86+
Set the ``navigate-to`` directive. A ``tuple`` or ``list``. *None*
87+
88+
Note: This doesn't use ``default-src`` as a fall-back.
89+
7090
``CSP_FORM_ACTION``
71-
Set the ``FORM_ACTION`` directive. A tuple or list. *None*
72-
Note: This doesn't use default-src as a fall-back.
91+
Set the ``FORM_ACTION`` directive. A ``tuple`` or ``list``. *None*
92+
93+
Note: This doesn't use ``default-src`` as a fall-back.
94+
7395
``CSP_SANDBOX``
74-
Set the ``sandbox`` directive. A tuple or list. *None*
75-
Note: This doesn't use default-src as a fall-back.
96+
Set the ``sandbox`` directive. A ``tuple`` or ``list``. *None*
97+
98+
Note: This doesn't use ``default-src`` as a fall-back.
99+
76100
``CSP_REPORT_URI``
77-
Set the ``report-uri`` directive. A tuple or list. Each URI can be a
78-
full or relative URI. *None*
79-
Note: This doesn't use default-src as a fall-back.
101+
Set the ``report-uri`` directive. A ``tuple`` or ``list`` of URIs.
102+
Each URI can be a full or relative URI. *None*
103+
104+
Note: This doesn't use ``default-src`` as a fall-back.
105+
80106
``CSP_REPORT_TO``
81-
Set the ``report-to`` directive. A string describing a reporting group. *None*
82-
Note: This doesn't use default-src as a fall-back.
107+
Set the ``report-to`` directive. A ``string`` describing a reporting
108+
group. *None*
109+
83110
See Section 1.2: https://w3c.github.io/reporting/#group
111+
84112
``CSP_MANIFEST_SRC``
85-
Set the ``manifest-src`` directive. A tuple or list. *None*
113+
Set the ``manifest-src`` directive. A ``tuple`` or ``list``. *None*
114+
86115
``CSP_WORKER_SRC``
87-
Set the ``worker-src`` directive. A tuple or list. *None*
116+
Set the ``worker-src`` directive. A ``tuple`` or ``list``. *None*
117+
88118
``CSP_PLUGIN_TYPES``
89-
Set the ``plugin-types`` directive. A tuple or list. *None*
90-
Note: This doesn't use default-src as a fall-back.
119+
Set the ``plugin-types`` directive. A ``tuple`` or ``list``. *None*
120+
91121
``CSP_REQUIRE_SRI_FOR``
92-
Set the ``require-sri-for`` directive. A tuple or list. *None*
93-
Valid values: ``script``, ``style``, or both. See: require-sri-for-known-tokens_
94-
Note: This doesn't use default-src as a fall-back.
122+
Set the ``require-sri-for`` directive. A ``tuple`` or ``list``. *None*
123+
124+
Valid values: a ``list`` containing ``'script'``, ``'style'``, or both.
125+
126+
See: require-sri-for-known-tokens_
127+
95128
``CSP_UPGRADE_INSECURE_REQUESTS``
96-
Include ``upgrade-insecure-requests`` directive. A boolean. *False*
129+
Include ``upgrade-insecure-requests`` directive. A ``boolean``. *False*
130+
97131
See: upgrade-insecure-requests_
132+
98133
``CSP_REQUIRE_TRUSTED_TYPES_FOR``
99-
Include ``reuire-trusted-types-for`` directive. A tuple or list. *None*
100-
Valid values: ``'script'``
101-
Note: This doesn't use default-src as a fall-back.
134+
Include ``require-trusted-types-for`` directive.
135+
A ``tuple`` or ``list``. *None*
136+
137+
Valid values: ``["'script'"]``
138+
102139
``CSP_TRUSTED_TYPES``
103-
Include ``trusted-types`` directive. A tuple of list. *This header is empty by default*
104-
Valid values: a list of allowed policy names that may include ``default`` and/or ``'allow-duplicates'``
105-
Note: This doesn't use default-src as a fall-back.
140+
Include ``trusted-types`` directive.
141+
A ``tuple`` or ``list``. *None*
142+
143+
Valid values: a ``list`` of allowed policy names that may include
144+
``default`` and/or ``'allow-duplicates'``
145+
106146
``CSP_BLOCK_ALL_MIXED_CONTENT``
107-
Include ``block-all-mixed-content`` directive. A boolean. *False*
147+
Include ``block-all-mixed-content`` directive. A ``boolean``. *False*
148+
108149
See: block-all-mixed-content_
150+
109151
``CSP_INCLUDE_NONCE_IN``
110-
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*
152+
Include dynamically generated nonce in all listed directives.
153+
A ``tuple`` or ``list``, e.g.: ``CSP_INCLUDE_NONCE_IN = ['script-src']``
154+
will add ``'nonce-<b64-value>'`` to the ``script-src`` directive.
155+
*['default-src']*
156+
157+
Note: The nonce value will only be generated if ``request.cps_nonce``
158+
is accessed during the request/response cycle.
111159

112160

113161
Changing the Policy
@@ -124,22 +172,25 @@ These settings control the behavior of django-csp. Defaults are in
124172
*italics*.
125173

126174
``CSP_REPORT_ONLY``
127-
Send "report-only" headers instead of real headers. See the spec_
128-
and the chapter on :ref:`reports <reports-chapter>` for more info. A
129-
boolean. *False*
175+
Send "report-only" headers instead of real headers.
176+
A ``boolean``. *False*
177+
178+
See the spec_ and the chapter on :ref:`reports <reports-chapter>` for
179+
more info.
180+
130181
``CSP_EXCLUDE_URL_PREFIXES``
131-
A **tuple** of URL prefixes. URLs beginning with any of these will
132-
not get the CSP headers. *()*
182+
A ``tuple`` (*not* a ``list``) of URL prefixes. URLs beginning with any
183+
of these will not get the CSP headers. *()*
133184

134185
.. warning::
135186

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

142-
.. _Content-Security-Policy: http://www.w3.org/TR/CSP/
193+
.. _Content-Security-Policy: https://www.w3.org/TR/CSP/
143194
.. _Content-Security-Policy-L3: https://w3c.github.io/webappsec-csp/
144195
.. _spec: Content-Security-Policy_
145196
.. _require-sri-for-known-tokens: https://w3c.github.io/webappsec-subresource-integrity/#opt-in-require-sri-for

0 commit comments

Comments
 (0)