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:

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

Basic Usage

Include the following in your webpack config:

`js
const HtmlWebpackPlugin = require('html-webpack-plugin');
const CspHtmlWebpackPlugin = require('csp-html-webpack-plugin');

module.exports = {
// rest of webpack config

plugins: [
new HtmlWebpackPlugin()
new CspHtmlWebpackPlugin({
// config here, see below
})
]
}
`

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:

`

`

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

All Configuration Options

$3

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 entry for which policy rules are allowed to include hashes
- {object} nonceEnabled - a 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

$3

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 entry for which policy rules are allowed to include hashes
- {object} nonceEnabled - a 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

$3

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:

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

#### Default Additional Options:

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

#### Full Default Configuration:

`js
new HtmlWebpackPlugin({
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
}
});

new CspHtmlWebpackPlugin({
'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
})
`


Advanced Usage

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:

`js
const RawSource = require('webpack-sources').RawSource;

function generateNginxHeaderFile(
builtPolicy,
_htmlPluginData,
_obj,
compilation
) {
const header =
'add_header Content-Security-Policy "' +
builtPolicy +
'; report-uri /csp-report/ ";';
compilation.emitAsset('nginx-csp-header.conf', new RawSource(header));
}

module.exports = {
{...},
plugins: [
new CspHtmlWebpackPlugin(
{...}, {
processFn: generateNginxHeaderFile
})
]
};
`
In your nginx config:
`nginx
location / {
...
include /path/to/webpack/output/nginx-csp-header.conf
}
``

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.