loofah 1.0.0 → 2.19.1

data/README.md

@@ -0,0 +1,364 @@
+# Loofah
+
+* https://github.com/flavorjones/loofah
+* Docs: http://rubydoc.info/github/flavorjones/loofah/main/frames
+* Mailing list: [loofah-talk@googlegroups.com](https://groups.google.com/forum/#!forum/loofah-talk)
+
+## Status
+
+[![ci](https://github.com/flavorjones/loofah/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/flavorjones/loofah/actions/workflows/ci.yml)
+[![Tidelift dependencies](https://tidelift.com/badges/package/rubygems/loofah)](https://tidelift.com/subscription/pkg/rubygems-loofah?utm_source=rubygems-loofah&utm_medium=referral&utm_campaign=readme)
+
+
+## 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 and line break elements.
+
+``` ruby
+doc = Loofah.fragment("<h1>Title</h1><div>Content<br>Next line</div>")
+doc.text    # => "TitleContentNext line"            # probably not what you want
+doc.to_text # => "\nTitle\n\nContent\nNext line\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.
+
+Consider subscribing to [Tidelift][tidelift] which provides license assurances and timely security notifications for your open source dependencies, including Loofah. [Tidelift][tidelift] subscriptions also help the Loofah maintainers fund our [automated testing](https://ci.nokogiri.org) which in turn allows us to ship releases, bugfixes, and security updates more often.
+
+  [tidelift]: https://tidelift.com/subscription/pkg/rubygems-loofah?utm_source=undefined&utm_medium=referral&utm_campaign=enterprise
+
+
+## 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 funded 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.

data/SECURITY.md

@@ -0,0 +1,18 @@
+# Security and Vulnerability Reporting
+
+The Loofah core contributors take security very seriously and investigate all reported vulnerabilities.
+
+If you would like to report a vulnerablity or have a security concern regarding Loofah, please [report it via HackerOne](https://hackerone.com/loofah/reports/new).
+
+Your report will be acknowledged within 24 hours, and you'll receive a more detailed response within 72 hours indicating next steps in handling your report.
+
+If you have not received a reply to your submission within 48 hours, there are a few steps you can take:
+
+* Contact the current security coordinator (Mike Dalessio <mike.dalessio@gmail.com>)
+* Email the Loofah user group at loofah-talk@googlegroups.com (archive at https://groups.google.com/forum/#!forum/loofah-talk)
+
+Please note, the user group list is a public area. When escalating in that venue, please do not discuss your issue. Simply say that you're trying to get a hold of someone from the core team.
+
+The information you share with the Loofah core contributors as part of this process will be kept confidential within the team, unless or until we need to share information upstream with our dependent libraries' core teams, at which point we will notify you.
+
+If a vulnerability is first reported by you, we will credit you with the discovery in the public disclosure.

data/lib/loofah/elements.rb

@@ -1,19 +1,96 @@
+# frozen_string_literal: true
+require "set"
+
 module Loofah
   module Elements
-    # Block elements in HTML4
-    STRICT_BLOCK_LEVEL = %w[address blockquote center dir div dl
-      fieldset form h1 h2 h3 h4 h5 h6 hr isindex menu noframes
-      noscript ol p pre table ul]
+    STRICT_BLOCK_LEVEL_HTML4 = Set.new %w[
+                                         address
+                                         blockquote
+                                         center
+                                         dir
+                                         div
+                                         dl
+                                         fieldset
+                                         form
+                                         h1
+                                         h2
+                                         h3
+                                         h4
+                                         h5
+                                         h6
+                                         hr
+                                         isindex
+                                         menu
+                                         noframes
+                                         noscript
+                                         ol
+                                         p
+                                         pre
+                                         table
+                                         ul
+                                       ]
+
+    # https://developer.mozilla.org/en-US/docs/Web/HTML/Block-level_elements
+    STRICT_BLOCK_LEVEL_HTML5 = Set.new %w[
+                                         address
+                                         article
+                                         aside
+                                         blockquote
+                                         canvas
+                                         dd
+                                         div
+                                         dl
+                                         dt
+                                         fieldset
+                                         figcaption
+                                         figure
+                                         footer
+                                         form
+                                         h1
+                                         h2
+                                         h3
+                                         h4
+                                         h5
+                                         h6
+                                         header
+                                         hgroup
+                                         hr
+                                         li
+                                         main
+                                         nav
+                                         noscript
+                                         ol
+                                         output
+                                         p
+                                         pre
+                                         section
+                                         table
+                                         tfoot
+                                         ul
+                                         video
+                                       ]
+
+    # The following elements may also be considered block-level
+    # elements since they may contain block-level elements
+    LOOSE_BLOCK_LEVEL = Set.new %w[dd
+                                   dt
+                                   frameset
+                                   li
+                                   tbody
+                                   td
+                                   tfoot
+                                   th
+                                   thead
+                                   tr
+                                ]
 
-    # The following elements may also be considered block-level elements since they may contain block-level elements
-    LOOSE_BLOCK_LEVEL = %w[dd dt frameset li tbody td tfoot th thead tr]
+    # Elements that aren't block but should generate a newline in #to_text
+    INLINE_LINE_BREAK = Set.new(["br"])
 
+    STRICT_BLOCK_LEVEL = STRICT_BLOCK_LEVEL_HTML4 + STRICT_BLOCK_LEVEL_HTML5
     BLOCK_LEVEL = STRICT_BLOCK_LEVEL + LOOSE_BLOCK_LEVEL
+    LINEBREAKERS = BLOCK_LEVEL + INLINE_LINE_BREAK
   end
 
-  module HashedElements
-    include Loofah::MetaHelpers::HashifiedConstants(Elements)
-  end
+  ::Loofah::MetaHelpers.add_downcased_set_members_to_all_set_constants ::Loofah::Elements
 end
-
-

data/lib/loofah/helpers.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Loofah
   module Helpers
     class << self
@@ -16,14 +17,87 @@ module Loofah
       #   Loofah::Helpers.sanitize("<script src=http://ha.ckers.org/xss.js></script>") # => "&lt;script src=\"http://ha.ckers.org/xss.js\"&gt;&lt;/script&gt;"
       #
       def sanitize(string_or_io)
-        Loofah.scrub_fragment(string_or_io, :strip).to_s
+        loofah_fragment = Loofah.fragment(string_or_io)
+        loofah_fragment.scrub!(:strip)
+        loofah_fragment.xpath("./form").each { |form| form.remove }
+        loofah_fragment.to_s
+      end
+
+      #
+      #  A replacement for Rails's built-in +sanitize_css+ helper.
+      #
+      #    Loofah::Helpers.sanitize_css("display:block;background-image:url(http://www.ragingplatypus.com/i/cam-full.jpg)") # => "display: block;"
+      #
+      def sanitize_css(style_string)
+        ::Loofah::HTML5::Scrub.scrub_css style_string
       end
 
       #
       #  A helper to remove extraneous whitespace from text-ified HTML
+      #  TODO: remove this in a future major-point-release.
       #
       def remove_extraneous_whitespace(string)
-        string.gsub(/\n\s*\n\s*\n/,"\n\n")
+        Loofah.remove_extraneous_whitespace string
+      end
+    end
+
+    module ActionView
+      module ClassMethods # :nodoc:
+        def full_sanitizer
+          @full_sanitizer ||= ::Loofah::Helpers::ActionView::FullSanitizer.new
+        end
+
+        def safe_list_sanitizer
+          @safe_list_sanitizer ||= ::Loofah::Helpers::ActionView::SafeListSanitizer.new
+        end
+
+        def white_list_sanitizer
+          warn "warning: white_list_sanitizer is deprecated, please use safe_list_sanitizer instead."
+          safe_list_sanitizer
+        end
+      end
+
+      #
+      #  Replacement class for Rails's HTML::FullSanitizer.
+      #
+      #  To use by default, call this in an application initializer:
+      #
+      #    ActionView::Helpers::SanitizeHelper.full_sanitizer = ::Loofah::Helpers::ActionView::FullSanitizer.new
+      #
+      #  Or, to generally opt-in to Loofah's view sanitizers:
+      #
+      #    Loofah::Helpers::ActionView.set_as_default_sanitizer
+      #
+      class FullSanitizer
+        def sanitize(html, *args)
+          Loofah::Helpers.strip_tags html
+        end
+      end
+
+      #
+      #  Replacement class for Rails's HTML::WhiteListSanitizer.
+      #
+      #  To use by default, call this in an application initializer:
+      #
+      #    ActionView::Helpers::SanitizeHelper.safe_list_sanitizer = ::Loofah::Helpers::ActionView::SafeListSanitizer.new
+      #
+      #  Or, to generally opt-in to Loofah's view sanitizers:
+      #
+      #    Loofah::Helpers::ActionView.set_as_default_sanitizer
+      #
+      class SafeListSanitizer
+        def sanitize(html, *args)
+          Loofah::Helpers.sanitize html
+        end
+
+        def sanitize_css(style_string, *args)
+          Loofah::Helpers.sanitize_css style_string
+        end
+      end
+
+      WhiteListSanitizer = SafeListSanitizer
+      if Object.respond_to?(:deprecate_constant)
+        deprecate_constant :WhiteListSanitizer
       end
     end
   end

data/lib/loofah/html/document.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Loofah
   module HTML # :nodoc:
     #

data/lib/loofah/html/document_fragment.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 module Loofah
   module HTML # :nodoc:
     #
@@ -14,8 +15,13 @@ module Loofah
         #  constructor. Applications should use Loofah.fragment to
         #  parse a fragment.
         #
-        def parse tags
-          self.new(Loofah::HTML::Document.new, tags)
+        def parse(tags, encoding = nil)
+          doc = Loofah::HTML::Document.new
+
+          encoding ||= tags.respond_to?(:encoding) ? tags.encoding.name : "UTF-8"
+          doc.encoding = encoding
+
+          new(doc, tags)
         end
       end
 
@@ -25,6 +31,7 @@ module Loofah
       def to_s
         serialize_root.children.to_s
       end
+
       alias :serialize :to_s
 
       def serialize_root

data/lib/loofah/html5/libxml2_workarounds.rb

@@ -0,0 +1,27 @@
+# coding: utf-8
+# frozen_string_literal: true
+require "set"
+
+module Loofah
+  #
+  #  constants related to working around unhelpful libxml2 behavior
+  #
+  #  ಠ_ಠ
+  #
+  module LibxmlWorkarounds
+    #
+    #  these attributes and qualifying parent tags are determined by the code at:
+    #
+    #    https://git.gnome.org/browse/libxml2/tree/HTMLtree.c?h=v2.9.2#n714
+    #
+    #  see comments about CVE-2018-8048 within the tests for more information
+    #
+    BROKEN_ESCAPING_ATTRIBUTES = Set.new %w[
+                                           href
+                                           action
+                                           src
+                                           name
+                                         ]
+    BROKEN_ESCAPING_ATTRIBUTES_QUALIFYING_TAG = { "name" => "a" }
+  end
+end