Skip to content

Commit 13d45b5

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 13d45b5

File tree

1 file changed

+123
-63
lines changed

1 file changed

+123
-63
lines changed

‎docs/configuration.rst‎

Lines changed: 123 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -7,107 +7,164 @@ 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+
112+
Note: This doesn't use ``default-src`` as a fall-back.
113+
84114
``CSP_MANIFEST_SRC``
85-
Set the ``manifest-src`` directive. A tuple or list. *None*
115+
Set the ``manifest-src`` directive. A ``tuple`` or ``list``. *None*
116+
86117
``CSP_WORKER_SRC``
87-
Set the ``worker-src`` directive. A tuple or list. *None*
118+
Set the ``worker-src`` directive. A ``tuple`` or ``list``. *None*
119+
88120
``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.
121+
Set the ``plugin-types`` directive. A ``tuple`` or ``list``. *None*
122+
123+
Note: This doesn't use ``default-src`` as a fall-back.
124+
91125
``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.
126+
Set the ``require-sri-for`` directive. A ``tuple`` or ``list``. *None*
127+
Valid values: ``script``, ``style``, or both.
128+
129+
See: require-sri-for-known-tokens_
130+
131+
Note: This doesn't use ``default-src`` as a fall-back.
132+
95133
``CSP_UPGRADE_INSECURE_REQUESTS``
96-
Include ``upgrade-insecure-requests`` directive. A boolean. *False*
134+
Include ``upgrade-insecure-requests`` directive. A ``boolean``. *False*
135+
97136
See: upgrade-insecure-requests_
137+
98138
``CSP_REQUIRE_TRUSTED_TYPES_FOR``
99-
Include ``reuire-trusted-types-for`` directive. A tuple or list. *None*
139+
Include ``reuire-trusted-types-for`` directive.
140+
A ``tuple`` or ``list``. *None*
141+
100142
Valid values: ``'script'``
101-
Note: This doesn't use default-src as a fall-back.
143+
144+
Note: This doesn't use ``default-src`` as a fall-back.
145+
102146
``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.
147+
Include ``trusted-types`` directive.
148+
A ``tuple`` or ``list``. *None*
149+
150+
Valid values: a list of allowed policy names that may include
151+
``default`` and/or ``'allow-duplicates'``
152+
153+
Note: This doesn't use ``default-src`` as a fall-back.
154+
106155
``CSP_BLOCK_ALL_MIXED_CONTENT``
107-
Include ``block-all-mixed-content`` directive. A boolean. *False*
156+
Include ``block-all-mixed-content`` directive. A ``boolean``. *False*
157+
108158
See: block-all-mixed-content_
159+
109160
``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*
161+
Include dynamically generated nonce in all listed directives.
162+
A ``tuple`` or ``list``, e.g.: ``CSP_INCLUDE_NONCE_IN = ['script-src']``
163+
will add ``'nonce-<b64-value>'`` to the ``script-src`` directive.
164+
*['default-src']*
165+
166+
Note: The nonce value will only be included if ``request.cps_nonce``
167+
is accessed during the request/response cycle.
111168

112169

113170
Changing the Policy
@@ -124,22 +181,25 @@ These settings control the behavior of django-csp. Defaults are in
124181
*italics*.
125182

126183
``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*
184+
Send "report-only" headers instead of real headers.
185+
A ``boolean``. *False*
186+
187+
See the spec_ and the chapter on :ref:`reports <reports-chapter>` for
188+
more info.
189+
130190
``CSP_EXCLUDE_URL_PREFIXES``
131-
A **tuple** of URL prefixes. URLs beginning with any of these will
191+
A ``tuple`` of URL prefixes. URLs beginning with any of these will
132192
not get the CSP headers. *()*
133193

134194
.. warning::
135195

136196
Excluding any path on your site will eliminate the benefits of CSP
137197
everywhere on your site. The typical browser security model for
138198
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.
199+
on, e.g., ``excluded-page/`` can therefore be leveraged to access
200+
everything on the same origin.
141201

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

0 commit comments

Comments
 (0)