Skip to content

Commit 372502c

Browse files
garvinhickinglinawolfbrotkruemlsarahmccarthy123
authored
[TASK] Rework CSP documentation, add reference to Config module (#5455)
* [TASK] Rework CSP documentation, add reference to Config module Resolves #5005 Releases: main, 13.4, 12.4 * [TASK] Apply review feedback * [TASK] Link to "Nonce" * [TASK] Add real-world example, add sub-sections, more more more * [TASK] Adjust for CGL * [TASK] More CGL * Update Index.rst Co-authored-by: Lina Wolf <[email protected]> * Update Index.rst Co-authored-by: Lina Wolf <[email protected]> * Update Index.rst * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update _csp_example_com.yaml Co-authored-by: Chris Müller <[email protected]> * Update _csp_example_org.yaml Co-authored-by: Chris Müller <[email protected]> * Update ContentSecurityPolicy.rst Co-authored-by: Chris Müller <[email protected]> * [TASK] Adjust intendation * [TASK] Language checks Releases: main * Update _csp_example_com.yaml Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update Index.rst Co-authored-by: Chris Müller <[email protected]> * Update _csp_example_org.yaml Co-authored-by: Chris Müller <[email protected]> * [TASK] Add link to chris' CSP resources * [TASK] Do not whitelist iframe src examples --------- Co-authored-by: Lina Wolf <[email protected]> Co-authored-by: Chris Müller <[email protected]> Co-authored-by: Sarah McCarthy <[email protected]>
1 parent 430a677 commit 372502c

File tree

8 files changed

+533
-58
lines changed

8 files changed

+533
-58
lines changed

‎Documentation/ApiOverview/ContentSecurityPolicy/Index.rst‎

Lines changed: 356 additions & 16 deletions
Large diffs are not rendered by default.

‎Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies.php‎

Lines changed: 58 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -12,50 +12,66 @@
1212
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
1313
use TYPO3\CMS\Core\Type\Map;
1414

15-
return Map::fromEntries([
16-
// Provide declarations for the backend
17-
Scope::backend(),
18-
// NOTICE: When using `MutationMode::Set` existing declarations will be overridden
15+
return Map::fromEntries(
16+
[
17+
// Provide declarations for the backend
18+
Scope::backend(),
19+
// NOTICE: When using `MutationMode::Set` existing declarations will be overridden
1920

20-
new MutationCollection(
21-
// Results in `default-src 'self'`
22-
new Mutation(
23-
MutationMode::Set,
24-
Directive::DefaultSrc,
25-
SourceKeyword::self,
26-
),
21+
new MutationCollection(
22+
// Results in `default-src 'self'`
23+
new Mutation(
24+
MutationMode::Set,
25+
Directive::DefaultSrc,
26+
SourceKeyword::self,
27+
),
2728

28-
// Extends the ancestor directive ('default-src'),
29-
// thus reuses 'self' and adds additional sources
30-
// Results in `img-src 'self' data: https://*.typo3.org`
31-
new Mutation(
32-
MutationMode::Extend,
33-
Directive::ImgSrc,
34-
SourceScheme::data,
35-
new UriValue('https://*.typo3.org'),
36-
),
37-
// NOTICE: the following two instructions for `Directive::ImgSrc` are identical to the previous instruction,
38-
// `MutationMode::Extend` is a shortcut for `MutationMode::InheritOnce` and `MutationMode::Append`
39-
// new Mutation(MutationMode::InheritOnce, Directive::ImgSrc, SourceScheme::data),
40-
// new Mutation(MutationMode::Append, Directive::ImgSrc, SourceScheme::data, new UriValue('https://*.typo3.org')),
29+
// Extends the ancestor directive ('default-src'),
30+
// thus reuses 'self' and adds additional sources
31+
// Results in `img-src 'self' data: https://*.typo3.org`
32+
new Mutation(
33+
MutationMode::Extend,
34+
Directive::ImgSrc,
35+
SourceScheme::data,
36+
new UriValue('https://*.typo3.org'),
37+
),
38+
// NOTICE: the following two instructions for `Directive::ImgSrc` are identical to the previous instruction,
39+
// `MutationMode::Extend` is a shortcut for `MutationMode::InheritOnce` and `MutationMode::Append`
40+
// new Mutation(MutationMode::InheritOnce, Directive::ImgSrc, SourceScheme::data),
41+
// new Mutation(MutationMode::Append, Directive::ImgSrc, SourceScheme::data, new UriValue('https://*.typo3.org')),
4142

42-
// Extends the ancestor directive ('default-src'),
43-
// thus reuses 'self' and adds additional sources
44-
// Results in `script-src 'self' 'nonce-[random]'`
45-
// ('nonce-proxy' is substituted when compiling the policy)
46-
new Mutation(
47-
MutationMode::Extend,
48-
Directive::ScriptSrc,
49-
SourceKeyword::nonceProxy,
50-
),
43+
// Extends the ancestor directive ('default-src'),
44+
// thus reuses 'self' and adds additional sources
45+
// Results in `script-src 'self' 'nonce-[random]'`
46+
// ('nonce-proxy' is substituted when compiling the policy)
47+
new Mutation(
48+
MutationMode::Extend,
49+
Directive::ScriptSrc,
50+
SourceKeyword::nonceProxy,
51+
),
5152

52-
// Sets (overrides) the directive,
53-
// thus ignores 'self' of the 'default-src' directive
54-
// Results in `worker-src blob:`
55-
new Mutation(
56-
MutationMode::Set,
57-
Directive::WorkerSrc,
58-
SourceScheme::blob,
53+
// Sets (overrides) the directive,
54+
// thus ignores 'self' of the 'default-src' directive
55+
// Results in `worker-src blob:`
56+
new Mutation(
57+
MutationMode::Set,
58+
Directive::WorkerSrc,
59+
SourceScheme::blob,
60+
),
61+
),
62+
],
63+
[
64+
// You can also additionally provide frontend declarations
65+
Scope::frontend(),
66+
new MutationCollection(
67+
// Sets (overrides) the directive,
68+
// thus ignores 'self' of the 'default-src' directive
69+
// Results in `worker-src https://*.workers.example.com:`
70+
new Mutation(
71+
MutationMode::Set,
72+
Directive::WorkerSrc,
73+
new UriValue('https://*.workers.example.com'),
74+
),
5975
),
60-
),
61-
]);
76+
],
77+
);

‎Documentation/ApiOverview/ContentSecurityPolicy/_ContentSecurityPolicies_example.php‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Directive;
6+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Mutation;
7+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationCollection;
8+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\MutationMode;
9+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\Scope;
10+
use TYPO3\CMS\Core\Security\ContentSecurityPolicy\UriValue;
11+
use TYPO3\CMS\Core\Type\Map;
12+
13+
return Map::fromEntries([
14+
// Provide declarations for the backend only
15+
Scope::backend(),
16+
new MutationCollection(
17+
new Mutation(
18+
MutationMode::Extend,
19+
// Note: it's "FrameSrc" not "IFrameSrc"
20+
Directive::FrameSrc,
21+
new UriValue('https://cdn.example.com'),
22+
),
23+
new Mutation(
24+
MutationMode::Extend,
25+
Directive::ImgSrc,
26+
new UriValue('https://cdn.example.com'),
27+
),
28+
new Mutation(
29+
MutationMode::Extend,
30+
Directive::ScriptSrc,
31+
new UriValue('https://cdn.example.com'),
32+
),
33+
),
34+
]);

‎Documentation/ApiOverview/ContentSecurityPolicy/_csp_enforce.yaml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
enforce:
2+
inheritDefault: true
3+
# site-specific mutations could also be listed, like this:
4+
# mutations:
5+
# - mode: "append"
6+
# directive: "img-src"
7+
# sources:
8+
# - "cdn.example.com"
9+
# - "assets.example.com"
10+
11+
# alternatively (or additionally!), reporting can be set too,
12+
# for example when testing stricter rules than above
13+
# (note the missing 'assets.example.com')
14+
# reporting:
15+
# inheritDefault: true
16+
# mutations:
17+
# - mode: "append"
18+
# directive: "img-src"
19+
# sources:
20+
# - "cdn.example.com"
21+
#

‎Documentation/ApiOverview/ContentSecurityPolicy/_csp_example_com.yaml‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Inherits default frontend policy mutations provided by Core and 3rd-party extensions (enabled per default)
2+
inheritDefault: true
3+
mutations:
4+
# Allow frames/iframes to TRUSTED specific locations
5+
# Avoid "protocol only" white-list like "https:" here,
6+
# because it could inject javascript easily, the most important reason
7+
# why CSP was invented was to block security issues like this.
8+
# (Note: it's "frame-src" not "iframe-src")
9+
- mode: "extend"
10+
directive: "frame-src"
11+
sources:
12+
- "https://*.example.org"
13+
- "https://*.example.com"
14+
- "https://*.instagram.com"
15+
- "https://*.vimeo.com"
16+
- "https://*.youtube.com"
17+
18+
# Allow img src to anyhwere (HTTPS only, not HTTP)
19+
- mode: "extend"
20+
directive: "img-src"
21+
sources:
22+
- "https:"
23+
24+
# Allow script src to the specified domains (HTTPS only)
25+
- mode: "extend"
26+
directive: "script-src"
27+
sources:
28+
- "https://cdn.example.com"
29+
- "https://*.youtube.com"
30+
- "https://*.google.com"

‎Documentation/ApiOverview/ContentSecurityPolicy/_csp_example_org.yaml‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# Inherits default frontend policy mutations provided by Core and 3rd-party extensions (enabled per default)
2+
inheritDefault: true
3+
mutations:
4+
# Allow frame/iframe src to the specified domains (HTTPS only)
5+
- mode: "extend"
6+
# (Note: it's "frame-src" not "iframe-src")
7+
directive: "frame-src"
8+
sources:
9+
- "https://cdn.example.com"
10+
- "https://*.youtube.com"
11+
12+
# Allow img src to the specified domains (HTTPS only)
13+
- mode: "extend"
14+
directive: "img-src"
15+
sources:
16+
- "https://cdn.example.com"
17+
- "https://*.instagram.com"
18+
19+
# Allow script src to the specified domains (HTTPS only)
20+
- mode: "extend"
21+
directive: "script-src"
22+
sources:
23+
- "https://cdn.example.com"
24+
- "https://*.youtube.com"
25+
- "https://*.google.com"

‎Documentation/Images/ManualScreenshots/ContentSecurityPolicy/CspBackendConfiguration.png‎

103 KB
Loading

‎Documentation/Security/GuidelinesAdministrators/ContentSecurityPolicy.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,15 @@ impractical for some sites) or add content security policy headers for
3131
these directories - basically all public available base directories of
3232
file storages (`sys_file_storage`).
3333

34+
Please note that the CSP configuration in :ref:`content-security-policy`
35+
only applies to pages served by TYPO3 (when PHP is involved, allowing
36+
the configured Middleware to be utilized).
37+
38+
Files that are not served by TYPO3, as is the case with files in :file:`fileadmin/`, need
39+
manual server configuration if CSP is to be applied, for example to :file:`.svg` files
40+
to prevent possible execution and loading of further
41+
remote resources or scripts.
42+
3443
The following example sends a corresponding CSP_ header for any file
3544
accessed via :samp:`https://example.org/fileadmin/...`:
3645

0 commit comments

Comments
 (0)