# csp-html-webpack-plugin

> A plugin which, when combined with HTMLWebpackPlugin, adds CSP tags to the HTML output

Latest version **5.1.0** (published 2021-01-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install csp-html-webpack-plugin
pnpm add csp-html-webpack-plugin
yarn add csp-html-webpack-plugin
bun add csp-html-webpack-plugin
```

## Health

**Score 23/100 (F)** — status: abandoned.

Positive: has types package; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2021-01-12 |
| First published | 2018-01-18 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/csp-html-webpack-plugin) |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 70.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Anuj Nair |
| Maintainers | anujrnair |
| Keywords | webpack, csp, plugin, html |

## Links

- npm: https://www.npmjs.com/package/csp-html-webpack-plugin
- Repository: https://github.com/slackhq/csp-html-webpack-plugin
- Issues: https://github.com/slackhq/csp-html-webpack-plugin/issues
- npm.io page: https://npm.io/package/csp-html-webpack-plugin

## Dependencies (2)

- [lodash](https://npm.io/package/lodash.md) ^4.17.20
- [cheerio](https://npm.io/package/cheerio.md) ^1.0.0-rc.5

## Alternatives

- [@tsparticles/shape-image](https://npm.io/package/@tsparticles/shape-image.md) — 303.7K weekly downloads
- [@tsparticles/shape-line](https://npm.io/package/@tsparticles/shape-line.md) — 233.7K weekly downloads
- [stringify-attributes](https://npm.io/package/stringify-attributes.md) — 58.6K weekly downloads
- [mobile-drag-drop](https://npm.io/package/mobile-drag-drop.md) — 46.3K weekly downloads
- [@comunica/actor-rdf-parse-html](https://npm.io/package/@comunica/actor-rdf-parse-html.md) — 29.2K weekly downloads

## Recent versions

- 5.1.0 (latest) — 2021-01-12
- 5.0.1 — 2020-12-23
- 5.0.0 — 2020-12-17
- 4.0.0 — 2020-04-09
- 3.0.4 — 2019-10-29
- 3.0.3 — 2019-07-30
- 3.0.2 — 2019-06-03
- 3.0.1 — 2019-02-18
- 3.0.0 — 2019-01-30
- 3.0.0-beta.2 — 2019-01-03
- 3.0.0-beta.1 — 2019-01-03
- 2.5.0 — 2018-12-19
- 2.4.0 — 2018-11-30
- 2.3.0 — 2018-05-16
- 2.2.0 — 2018-03-21
- … 7 more at https://npm.io/package/csp-html-webpack-plugin/versions

## README

# CSP HTML Webpack Plugin

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/slackhq/csp-html-webpack-plugin/blob/master/LICENSE)
[![npm](https://img.shields.io/npm/v/csp-html-webpack-plugin.svg)](https://www.npmjs.com/package/csp-html-webpack-plugin)
[![Code Style](https://img.shields.io/badge/code%20style-prettier-brightgreen.svg)](https://github.com/prettier/prettier)
[![Build Status](https://travis-ci.org/slackhq/csp-html-webpack-plugin.svg?branch=master)](https://travis-ci.org/slackhq/csp-html-webpack-plugin)
[![codecov](https://codecov.io/gh/slackhq/csp-html-webpack-plugin/branch/master/graph/badge.svg?token=cBemDmnz85)](https://codecov.io/gh/slackhq/csp-html-webpack-plugin)

## About

This plugin will generate meta content for your [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)
tag and input the correct data into your HTML template, generated by [html-webpack-plugin](https://github.com/jantimon/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:

```
<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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) 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:

```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
### 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:

```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.

---
_Source: https://npm.io/package/csp-html-webpack-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._