sanitize 1.0.0

data/HISTORY

@@ -0,0 +1,5 @@
+Sanitize History
+================================================================================
+
+Version 1.0.0 (2008-12-25)
+  * First release.

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+
+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/README

@@ -0,0 +1,142 @@
+= 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.
+
+Using a simple configuration syntax, you can tell Sanitize to allow certain
+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.
+
+Because it's based on Hpricot, a full-fledged HTML parser, rather than a bunch
+of fragile regular expressions, Sanitize has no trouble dealing with malformed
+or maliciously-formed HTML. When in doubt, Sanitize always errs on the side of
+caution.
+
+*Author*::    Ryan Grove (mailto:ryan@wonko.com)
+*Version*::   1.0.0 (2008-12-25)
+*Copyright*:: Copyright (c) 2008 Ryan Grove. All rights reserved.
+*License*::   MIT License (http://opensource.org/licenses/mit-license.php)
+*Website*::   http://github.com/rgrove/sanitize
+
+== Requires
+
+* RubyGems
+* Hpricot 0.6+
+
+== Usage
+
+If you don't specify any configuration options, Sanitize will use its strictest
+settings by default, which means it will strip all HTML.
+
+  require 'rubygems'
+  require 'sanitize'
+
+  html = '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg" />'
+
+  Sanitize.clean(html) # => 'foo'
+
+== Configuration
+
+In addition to the ultra-safe default settings, Sanitize comes with three other
+built-in modes.
+
+=== Sanitize::Config::RESTRICTED
+
+Allows only very simple inline formatting markup. No links, images, or block
+elements.
+
+  Sanitize.clean(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 <code>rel="nofollow"</code> attribute is added to all links to
+mitigate SEO spam.
+
+  Sanitize.clean(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, <code>rel="nofollow"</code> is not
+added to links.
+
+  Sanitize.clean(html, Sanitize::Config::RELAXED)
+  # => '<b><a href="http://foo.com/">foo</a></b><img src="http://foo.com/bar.jpg" />'
+
+=== Custom Configuration
+
+If the built-in modes don't meet your needs, you can easily specify a custom
+configuration:
+
+  Sanitize.clean(html, :elements => ['a', 'span'],
+      :attributes => {'a' => ['href', 'title'], 'span' => ['class']},
+      :protocols => {'a' => {'href' => ['http', 'https', 'mailto']}})
+
+==== :elements
+
+Array of element names to allow. Specify all names in lowercase.
+
+  :elements => [
+    'a', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'dl', 'dt', 'em',
+    'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'strong', 'sub',
+    'sup', 'u', 'ul'
+  ]
+
+==== :attributes
+
+Attributes to allow for specific elements. Specify all element names and
+attributes in lowercase.
+
+  :attributes => {
+    'a'          => ['href', 'title'],
+    'blockquote' => ['cite'],
+    'img'        => ['alt', 'src', 'title']
+  }
+
+==== :add_attributes
+
+Attributes to add to specific elements. If the attribute already exists, it will
+be replaced with the value specified here. Specify all element names and
+attributes in lowercase.
+
+  :add_attributes => {
+    'a' => {'rel' => 'nofollow'}
+  }
+
+==== :protocols
+
+URL protocols to allow in specific attributes. If an attribute is listed here
+and contains a protocol other than those specified (or if it contains no
+protocol at all), it will be removed.
+
+  :protocols => {
+    'a'   => {'href' => ['ftp', 'http', 'https', 'mailto']},
+    'img' => {'src'  => ['http', 'https']}
+  }
+
+== License
+
+Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+
+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/lib/sanitize/config/basic.rb

@@ -0,0 +1,48 @@
+#--
+# Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+# 
+# 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.
+#++
+
+class Sanitize
+  module Config
+    BASIC = {
+      :elements => [
+        'a', 'b', 'blockquote', 'br', 'cite', 'code', 'dd', 'dl', 'dt', 'em',
+        'i', 'li', 'ol', 'p', 'pre', 'q', 'small', 'strike', 'strong', 'sub',
+        'sup', 'u', 'ul'],
+
+      :attributes => {
+        'a'          => ['href'],
+        'blockquote' => ['cite'],
+        'q'          => ['cite']
+      },
+
+      :add_attributes => {
+        'a' => {'rel' => 'nofollow'}
+      },
+
+      :protocols => {
+        'a'          => {'href' => ['ftp', 'http', 'https', 'mailto']},
+        'blockquote' => {'cite' => ['http', 'https']},
+        'q'          => {'cite' => ['http', 'https']}
+      }
+    }
+  end
+end

data/lib/sanitize/config/relaxed.rb

@@ -0,0 +1,55 @@
+#--
+# Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+# 
+# 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.
+#++
+
+class Sanitize
+  module Config
+    RELAXED = {
+      :elements => [
+        'a', 'b', 'blockquote', 'br', 'caption', 'cite', 'code', 'col',
+        'colgroup', 'dd', 'dl', 'dt', 'em', 'i', 'img', 'li', 'ol', 'p', 'pre',
+        'q', 'small', 'strike', 'strong', 'sub', 'sup', 'table', 'tbody', 'td',
+        'tfoot', 'th', 'thead', 'tr', 'u', 'ul'],
+
+      :attributes => {
+        'a'          => ['href', 'title'],
+        'blockquote' => ['cite'],
+        'col'        => ['span', 'width'],
+        'colgroup'   => ['span', 'width'],
+        'img'        => ['align', 'alt', 'height', 'src', 'title', 'width'],
+        'ol'         => ['start', 'type'],
+        'q'          => ['cite'],
+        'table'      => ['summary', 'width'],
+        'td'         => ['abbr', 'axis', 'colspan', 'rowspan', 'width'],
+        'th'         => ['abbr', 'axis', 'colspan', 'rowspan', 'scope',
+                         'width'],
+        'ul'         => ['type']
+      },
+
+      :protocols => {
+        'a'          => {'href' => ['ftp', 'http', 'https', 'mailto']},
+        'blockquote' => {'cite' => ['http', 'https']},
+        'img'        => {'src'  => ['http', 'https']},
+        'q'          => {'cite' => ['http', 'https']}
+      }
+    }
+  end
+end

data/lib/sanitize/config/restricted.rb

@@ -0,0 +1,29 @@
+#--
+# Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+# 
+# 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.
+#++
+
+class Sanitize
+  module Config
+    RESTRICTED = {
+      :elements => ['b', 'em', 'i', 'strong', 'u']
+    }
+  end
+end

data/lib/sanitize/config.rb

@@ -0,0 +1,48 @@
+#--
+# Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+# 
+# 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.
+#++
+
+class Sanitize
+  module Config
+    DEFAULT = {
+      # Whether or not to allow HTML comments. Allowing comments is strongly
+      # discouraged, since IE allows script execution within conditional
+      # comments.
+      :allow_comments => false,
+
+      # HTML elements to allow. By default, no elements are allowed (which means
+      # that all HTML will be stripped).
+      :elements => [],
+
+      # HTML attributes to allow in specific elements. By default, no attributes
+      # are allowed.
+      :attributes => {},
+
+      # HTML attributes to add to specific elements. By default, no attributes
+      # are added.
+      :add_attributes => {},
+
+      # URL handling protocols to allow in specific attributes. By default, no
+      # protocols are allowed.
+      :protocols => {}
+    }
+  end
+end

data/lib/sanitize.rb

@@ -0,0 +1,132 @@
+#--
+# Copyright (c) 2008 Ryan Grove <ryan@wonko.com>
+# 
+# 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.
+#++
+
+# Append this file's directory to the include path if it's not there already.
+$:.unshift(File.dirname(File.expand_path(__FILE__)))
+$:.uniq!
+
+require 'rubygems'
+gem 'hpricot', '~> 0.6'
+
+require 'hpricot'
+require 'sanitize/config'
+require 'sanitize/config/restricted'
+require 'sanitize/config/basic'
+require 'sanitize/config/relaxed'
+
+class Sanitize
+  #--
+  # Class Methods
+  #++
+
+  # Returns a sanitized copy of _html_, using the settings in _config_ if
+  # specified.
+  def self.clean(html, config = {})
+    sanitize = Sanitize.new(config)
+    sanitize.clean(html)
+  end
+
+  # Performs Sanitize#clean in place, returning _html_, or +nil+ if no changes
+  # were necessary.
+  def self.clean!(html, config = {})
+    sanitize = Sanitize.new(config)
+    sanitize.clean!(html)
+  end
+
+  #--
+  # Instance Methods
+  #++
+
+  # Returns a new Sanitize object initialized with the settings in _config_.
+  def initialize(config = {})
+    @config = Config::DEFAULT.merge(config)
+  end
+
+  # Returns a sanitized copy of _html_.
+  def clean(html)
+    dupe = html.dup
+    clean!(dupe) || dupe
+  end
+
+  # Performs clean in place, returning _html_, or +nil+ if no changes were
+  # necessary.
+  def clean!(html)
+    fragment = Hpricot(html)
+
+    fragment.traverse_element do |node|
+      if node.bogusetag? || node.doctype? || node.procins? || node.xmldecl?
+        node.swap('')
+        next
+      end
+
+      if node.comment?
+        node.swap('') unless @config[:allow_comments]
+      elsif node.elem?
+        name = node.name.downcase
+
+        # Delete any element that isn't in the whitelist.
+        unless @config[:elements].include?(name)
+          node.parent.replace_child(node, node.children)
+          next
+        end
+
+        if @config[:attributes].has_key?(name)
+          # Delete any attribute that isn't in the whitelist for this element.
+          node.raw_attributes.delete_if do |key, value|
+            !@config[:attributes][name].include?(key.downcase)
+          end
+
+          # Delete remaining attributes that use unacceptable protocols.
+          if @config[:protocols].has_key?(name)
+            protocol = @config[:protocols][name]
+
+            node.raw_attributes.delete_if do |key, value|
+              protocol.has_key?(key) && (!(value.downcase =~ /^([^:]+):/) ||
+                  !protocol[key].include?($1.downcase))
+            end
+          end
+        else
+          # Delete all attributes from elements with no whitelisted
+          # attributes.
+          node.raw_attributes = {}
+        end
+
+        # Add required attributes.
+        if @config[:add_attributes].has_key?(name)
+          node.raw_attributes.merge!(@config[:add_attributes][name])
+        end
+      end
+    end
+
+    # Make one last pass through the fragment and replace angle brackets with
+    # entities in all text nodes. This helps eliminate certain types of
+    # maliciously-malformed nested tags.
+    fragment.traverse_element do |node|
+      if node.text?
+        node.swap(node.inner_text.gsub('<', '&lt;').gsub('>', '&gt;'))
+      end
+    end
+
+    result = fragment.to_s
+    return result == html ? nil : html[0, html.length] = result
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification 
+name: sanitize
+version: !ruby/object:Gem::Version 
+  version: 1.0.0
+platform: ruby
+authors: 
+- Ryan Grove
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-24 00:00:00 -08:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: "0.6"
+    version: 
+description: 
+email: ryan@wonko.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- HISTORY
+- LICENSE
+- README
+- lib/sanitize.rb
+- lib/sanitize/config.rb
+- lib/sanitize/config/basic.rb
+- lib/sanitize/config/relaxed.rb
+- lib/sanitize/config/restricted.rb
+has_rdoc: false
+homepage: http://github.com/rgrove/sanitize/
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.6
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: Whitelist-based HTML sanitizer.
+test_files: []
+