loofah 2.1.1 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ca2c20c5ce7252fd9d37c4588ce3d505e39480dc
-  data.tar.gz: eec13222402419857eb4d1cffbde0fcf837b59c3
+SHA256:
+  metadata.gz: 521948af26b151c0584b5eabd8e60c8c31ff451d2b134da4bc632256feeb87f4
+  data.tar.gz: 9b699d079c84a6c498fcb5be0e56f7c68ad7049bb0aa498e3413343803fcf585
 SHA512:
-  metadata.gz: 2d351e77bef7101ba64be53b98e5630597aa2e72af8e2940d10c79f6479325560069b8daff12091fd4f2eb5c562b8bcbfd6bef53501a0c80d42c9850ebfd4f13
-  data.tar.gz: 8261bcadedc0943141eb21b198553a7151f030d1f381cf9427a9b9985ff0a6c59e65c95141afc4d48e284d0a38f9b2ce53e02d96cfdf3e99475ab5ee222f9e68
+  metadata.gz: 7781d0db35620637fd69051e3729db36f4d10712bab60038df78f523d72b991b8e8f86009655495b56ef69d5b97aa5a621cc22698bc4eaec06577bece6841ec6
+  data.tar.gz: e42ab470cc2f3fbb5d0c3965b6a60fe698d0d076b3d87d58f6c4fa209531eac82188bef01c8005a94f3caa3f342ae7df4a850a4107fa043b618bdbd9f98c8d86

data/CHANGELOG.md

@@ -1,26 +1,105 @@
 # Changelog
 
