README.md

Sanitize

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 HTML
elements, certain attributes within those elements, and even certain URL
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.

Sanitize is based on Google's Gumbo HTML5 parser, which parses HTML
exactly the same way modern browsers do, and 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.

Links

Installation

gem install sanitize

Quick Start

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 safe text
behind.

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.

Sanitize::Config::RELAXED

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.

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:

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:

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:

:protocols => {
'a' => {'href' => ['http', 'https', :relative]}
}

:remove_contents (boolean or Array or Set)

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.

If set to an array of element names, then only the contents of the specified
elements (when filtered) will be removed, and the contents of all other filtered
elements will be left behind.

The default value is false.

:transformers (Array or callable)

Custom HTML transformer or array of custom transformers. See the Transformers
section below for details.

:whitespace_elements (Hash)

Hash of element names which, when removed, should have their contents surrounded
by whitespace to preserve readability.

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.

Transformers

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.

Input

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.

:is_whitelisted - true if the current node has been whitelisted by a
previous transformer, false otherwise. It's generally bad form to remove
a node that a previous transformer has whitelisted.

:node - A Nokogiri::XML::Node object representing an HTML node. The
node may be an element, a text node, a comment, a CDATA node, or a document
fragment. Use Nokogiri's inspection methods (element?, text?, etc.) to
selectively ignore node types you aren't interested in.

:node_name - The name of the current HTML node, always lowercase (e.g.
"div" or "span"). For non-element nodes, the name will be something like
"text", "comment", "#cdata-section", "#document-fragment", etc.

:node_whitelist - Set of Nokogiri::XML::Node objects in the current
document that have been whitelisted by previous transformers, if any. It's
generally bad form to remove a node that a previous transformer has
whitelisted.

Output

A transformer doesn't have to return anything, but may optionally return a Hash,
which may contain the following items:

:node_whitelist - Array or Set of specific Nokogiri::XML::Node objects
to add to the document's whitelist, bypassing the current Sanitize config.
These specific nodes and all their attributes will be whitelisted, but
their children will not be.

If a transformer returns anything other than a Hash, the return value will be
ignored.

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
changes made to the current node or to the document will be reflected instantly
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.
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.

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 image URLs by domain

The following example demonstrates how to remove image elements unless they use
a relative URL or are hosted on a specific domain. It assumes that the <img>
element and its src attribute are already whitelisted.

Example: Transformer to whitelist YouTube video embeds

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:

youtube_transformer = lambda do |env|
node = env[:node]
node_name = env[:node_name]
# Don't continue if this node is already whitelisted or is not an element.returnif env[:is_whitelisted] ||!node.element?
# Don't continue unless the node is an iframe.returnunless node_name =='iframe'# Verify that the video URL is actually a valid YouTube video URL.returnunless 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.node!(node, {
:elements => %w[iframe],
:attributes => {
'iframe' => %w[allowfullscreen frameborder height src width]
}
})
# Now that we're sure that this is a valid YouTube embed and that there are# no unwanted elements or attributes hidden inside it, we can tell Sanitize# to whitelist the current node.
{:node_whitelist => [node]}
end
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

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.