{"id":13463221,"url":"https://github.com/slackhq/csp-html-webpack-plugin","last_synced_at":"2025-04-04T11:08:24.677Z","repository":{"id":40750933,"uuid":"117714206","full_name":"slackhq/csp-html-webpack-plugin","owner":"slackhq","description":"A plugin which, when combined with HTMLWebpackPlugin, adds CSP tags to the HTML output.","archived":false,"fork":false,"pushed_at":"2023-07-18T21:39:11.000Z","size":1671,"stargazers_count":166,"open_issues_count":27,"forks_count":41,"subscribers_count":76,"default_branch":"master","last_synced_at":"2025-03-21T08:46:42.264Z","etag":null,"topics":["csp","html-webpack-plugin","webpack"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slackhq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2018-01-16T17:05:48.000Z","updated_at":"2025-03-07T01:28:21.000Z","dependencies_parsed_at":"2023-12-02T16:44:50.837Z","dependency_job_id":null,"html_url":"https://github.com/slackhq/csp-html-webpack-plugin","commit_stats":{"total_commits":83,"total_committers":13,"mean_commits":6.384615384615385,"dds":0.4698795180722891,"last_synced_commit":"c4c977177cca885f8e4ea184edfc150b18bc67b5"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Fcsp-html-webpack-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Fcsp-html-webpack-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Fcsp-html-webpack-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slackhq%2Fcsp-html-webpack-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slackhq","download_url":"https://codeload.github.com/slackhq/csp-html-webpack-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247160398,"owners_count":20893824,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["csp","html-webpack-plugin","webpack"],"created_at":"2024-07-31T13:00:48.385Z","updated_at":"2025-04-04T11:08:24.652Z","avatar_url":"https://github.com/slackhq.png","language":"JavaScript","readme":"# CSP HTML Webpack Plugin\n\n[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/slackhq/csp-html-webpack-plugin/blob/master/LICENSE)\n[![npm](https://img.shields.io/npm/v/csp-html-webpack-plugin.svg)](https://www.npmjs.com/package/csp-html-webpack-plugin)\n[![Code Style](https://img.shields.io/badge/code%20style-prettier-brightgreen.svg)](https://github.com/prettier/prettier)\n[![Build Status](https://travis-ci.org/slackhq/csp-html-webpack-plugin.svg?branch=master)](https://travis-ci.org/slackhq/csp-html-webpack-plugin)\n[![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)\n\n## About\n\nThis plugin will generate meta content for your [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy)\ntag and input the correct data into your HTML template, generated by [html-webpack-plugin](https://github.com/jantimon/html-webpack-plugin/).\n\nAll inline JS and CSS will be hashed and inserted into the policy.\n\n## Installation\n\nInstall the plugin with npm:\n\n```bash\nnpm i --save-dev csp-html-webpack-plugin\n```\n\n## Basic Usage\n\nInclude the following in your webpack config:\n\n```js\nconst HtmlWebpackPlugin = require('html-webpack-plugin');\nconst CspHtmlWebpackPlugin = require('csp-html-webpack-plugin');\n\nmodule.exports = {\n  // rest of webpack config\n\n  plugins: [\n    new HtmlWebpackPlugin()\n    new CspHtmlWebpackPlugin({\n      // config here, see below\n    })\n  ]\n}\n```\n\n## Recommended Configuration\n\nBy default, the `csp-html-webpack-plugin` has a very lax policy. You should configure it for your needs.\n\nA good starting policy would be the following:\n\n```\nnew CspHtmlWebpackPlugin({\n  'script-src': '',\n  'style-src': ''\n});\n```\n\nAlthough we're configuring `script-src` and `style-src` to be blank, the CSP plugin will scan your HTML\ngenerated in `html-webpack-plugin` for external/inline script and style tags, and will add the appropriate\nhashes and nonces to your CSP policy. This configuration will also add a `base-uri` and `object-src` entry\nthat exist in the default policy:\n\n```\n\u003cmeta http-equiv=\"Content-Security-Policy\" content=\"\n  base-uri 'self';\n  object-src 'none';\n  script-src 'sha256-0Tumwf1AbPDHZO4kdvXUd4c5PiHwt55hre+RDxj9O3Q='\n             'nonce-hOlyTAhW5QI5p+rv9VUPZg==';\n  style-src 'sha256-zfLUTOi9wwJktpDIoBZQecK4DNIVxW8Tl0cadROvQgo='\n\"\u003e\n```\n\nThis configuration should work for most use cases, and will provide a strong layer of extra security.\n\n## All Configuration Options\n\n### `CspHtmlWebpackPlugin`\n\nThis `CspHtmlWebpackPlugin` accepts 2 params with the following structure:\n\n- `{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.\n- `{object}` Additional Options (optional) - a flat object with the optional configuration options:\n  - `{boolean|Function}` enabled - if false, or the function returns false, the empty CSP tag will be stripped from the html output.\n    - The `htmlPluginData` is passed into the function as it's first param.\n    - If `enabled` is set the false, it will disable generating a CSP for all instances of `HtmlWebpackPlugin` in your webpack config.\n  - `{string}` hashingMethod - accepts 'sha256', 'sha384', 'sha512' - your node version must also accept this hashing method.\n  - `{object}` hashEnabled - a `\u003cstring, boolean\u003e` entry for which policy rules are allowed to include hashes\n  - `{object}` nonceEnabled - a `\u003cstring, boolean\u003e` entry for which policy rules are allowed to include nonces\n  - `{Function}` processFn - allows the developer to overwrite the default method of what happens to the CSP after it has been created\n    - Parameters are:\n      - `builtPolicy`: a `string` containing the completed policy;\n      - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;\n      - `$`: the `cheerio` object of the html file currently being processed\n      - `compilation`: Internal webpack object to manipulate the build\n\n### `HtmlWebpackPlugin`\n\nThe plugin also adds a new config option onto each `HtmlWebpackPlugin` instance:\n\n- `{object}` cspPlugin - an object containing the following properties:\n  - `{boolean}` enabled - if false, the CSP tag will be removed from the HTML which this HtmlWebpackPlugin instance is generating.\n  - `{object}` policy - A custom policy which should be applied only to this instance of the HtmlWebpackPlugin\n  - `{object}` hashEnabled - a `\u003cstring, boolean\u003e` entry for which policy rules are allowed to include hashes\n  - `{object}` nonceEnabled - a `\u003cstring, boolean\u003e` entry for which policy rules are allowed to include nonces\n  - `{Function}` processFn - allows the developer to overwrite the default method of what happens to the CSP after it has been created\n    - Parameters are:\n      - `builtPolicy`: a `string` containing the completed policy;\n      - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;\n      - `$`: the `cheerio` object of the html file currently being processed\n      - `compilation`: Internal webpack object to manipulate the build\n\n### Order of Precedence:\n\nYou don't have to include the same policy / `hashEnabled` / `nonceEnabled` configuration object in both `HtmlWebpackPlugin` and `CspHtmlWebpackPlugin`.\n\n- Config included in `CspHtmlWebpackPlugin` will be applied to all instances of `HtmlWebpackPlugin`.\n- Config included in a single `HtmlWebpackPlugin` instantiation will only be applied to that instance.\n\nIn 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.\n\n```\n\u003e HtmlWebpackPlugin cspPlugin.policy\n\u003e CspHtmlWebpackPlugin policy\n\u003e CspHtmlWebpackPlugin defaultPolicy\n```\n\n## Appendix\n\n#### Default Policy:\n\n```js\n{\n  'base-uri': \"'self'\",\n  'object-src': \"'none'\",\n  'script-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"],\n  'style-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"]\n};\n```\n\n#### Default Additional Options:\n\n```js\n{\n  enabled: true\n  hashingMethod: 'sha256',\n  hashEnabled: {\n    'script-src': true,\n    'style-src': true\n  },\n  nonceEnabled: {\n    'script-src': true,\n    'style-src': true\n  },\n  processFn: defaultProcessFn\n}\n```\n\n#### Full Default Configuration:\n\n```js\nnew HtmlWebpackPlugin({\n  cspPlugin: {\n    enabled: true,\n    policy: {\n      'base-uri': \"'self'\",\n      'object-src': \"'none'\",\n      'script-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"],\n      'style-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"]\n    },\n    hashEnabled: {\n      'script-src': true,\n      'style-src': true\n    },\n    nonceEnabled: {\n      'script-src': true,\n      'style-src': true\n    },\n    processFn: defaultProcessFn  // defined in the plugin itself\n  }\n});\n\nnew CspHtmlWebpackPlugin({\n  'base-uri': \"'self'\",\n  'object-src': \"'none'\",\n  'script-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"],\n  'style-src': [\"'unsafe-inline'\", \"'self'\", \"'unsafe-eval'\"]\n}, {\n  enabled: true,\n  hashingMethod: 'sha256',\n  hashEnabled: {\n    'script-src': true,\n    'style-src': true\n  },\n  nonceEnabled: {\n    'script-src': true,\n    'style-src': true\n  },\n  processFn: defaultProcessFn  // defined in the plugin itself\n})\n```\n## Advanced Usage\n### Generating a file containing the CSP directives\n\nSome specific directives require the CSP to be sent to the client via a response header (e.g. `report-uri` and `report-to`)\nYou can set your own `processFn` callback to make this happen.\n\n#### nginx\n\nIn your webpack config:\n\n```js\nconst RawSource = require('webpack-sources').RawSource;\n\nfunction generateNginxHeaderFile(\n  builtPolicy,\n  _htmlPluginData,\n  _obj,\n  compilation\n) {\n  const header =\n    'add_header Content-Security-Policy \"' +\n    builtPolicy +\n    '; report-uri /csp-report/ \";';\n  compilation.emitAsset('nginx-csp-header.conf', new RawSource(header));\n}\n\nmodule.exports = {\n  {...},\n  plugins: [\n    new CspHtmlWebpackPlugin(\n      {...}, {\n      processFn: generateNginxHeaderFile\n    })\n  ]\n};\n```\nIn your nginx config:\n```nginx\nlocation / {\n  ...\n  include /path/to/webpack/output/nginx-csp-header.conf\n}\n```\n## Contribution\n\nContributions are most welcome! Please see the included contributing file for more information.\n\n## License\n\nThis project is licensed under MIT. Please see the included license file for more information.\n","funding_links":[],"categories":["JavaScript","Headers"],"sub_categories":["Content-Security-Policy"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslackhq%2Fcsp-html-webpack-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslackhq%2Fcsp-html-webpack-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslackhq%2Fcsp-html-webpack-plugin/lists"}