diff --git a/README.md b/README.md index 9b0d35e..b32d1bd 100644 --- a/README.md +++ b/README.md @@ -371,7 +371,10 @@ to ```html - + ``` diff --git a/a-tag-test.html b/a-tag-test.html index 5fd482b..653fdf6 100644 --- a/a-tag-test.html +++ b/a-tag-test.html @@ -20,6 +20,7 @@ + A Tag Tests diff --git a/attr-property-aliasing-test.html b/attr-property-aliasing-test.html index b2ba345..b507287 100644 --- a/attr-property-aliasing-test.html +++ b/attr-property-aliasing-test.html @@ -20,6 +20,7 @@ + Attr Property Aliasing Tests diff --git a/classify-test.html b/classify-test.html index 91ff3a6..666d333 100644 --- a/classify-test.html +++ b/classify-test.html @@ -20,6 +20,7 @@ + Classify Tests diff --git a/computed-value-test.html b/computed-value-test.html index dcd6d30..f7b1b90 100644 --- a/computed-value-test.html +++ b/computed-value-test.html @@ -20,6 +20,7 @@ + Computed Value Tests diff --git a/custom-element-test.html b/custom-element-test.html index 5715e31..5f28317 100644 --- a/custom-element-test.html +++ b/custom-element-test.html @@ -20,6 +20,7 @@ + Custom Element Tests diff --git a/enum-attribute-test.html b/enum-attribute-test.html index ce2ddc0..dde947d 100644 --- a/enum-attribute-test.html +++ b/enum-attribute-test.html @@ -20,6 +20,7 @@ + Enum Attribute Test diff --git a/getting-started.md b/getting-started.md index 721ffcd..7d677dc 100644 --- a/getting-started.md +++ b/getting-started.md @@ -41,9 +41,7 @@ bower install --save polymer-resin#1.2.3 ### Downloading a release If you don't want to use bower, you can browse releases of polymer-resin via the -project's [Github release -page](https://github.com/Polymer/polymer-resin/releases) and tarballs are -available there. +project's [Github release page][releases] and tarballs are available there. ### Integrating @@ -84,8 +82,7 @@ Before | After ` ` | `. . ` ` ` | `. . ` `. . ` | `. . ` `. ` | `. ` @@ -99,41 +96,104 @@ importing, and must appear before polymer-resin is loaded. The above Polymer document shows a synchronous script tag. ```html - + ``` -Due to a quirk of how HTML imports work, this must be present even if you don't -need to do any configuration. This makes sure that the polymer-resin JS will -load before ` ``` +#### `{ 'reportHandler': myReportHandlerFn }` + +`reportHandler` is a callback that receives reports about rejected values and +module status. + +By default, if `goog.DEBUG` is false at init time, reportHandler is never +called, and if `goog.DEBUG` is true at init time, reportHandler logs to the JS +developer console. + +Assuming it is enabled, either via `goog.DEBUG` or an explicit call to this +setter, then it is called on every rejected value, and on major events like +module initialization. + +This may be used to identify false positives during debugging; to compile lists +of false positives when migrating; or to gather telemetry by compiling a table +summarizing disallowed value reports. + ## Migrating an app or element to work with polymer-resin -TODO: explain how one can load a variant of polymer-resin compiled in -`UNSAFE_ADVISORY_ONLY` mode. Polymer-resin doesn't actually substitute innocuous -values for unsafe inputs but logs and one can get a digest from the console of -rejected (element, attribute/property, value) triples which allows running tests -that don't include attempted attacks and seeing the kinds of false positives -that tend to show up. +When migrating an app to use polymer-resin, it can be helpful to get a list of +false positives. One false negative can cause a cascading security failure that +compromises your app, but false positives can also cause a cascading failure +that makes it hard to get coverage when manually testing an application. + +```html + +``` + +This configuration MUST NOT be used in production systems since +**UNSAFE_passThruDisallowedValues** disables the security protections similar to +[CSP Report-Only][csp-report-only] mode. + +With this configuration, Polymer-resin doesn't actually substitute innocuous +values for unsafe inputs but collects them so that you can dump a digest to the +console. ## Debugging an app or element that uses polymer-resin @@ -223,6 +283,10 @@ Instead of using a contract type, code can often be refactored to do without. This sample code could be refactored to use a `