Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
HTML/XML manipulation and sanitization based on Nokogiri
Ruby JavaScript
Branch: master
Pull request Compare This branch is 1 commit ahead, 173 commits behind flavorjones:master.

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
benchmark
lib
rails_test
test
.gitignore
CHANGELOG.rdoc
DEPRECATED.rdoc
MIT-LICENSE.txt
Manifest.txt
README.rdoc
Rakefile
TODO.rdoc
init.rb

README.rdoc

Loofah

Description

Loofah is a general library for manipulating 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 whitelist, so it most likely won't make your codes less secure. (These statements have not been evaluated by Netexperts.)

Features

  • Easily write custom scrubbers for HTML/XML leveraging the sweetness of Nokogiri (and HTML5lib's whitelists).

  • 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 < and > 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.

  • Replace Rails's strip_tags and sanitize helper methods.

  • Two ActiveRecord extensions:

    • Loofah::XssFoliate, an XssTerminate drop-in replacement, is an opt-out sanitizer. By default all models and attributes are sanitized.

    • Loofah::ActiveRecordExtension is an opt-in sanitizer. You must explicitly declare attributes to be sanitized.

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 fine 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):

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 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,

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. Loofah won't wrap the result in html and body tags, won't add a DOCTYPE declaration, and will ignore head elements.

XML fragments should be parsed with Loofah.xml_fragment. Loofah won't add a DOCTYPE declaration and will allow multiple root nodes.

HTML documents should be parsed with Loofah.document, which will add the DOCTYPE declaration, and properly handle head and body elements.

XML documents should be parsed with Loofah.xml_document. Loofah will make sure there's 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.

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:

unsafe_html = "ohai! <div>div is safe</div> <script>but script is not</script>"

doc = Loofah.fragment(unsafe_html).scrub!(:strip)
doc.to_s    # => "ohai! <div>div is safe</div> "

and text to return plain text:

doc.text    # => "ohai! div is safe "

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.

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 in the document:

Loofah.xml_document(bad_xml).xpath("//employee").scrub!(employee_scrubber)

Loofah::Scrubber

A Scrubber wraps up a block (or method) that is run on a document node:

# 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:

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:

# 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 whitelist algorithm:

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:

doc.scrub!(:nofollow)    #     adds rel="nofollow" attribute to links

See Loofah::Scrubbers for more details and example usage.

Chaining Scrubbers

You can chain scrubbers:

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.

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):

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)

ActiveRecord Extension #1: Opt-In

See Loofah::ActiveRecordExtension for full documentation. The methods mixed into ActiveRecord are:

  • Loofah::ActiveRecordExtension.html_document

  • Loofah::ActiveRecordExtension.html_fragment

which are used to declare how specific string and text attributes should be scrubbed at before_validation.

# app/model/post.rb
class Post < ActiveRecord::Base
  html_fragment :body, :scrub => :prune  # scrubs 'body' at before_validation
end

ActiveRecord Extension #2: Opt-Out

See Loofah::XssFoliate::ClassMethods for more documentation. The methods mixed into ActiveRecord are:

  • Loofah::XssFoliate::ClassMethods.xss_foliate

  • Loofah::XssFoliate::ClassMethods.xss_foliated?

which are used to declare how specific string and text attributes should be scrubbed at before_validation.

Attributes are stripped by default, unless another scrubber is specified or the attribute is present in an :except clause.

View Helpers

Loofah has two “view helpers”: Loofah::Helpers.sanitize and Loofah::Helpers.strip_tags, both of which are drop-in replacements for the ActionView helpers of the same name.

Requirements

  • Nokogiri >= 1.3.3

  • Rails 2.3, 2.2, 2.1, 2.0 or 1.2 (if you're using the ActiveRecord extensions)

Installation

Unsurprisingly:

  • gem install loofah

Support

The bug tracker is available here:

And the mailing list is on librelist:

And the IRC channel is #loofah on freenode.

Related Links

Authors

Featuring code contributed by:

  • Aaron Patterson

  • John Barnette

  • Josh Owens

  • Paul Dix

  • Josh Nichols

  • Luke Melia

And a big shout-out to Corey Innis for the name, and feedback on the API.

Historical Note

This library was formerly known as Dryopteris, which was a very bad name that nobody could spell properly.

License

The MIT License

Copyright © 2009 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.

Something went wrong with that request. Please try again.