RubyGems - sanitize - Versions diffs - 2.1.1 → 3.0.0 - Mend

sanitize 2.1.1 → 3.0.0

Potentially problematic release.

This version of sanitize might be problematic. Click here for more details.

Files changed (30) hide show

checksums.yaml +5 -5
data/HISTORY.md +93 -14
data/README.md +346 -134
data/lib/sanitize.rb +177 -132
data/lib/sanitize/config.rb +53 -79
data/lib/sanitize/config/basic.rb +12 -32
data/lib/sanitize/config/default.rb +103 -0
data/lib/sanitize/config/relaxed.rb +517 -52
data/lib/sanitize/config/restricted.rb +3 -23
data/lib/sanitize/css.rb +218 -0
data/lib/sanitize/transformers/clean_cdata.rb +3 -3
data/lib/sanitize/transformers/clean_comment.rb +6 -3
data/lib/sanitize/transformers/clean_css.rb +57 -0
data/lib/sanitize/transformers/clean_doctype.rb +13 -0
data/lib/sanitize/transformers/clean_element.rb +99 -129
data/lib/sanitize/version.rb +3 -1
data/test/common.rb +34 -0
data/test/test_clean_comment.rb +51 -0
data/test/test_clean_css.rb +66 -0
data/test/test_clean_doctype.rb +71 -0
data/test/test_clean_element.rb +399 -0
data/test/test_config.rb +65 -0
data/test/test_malicious_css.rb +42 -0
data/test/test_malicious_html.rb +128 -0
data/test/test_parser.rb +104 -0
data/test/test_sanitize.rb +65 -693
data/test/test_sanitize_css.rb +222 -0
data/test/test_transformers.rb +144 -0
data/test/test_unicode.rb +84 -0
metadata +56 -8

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
-SHA256:
-  metadata.gz: 9e75a99c50777d57667e66bee0787e3259085c38ec616bb14f13f3c2d8673827
-  data.tar.gz: 6819e4c2c9730157b5b0acb4571c72dfecf02d9e5e1f0e31425cf8fdcfb8af97
+SHA1:
+  metadata.gz: 5d54b7ff5de5e70aa002451d1654015521de8c02
+  data.tar.gz: f326532bce90a02b4ca27664ea97778ffa81f594
 SHA512:
-  metadata.gz: '08a334cb79442b561ce83bcacc1f4401907b47c3802d91934abf5ae3b13fe91c760df21402f30b126d489815c06eac8d055d65924b826e7e4c41017e08c96ad9'
-  data.tar.gz: '0858de4b6b03e1c41c079e96165d3714a4a8b8512deb85b2d7cb837d45a76f2503e1c16f1e8eb18d775a2f5c4337966c36a62a4d98a2162e4301a83338bee595'
+  metadata.gz: 48d4d41b9e4ac666d1c67937e36cdce5ca8e47a4fdf90f478dd7a0f71e01aef03d45294e77fd9676983f20096c31740a5019eb1cb626df608ab20f134143d2cc
+  data.tar.gz: 6b134ba669333ce6715c69207304ca1a73682e8255314933ff78d9d2b8ff08f287c70da23e1d0c707e70c54a2f4833c79271670182f15879452764c3bbeb09ee

data/HISTORY.md CHANGED Viewed

@@ -1,25 +1,104 @@
 Sanitize History
 ================================================================================
