htmlscrubber: Add a config setting that can be used to disable the scrubber acting...

[ikiwiki.git] / doc / plugins / htmlscrubber.mdwn

diff --git a/doc/plugins/htmlscrubber.mdwn b/doc/plugins/htmlscrubber.mdwn
index 7962b3b52f9b7b667f1dc5a3f67d53e19ca5b10c..7db372e1be272b185dc735f8fb27a79ed612420c 100644 (file)
--- a/doc/plugins/htmlscrubber.mdwn
+++ b/doc/plugins/htmlscrubber.mdwn
@@ -1,5 +1,5 @@
-[[template id=plugin name=htmlscrubber core=1 author="[[Joey]]"]]
-[[tag type/html]]
+[[!template id=plugin name=htmlscrubber core=1 author="[[Joey]]"]]
+[[!tag type/html]]

 
 This plugin is enabled by default. It sanitizes the html on pages it renders
 to avoid XSS attacks and the like.
 
 This plugin is enabled by default. It sanitizes the html on pages it renders
 to avoid XSS attacks and the like.


@@ -7,9 +7,13 @@ to avoid XSS attacks and the like.
 It excludes all html tags and attributes except for those that are
 whitelisted using the same lists as used by Mark Pilgrim's Universal Feed
 Parser, documented at <http://feedparser.org/docs/html-sanitization.html>.
 It excludes all html tags and attributes except for those that are
 whitelisted using the same lists as used by Mark Pilgrim's Universal Feed
 Parser, documented at <http://feedparser.org/docs/html-sanitization.html>.

-Notably it strips `style`, `link`, and the `style` attribute.
+Notably it strips `style` and `link` tags, and the `style` attribute.

 
 

-It uses the [[cpan HTML::Scrubber]] perl module to perform its html
+All attributes that can be used to specify an url are checked to make sure
+that the url is in a known, safe scheme, and to block embedded javascript
+in such urls.
+
+It uses the [[!cpan HTML::Scrubber]] perl module to perform its html

 sanitisation, and this perl module also deals with various entity encoding
 tricks.
 
 sanitisation, and this perl module also deals with various entity encoding
 tricks.
 


@@ -23,9 +27,15 @@ The web's security model is *fundamentally broken*; ikiwiki's html
 sanitisation is only a patch on the underlying gaping hole that is your web
 browser.
 
 sanitisation is only a patch on the underlying gaping hole that is your web
 browser.
 

-Note that enabling or disabling the htmlscrubber plugin also affects some other
-HTML-related functionality, such as whether [[meta]] allows potentially unsafe
-HTML tags.
+Note that enabling or disabling the htmlscrubber plugin also affects some
+other HTML-related functionality, such as whether [[meta]] allows
+potentially unsafe HTML tags.
+
+The `htmlscrubber_skip` configuration setting can be used to skip scrubbing
+of some pages. Set it to a [[PageSpec]], such as "!*/Discussion", and pages
+matching that can have all the evil CSS, JavsScript, and unsafe html
+elements you like. One safe way to use this is to use [[lockedit]] to lock
+those pages, so only admins can edit them.

 
 ----
 
 
 ----
 


@@ -36,3 +46,4 @@ plugin is active:
 * <span style="background: url(javascript:window.location='http://example.org/')">CSS script test</span>
 * <span style="&#x61;&#x6e;&#x79;&#x3a;&#x20;&#x65;&#x78;&#x70;&#x72;&#x65;&#x73;&#x73;&#x69;&#x6f;&#x6e;&#x28;&#x77;&#x69;&#x6e;&#x64;&#x6f;&#x77;&#x2e;&#x6c;&#x6f;&#x63;&#x61;&#x74;&#x69;&#x6f;&#x6e;&#x3d;&#x27;&#x68;&#x74;&#x74;&#x70;&#x3a;&#x2f;&#x2f;&#x65;&#x78;&#x61;&#x6d;&#x70;&#x6c;&#x65;&#x2e;&#x6f;&#x72;&#x67;&#x2f;&#x27;&#x29;">entity-encoded CSS script test</span>
 * <span style="&#97;&#110;&#121;&#58;&#32;&#101;&#120;&#112;&#114;&#101;&#115;&#115;&#105;&#111;&#110;&#40;&#119;&#105;&#110;&#100;&#111;&#119;&#46;&#108;&#111;&#99;&#97;&#116;&#105;&#111;&#110;&#61;&#39;&#104;&#116;&#116;&#112;&#58;&#47;&#47;&#101;&#120;&#97;&#109;&#112;&#108;&#101;&#46;&#111;&#114;&#103;&#47;&#39;&#41;">entity-encoded CSS script test</span>
 * <span style="background: url(javascript:window.location='http://example.org/')">CSS script test</span>
 * <span style="&#x61;&#x6e;&#x79;&#x3a;&#x20;&#x65;&#x78;&#x70;&#x72;&#x65;&#x73;&#x73;&#x69;&#x6f;&#x6e;&#x28;&#x77;&#x69;&#x6e;&#x64;&#x6f;&#x77;&#x2e;&#x6c;&#x6f;&#x63;&#x61;&#x74;&#x69;&#x6f;&#x6e;&#x3d;&#x27;&#x68;&#x74;&#x74;&#x70;&#x3a;&#x2f;&#x2f;&#x65;&#x78;&#x61;&#x6d;&#x70;&#x6c;&#x65;&#x2e;&#x6f;&#x72;&#x67;&#x2f;&#x27;&#x29;">entity-encoded CSS script test</span>
 * <span style="&#97;&#110;&#121;&#58;&#32;&#101;&#120;&#112;&#114;&#101;&#115;&#115;&#105;&#111;&#110;&#40;&#119;&#105;&#110;&#100;&#111;&#119;&#46;&#108;&#111;&#99;&#97;&#116;&#105;&#111;&#110;&#61;&#39;&#104;&#116;&#116;&#112;&#58;&#47;&#47;&#101;&#120;&#97;&#109;&#112;&#108;&#101;&#46;&#111;&#114;&#103;&#47;&#39;&#41;">entity-encoded CSS script test</span>

+* <a href="javascript&#x3A;alert('foo')">click me</a>