+## 2.3.0 / unreleased
+
+### Features
+
+* Expand set of allowed protocols to include `tel:` and `line:`. [#104, #147]
+* Expand set of allowed CSS functions. [related to #122]
+* Allow greater precision in shorthand CSS values. [#149] (Thanks, @danfstucky!)
+* Allow CSS property `list-style` [#162] (Thanks, @jaredbeck!)
+* Allow CSS keywords `thick` and `thin` [#168] (Thanks, @georgeclaghorn!)
+* Allow HTML property `contenteditable` [#167] (Thanks, @andreynering!)
+
+
+### Bug fixes
+
+* CSS hex values are no longer limited to lowercase hex. Previously uppercase hex were scrubbed. [#165] (Thanks, @asok!)
+
+
+### Deprecations / Name Changes
+
+The following method and constants are hereby deprecated, and will be completely removed in a future release:
+
+* Deprecate `Loofah::Helpers::ActionView.white_list_sanitizer`, please use `Loofah::Helpers::ActionView.safe_list_sanitizer` instead.
+* Deprecate `Loofah::Helpers::ActionView::WhiteListSanitizer`, please use `Loofah::Helpers::ActionView::SafeListSanitizer` instead.
+* Deprecate `Loofah::HTML5::WhiteList`, please use `Loofah::HTML5::SafeList` instead.
+
+Thanks to @JuanitoFatas for submitting these changes in #164 and for making the language used in Loofah more inclusive.
+
+
+## 2.2.3 / 2018-10-30
+
+### Security
+
+Address CVE-2018-16468: Unsanitized JavaScript may occur in sanitized output when a crafted SVG element is republished.
+
+This CVE's public notice is at https://github.com/flavorjones/loofah/issues/154
+
+
+## Meta / 2018-10-27
+
+The mailing list is now on Google Groups [#146](https://github.com/flavorjones/loofah/issues/146):
+
+* Mail: loofah-talk@googlegroups.com
+* Archive: https://groups.google.com/forum/#!forum/loofah-talk
+
+This change was made because librelist no longer appears to be maintained.
+
+
+## 2.2.2 / 2018-03-22
+
+Make public `Loofah::HTML5::Scrub.force_correct_attribute_escaping!`,
+which was previously a private method. This is so that downstream gems
+(like rails-html-sanitizer) can use this logic directly for their own
+attribute scrubbers should they need to address CVE-2018-8048.
+
+
+## 2.2.1 / 2018-03-19
+
+### Security
+
+Addresses CVE-2018-8048. Loofah allowed non-whitelisted attributes to be present in sanitized output when input with specially-crafted HTML fragments.
+
+This CVE's public notice is at https://github.com/flavorjones/loofah/issues/144
+
+
+## 2.2.0 / 2018-02-11
+
+### Features:
+
+* Support HTML5 `<main>` tag. #133 (Thanks, @MothOnMars!)
+* Recognize HTML5 block elements. #136 (Thanks, @MothOnMars!)
+* Support SVG `<symbol>` tag. #131 (Thanks, @baopham!)
+* Support for whitelisting CSS functions, initially just `calc` and `rgb`. #122/#123/#129 (Thanks, @NikoRoberts!)
+* Whitelist CSS property `list-style-type`. #68/#137/#142 (Thanks, @andela-ysanni and @NikoRoberts!)
+
+### Bugfixes:
+
+* Properly handle nested `script` tags. #127.
+
+
 ## 2.1.1 / 2017-09-24
 
-Bugfixes:
+### Bugfixes:
 
 * Removed warning for unused variable. #124 (Thanks, @y-yagi!)
 
 
 ## 2.1.0 / 2017-09-24
 
-Notes:
+### Notes:
 
-* Re-implemented CSS parsing and sanitization using the {crass}[https://github.com/rgrove/crass] library. #91
+* Re-implemented CSS parsing and sanitization using the [crass](https://github.com/rgrove/crass) library. #91
 
 
-Features:
+### Features:
 
 * Added :noopener HTML scrubber (Thanks, @tastycode!)
 * Support `data` URIs with the following media types: text/plain, text/css, image/png, image/gif, image/jpeg, image/svg+xml. #101, #120. (Thanks, @mrpasquini!)
 
 
-Bugfixes:
+### Bugfixes:
 
 * The :unprintable scrubber now scrubs unprintable characters in CDATA nodes (like `<script>`). #124
 * Allow negative values in CSS properties. Restores functionality that was reverted in v2.0.3. #91
@@ -28,14 +107,14 @@ Bugfixes:
 
 ## 2.0.3 / 2015-08-17
 
-Bug fixes:
+### Bug fixes:
 
 * Revert support for negative values in CSS properties due to slow performance. #90 (Related to #85.)
 
 
 ## 2.0.2 / 2015-05-05
 
-Bug fixes:
+### Bug fixes:
 
 * Fix error with `#to_text` when Loofah::Helpers hadn't been required. #75
 * Allow multi-word data attributes. #84 (Thanks, @jstorimer!)
@@ -44,24 +123,24 @@ Bug fixes:
 
 ## 2.0.1 / 2014-08-21
 
-Bug fixes:
+### Bug fixes:
 
 * Load RR correctly when running test files directly. (Thanks, @ktdreyer!)
 
 
-Notes:
+### Notes:
 
 * Extracted HTML5::Scrub#scrub_css_attribute to accommodate the Rails integration work. (Thanks, @kaspth!)
 
 
 ## 2.0.0 / 2014-05-09
 
-Compatibility notes:
+### Compatibility notes:
 
 * ActionView helpers now must be required explicitly: `require "loofah/helpers"`
 * Support for Ruby 1.8.7 and prior has been dropped
 
-Enhancements:
+### Enhancements:
 
 * HTML5 whitelist allows the following ...
   * tags: `article`, `aside`, `bdi`, `bdo`, `canvas`, `command`, `datalist`, `details`, `figcaption`, `figure`, `footer`, `header`, `mark`, `meter`, `nav`, `output`, `section`, `summary`, `time`
@@ -71,7 +150,7 @@ Enhancements:
 * `Loofah.fragment` accepts an optional encoding argument, compatible with `Nokogiri::HTML::DocumentFragment.parse`. #62 (Thanks, Ben Atkins!)
 * HTML5 sanitizers now remove attributes without values. (Thanks, Kasper Timm Hansen!)
 
-Bug fixes:
+### Bug fixes:
 
 * HTML5 sanitizers' CSS keyword check now actually works (broken in v2.0). Additional regression tests added. (Thanks, Kasper Timm Hansen!)
 * HTML5 sanitizers now allow negative arguments to CSS. #64 (Thanks, Jon Calhoun!)
@@ -84,7 +163,7 @@ Bug fixes:
 
 ## 1.2.0 (2011-08-08)
 
-Enhancements:
+### Enhancements:
 
 * Loofah::Helpers.sanitize_css is a replacement for Rails's built-in sanitize_css helper.
 * Improving ActionView integration.
@@ -92,7 +171,7 @@ Enhancements:
 
 ## 1.1.0 (2011-08-08)
 
-Enhancements:
+### Enhancements:
 
 * Additional HTML5lib whitelist elements (from html5lib 1524:80b5efe26230).
   Up to date with HTML5lib ruby code as of 1723:7ee6a0331856.
@@ -102,7 +181,7 @@ Enhancements:
 
 ## 1.0.0 (2010-10-26)
 
-Notes:
+### Notes:
 
 * Moved ActiveRecord functionality into `loofah-activerecord` gem.
 * Removed DEPRECATIONS.rdoc documenting 0.3.0 API changes.
@@ -110,7 +189,7 @@ Notes:
 
 ## 0.4.7 (2010-03-09)
 
-Enhancements:
+### Enhancements:
 
 * New methods Loofah::HTML::Document#to_text and
   Loofah::HTML::DocumentFragment#to_text do the right thing with
@@ -123,23 +202,23 @@ Enhancements:
 
 ## 0.4.4, 0.4.5, 0.4.6 (2010-02-01)
 
-Enhancements:
+### Enhancements:
 
 * Loofah::HTML::Document#text and Loofah::HTML::DocumentFragment#text now escape HTML entities.
 
-Bug fixes:
+### Bug fixes:
 
 * Loofah::XssFoliate was not properly escaping HTML entities when implicitly scrubbing a string attribute. GH #17
 
 
 ## 0.4.3 (2010-01-29)
 
-Enhancements:
+### Enhancements:
 
 * All built-in scrubbers are accepted by ActiveRecord::Base.xss_foliate
 * Loofah::XssFoliate.xss_foliate_all_models replaces use of the constant LOOFAH_XSS_FOLIATE_ALL_MODELS
 
-Miscellaneous:
+### Miscellaneous:
 
 * Modified documentation for bootstrapping XssFoliate in a Rails app,
   since the use of Bundler breaks the previously-documented method. To
@@ -148,18 +227,18 @@ Miscellaneous:
 
 ## 0.4.2 (2010-01-22)
 
-Enhancements:
+### Enhancements:
 
 * Implemented Node#scrub! for scrubbing subtrees.
 * Implemented NodeSet#scrub! for scrubbing a set of subtrees.
 * Document.text now only serializes <body> contents (ignores <head>)
 * <head>, <html> and <body> added to the HTML5lib whitelist.
 
-Bug fixes:
+### Bug fixes:
 
 * Supporting Rails apps that aren't loading ActiveRecord. GH #10
 
-Miscellaneous:
+### Miscellaneous:
 
 * Mailing list is now loofah@librelist.com / http://librelist.com
 * IRC channel is now \#loofah on freenode.
@@ -167,14 +246,14 @@ Miscellaneous:
 
 ## 0.4.1 (2009-11-23)
 
-Bugfix:
+### Bugfix:
 
 * Manifest fixed. Whoops.
 
 
 ## 0.4.0 (2009-11-21)
 
-Enhancements:
+### Enhancements:
 
 * Scrubber class introduced, allowing development of custom scrubbers.
 * Added support for XML documents and fragments.
@@ -185,20 +264,20 @@ Enhancements:
 
 ## 0.3.1 (2009-10-12)
 
-Bug fixes:
+### Bug fixes:
 
 * Scrubbed Documents properly render html, head and body tags when serialized.
 
 
 ## 0.3.0 (2009-10-06)
 
-Enhancements:
+### Enhancements:
 
 * New ActiveRecord extension `xss_foliate`, a drop-in replacement for xss_terminate[http://github.com/look/xss_terminate/tree/master].
 * Replacement methods for Rails's helpers, Loofah::Rails.sanitize and Loofah::Rails.strip_tags.
 * Official support (and test coverage) for Rails versions 2.3, 2.2, 2.1, 2.0 and 1.2.
 
-Deprecations:
+### Deprecations:
 
 * The methods strip_tags, whitewash, whitewash_document, sanitize, and
   sanitize_document have been deprecated. See DEPRECATED.rdoc for
@@ -207,7 +286,7 @@ Deprecations:
 
 ## 0.2.2 (2009-09-30)
 
-Enhancements:
+### Enhancements:
 
 * ActiveRecord extension scrubs fields in a before_validation callback
   (was previously in a before_save)
@@ -215,12 +294,12 @@ Enhancements:
 
 ## 0.2.1 (2009-09-19)
 
-Enhancements:
+### Enhancements:
 
 * when loaded in a Rails app, automatically extend ActiveRecord::Base
   with html_fragment and html_document. GH #6 (Thanks Josh Nichols!)
 
-Bugfixes:
+### Bugfixes:
 
 * ActiveRecord scrubbing should generate strings instead of Document or
   DocumentFragment objects. GH #5

data/Gemfile

@@ -15,8 +15,8 @@ gem "hoe-gemspec", ">=0", :group => [:development, :test]
 gem "hoe-debugging", ">=0", :group => [:development, :test]
 gem "hoe-bundler", ">=0", :group => [:development, :test]
 gem "hoe-git", ">=0", :group => [:development, :test]
-gem "concourse", ">=0.14.0", :group => [:development, :test]
-gem "rdoc", "~>4.0", :group => [:development, :test]
-gem "hoe", "~>3.16", :group => [:development, :test]
+gem "concourse", ">=0.26.0", :group => [:development, :test]
+gem "rdoc", ">=4.0", "<7", :group => [:development, :test]
+gem "hoe", "~>3.17", :group => [:development, :test]
 
 # vim: syntax=ruby

data/MIT-LICENSE.txt

@@ -2,7 +2,7 @@ The MIT License
 
 The MIT License
 
-Copyright (c) 2009 -- 2014 by Mike Dalessio, Bryan Helmkamp
+Copyright (c) 2009 -- 2018 by Mike Dalessio, Bryan Helmkamp
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/Manifest.txt

@@ -3,8 +3,9 @@ CHANGELOG.md
 Gemfile
 MIT-LICENSE.txt
 Manifest.txt
-README.rdoc
+README.md
 Rakefile
+SECURITY.md
 benchmark/benchmark.rb
 benchmark/fragment.html
 benchmark/helper.rb
@@ -14,17 +15,20 @@ lib/loofah/elements.rb
 lib/loofah/helpers.rb
 lib/loofah/html/document.rb
 lib/loofah/html/document_fragment.rb
+lib/loofah/html5/libxml2_workarounds.rb
+lib/loofah/html5/safelist.rb
 lib/loofah/html5/scrub.rb
-lib/loofah/html5/whitelist.rb
 lib/loofah/instance_methods.rb
 lib/loofah/metahelpers.rb
 lib/loofah/scrubber.rb
 lib/loofah/scrubbers.rb
 lib/loofah/xml/document.rb
 lib/loofah/xml/document_fragment.rb
+test/assets/msword.html
 test/assets/testdata_sanitizer_tests1.dat
 test/helper.rb
 test/html5/test_sanitizer.rb
+test/html5/test_scrub.rb
 test/integration/test_ad_hoc.rb
 test/integration/test_helpers.rb
 test/integration/test_html.rb

data/README.md

@@ -0,0 +1,369 @@
+# Loofah
+
+* https://github.com/flavorjones/loofah
+* Docs: http://rubydoc.info/github/flavorjones/loofah/master/frames
+* Mailing list: [loofah-talk@googlegroups.com](https://groups.google.com/forum/#!forum/loofah-talk)
+
+## Status
+
+|System|Status|
+|--|--|
+| Concourse CI | [![Concourse CI](https://ci.nokogiri.org/api/v1/teams/nokogiri-core/pipelines/loofah/jobs/ruby-2.5/badge)](https://ci.nokogiri.org/teams/nokogiri-core/pipelines/loofah?groups=master) |
+| Code Climate | [![Code Climate](https://codeclimate.com/github/flavorjones/loofah.svg)](https://codeclimate.com/github/flavorjones/loofah) |
+
+
+## Description
+
+Loofah is a general library for manipulating and transforming HTML/XML
+documents and fragments. It's built on top of Nokogiri and libxml2, so
+it's fast and has a nice API.
+
+Loofah excels at HTML sanitization (XSS prevention). It includes some
+nice HTML sanitizers, which are based on HTML5lib's safelist, so it
+most likely won't make your codes less secure. (These statements have
+not been evaluated by Netexperts.)
+
+ActiveRecord extensions for sanitization are available in the
+[`loofah-activerecord` gem](https://github.com/flavorjones/loofah-activerecord).
+
+
+## Features
+
+* Easily write custom scrubbers for HTML/XML leveraging the sweetness of Nokogiri (and HTML5lib's safelists).
+* Common HTML sanitizing tasks are built-in:
+  * _Strip_ unsafe tags, leaving behind only the inner text.
+  * _Prune_ unsafe tags and their subtrees, removing all traces that they ever existed.
+  * _Escape_ unsafe tags and their subtrees, leaving behind lots of <tt>&lt;</tt> and <tt>&gt;</tt> entities.
+  * _Whitewash_ the markup, removing all attributes and namespaced nodes.
+* Common HTML transformation tasks are built-in:
+  * Add the _nofollow_ attribute to all hyperlinks.
+* Format markup as plain text, with or without sensible whitespace handling around block elements.
+* Replace Rails's `strip_tags` and `sanitize` view helper methods.
+
+
+## Compare and Contrast
+
+Loofah is one of two known Ruby XSS/sanitization solutions that
+guarantees well-formed and valid markup (the other is Sanitize, which
+also uses Nokogiri).
+
+Loofah works on XML, XHTML and HTML documents.
+
+Also, it's pretty fast. Here is a benchmark comparing Loofah to other
+commonly-used libraries (ActionView, Sanitize, HTML5lib and HTMLfilter):
+
+* https://gist.github.com/170193
+
+Lastly, Loofah is extensible. It's super-easy to write your own custom
+scrubbers for whatever document manipulation you need. You don't like
+the built-in scrubbers? Build your own, like a boss.
+
+
+## The Basics
+
+Loofah wraps [Nokogiri](http://nokogiri.org) in a loving
+embrace. Nokogiri is an excellent HTML/XML parser. If you don't know
+how Nokogiri works, you might want to pause for a moment and go check
+it out. I'll wait.
+
+Loofah presents the following classes:
+
+* `Loofah::HTML::Document` and `Loofah::HTML::DocumentFragment`
+* `Loofah::XML::Document` and `Loofah::XML::DocumentFragment`
+* `Loofah::Scrubber`
+
+The documents and fragments are subclasses of the similar Nokogiri classes.
+
+The Scrubber represents the document manipulation, either by wrapping
+a block,
+
+``` ruby
+span2div = Loofah::Scrubber.new do |node|
+  node.name = "div" if node.name == "span"
+end
+```
+
+or by implementing a method.
+
+
+### Side Note: Fragments vs Documents
+
+Generally speaking, unless you expect to have a DOCTYPE and a single
+root node, you don't have a *document*, you have a *fragment*. For
+HTML, another rule of thumb is that *documents* have `html` and `body`
+tags, and *fragments* usually do not.
+
+HTML fragments should be parsed with Loofah.fragment. The result won't
+be wrapped in `html` or `body` tags, won't have a DOCTYPE declaration,
+`head` elements will be silently ignored, and multiple root nodes are
+allowed.
+
+XML fragments should be parsed with Loofah.xml_fragment. The result
+won't have a DOCTYPE declaration, and multiple root nodes are allowed.
+
+HTML documents should be parsed with Loofah.document. The result will
+have a DOCTYPE declaration, along with `html`, `head` and `body` tags.
+
+XML documents should be parsed with Loofah.xml_document. The result
+will have a DOCTYPE declaration and a single root node.
+
+
+### Loofah::HTML::Document and Loofah::HTML::DocumentFragment
+
+These classes are subclasses of Nokogiri::HTML::Document and
+Nokogiri::HTML::DocumentFragment, so you get all the markup
+fixer-uppery and API goodness of Nokogiri.
+
+The module methods Loofah.document and Loofah.fragment will parse an
+HTML document and an HTML fragment, respectively.
+
+``` ruby
+Loofah.document(unsafe_html).is_a?(Nokogiri::HTML::Document)         # => true
+Loofah.fragment(unsafe_html).is_a?(Nokogiri::HTML::DocumentFragment) # => true
+```
+
+Loofah injects a `scrub!` method, which takes either a symbol (for
+built-in scrubbers) or a Loofah::Scrubber object (for custom
+scrubbers), and modifies the document in-place.
+
+Loofah overrides `to_s` to return HTML:
+
+``` ruby
+unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"
+
+doc = Loofah.fragment(unsafe_html).scrub!(:prune)
+doc.to_s    # => "ohai! <div>div is safe</div> "
+```
+
+and `text` to return plain text:
+
+``` ruby
+doc.text    # => "ohai! div is safe "
+```
+
+Also, `to_text` is available, which does the right thing with
+whitespace around block-level elements.
+
+``` ruby
+doc = Loofah.fragment("<h1>Title</h1><div>Content</div>")
+doc.text    # => "TitleContent"           # probably not what you want
+doc.to_text # => "\nTitle\n\nContent\n"   # better
+```
+
+### Loofah::XML::Document and Loofah::XML::DocumentFragment
+
+These classes are subclasses of Nokogiri::XML::Document and
+Nokogiri::XML::DocumentFragment, so you get all the markup
+fixer-uppery and API goodness of Nokogiri.
+
+The module methods Loofah.xml_document and Loofah.xml_fragment will
+parse an XML document and an XML fragment, respectively.
+
+``` ruby
+Loofah.xml_document(bad_xml).is_a?(Nokogiri::XML::Document)         # => true
+Loofah.xml_fragment(bad_xml).is_a?(Nokogiri::XML::DocumentFragment) # => true
+```
+
+### Nodes and NodeSets
+
+Nokogiri::XML::Node and Nokogiri::XML::NodeSet also get a `scrub!`
+method, which makes it easy to scrub subtrees.
+
+The following code will apply the `employee_scrubber` only to the
+`employee` nodes (and their subtrees) in the document:
+
+``` ruby
+Loofah.xml_document(bad_xml).xpath("//employee").scrub!(employee_scrubber)
+```
+
+And this code will only scrub the first `employee` node and its subtree:
+
+``` ruby
+Loofah.xml_document(bad_xml).at_xpath("//employee").scrub!(employee_scrubber)
+```
+
+### Loofah::Scrubber
+
+A Scrubber wraps up a block (or method) that is run on a document node:
+
+``` ruby
+# change all <span> tags to <div> tags
+span2div = Loofah::Scrubber.new do |node|
+  node.name = "div" if node.name == "span"
+end
+```
+
+This can then be run on a document:
+
+``` ruby
+Loofah.fragment("<span>foo</span><p>bar</p>").scrub!(span2div).to_s
+# => "<div>foo</div><p>bar</p>"
+```
+
+Scrubbers can be run on a document in either a top-down traversal (the
+default) or bottom-up. Top-down scrubbers can optionally return
+Scrubber::STOP to terminate the traversal of a subtree. Read below and
+in the Loofah::Scrubber class for more detailed usage.
+
+Here's an XML example:
+
+``` ruby
+# remove all <employee> tags that have a "deceased" attribute set to true
+bring_out_your_dead = Loofah::Scrubber.new do |node|
+  if node.name == "employee" and node["deceased"] == "true"
+    node.remove
+    Loofah::Scrubber::STOP # don't bother with the rest of the subtree
+  end
+end
+Loofah.xml_document(File.read('plague.xml')).scrub!(bring_out_your_dead)
+```
+
+=== Built-In HTML Scrubbers
+
+Loofah comes with a set of sanitizing scrubbers that use HTML5lib's
+safelist algorithm:
+
+``` ruby
+doc.scrub!(:strip)       # replaces unknown/unsafe tags with their inner text
+doc.scrub!(:prune)       #  removes unknown/unsafe tags and their children
+doc.scrub!(:escape)      #  escapes unknown/unsafe tags, like this: &lt;script&gt;
+doc.scrub!(:whitewash)   #  removes unknown/unsafe/namespaced tags and their children,
+                         #          and strips all node attributes
+```
+
+Loofah also comes with some common transformation tasks: 
+
+``` ruby
+doc.scrub!(:nofollow)    #     adds rel="nofollow" attribute to links
+doc.scrub!(:unprintable) #  removes unprintable characters from text nodes
+```
+
+See Loofah::Scrubbers for more details and example usage.
+
+
+### Chaining Scrubbers
+
+You can chain scrubbers:
+
+``` ruby
+Loofah.fragment("<span>hello</span> <script>alert('OHAI')</script>") \
+      .scrub!(:prune) \
+      .scrub!(span2div).to_s
+# => "<div>hello</div> "
+```
+
+### Shorthand
+
+The class methods Loofah.scrub_fragment and Loofah.scrub_document are
+shorthand.
+
+``` ruby
+Loofah.scrub_fragment(unsafe_html, :prune)
+Loofah.scrub_document(unsafe_html, :prune)
+Loofah.scrub_xml_fragment(bad_xml, custom_scrubber)
+Loofah.scrub_xml_document(bad_xml, custom_scrubber)
+```
+
+are the same thing as (and arguably semantically clearer than):
+
+``` ruby
+Loofah.fragment(unsafe_html).scrub!(:prune)
+Loofah.document(unsafe_html).scrub!(:prune)
+Loofah.xml_fragment(bad_xml).scrub!(custom_scrubber)
+Loofah.xml_document(bad_xml).scrub!(custom_scrubber)
+```
+
+
+### View Helpers
+
+Loofah has two "view helpers": Loofah::Helpers.sanitize and
+Loofah::Helpers.strip_tags, both of which are drop-in replacements for
+the Rails ActionView helpers of the same name.
+These are no longer required automatically. You must require `loofah/helpers`. 
+
+
+## Requirements
+
+* Nokogiri >= 1.5.9
+
+
+## Installation
+
+Unsurprisingly:
+
+* gem install loofah
+
+
+## Support
+
+The bug tracker is available here:
+
+* https://github.com/flavorjones/loofah/issues
+
+And the mailing list is on Google Groups:
+
+* Mail: loofah-talk@googlegroups.com
+* Archive: https://groups.google.com/forum/#!forum/loofah-talk
+
+And the IRC channel is \#loofah on freenode.
+
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md) for vulnerability reporting details.
+
+
+### "Secure by Default"
+
+Some tools may incorrectly report Loofah as a potential security
+vulnerability.
+
+Loofah depends on Nokogiri, and it's _possible_ to use Nokogiri in a
+dangerous way (by enabling its DTDLOAD option and disabling its NONET
+option). This specifically allows the opportunity for an XML External
+Entity (XXE) vulnerability if the XML data is untrusted.
+
+However, Loofah __never enables this Nokogiri configuration__; Loofah
+never enables DTDLOAD, and it never disables NONET, thereby protecting
+you by default from this XXE vulnerability.
+
+
+## Related Links
+
+* Nokogiri: http://nokogiri.org
+* libxml2: http://xmlsoft.org
+* html5lib: https://code.google.com/p/html5lib
+
+
+## Authors
+
+* [Mike Dalessio](http://mike.daless.io) ([@flavorjones](https://twitter.com/flavorjones))
+* Bryan Helmkamp
+
+Featuring code contributed by:
+
+* Aaron Patterson
+* John Barnette
+* Josh Owens
+* Paul Dix
+* Luke Melia
+
+And a big shout-out to Corey Innis for the name, and feedback on the API.
+
+
+## Thank You
+
+The following people have generously donated via the [Pledgie](http://pledgie.com) badge on the [Loofah github page](https://github.com/flavorjones/loofah):
+
+* Bill Harding
+
+
+## Historical Note
+
+This library was formerly known as Dryopteris, which was a very bad
+name that nobody could spell properly.
+
+
+## License
+
+Distributed under the MIT License. See `MIT-LICENSE.txt` for details.