Merge pull request #78 from slackhq/an-readme-updates

Updates to the readme to clarify best practices and how to configure the plugin

Author: AnujRNair

README.md

@@ -8,9 +8,10 @@
 
 ## 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](https://github.com/jantimon/html-webpack-plugin/).
+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.
+All inline JS and CSS will be hashed and inserted into the policy.
 
 ## Installation
 
@@ -22,18 +23,61 @@ npm i --save-dev csp-html-webpack-plugin
 
 ## Basic Usage
 
-In the plugins section of your webpack config file, include the following:
+Include the following in your webpack config:
 
 ```
-new HtmlWebpackPlugin()
-new CspHtmlWebpackPlugin()
+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
+    })
+  ]
+}
 ```
 
-## Configuration
+## 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}` 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.
@@ -47,6 +91,8 @@ This `CspHtmlWebpackPlugin` accepts 2 params with the following structure:
       - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;
       - `$`: the `cheerio` object of the html file currently being processed
 
+### `HtmlWebpackPlugin`
+
 The plugin also adds a new config option onto each `HtmlWebpackPlugin` instance:
 
 - `{object}` cspPlugin - an object containing the following properties:
@@ -60,20 +106,22 @@ The plugin also adds a new config option onto each `HtmlWebpackPlugin` instance:
       - `htmlPluginData`: the `HtmlWebpackPlugin` `object`;
       - `$`: the `cheerio` object of the html file currently being processed
 
-#### Order of Precedence:
+### Order of Precedence:
 
-Note that policies and `hashEnabled` / `nonceEnabled` are merged in the following order:
+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
 ```
 
-If 2 policies have the same key/policy rule, the former policy will override the latter policy. Entries in a specific rule will not be merged; they will be replaced.
-
-This is useful if you need different policy rules / processing functions for different `HtmlWebpackPlugin` instances
-in the same webpack config.
+## Appendix
 
 #### Default Policy:
 
@@ -104,10 +152,7 @@ in the same webpack config.
 }
 ```
 
-#### Full Configuration with all options:
-
-Note that you don't have to include the same section in both `HtmlWebpackPlugin` and `CspHtmlWebpackPlugin`.
-See the [Order of Precedence](#order-of-precedence) section above.
+#### Full Default Configuration:
 
 ```
 new HtmlWebpackPlugin({
@@ -127,7 +172,7 @@ new HtmlWebpackPlugin({
       'script-src': true,
       'style-src': true
     },
-    processFn: defaultProcessFn
+    processFn: defaultProcessFn  // defined in the plugin itself
   }
 });
 
@@ -147,7 +192,7 @@ new CspHtmlWebpackPlugin({
     'script-src': true,
     'style-src': true
   },
-  processFn: defaultProcessFn
+  processFn: defaultProcessFn  // defined in the plugin itself
 })
 ```