CSP HTML Webpack Plugin

About

This plugin will generate meta content for your Content Security Policy tag and input the correct data into your HTML template, generated by html-webpack-plugin.

All inline JS and CSS will be hashed and inserted into the policy.

Installation

Install the plugin with npm:

1npm i --save-dev csp-html-webpack-plugin

Basic Usage

Include the following in your webpack config:

1const HtmlWebpackPlugin = require('html-webpack-plugin');
2const CspHtmlWebpackPlugin = require('csp-html-webpack-plugin');
3
4module.exports = {
5  // rest of webpack config
6
7  plugins: [
8    new HtmlWebpackPlugin()
9    new CspHtmlWebpackPlugin({
10      // config here, see below
11    })
12  ]
13}

Recommended Configuration

By default, the csp-html-webpack-plugin has a very lax policy. You should configure it for your needs.

A good starting policy would be the following:

new CspHtmlWebpackPlugin({
  'script-src': '',
  'style-src': ''
});

Although we're configuring script-src and style-src to be blank, the CSP plugin will scan your HTML generated in html-webpack-plugin for external/inline script and style tags, and will add the appropriate hashes and nonces to your CSP policy. This configuration will also add a base-uri and object-src entry that exist in the default policy:

<meta http-equiv="Content-Security-Policy" content="
  base-uri 'self';
  object-src 'none';
  script-src 'sha256-0Tumwf1AbPDHZO4kdvXUd4c5PiHwt55hre+RDxj9O3Q='
             'nonce-hOlyTAhW5QI5p+rv9VUPZg==';
  style-src 'sha256-zfLUTOi9wwJktpDIoBZQecK4DNIVxW8Tl0cadROvQgo='
">

This configuration should work for most use cases, and will provide a strong layer of extra security.

All Configuration Options

CspHtmlWebpackPlugin

This CspHtmlWebpackPlugin accepts 2 params with the following structure:

• {object} Policy (optional) - a flat object which defines your CSP policy. Valid keys and values can be found on the MDN CSP page. Values can either be a string, or an array of strings.
• {object} Additional Options (optional) - a flat object with the optional configuration options:
  • {boolean|Function} enabled - if false, or the function returns false, the empty CSP tag will be stripped from the html output.
    • The htmlPluginData is passed into the function as it's first param.
    • If enabled is set the false, it will disable generating a CSP for all instances of HtmlWebpackPlugin in your webpack config.
  • {string} hashingMethod - accepts 'sha256', 'sha384', 'sha512' - your node version must also accept this hashing method.
  • {object} hashEnabled - a <string, boolean> entry for which policy rules are allowed to include hashes
  • {object} nonceEnabled - a <string, boolean> entry for which policy rules are allowed to include nonces
  • {Function} processFn - allows the developer to overwrite the default method of what happens to the CSP after it has been created
    • Parameters are:
      • builtPolicy: a string containing the completed policy;
      • htmlPluginData: the HtmlWebpackPlugin object;
      • $: the cheerio object of the html file currently being processed
      • compilation: Internal webpack object to manipulate the build

HtmlWebpackPlugin

The plugin also adds a new config option onto each HtmlWebpackPlugin instance:

• {object} cspPlugin - an object containing the following properties:
  • {boolean} enabled - if false, the CSP tag will be removed from the HTML which this HtmlWebpackPlugin instance is generating.
  • {object} policy - A custom policy which should be applied only to this instance of the HtmlWebpackPlugin
  • {object} hashEnabled - a <string, boolean> entry for which policy rules are allowed to include hashes
  • {object} nonceEnabled - a <string, boolean> entry for which policy rules are allowed to include nonces
  • {Function} processFn - allows the developer to overwrite the default method of what happens to the CSP after it has been created
    • Parameters are:
      • builtPolicy: a string containing the completed policy;
      • htmlPluginData: the HtmlWebpackPlugin object;
      • $: the cheerio object of the html file currently being processed
      • compilation: Internal webpack object to manipulate the build

Order of Precedence:

You don't have to include the same policy / hashEnabled / nonceEnabled configuration object in both HtmlWebpackPlugin and CspHtmlWebpackPlugin.

• Config included in CspHtmlWebpackPlugin will be applied to all instances of HtmlWebpackPlugin.
• Config included in a single HtmlWebpackPlugin instantiation will only be applied to that instance.

In the case where a config object is defined in multiple places, it will be merged in the order defined below, with former keys overriding latter. This means entries for a specific rule will not be merged; they will be replaced.

> HtmlWebpackPlugin cspPlugin.policy
> CspHtmlWebpackPlugin policy
> CspHtmlWebpackPlugin defaultPolicy

Appendix

Default Policy:

1{
2  'base-uri': "'self'",
3  'object-src': "'none'",
4  'script-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"],
5  'style-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"]
6};

Default Additional Options:

1{
2  enabled: true
3  hashingMethod: 'sha256',
4  hashEnabled: {
5    'script-src': true,
6    'style-src': true
7  },
8  nonceEnabled: {
9    'script-src': true,
10    'style-src': true
11  },
12  processFn: defaultProcessFn
13}

Full Default Configuration:

1new HtmlWebpackPlugin({
2  cspPlugin: {
3    enabled: true,
4    policy: {
5      'base-uri': "'self'",
6      'object-src': "'none'",
7      'script-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"],
8      'style-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"]
9    },
10    hashEnabled: {
11      'script-src': true,
12      'style-src': true
13    },
14    nonceEnabled: {
15      'script-src': true,
16      'style-src': true
17    },
18    processFn: defaultProcessFn  // defined in the plugin itself
19  }
20});
21
22new CspHtmlWebpackPlugin({
23  'base-uri': "'self'",
24  'object-src': "'none'",
25  'script-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"],
26  'style-src': ["'unsafe-inline'", "'self'", "'unsafe-eval'"]
27}, {
28  enabled: true,
29  hashingMethod: 'sha256',
30  hashEnabled: {
31    'script-src': true,
32    'style-src': true
33  },
34  nonceEnabled: {
35    'script-src': true,
36    'style-src': true
37  },
38  processFn: defaultProcessFn  // defined in the plugin itself
39})

Advanced Usage

Generating a file containing the CSP directives

Some specific directives require the CSP to be sent to the client via a response header (e.g. report-uri and report-to) You can set your own processFn callback to make this happen.

nginx

In your webpack config:

1const RawSource = require('webpack-sources').RawSource;
2
3function generateNginxHeaderFile(
4  builtPolicy,
5  _htmlPluginData,
6  _obj,
7  compilation
8) {
9  const header =
10    'add_header Content-Security-Policy "' +
11    builtPolicy +
12    '; report-uri /csp-report/ ";';
13  compilation.emitAsset('nginx-csp-header.conf', new RawSource(header));
14}
15
16module.exports = {
17  {...},
18  plugins: [
19    new CspHtmlWebpackPlugin(
20      {...}, {
21      processFn: generateNginxHeaderFile
22    })
23  ]
24};

In your nginx config:

1location / {
2  ...
3  include /path/to/webpack/output/nginx-csp-header.conf
4}

Contribution

Contributions are most welcome! Please see the included contributing file for more information.

License

This project is licensed under MIT. Please see the included license file for more information.