1 | # Content Security Policy middleware
|
2 |
|
3 | Content Security Policy (CSP) helps prevent unwanted content from being injected/loaded into your webpages. This can mitigate cross-site scripting (XSS) vulnerabilities, clickjacking, formjacking, malicious frames, unwanted trackers, and other web client-side attacks.
|
4 |
|
5 | If you want to learn how CSP works, check out the fantastic [HTML5 Rocks guide](https://www.html5rocks.com/en/tutorials/security/content-security-policy/), the [Content Security Policy Reference](https://content-security-policy.com/), and the [Content Security Policy specification](https://www.w3.org/TR/CSP/).
|
6 |
|
7 | This middleware helps set Content Security Policies.
|
8 |
|
9 | Basic usage:
|
10 |
|
11 | ```javascript
|
12 | const contentSecurityPolicy = require("helmet-csp");
|
13 |
|
14 | app.use(
|
15 | contentSecurityPolicy({
|
16 | useDefaults: true,
|
17 | directives: {
|
18 | defaultSrc: ["'self'", "default.example"],
|
19 | scriptSrc: ["'self'", "js.example.com"],
|
20 | objectSrc: ["'none'"],
|
21 | upgradeInsecureRequests: [],
|
22 | },
|
23 | reportOnly: false,
|
24 | })
|
25 | );
|
26 | ```
|
27 |
|
28 | If no directives are supplied, the following policy is set (whitespace added for readability):
|
29 |
|
30 | default-src 'self';
|
31 | base-uri 'self';
|
32 | block-all-mixed-content;
|
33 | font-src 'self' https: data:;
|
34 | frame-ancestors 'self';
|
35 | img-src 'self' data:;
|
36 | object-src 'none';
|
37 | script-src 'self';
|
38 | script-src-attr 'none';
|
39 | style-src 'self' https: 'unsafe-inline';
|
40 | upgrade-insecure-requests
|
41 |
|
42 | You can use this default with the `useDefaults` option. `useDefaults` is `false` by default, but will be `true` in the next major version of this module.
|
43 |
|
44 | You can also get the default directives object with `contentSecurityPolicy.getDefaultDirectives()`.
|
45 |
|
46 | You can set any directives you wish. `defaultSrc` is required, but can be explicitly disabled by setting its value to `contentSecurityPolicy.dangerouslyDisableDefaultSrc`. Directives can be kebab-cased (like `script-src`) or camel-cased (like `scriptSrc`). They are equivalent, but duplicates are not allowed.
|
47 |
|
48 | The `reportOnly` option, if set to `true`, sets the `Content-Security-Policy-Report-Only` header instead.
|
49 |
|
50 | This middleware does minimal validation. You should use a more sophisticated CSP validator, like [Google's CSP Evaluator](https://csp-evaluator.withgoogle.com/), to make sure your CSP looks good.
|
51 |
|
52 | ## Recipe: generating nonces
|
53 |
|
54 | You can dynamically generate nonces to allow inline `<script>` tags to be safely evaluated. Here's a simple example:
|
55 |
|
56 | ```js
|
57 | const crypto = require("crypto");
|
58 |
|
59 | app.use((req, res, next) => {
|
60 | res.locals.nonce = crypto.randomBytes(16).toString("hex");
|
61 | next();
|
62 | });
|
63 |
|
64 | app.use((req, res, next) => {
|
65 | csp({
|
66 | useDefaults: true,
|
67 | directives: {
|
68 | scriptSrc: ["'self'", `'nonce-${res.locals.nonce}'`],
|
69 | },
|
70 | })(req, res, next);
|
71 | });
|
72 |
|
73 | app.use((req, res) => {
|
74 | res.end(`<script nonce="${res.locals.nonce}">alert(1 + 1);</script>`);
|
75 | });
|
76 | ```
|
77 |
|
78 | ## See also
|
79 |
|
80 | - [Google's CSP Evaluator tool](https://csp-evaluator.withgoogle.com/)
|
81 | - [CSP Scanner](https://cspscanner.com/)
|
82 | - [GitHub's CSP journey](https://githubengineering.com/githubs-csp-journey/)
|
83 | - [Content Security Policy for Single Page Web Apps](https://developer.squareup.com/blog/content-security-policy-for-single-page-web-apps/)
|