|
1 | 1 | # volto-csp |
2 | 2 |
|
3 | | -## Introduction |
| 3 | +Volto addon to provide Content Security Policy (CSP) headers to a volto site. |
4 | 4 |
|
5 | | -## Development |
| 5 | +For more information on CSP see: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy |
6 | 6 |
|
7 | | -You can develop an add-on in isolation using the boilerplate already provided by the add-on generator. |
8 | | -The project is configured to have the current add-on installed and ready to work with. |
9 | | -This is useful to bootstrap an isolated environment that can be used to quickly develop the add-on or for demo purposes. |
10 | | -It's also useful when testing an add-on in a CI environment. |
| 7 | +This package sets the necessary `<meta http-equiv="Content-Security-Policy">` tag in the head section of a rendered page. |
11 | 8 |
|
12 | | -```{note} |
13 | | -It's quite similar when you develop a Plone backend add-on in the Python side, and embed a ready to use Plone build (using buildout or pip) in order to develop and test the package. |
14 | | -``` |
15 | | - |
16 | | -The dockerized approach performs all these actions in a custom built docker environment: |
17 | | - |
18 | | -1. Generates a vanilla project using the official Volto Yo Generator (@plone/generator-volto) |
19 | | -2. Configures it to use the add-on with the name stated in the `package.json` |
20 | | -3. Links the root of the add-on inside the created project |
21 | | - |
22 | | -After that you can use the inner dockerized project, and run any standard Volto command for linting, acceptance test or unit tests using Makefile commands provided for your convenience. |
| 9 | +It automtacially adds the hash values for inline scripts generated by volto, meaning `unsafe-inline` need not be used when hosting a volto site. |
23 | 10 |
|
24 | | -### Setup the environment |
| 11 | +## Installation |
25 | 12 |
|
26 | | -Run once |
| 13 | +Add the following lines to your `package.json`: |
27 | 14 |
|
28 | | -```shell |
29 | | -make dev |
30 | 15 | ``` |
31 | | - |
32 | | -which will build and launch the backend and frontend containers. |
33 | | -There's no need to build them again after doing it the first time unless something has changed from the container setup. |
34 | | - |
35 | | -In order to make the local IDE play well with this setup, is it required to run once `yarn` to install locally the required packages (ESlint, Prettier, Stylelint). |
36 | | - |
37 | | -Run |
38 | | - |
39 | | -```shell |
40 | | -yarn |
| 16 | +"addons": [ |
| 17 | + "volto-csp" |
| 18 | + ], |
41 | 19 | ``` |
42 | 20 |
|
43 | | -### Build the containers manually |
44 | | - |
45 | | -Run |
| 21 | +and run `yarn build` |
46 | 22 |
|
47 | | -```shell |
48 | | -make build-backend |
49 | | -make build-addon |
50 | | -``` |
| 23 | +## Basic Usage |
51 | 24 |
|
52 | | -### Run the containers |
| 25 | +This addon is enabled by setting one or more of the `RAZZLE_CSP_...` headers. |
53 | 26 |
|
54 | | -Run |
| 27 | +E.g. to set the `default-src` directive to `'self' data: https:` you would set: |
55 | 28 |
|
56 | | -```shell |
57 | | -make start-dev |
| 29 | +``` |
| 30 | +RAZZLE_CSP_DEFAULT_SRC="'self' data: https:" |
58 | 31 | ``` |
59 | 32 |
|
60 | | -This will start both the frontend and backend containers. |
61 | | - |
62 | | -### Stop Backend (Docker) |
63 | | - |
64 | | -After developing, in order to stop the running backend, don't forget to run: |
| 33 | +Every valid CSP header can be set this way. |
65 | 34 |
|
66 | | -Run |
| 35 | +CSP directives can be added to `RAZZLE_CSP_` by taking the directive name, swappings hyphens (`-`) to underscores (`_`) and making it uppercase. |
67 | 36 |
|
68 | | -```shell |
69 | | -make stop-backend |
70 | | -``` |
| 37 | +Some common values are: |
71 | 38 |
|
72 | | -### Linting |
| 39 | +--- |
| 40 | +Directive|Environment Variable |
| 41 | +-|- |
| 42 | +`default-src`|`RAZZLE_CSP_DEFAULT_SRC` |
| 43 | +`script-src`|`RAZZLE_CSP_SCRIPT_SRC` |
| 44 | +`font-src`|`RAZZLE_CSP_FONT_SRC` |
73 | 45 |
|
74 | | -Run |
75 | 46 |
|
76 | | -```shell |
77 | | -make lint |
78 | | -``` |
| 47 | +The full list of environment variables is below. |
79 | 48 |
|
80 | | -### Formatting |
| 49 | +## Script Hashes |
81 | 50 |
|
82 | | -Run |
| 51 | +Volto includes a number of inline scripts. Good practice is to not use the `unsafe-inline` source value for `script-src`. This package creates sha256 hashes of the inline scripts and includes those hash digests as sources in any `script-src` directive. |
83 | 52 |
|
84 | | -```shell |
85 | | -make format |
86 | | -``` |
| 53 | +If `RAZZLE_CSP_DEFAULT_SRC` is set and no value for `RAZZLE_CSP_SCRIPT_SRC` is set. Then the addon will add the `script-src` directive as a duplicate of the `default-src` with the hashed inline scripts added. |
87 | 54 |
|
88 | | -### i18n |
| 55 | +## Critical CSS |
89 | 56 |
|
90 | | -Run |
| 57 | +Volto allows you to automatically include [critical css](https://2022.training.plone.org/effective-volto/development/criticalCSS.html) as inline styles. |
91 | 58 |
|
92 | | -```shell |
93 | | -make i18n |
94 | | -``` |
| 59 | +This addon will generate and add the necessary hashsum for the critical css to the `style-src` directive. |
95 | 60 |
|
96 | | -### Unit tests |
| 61 | +The addon has not been configured to work with single page critical css. If you are setting `settings.serverConfig.readCricitalCss` the checksum will likely not match. It may be possible to integrate this kind of config in future, please raise an issue if you need make use of it. |
| 62 | +## Development Mode |
97 | 63 |
|
98 | | -Run |
| 64 | +If you set `RAZZLE_CSP_DEFAULT_SRC` or `RAZZLE_CSP_STYLE_SRC` and are running in development mode, this addon will automatically include the `'unsafe-inline'` to the `style-src` directive. This is because in development mode Volto adds a lot of inline styles which would otherwise be blocked. |
99 | 65 |
|
100 | | -```shell |
101 | | -make test |
102 | | -``` |
| 66 | +Future versions of this addon may be able to generate and add the hashes for inline styles. |
| 67 | +## Limitations |
103 | 68 |
|
104 | | -### Acceptance tests |
| 69 | +As this package adds the policy via meta http-equiv tags it has some limitations vs setting http headers: |
105 | 70 |
|
106 | | -Run once |
| 71 | + - The following directives aren't supported: |
| 72 | + - report-uri |
| 73 | + - frame-ancestors |
| 74 | + - sandbox |
107 | 75 |
|
108 | | -```shell |
109 | | -make install-acceptance |
110 | | -``` |
| 76 | +This means that if you wish to enable CSP reporting, you will not be able to use this addon. A workaround is to set the same policy via HTTP headers using `Content-Security-Policy-Report-Only`. This would give you error reporting as well as the additional script hashing provided by this package. In this scenario, you would need to enable `unsafe-inline` in the http headers for `script-src` (otherwise you would get reports every time a page is rendered). |
111 | 77 |
|
112 | | -For starting the servers |
| 78 | +## Environment Variables |
113 | 79 |
|
114 | | -Run |
| 80 | +### Special Variables |
115 | 81 |
|
116 | | -```shell |
117 | | -make start-test-acceptance-server |
118 | 82 | ``` |
| 83 | +RAZZLE_CSP_DEFAULT_SRC |
| 84 | +RAZZLE_CSP_SCRIPT_SRC |
| 85 | +RAZZLE_CSP_STYLE_SRC |
| 86 | +``` |
| 87 | +### Standard Variables |
119 | 88 |
|
120 | | -The frontend is run in dev mode, so development while writing tests is possible. |
| 89 | +``` |
| 90 | +RAZZLE_CSP_BASE_URI |
| 91 | +RAZZLE_CSP_BLOCK_ALL_MIXED_CONTENT |
| 92 | +RAZZLE_CSP_CHILD_SRC |
| 93 | +RAZZLE_CSP_CONNECT_SRC |
| 94 | +RAZZLE_CSP_FONT_SRC |
| 95 | +RAZZLE_CSP_FORM_ACTION |
| 96 | +RAZZLE_CSP_FRAME_SRC |
| 97 | +RAZZLE_CSP_IMG_SRC |
| 98 | +RAZZLE_CSP_MANIFEST_SRC |
| 99 | +RAZZLE_CSP_MEDIA_SRC |
| 100 | +RAZZLE_CSP_OBJECT_SRC |
| 101 | +RAZZLE_CSP_REQUIRE_TRUSTED_TYPES_FOR |
| 102 | +RAZZLE_CSP_SCRIPT_SRC_ATTR |
| 103 | +RAZZLE_CSP_SCRIPT_SRC_ELEM |
| 104 | +RAZZLE_CSP_STYLE_SRC_ATTR |
| 105 | +RAZZLE_CSP_STYLE_SRC_ELEM |
| 106 | +RAZZLE_CSP_TRUSTED_TYPES |
| 107 | +RAZZLE_CSP_UPGRADE_INSECURE_REQUESTS |
| 108 | +RAZZLE_CSP_WORKDER_SRC |
| 109 | +``` |
| 110 | +### Deprecated Variables |
121 | 111 |
|
122 | | -Run |
| 112 | +A server side console warning will be displayed if the following are used. The headers will still be added to the meta tag. |
123 | 113 |
|
124 | | -```shell |
125 | | -make test-acceptance |
126 | 114 | ``` |
| 115 | +RAZZLE_CSP_PLUGIN_TYPES |
| 116 | +RAZZLE_CSP_PREFETCH_SRC |
| 117 | +RAZZLE_CSP_REFERRER |
| 118 | +``` |
| 119 | +### Invalid Variables |
127 | 120 |
|
128 | | -To run Cypress tests afterwards. |
129 | | - |
130 | | -When finished, don't forget to shutdown the backend server. |
| 121 | +These directives are not compatible with meta tag syntax and will not be added. |
131 | 122 |
|
132 | | -```shell |
133 | | -make stop-test-acceptance-server |
| 123 | +``` |
| 124 | +RAZZLE_CSP_FRAME_ANCESTORS |
| 125 | +RAZZLE_CSP_SANDBOX |
| 126 | +RAZZLE_CSP_REPORT_TO |
| 127 | +RAZZLE_CSP_REPORT_URI |
134 | 128 | ``` |
135 | 129 |
|
136 | | -### Release |
137 | | - |
138 | | -Run |
| 130 | +## Author |
139 | 131 |
|
140 | | -```shell |
141 | | -make release |
142 | | -``` |
| 132 | +[Jon Pentland](https://github.com/instification), PretaGov Ltd |
143 | 133 |
|
144 | | -For releasing a RC version |
| 134 | +## Licence |
145 | 135 |
|
146 | | -Run |
| 136 | +This addon is packaged under the MIT licence. See `LICENCE.md`. |
147 | 137 |
|
148 | | -```shell |
149 | | -make release-rc |
150 | | -``` |
0 commit comments