helmet-csp

Content Security Policy middleware

The Content-Security-Policy header mitigates a large number of attacks, such as [cross-site scripting][XSS]. See MDN's introductory article on Content Security Policy.

This header is powerful but likely requires some configuration for your specific app.

To configure this header, pass an object with a nested directives object. Each key is a directive name in camel case (such as defaultSrc) or kebab case (such as default-src). Each value is an array (or other iterable) of strings or functions for that directive. If a function appears in the array, it will be called with the request and response objects.

const contentSecurityPolicy = require("helmet-csp");

// Sets all of the defaults, but overrides `script-src`
// and disables the default `style-src`.
app.use(
  contentSecurityPolicy({
    directives: {
      "script-src": ["'self'", "example.com"],
      "style-src": null,
    },
  }),
);

// Sets the `script-src` directive to
// "'self' 'nonce-e33cc...'"
// (or similar)
app.use((req, res, next) => {
  res.locals.cspNonce = crypto.randomBytes(32).toString("hex");
  next();
});
app.use(
  contentSecurityPolicy({
    directives: {
      scriptSrc: ["'self'", (req, res) => `'nonce-${res.locals.cspNonce}'`],
    },
  }),
);

These directives are merged into a default policy, which you can disable by setting useDefaults to false.

// Sets "Content-Security-Policy: default-src 'self';
// script-src 'self' example.com;object-src 'none';
// upgrade-insecure-requests"
app.use(
  contentSecurityPolicy({
    useDefaults: false,
    directives: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "example.com"],
      objectSrc: ["'none'"],
      upgradeInsecureRequests: [],
    },
  }),
);

You can get the default directives object with contentSecurityPolicy.getDefaultDirectives(). Here is the default policy (formatted for readability):

default-src 'self';
base-uri 'self';
font-src 'self' https: data:;
form-action 'self';
frame-ancestors 'self';
img-src 'self' data:;
object-src 'none';
script-src 'self';
script-src-attr 'none';
style-src 'self' https: 'unsafe-inline';
upgrade-insecure-requests

The default-src directive can be explicitly disabled by setting its value to contentSecurityPolicy.dangerouslyDisableDefaultSrc, but this is not recommended.

You can set the Content-Security-Policy-Report-Only instead:

// Sets the Content-Security-Policy-Report-Only header
app.use(
  contentSecurityPolicy({
    directives: {
      /* ... */
    },
    reportOnly: true,
  }),
);

This module performs very little validation on your CSP. You should rely on CSP checkers like CSP Evaluator instead.

Changelog

4.0.0 - 2020-08-02

See the Helmet 4 upgrade guide for help upgrading from Helmet 3.

Added

• helmet.contentSecurityPolicy:
  • If no default-src directive is supplied, an error is thrown
  • Directive lists can be any iterable, not just arrays

Changed

• This package no longer has dependencies. This should have no effect on end users, other than speeding up installation time.
• helmet.contentSecurityPolicy:
  • There is now a default set of directives if none are supplied
  • Duplicate keys now throw an error. See helmetjs/csp#73
  • This middleware is more lenient, allowing more directive names or values
• helmet.xssFilter now disables the buggy XSS filter by default. See #230

Removed

• Dropped support for old Node versions. Node 10+ is now required
• helmet.featurePolicy. If you still need it, use the feature-policy package on npm.
• helmet.hpkp. If you still need it, use the hpkp package on npm.
• helmet.noCache. If you still need it, use the nocache package on npm.
• helmet.contentSecurityPolicy:
  • Removed browser sniffing (including the browserSniff and disableAndroid parameters). See helmetjs/csp#97
  • Removed conditional support. This includes directive functions and support for a function as the reportOnly. Read this if you need help.
  • Removed a lot of checks—you should be checking your CSP with a different tool
  • Removed support for legacy headers (and therefore the setAllHeaders parameter). Read this if you need help.
  • Removed the loose option
  • Removed support for functions as directive values. You must supply an iterable of strings
• helmet.frameguard:
  • Dropped support for the ALLOW-FROM action. Read more here.
• helmet.hidePoweredBy no longer accepts arguments. See this article to see how to replicate the removed behavior. See #224.
• helmet.hsts:
  • Dropped support for includeSubdomains with a lowercase D. See #231
  • Dropped support for setIf. Read this if you need help. See #232
• helmet.xssFilter no longer accepts options. Read "How to disable blocking with X-XSS-Protection" and "How to enable the report directive with X-XSS-Protection" if you need the legacy behavior.