loofah 2.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1196afab25d29644d1961e4516ac317a2c38dee3295f35354c468e6a9318fa55
+  data.tar.gz: 2e07ff641edb37d2b0dce2933288da4667d4b680a586912af9c171db7dfb0a63
+SHA512:
+  metadata.gz: 37ac2cdb0d136da417cff62e3845c5b71769f044d8150c636a549dc9ca4cf98bcef4c6d2b6e653eff56922b95d812ed39310a406c49366c14791456ca905e8fe
+  data.tar.gz: 0fa3cdd75a3d2950801a1cfe7f8d4cad6bb73bbec67d24ba25980c09a565f6c95c5d664c1789ccd62486d1917c685a5b0f762cc073a054bbb0f02fb0222688f0

data/CHANGELOG.md

@@ -0,0 +1,336 @@
+# Changelog
+
+## 2.3.1 / 2019-10-22
+
+### Security
+
+Address CVE-2019-15587: 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/171
+
+
+## 2.3.0 / 2019-09-28
+
+### 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:
+
+* Removed warning for unused variable. #124 (Thanks, @y-yagi!)
+
+
+## 2.1.0 / 2017-09-24
+
+### Notes:
+
+* Re-implemented CSS parsing and sanitization using the [crass](https://github.com/rgrove/crass) library. #91
+
+
+### 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:
+
+* 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
+
+
+## 2.0.3 / 2015-08-17
+
+### 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:
+
+* Fix error with `#to_text` when Loofah::Helpers hadn't been required. #75
+* Allow multi-word data attributes. #84 (Thanks, @jstorimer!)
+* Allow negative values in CSS properties. #85 (Thanks, @siddhartham!)
+
+
+## 2.0.1 / 2014-08-21
+
+### Bug fixes:
+
+* Load RR correctly when running test files directly. (Thanks, @ktdreyer!)
+
+
+### Notes:
+
+* Extracted HTML5::Scrub#scrub_css_attribute to accommodate the Rails integration work. (Thanks, @kaspth!)
+
+
+## 2.0.0 / 2014-05-09
+
+### Compatibility notes:
+
+* ActionView helpers now must be required explicitly: `require "loofah/helpers"`
+* Support for Ruby 1.8.7 and prior has been dropped
+
+### 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`
+  * attributes: `data-*` (Thanks, Rafael Franca!)
+  * URI attributes: `poster` and `preload`
+* Addition of the `:unprintable` scrubber to remove unprintable characters from text nodes. #65 (Thanks, Matt Swanson!)
+* `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:
+
+* 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!)
+
+
+## 1.2.1 (2012-04-14)
+
+* Declaring encoding in html5/scrub.rb. Without this, use of the ruby -KU option would cause havoc. (#32)
+
+
+## 1.2.0 (2011-08-08)
+
+### Enhancements:
+
+* Loofah::Helpers.sanitize_css is a replacement for Rails's built-in sanitize_css helper.
+* Improving ActionView integration.
+
+
+## 1.1.0 (2011-08-08)
+
+### Enhancements:
+
+* Additional HTML5lib whitelist elements (from html5lib 1524:80b5efe26230).
+  Up to date with HTML5lib ruby code as of 1723:7ee6a0331856.
+* Whitelists (which are not part of the public API) are now Sets (were previously Arrays).
+* Don't explode when encountering UTF-8 URIs. (#25, #29)
+
+
+## 1.0.0 (2010-10-26)
+
+### Notes:
+
+* Moved ActiveRecord functionality into `loofah-activerecord` gem.
+* Removed DEPRECATIONS.rdoc documenting 0.3.0 API changes.
+
+
+## 0.4.7 (2010-03-09)
+
+### Enhancements:
+
+* New methods Loofah::HTML::Document#to_text and
+  Loofah::HTML::DocumentFragment#to_text do the right thing with
+  whitespace. Note that these methods are significantly slower than
+  #text. GH #12
+* Loofah::Elements::BLOCK_LEVEL contains a canonical list of HTML4 block-level4 elements.
+* Loofah::HTML::Document#text and Loofah::HTML::DocumentFragment#text
+  will return unescaped HTML entities by passing :encode_special_chars => false.
+
+
+## 0.4.4, 0.4.5, 0.4.6 (2010-02-01)
+
+### Enhancements:
+
+* Loofah::HTML::Document#text and Loofah::HTML::DocumentFragment#text now escape HTML entities.
+
+### 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:
+
+* 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:
+
+* Modified documentation for bootstrapping XssFoliate in a Rails app,
+  since the use of Bundler breaks the previously-documented method. To
+  be safe, always use an initializer file.
+
+
+## 0.4.2 (2010-01-22)
+
+### 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:
+
+* Supporting Rails apps that aren't loading ActiveRecord. GH #10
+
+### Miscellaneous:
+
+* Mailing list is now loofah@librelist.com / http://librelist.com
+* IRC channel is now \#loofah on freenode.
+
+
+## 0.4.1 (2009-11-23)
+
+### Bugfix:
+
+* Manifest fixed. Whoops.
+
+
+## 0.4.0 (2009-11-21)
+
+### Enhancements:
+
+* Scrubber class introduced, allowing development of custom scrubbers.
+* Added support for XML documents and fragments.
+* Added :nofollow HTML scrubber (thanks Luke Melia!)
+* Built-in scrubbing methods refactored to use Scrubber.
+
+
+
+## 0.3.1 (2009-10-12)
+
+### Bug fixes:
+
+* Scrubbed Documents properly render html, head and body tags when serialized.
+
+
+## 0.3.0 (2009-10-06)
+
+### 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:
+
+* The methods strip_tags, whitewash, whitewash_document, sanitize, and
+  sanitize_document have been deprecated. See DEPRECATED.rdoc for
+  details on the equivalent calls with the post-0.2 API.
+
+
+## 0.2.2 (2009-09-30)
+
+### Enhancements:
+
+* ActiveRecord extension scrubs fields in a before_validation callback
+  (was previously in a before_save)
+
+
+## 0.2.1 (2009-09-19)
+
+### Enhancements:
+
+* when loaded in a Rails app, automatically extend ActiveRecord::Base
+  with html_fragment and html_document. GH #6 (Thanks Josh Nichols!)
+
+### Bugfixes:
+
+* ActiveRecord scrubbing should generate strings instead of Document or
+  DocumentFragment objects. GH #5
+* init.rb fixed to support installation as a Rails plugin. GH #6
+  (Thanks Josh Nichols!)
+
+
+## 0.2.0 (2009-09-11)
+
+* Swank new API.
+* ActiveRecord extension.
+* Uses Nokogiri's Document and DocumentFragment for parsing.
+* Updated html5lib codes and tests to revision 1384:b9d3153d7be7.
+* Deprecated the Dryopteris sanitization methods. Will be removed in 0.3.0.
+* Documentation! Hey!
+
+
+## 0.1.2 (2009-04-30)
+
+* Added whitewashing -- removal of all attributes and namespaced nodes. You know, for microsofty HTML.
+
+
+## 0.1.0 (2009-02-10)
+
+* Birthday!

data/Gemfile

@@ -0,0 +1,22 @@
+# -*- ruby -*-
+
+# DO NOT EDIT THIS FILE. Instead, edit Rakefile, and run `rake bundler:gemfile`.
+
+source "https://rubygems.org/"
+
+gem "nokogiri", ">=1.5.9"
+gem "crass", "~>1.0.2"
+
+gem "rake", ">=0.8", :group => [:development, :test]
+gem "minitest", "~>2.2", :group => [:development, :test]
+gem "rr", "~>1.2.0", :group => [:development, :test]
+gem "json", ">=0", :group => [:development, :test]
+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.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

@@ -0,0 +1,23 @@
+The MIT License
+
+The MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,41 @@
+.gemtest
+CHANGELOG.md
+Gemfile
+MIT-LICENSE.txt
+Manifest.txt
+README.md
+Rakefile
+SECURITY.md
+benchmark/benchmark.rb
+benchmark/fragment.html
+benchmark/helper.rb
+benchmark/www.slashdot.com.html
+lib/loofah.rb
+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/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
+test/integration/test_scrubbers.rb
+test/integration/test_xml.rb
+test/unit/test_api.rb
+test/unit/test_encoding.rb
+test/unit/test_helpers.rb
+test/unit/test_scrubber.rb
+test/unit/test_scrubbers.rb

data/README.md

@@ -0,0 +1,363 @@
+# 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, built on top of Nokogiri.
+
+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.