-Version 2.1.1 (2018-09-30)
---------------------------
+Version 3.0.0 (git)
+-------------------
+As of this version, Sanitize adheres strictly to the [SemVer 2.0.0][semver]
+versioning standard. This release contains API and output changes that are
+incompatible with previous releases, as indicated by the major version
+increment.
+[semver]:http://semver.org/
+### Backwards-incompatible changes
+* HTML is now parsed using Google's Gumbo HTML5 parser, which adheres to the
+  HTML5 parsing spec and behaves much more like modern browser parsers than the
+  previous libxml2-based parser. As a result, HTML output may differ from that
+  of previous versions of Sanitize.
+* All transformers now traverse the document from the top down, starting with
+  the first node, then its first child, and so on. The `:transformers_breadth`
+  config has been removed, and old bottom-up transformers (the previous default)
+  may need to be rewritten.
+* Sanitize's built-in configs are now deeply frozen to prevent people from
+  modifying them (either accidentally or maliciously). To customize a built-in
+  config, create a new copy using `Sanitize::Config.merge()`, like so:
+```ruby
+Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
+  :elements        => Sanitize::Config::BASIC[:elements] + ['div', 'table'],
+  :remove_contents => true
+))
+```
+* The `clean!` and `clean_document!` methods were removed, since they weren't
+  useful and tended to confuse people.
+* The `clean` method was renamed to `fragment` to more clearly indicate that its
+  intended use is to sanitize an HTML fragment.
+* The `clean_document` method was renamed to `document`.
+* The `clean_node!` method was renamed to `node!`.
+* The `document` method now raises a `Sanitize::Error` if the `<html>` element
+  isn't whitelisted, rather than a `RuntimeError`. This error is also now raised
+  regardless of the `:remove_contents` config setting.
+* The `:output` config has been removed. Output is now always HTML, not XHTML.
+* The `:output_encoding` config has been removed. Output is now always UTF-8.
+### Other changes
+* Added advanced CSS sanitization support using [Crass][crass], which is fully
+  compliant with the CSS Syntax Module Level 3 parsing spec. The contents of
+  whitelisted `<style>` elements and `style` attributes in HTML will be
+  sanitized as CSS, or you can use the `Sanitize::CSS` class to manually
+  sanitize CSS stylesheets or properties.
+* Added an `:allow_doctype` setting. When `true`, well-formed doctype
+  definitions will be allowed in documents. When `false` (the default), doctype
+  definitions will be removed from documents. Doctype definitions are never
+  allowed in fragments, regardless of this setting.
+* Added the following elements to the relaxed config, in addition to various
+  attributes: `article`, `aside`, `body`, `data`, `div`, `footer`, `head`,
+  `header`, `html`, `main`, `nav`, `section`, `span`, `style`, `title`.
+* The `:whitespace_elements` config is now a Hash, and allows you to specify the
+  text that should be inserted before and after these elements when they're
+  removed. The old-style Array-based config value is still supported for
+  backwards compatibility. [@alperkokmen - #94][94]
+* Unsuitable Unicode characters are now removed from HTML before it's parsed.
+  [#106][106]
-* [CVE-2018-3740][176]: Fixed an HTML injection vulnerability that could allow
-  XSS (backported from Sanitize 4.6.3). [@dometto - #188][188]
+* Fixed: Non-tag brackets in input like `"1 > 2 and 2 < 1"` are now parsed and
+  escaped correctly in accordance with the HTML5 spec, becoming
+  `"1 &gt; 2 and 2 &lt; 1"`. [#83][83]
-  When Sanitize <= 2.1.0 is used in combination with libxml2 >= 2.9.2, a
-  specially crafted HTML fragment can cause libxml2 to generate improperly
-  escaped output, allowing non-whitelisted attributes to be used on whitelisted
-  elements.
+* Fixed: Siblings added after the current node during traversal are now
+  also traversed. In previous versions they were simply skipped. [#91][91]
-  Sanitize now performs additional escaping on affected attributes to prevent
-  this.
+* Fixed: Nokogiri has been smacked and instructed to stop adding newlines after
+  certain elements, because if people wanted newlines there they'd have put them
+  there, dammit. [#103][103]
-  Many thanks to the Shopify Application Security Team for responsibly reporting
-  this issue.
+* Fixed: Added a workaround for a libxml2 bug that caused an undesired
+  content-type meta tag to be added to all documents with `<head>` elements.
+  [Nokogiri #1008][n1008]
-[176]:https://github.com/rgrove/sanitize/issues/176
-[188]:https://github.com/rgrove/sanitize/pull/188
+[crass]:https://github.com/rgrove/crass
+[83]:https://github.com/rgrove/sanitize/issues/83
+[91]:https://github.com/rgrove/sanitize/issues/91
+[94]:https://github.com/rgrove/sanitize/pull/94/
+[103]:https://github.com/rgrove/sanitize/issues/103
+[106]:https://github.com/rgrove/sanitize/issues/106
+[n1008]:https://github.com/sparklemotion/nokogiri/issues/1008
 Version 2.1.0 (2014-01-13)

data/README.md CHANGED Viewed

@@ -1,20 +1,36 @@
 Sanitize
 ========
-Sanitize is a whitelist-based HTML sanitizer. Given a list of acceptable
-elements and attributes, Sanitize will remove all unacceptable HTML from a
-string.
+Sanitize is a whitelist-based HTML and CSS sanitizer. Given a list of acceptable
+elements, attributes, and CSS properties, Sanitize will remove all unacceptable
+HTML and/or CSS from a string.
-Using a simple configuration syntax, you can tell Sanitize to allow certain
+Using a simple configuration syntax, you can tell Sanitize to allow certain HTML
 elements, certain attributes within those elements, and even certain URL
-protocols within attributes that contain URLs. Any HTML elements or attributes
-that you don't explicitly allow will be removed.
+protocols within attributes that contain URLs. You can also whitelist CSS
+properties, @ rules, and URL protocols you wish to allow in elements or
+attributes containing CSS. Any HTML or CSS that you don't explicitly allow will
+be removed.
-Because it's based on Nokogiri, a full-fledged HTML parser, rather than a bunch
-of fragile regular expressions, Sanitize has no trouble dealing with malformed
-or maliciously-formed HTML and returning safe output.
+Sanitize is based on [Google's Gumbo HTML5 parser][gumbo], which parses HTML
+exactly the same way modern browsers do, and [Crass][crass], which parses CSS
+exactly the same way modern browsers do. As long as your whitelist config only
+allows safe markup and CSS, even the most malformed or malicious input will be
+transformed into safe output.
-[![Build Status](https://travis-ci.org/rgrove/sanitize.png?branch=master)](https://travis-ci.org/rgrove/sanitize?branch=master)
+[![Build Status](https://travis-ci.org/rgrove/sanitize.svg?branch=master)](https://travis-ci.org/rgrove/sanitize)
+[![Gem Version](https://badge.fury.io/rb/sanitize.svg)](http://badge.fury.io/rb/sanitize)
+[crass]:https://github.com/rgrove/crass
+[gumbo]:https://github.com/google/gumbo-parser
+Links
+-----
+* [Home](https://github.com/rgrove/sanitize/)
+* [API Docs](http://rubydoc.info/github/rgrove/sanitize/master)
+* [Issues](https://github.com/rgrove/sanitize/issues)
+* [Biased comparison of Ruby HTML sanitization libraries](https://github.com/rgrove/sanitize/blob/master/COMPARISON.md)
 Installation
 -------------
@@ -23,63 +39,201 @@ Installation
 gem install sanitize
 ```
+Quick Start
+-----------
+```ruby
+require 'sanitize'
+# Clean up an HTML fragment using Sanitize's permissive but safe Relaxed config.
+# This also sanitizes any CSS in `<style>` elements or `style` attributes.
+Sanitize.fragment(html, Sanitize::Config::RELAXED)
+# Clean up an HTML document using the Relaxed config.
+Sanitize.document(html, Sanitize::Config::RELAXED)
+# Clean up a standalone CSS stylesheet using the Relaxed config.
+Sanitize::CSS.stylesheet(css, Sanitize::Config::RELAXED)
+# Clean up some CSS properties using the Relaxed config.
+Sanitize::CSS.properties(css, Sanitize::Config::RELAXED)
+```
 Usage
 -----
+Sanitize can sanitize the following types of input:
+* HTML fragments
+* HTML documents
+* CSS stylesheets inside HTML `<style>` elements
+* CSS properties inside HTML `style` attributes
+* Standalone CSS stylesheets
+* Standalone CSS properties
+### HTML Fragments
+A fragment is a snippet of HTML that doesn't contain a root-level `<html>`
+element.
 If you don't specify any configuration options, Sanitize will use its strictest
-settings by default, which means it will strip all HTML and leave only text
+settings by default, which means it will strip all HTML and leave only safe text
 behind.
 ```ruby
-require 'rubygems'
-require 'sanitize'
+html = '<b><a href="http://foo.com/">foo</a></b><img src="bar.jpg">'
+Sanitize.fragment(html)
+# => 'foo'
+```
+To keep certain elements, add them to the element whitelist.
+```ruby
+Sanitize.fragment(html, :elements => ['b'])
+# => '<b>foo</b>'
+```
-html = '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg">'
+### HTML Documents
-Sanitize.clean(html) # => 'foo'
+When sanitizing a document, the `<html>` element must be whitelisted. You can
+also set `:allow_doctype` to `true` to allow well-formed document type
+definitions.
+```ruby
+html = %[
+  <!DOCTYPE html>
+  <html>
+    <b><a href="http://foo.com/">foo</a></b><img src="bar.jpg">
+  </html>
+]
+Sanitize.document(html,
+  :allow_doctype => true,
+  :elements      => ['html']
+)
+# => %[
+#   <!DOCTYPE html>
+#   <html>foo
+#
+#   </html>
+# ]
+```
+### CSS in HTML
+To sanitize CSS in an HTML fragment or document, first whitelist the `<style>`
+element and/or the `style` attribute. Then whitelist the CSS properties,
+@ rules, and URL protocols you wish to allow. You can also choose whether to
+allow CSS comments or browser compatibility hacks.
+```ruby
+html = %[
+  <style>
+    div { color: green; width: 1024px; }
+  </style>
+  <div style="height: 100px; width: 100px;"></div>
+  <p>hello!</p>
+]
+Sanitize.fragment(html,
+  :elements   => ['div', 'style'],
+  :attributes => {'div' => ['style']},
+  :css => {
+    :properties => ['width']
+  }
+)
+#=> %[
+#   <style>
+#     div {  width: 1024px; }
+#   </style>
+#
+#   <div style=" width: 100px;"></div>
+#   hello!
+# ]
+```
+### Standalone CSS
+Sanitize will happily clean up a standalone CSS stylesheet or property string
+without needing to invoke the HTML parser.
+```ruby
+css = %[
+  @import url(evil.css);
+  a { text-decoration: none; }
+  a:hover {
+    left: expression(alert('xss!'));
+    text-decoration: underline;
+  }
+]
+Sanitize::CSS.stylesheet(css, Sanitize::Config::RELAXED)
+# => %[
+#
+#
+#
+#   a { text-decoration: none; }
+#
+#   a:hover {
+#
+#     text-decoration: underline;
+#   }
+# ]
+Sanitize::CSS.properties(%[
+  left: expression(alert('xss!'));
+  text-decoration: underline;
+], Sanitize::Config::RELAXED)
+# => %[
+#
+#   text-decoration: underline;
+# ]
-# or sanitize an entire HTML document (example assumes _html_ is whitelisted)
-html = '<!DOCTYPE html><html><b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg"></html>'
-Sanitize.clean_document(html) # => '<!DOCTYPE html>\n<html>foo</html>\n'
 ```
 Configuration
 -------------
 In addition to the ultra-safe default settings, Sanitize comes with three other
-built-in modes.
+built-in configurations that you can use out of the box or adapt to meet your
+needs.
 ### Sanitize::Config::RESTRICTED
-Allows only very simple inline formatting markup. No links, images, or block
-elements.
+Allows only very simple inline markup. No links, images, or block elements.
 ```ruby
-Sanitize.clean(html, Sanitize::Config::RESTRICTED) # => '<b>foo</b>'
+Sanitize.fragment(html, Sanitize::Config::RESTRICTED)
+# => '<b>foo</b>'
 ```
 ### Sanitize::Config::BASIC
-Allows a variety of markup including formatting tags, links, and lists. Images
-and tables are not allowed, links are limited to FTP, HTTP, HTTPS, and mailto
-protocols, and a `rel="nofollow"` attribute is added to all links to
+Allows a variety of markup including formatting elements, links, and lists.
+Images and tables are not allowed, links are limited to FTP, HTTP, HTTPS, and
+mailto protocols, and a `rel="nofollow"` attribute is added to all links to
 mitigate SEO spam.
 ```ruby
-Sanitize.clean(html, Sanitize::Config::BASIC)
+Sanitize.fragment(html, Sanitize::Config::BASIC)
 # => '<b><a href="http://foo.com/" rel="nofollow">foo</a></b>'
 ```
 ### Sanitize::Config::RELAXED
-Allows an even wider variety of markup than BASIC, including images and tables.
-Links are still limited to FTP, HTTP, HTTPS, and mailto protocols, while images
-are limited to HTTP and HTTPS. In this mode, `rel="nofollow"` is not added to
-links.
+Allows an even wider variety of markup, including images and tables, as well as
+safe CSS. Links are still limited to FTP, HTTP, HTTPS, and mailto protocols,
+while images are limited to HTTP and HTTPS. In this mode, `rel="nofollow"` is
+not added to links.
 ```ruby
-Sanitize.clean(html, Sanitize::Config::RELAXED)
-# => '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg">'
+Sanitize.fragment(html, Sanitize::Config::RELAXED)
+# => '<b><a href="http://foo.com/">foo</a></b><img src="bar.jpg">'
 ```
 ### Custom Configuration
@@ -88,11 +242,51 @@ If the built-in modes don't meet your needs, you can easily specify a custom
 configuration:
 ```ruby
-Sanitize.clean(html, :elements => ['a', 'span'],
-    :attributes => {'a' => ['href', 'title'], 'span' => ['class']},
-    :protocols => {'a' => {'href' => ['http', 'https', 'mailto']}})
+Sanitize.fragment(html,
+  :elements => ['a', 'span'],
+  :attributes => {
+    'a'    => ['href', 'title'],
+    'span' => ['class']
+  },
+  :protocols => {
+    'a' => {'href' => ['http', 'https', 'mailto']}
+  }
+)
+```
+You can also start with one of Sanitize's built-in configurations and then
+customize it to meet your needs.
+The built-in configs are deeply frozen to prevent people from modifying them
+(either accidentally or maliciously). To customize a built-in config, create a
+new copy using `Sanitize::Config.merge()`, like so:
+```ruby
+# Create a customized copy of the Basic config, adding <div> and <table> to the
+# existing whitelisted elements.
+Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
+  :elements        => Sanitize::Config::BASIC[:elements] + ['div', 'table'],
+  :remove_contents => true
+))
+```
+The example above adds the `<div>` and `<table>` elements to a copy of the
+existing list of elements in `Sanitize::Config::BASIC`. If you instead want to
+completely overwrite the elements array with your own, you can omit the `+`
+operation:
+```ruby
+# Overwrite :elements instead of creating a copy with new entries.
+Sanitize.fragment(html, Sanitize::Config.merge(Sanitize::Config::BASIC,
+  :elements        => ['div', 'table'],
+  :remove_contents => true
+))
 ```
+### Config Settings
 #### :add_attributes (Hash)
 Attributes to add to specific elements. If the attribute already exists, it will
@@ -111,9 +305,15 @@ Whether or not to allow HTML comments. Allowing comments is strongly
 discouraged, since IE allows script execution within conditional comments. The
 default value is `false`.
+#### :allow_doctype (boolean)
+Whether or not to allow well-formed HTML doctype declarations such as "<!DOCTYPE
+html>" when sanitizing a document. This setting is ignored when sanitizing
+fragments. The default value is `false`.
 #### :attributes (Hash)
-Attributes to allow for specific elements. Specify all element names and
+Attributes to allow on specific elements. Specify all element names and
 attributes in lowercase.
 ```ruby
@@ -124,8 +324,8 @@ attributes in lowercase.
 }
 ```
-If you'd like to allow certain attributes on all elements, use the symbol
-`:all` instead of an element name.
+If you'd like to allow certain attributes on all elements, use the symbol `:all`
+instead of an element name.
 ```ruby
 # Allow the class attribute on all elements.
@@ -135,8 +335,8 @@ If you'd like to allow certain attributes on all elements, use the symbol
 }
 ```
-To allow arbitrary HTML5 `data-*` attributes, use the symbol
-`:data` in place of an attribute name.
+To allow arbitrary HTML5 `data-*` attributes, use the symbol `:data` in place of
+an attribute name.
 ```ruby
 # Allow arbitrary HTML5 data-* attributes on <div> elements.
@@ -145,9 +345,44 @@ To allow arbitrary HTML5 `data-*` attributes, use the symbol
 }
 ```
-#### :elements (Array)
+#### :css (Hash)
+Hash of the following CSS config settings to be used when sanitizing CSS (either
+standalone or embedded in HTML).
+##### :css => :allow_comments (boolean)
+Whether or not to allow CSS comments. The default value is `false`.
+##### :css => :allow_hacks (boolean)
+Whether or not to allow browser compatibility hacks such as the IE `*` and `_`
+hacks. These are generally harmless, but technically result in invalid CSS. The
+default is `false`.
+##### :css => :at_rules (Array or Set)
+Names of CSS [@ rules][at-rules] to allow. Names should be specified in
+lowercase.
+[at-rules]:https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule
+##### :css => :properties (Array or Set)
+Whitelist of CSS property names to allow. Names should be specified in
+lowercase.
+##### :css => :protocols (Array or Set)
+URL protocols to allow in CSS URLs. Should be specified in lowercase.
-Array of element names to allow. Specify all names in lowercase.
+If you'd like to allow the use of relative URLs which don't have a protocol,
+include the symbol `:relative` in the protocol array.
+#### :elements (Array or Set)
+Array of HTML element names to allow. Specify all names in lowercase. Any
+elements not in this array will be removed.
 ```ruby
 :elements => %w[
@@ -156,15 +391,6 @@ Array of element names to allow. Specify all names in lowercase.
 ]
 ```
-#### :output (Symbol)
-Output format. Supported formats are `:html` and `:xhtml`,
-defaulting to `:html`.
-#### :output_encoding (String)
-Character encoding to use for HTML output. Default is `utf-8`.
 #### :protocols (Hash)
 URL protocols to allow in specific attributes. If an attribute is listed here
@@ -187,9 +413,9 @@ include the symbol `:relative` in the protocol array:
 }
 ```
-#### :remove_contents (boolean or Array)
+#### :remove_contents (boolean or Array or Set)
-If set to +true+, Sanitize will remove the contents of any non-whitelisted
+If set to `true`, Sanitize will remove the contents of any non-whitelisted
 elements in addition to the elements themselves. By default, Sanitize leaves the
 safe parts of an element's contents behind when the element is removed.
@@ -199,49 +425,50 @@ elements will be left behind.
 The default value is `false`.
-#### :transformers
-Custom transformer or array of custom transformers to run using depth-first
-traversal. See the Transformers section below for details.
-#### :transformers_breadth
+#### :transformers (Array or callable)
-Custom transformer or array of custom transformers to run using breadth-first
-traversal. See the Transformers section below for details.
+Custom HTML transformer or array of custom transformers. See the Transformers
+section below for details.
-#### :whitespace_elements (Array)
+#### :whitespace_elements (Hash)
-Array of lowercase element names that should be replaced with whitespace when
-removed in order to preserve readability. For example,
-`foo<div>bar</div>baz` will become
-`foo bar baz` when the `<div>` is removed.
+Hash of element names which, when removed, should have their contents surrounded
+by whitespace to preserve readability.
-By default, the following elements are included in the
-`:whitespace_elements` array:
+Each element name is a key pointing to another Hash, which provides the specific
+whitespace that should be inserted `:before` and `:after` the removed element's
+position. The `:after` value will only be inserted if the removed element has
+children, in which case it will be inserted after those children.
-```
-address article aside blockquote br dd div dl dt footer h1 h2 h3 h4 h5
-h6 header hgroup hr li nav ol p pre section ul
+```ruby
+:whitespace_elements => {
+  'br'  => { :before => "\n", :after => "" },
+  'div' => { :before => "\n", :after => "\n" },
+  'p'   => { :before => "\n", :after => "\n" }
+}
 ```
-### Transformers
+## Transformers
-Transformers allow you to filter and modify nodes using your own custom logic,
-on top of (or instead of) Sanitize's core filter. A transformer is any object
-that responds to `call()` (such as a lambda or proc).
+Transformers allow you to filter and modify HTML nodes using your own custom
+logic, on top of (or instead of) Sanitize's core filter. A transformer is any
+object that responds to `call()` (such as a lambda or proc).
-To use one or more transformers, pass them to the `:transformers`
-config setting. You may pass a single transformer or an array of transformers.
+To use one or more transformers, pass them to the `:transformers` config
+setting. You may pass a single transformer or an array of transformers.
 ```ruby
-Sanitize.clean(html, :transformers => [transformer_one, transformer_two])
+Sanitize.fragment(html, :transformers => [
+  transformer_one,
+  transformer_two
+])
 ```
-#### Input
+### Input
-Each registered transformer's `call()` method will be called once for
-each node in the HTML (including elements, text nodes, comments, etc.), and will
-receive as an argument an environment Hash that contains the following items:
+Each transformer's `call()` method will be called once for each node in the HTML
+(including elements, text nodes, comments, etc.), and will receive as an
+argument a Hash that contains the following items:
   * **:config** - The current Sanitize configuration Hash.
@@ -263,10 +490,7 @@ receive as an argument an environment Hash that contains the following items:
     generally bad form to remove a node that a previous transformer has
     whitelisted.
-  * **:traversal_mode** - Current node traversal mode, either `:depth` for
-    depth-first (the default mode) or `:breadth` for breadth-first.
-#### Output
+### Output
 A transformer doesn't have to return anything, but may optionally return a Hash,
 which may contain the following items:
@@ -279,7 +503,7 @@ which may contain the following items:
 If a transformer returns anything other than a Hash, the return value will be
 ignored.
-#### Processing
+### Processing
 Each transformer has full access to the `Nokogiri::XML::Node` that's passed into
 it and to the rest of the document via the node's `document()` method. Any
@@ -288,42 +512,44 @@ in the document and passed on to subsequently called transformers and to
 Sanitize itself. A transformer may even call Sanitize internally to perform
 custom sanitization if needed.
-Nodes are passed into transformers in the order in which they're traversed. By
-default, depth-first traversal is used, meaning that markup is traversed from
-the deepest node upward (not from the first node to the last node):
+Nodes are passed into transformers in the order in which they're traversed.
+Sanitize performs top-down traversal, meaning that nodes are traversed in the
+same order you'd read them in the HTML, starting at the top node, then its first
+child, and so on.
 ```ruby
-html        = '<div><span>foo</span></div>'
-transformer = lambda{|env| puts env[:node_name] }
-# Prints "text", "span", "div", "#document-fragment".
-Sanitize.clean(html, :transformers => transformer)
-```
-You may use the `:transformers_breadth` config to specify one or more
-transformers that should traverse nodes in breadth-first mode:
+html = %[
+  <header>
+    <span>
+      <strong>foo</strong>
+    </span>
+    <p>bar</p>
+  </header>
+  <footer></footer>
+]
-```ruby
-html        = '<div><span>foo</span></div>'
-transformer = lambda{|env| puts env[:node_name] }
+transformer = lambda do |env|
+  puts env[:node_name] if env[:node].element?
+end
-# Prints "#document-fragment", "div", "span", "text".
-Sanitize.clean(html, :transformers_breadth => transformer)
+# Prints "header", "span", "strong", "p", "footer".
+Sanitize.fragment(html, :transformers => transformer)
 ```
 Transformers have a tremendous amount of power, including the power to
 completely bypass Sanitize's built-in filtering. Be careful! Your safety is in
 your own hands.
-#### Example: Transformer to whitelist YouTube video embeds
+### Example: Transformer to whitelist YouTube video embeds
-The following example demonstrates how to create a depth-first Sanitize
-transformer that will safely whitelist valid YouTube video embeds without having
-to blindly allow other kinds of embedded content, which would be the case if you
-tried to do this by just whitelisting all `<iframe>` elements:
+The following example demonstrates how to create a transformer that will safely
+whitelist valid YouTube video embeds without having to blindly allow other kinds
+of embedded content, which would be the case if you tried to do this by just
+whitelisting all `<iframe>` elements:
 ```ruby
-lambda do |env|
+youtube_transformer = lambda do |env|
   node      = env[:node]
   node_name = env[:node_name]
@@ -334,12 +560,12 @@ lambda do |env|
   return unless node_name == 'iframe'
   # Verify that the video URL is actually a valid YouTube video URL.
-  return unless node['src'] =~ /\A(https?:)?\/\/(?:www\.)?youtube(?:-nocookie)?\.com\//
+  return unless node['src'] =~ %r|\A(?:https?:)?//(?:www\.)?youtube(?:-nocookie)?\.com/|
   # We're now certain that this is a YouTube embed, but we still need to run
   # it through a special Sanitize step to ensure that no unwanted elements or
   # attributes that don't belong in a YouTube embed can sneak in.
-  Sanitize.clean_node!(node, {
+  Sanitize.node!(node, {
     :elements => %w[iframe],
     :attributes => {
@@ -352,29 +578,15 @@ lambda do |env|
   # to whitelist the current node.
   {:node_whitelist => [node]}
 end
-```
-Contributors
-------------
-Sanitize was created and is maintained by Ryan Grove (ryan@wonko.com).
-The following lovely people have also contributed to Sanitize:
-* Ben Anderson
-* Wilson Bilkovich
-* Peter Cooper
-* Gabe da Silveira
-* Nicholas Evans
-* Nils Gemeinhardt
-* Adam Hooper
-* Mutwin Kraus
-* Eaden McKee
-* Dev Purkayastha
-* David Reese
-* Ardie Saeidi
-* Rafael Souza
-* Ben Wanicur
+html = %[
+<iframe width="420" height="315" src="//www.youtube.com/embed/dQw4w9WgXcQ"
+    frameborder="0" allowfullscreen></iframe>
+]
+Sanitize.fragment(html, :transformers => youtube_transformer)
+# => '<iframe width="420" height="315" src="//www.youtube.com/embed/dQw4w9WgXcQ" frameborder="0" allowfullscreen=""></iframe>'
+```
 License
 -------