Repository files navigation

This plugin will generate meta content for yourContent Security Policytag and input the correct data into your HTML template, generated byhtml-webpack-plugin.

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

Install the plugin with npm:

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

Include the following in your webpack config:

constHtmlWebpackPlugin=require('html-webpack-plugin');constCspHtmlWebpackPlugin=require('csp-html-webpack-plugin');module.exports={// rest of webpack configplugins:[newHtmlWebpackPlugin()newCspHtmlWebpackPlugin({// config here, see below})]}

By default, thecsp-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 configuringscript-src andstyle-src to be blank, the CSP plugin will scan your HTMLgenerated inhtml-webpack-plugin for external/inline script and style tags, and will add the appropriatehashes and nonces to your CSP policy. This configuration will also add abase-uri andobject-src entrythat 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.

ThisCspHtmlWebpackPlugin 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 theMDN 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.
    • ThehtmlPluginData is passed into the function as it's first param.
    • Ifenabled is set the false, it will disable generating a CSP for all instances ofHtmlWebpackPlugin 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: astring containing the completed policy;
      • htmlPluginData: theHtmlWebpackPluginobject;
      • $: thecheerio object of the html file currently being processed
      • compilation: Internal webpack object to manipulate the build

The plugin also adds a new config option onto eachHtmlWebpackPlugin 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: astring containing the completed policy;
      • htmlPluginData: theHtmlWebpackPluginobject;
      • $: thecheerio object of the html file currently being processed
      • compilation: Internal webpack object to manipulate the build

You don't have to include the same policy /hashEnabled /nonceEnabled configuration object in bothHtmlWebpackPlugin andCspHtmlWebpackPlugin.

• Config included inCspHtmlWebpackPlugin will be applied to all instances ofHtmlWebpackPlugin.
• Config included in a singleHtmlWebpackPlugin 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

{'base-uri':"'self'",'object-src':"'none'",'script-src':["'unsafe-inline'","'self'","'unsafe-eval'"],'style-src':["'unsafe-inline'","'self'","'unsafe-eval'"]};

{  enabled:true  hashingMethod:'sha256',hashEnabled:{'script-src':true,'style-src':true},nonceEnabled:{'script-src':true,'style-src':true},processFn:defaultProcessFn}

newHtmlWebpackPlugin({cspPlugin:{enabled:true,policy:{'base-uri':"'self'",'object-src':"'none'",'script-src':["'unsafe-inline'","'self'","'unsafe-eval'"],'style-src':["'unsafe-inline'","'self'","'unsafe-eval'"]},hashEnabled:{'script-src':true,'style-src':true},nonceEnabled:{'script-src':true,'style-src':true},processFn:defaultProcessFn// defined in the plugin itself}});newCspHtmlWebpackPlugin({'base-uri':"'self'",'object-src':"'none'",'script-src':["'unsafe-inline'","'self'","'unsafe-eval'"],'style-src':["'unsafe-inline'","'self'","'unsafe-eval'"]},{enabled:true,hashingMethod:'sha256',hashEnabled:{'script-src':true,'style-src':true},nonceEnabled:{'script-src':true,'style-src':true},processFn:defaultProcessFn// defined in the plugin itself})

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

In your webpack config:

constRawSource=require('webpack-sources').RawSource;functiongenerateNginxHeaderFile(builtPolicy,_htmlPluginData,_obj,compilation){constheader='add_header Content-Security-Policy "'+builtPolicy+'; report-uri /csp-report/ ";';compilation.emitAsset('nginx-csp-header.conf',newRawSource(header));}module.exports={{...},plugins:[newCspHtmlWebpackPlugin({...},{processFn:generateNginxHeaderFile})]};

In your nginx config:

location/{  ...include /path/to/webpack/output/nginx-csp-header.conf}

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

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