rails-html-sanitizer 1.4.4 → 1.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a74021096590326ee357971bec71d2c4507a95cdaf05c8e21d383ce18fee18d3
-  data.tar.gz: faad0d5f268dad601b633b03912e353fcc2d760fceb253d9cde2064b010b997a
+  metadata.gz: 59897b4a0d7f69a21932ec1cb44e24ea0ba4c2cf79ef7101ef32e90f40ad766b
+  data.tar.gz: '063919ea5426a6938040672fefeabcaf82087a5ccd12ffc7457e34eb6984042b'
 SHA512:
-  metadata.gz: e7f01438708076a283326c78b052ba954a42de4134d8d1d7e7c336c82ecd04c661f75dad3a0f9b1ffebe278f76ef229c98a3f2568801f82d94c94a50f399a2ef
-  data.tar.gz: 4f44c0e92eb9e565611772ba28d426025621c0517c4217004c3409192991a17498dd38165a6c55561a5347d2fcdf34f51b24101ad6de525604e35785e89efbc0
+  metadata.gz: 2b0c23a07bc8acb3c1a039266cf053ad9044670a96620365b3ed722eb9a602def1bebe8de40697a2b12deba61cf224461ae8a4dc93749fa8c9675cda4cd216dd
+  data.tar.gz: 5dce2af04dd887e08773a975cc67d93987b15330d023cc68a6cc51322ed73b60681309b25feab1a2c54b0e062696af1dd78c83cdb609e8d179b6ef95419573b3

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 1.5.0 / 2023-01-20
+
+* `SafeListSanitizer`, `PermitScrubber`, and `TargetScrubber` now all support pruning of unsafe tags.
+
+  By default, unsafe tags are still stripped, but this behavior can be changed to prune the element
+  and its children from the document by passing `prune: true` to any of these classes' constructors.
+
+  *seyerian*
+
 ## 1.4.4 / 2022-12-13
 
 * Address inefficient regular expression complexity with certain configurations of Rails::Html::Sanitizer.
@@ -43,7 +52,6 @@
 
   *Mike Dalessio*
 
-
 ## 1.4.2 / 2021-08-23
 
 * Slightly improve performance.

data/README.md

@@ -21,6 +21,35 @@ Or install it yourself as:
 
 ## Usage
 
+### A note on HTML entities
+
+__Rails::HTML sanitizers are intended to be used by the view layer, at page-render time. They are *not* intended to sanitize persisted strings that will sanitized *again* at page-render time.__
+
+Proper HTML sanitization will replace some characters with HTML entities. For example, `<` will be replaced with `&lt;` to ensure that the markup is well-formed.
+
+This is important to keep in mind because __HTML entities will render improperly if they are sanitized twice.__
+
+
+#### A concrete example showing the problem that can arise
+
+Imagine the user is asked to enter their employer's name, which will appear on their public profile page. Then imagine they enter `JPMorgan Chase & Co.`.
+
+If you sanitize this before persisting it in the database, the stored string will be `JPMorgan Chase &amp; Co.`
+
+When the page is rendered, if this string is sanitized a second time by the view layer, the HTML will contain `JPMorgan Chase &amp;amp; Co.` which will render as "JPMorgan Chase &amp;amp; Co.".
+
+Another problem that can arise is rendering the sanitized string in a non-HTML context (for example, if it ends up being part of an SMS message). In this case, it may contain inappropriate HTML entities.
+
+
+#### Suggested alternatives
+
+You might simply choose to persist the untrusted string as-is (the raw input), and then ensure that the string will be properly sanitized by the view layer.
+
+That raw string, if rendered in an non-HTML context (like SMS), must also be sanitized by a method appropriate for that context. You may wish to look into using [Loofah](https://github.com/flavorjones/loofah) or [Sanitize](https://github.com/rgrove/sanitize) to customize how this sanitization works, including omitting HTML entities in the final string.
+
+If you really want to sanitize the string that's stored in your database, you may wish to look into  [Loofah::ActiveRecord](https://github.com/flavorjones/loofah-activerecord) rather than use the Rails::HTML sanitizers.
+
+
 ### Sanitizers
 
 All sanitizers respond to `sanitize`.
@@ -57,6 +86,9 @@ safe_list_sanitizer.sanitize(@article.body, scrubber: ArticleScrubber.new)
 
 # safe list sanitizer can also sanitize css
 safe_list_sanitizer.sanitize_css('background-color: #000;')
+
+# fully prune nodes from the tree instead of stripping tags and leaving inner content
+safe_list_sanitizer = Rails::Html::SafeListSanitizer.new(prune: true)
 ```
 
 ### Scrubbers
@@ -78,6 +110,24 @@ html_fragment.scrub!(scrubber)
 html_fragment.to_s # => "<a></a>"
 ```
 
+By default, inner content is left, but it can be removed as well.
+
+```ruby
+scrubber = Rails::Html::PermitScrubber.new
+scrubber.tags = ['a']
+
+html_fragment = Loofah.fragment('<a><span>text</span></a>')
+html_fragment.scrub!(scrubber)
+html_fragment.to_s # => "<a>text</a>"
+
+scrubber = Rails::Html::PermitScrubber.new(prune: true)
+scrubber.tags = ['a']
+
+html_fragment = Loofah.fragment('<a><span>text</span></a>')
+html_fragment.scrub!(scrubber)
+html_fragment.to_s # => "<a></a>"
+```
+
 #### `Rails::Html::TargetScrubber`
 
 Where `PermitScrubber` picks out tags and attributes to permit in sanitization,
@@ -95,6 +145,23 @@ html_fragment.scrub!(scrubber)
 html_fragment.to_s # => "<a></a>"
 ```
 
+Similarly to `PermitScrubber`, nodes can be fully pruned.
+
+```ruby
+scrubber = Rails::Html::TargetScrubber.new
+scrubber.tags = ['span']
+
+html_fragment = Loofah.fragment('<a><span>text</span></a>')
+html_fragment.scrub!(scrubber)
+html_fragment.to_s # => "<a>text</a>"
+
+scrubber = Rails::Html::TargetScrubber.new(prune: true)
+scrubber.tags = ['span']
+
+html_fragment = Loofah.fragment('<a><span>text</span></a>')
+html_fragment.scrub!(scrubber)
+html_fragment.to_s # => "<a></a>"
+```
 #### Custom Scrubbers
 
 You can also create custom scrubbers in your application if you want to.
@@ -138,5 +205,11 @@ Rails Html Sanitizers is work of many contributors. You're encouraged to submit
 
 See [CONTRIBUTING](CONTRIBUTING.md).
 
+### Security reports
+
+Trying to report a possible security vulnerability in this project? Please
+check out our [security policy](https://rubyonrails.org/security) for
+guidelines about how to proceed.
+
 ## License
 Rails Html Sanitizers is released under the [MIT License](MIT-LICENSE).

data/lib/rails/html/sanitizer/version.rb

@@ -1,7 +1,7 @@
 module Rails
   module Html
     class Sanitizer
-      VERSION = "1.4.4"
+      VERSION = "1.5.0"
     end
   end
 end

data/lib/rails/html/sanitizer.rb

@@ -110,8 +110,8 @@ module Rails
         acronym a img blockquote del ins))
       self.allowed_attributes = Set.new(%w(href src width height alt cite datetime title class name xml:lang abbr))
 
-      def initialize
-        @permit_scrubber = PermitScrubber.new
+      def initialize(prune: false)
+        @permit_scrubber = PermitScrubber.new(prune: prune)
       end
 
       def sanitize(html, options = {})

data/lib/rails/html/scrubbers.rb

@@ -45,10 +45,11 @@ module Rails
     # See the documentation for +Nokogiri::XML::Node+ to understand what's possible
     # with nodes: https://nokogiri.org/rdoc/Nokogiri/XML/Node.html
     class PermitScrubber < Loofah::Scrubber
-      attr_reader :tags, :attributes
+      attr_reader :tags, :attributes, :prune
 
-      def initialize
-        @direction = :bottom_up
+      def initialize(prune: false)
+        @prune = prune
+        @direction = @prune ? :top_down : :bottom_up
         @tags, @attributes = nil, nil
       end
 
@@ -98,7 +99,7 @@ module Rails
       end
 
       def scrub_node(node)
-        node.before(node.children) # strip
+        node.before(node.children) unless prune # strip
         node.remove
       end
 

data/test/sanitizer_test.rb

@@ -256,6 +256,12 @@ class SanitizersTest < Minitest::Test
     end
   end
 
+  def test_should_allow_prune
+    sanitizer = Rails::Html::SafeListSanitizer.new(prune: true)
+    text = '<u>leave me <b>now</b></u>'
+    assert_equal "<u>leave me </u>", sanitizer.sanitize(text, tags: %w(u))
+  end
+
   def test_should_allow_custom_tags
     text = "<u>foo</u>"
     assert_equal text, safe_list_sanitize(text, tags: %w(u))

data/test/scrubbers_test.rb

@@ -66,6 +66,13 @@ class PermitScrubberTest < ScrubberTest
     assert_scrubbed html, '<tag>leave me now</tag>'
   end
 
+  def test_prunes_tags
+    @scrubber = Rails::Html::PermitScrubber.new(prune: true)
+    @scrubber.tags = %w(tag)
+    html = '<tag>leave me <span>now</span></tag>'
+    assert_scrubbed html, '<tag>leave me </tag>'
+  end
+
   def test_leaves_comments_when_supplied_as_tag
     @scrubber.tags = %w(div comment)
     assert_scrubbed('<div>one</div><!-- two --><span>three</span>',
@@ -157,6 +164,13 @@ class TargetScrubberTest < ScrubberTest
     html = '<tag remove="" other=""></tag><a remove="" other=""></a>'
     assert_scrubbed html, '<a other=""></a>'
   end
+
+  def test_prunes_tags
+    @scrubber = Rails::Html::TargetScrubber.new(prune: true)
+    @scrubber.tags = %w(span)
+    html = '<tag>leave me <span>now</span></tag>'
+    assert_scrubbed html, '<tag>leave me </tag>'
+  end
 end
 
 class TextOnlyScrubberTest < ScrubberTest

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails-html-sanitizer
 version: !ruby/object:Gem::Version
-  version: 1.4.4
+  version: 1.5.0
 platform: ruby
 authors:
 - Rafael Mendonça França
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-13 00:00:00.000000000 Z
+date: 2023-01-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: loofah
@@ -109,9 +109,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/rails/rails-html-sanitizer/issues
-  changelog_uri: https://github.com/rails/rails-html-sanitizer/blob/v1.4.4/CHANGELOG.md
-  documentation_uri: https://www.rubydoc.info/gems/rails-html-sanitizer/1.4.4
-  source_code_uri: https://github.com/rails/rails-html-sanitizer/tree/v1.4.4
+  changelog_uri: https://github.com/rails/rails-html-sanitizer/blob/v1.5.0/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/rails-html-sanitizer/1.5.0
+  source_code_uri: https://github.com/rails/rails-html-sanitizer/tree/v1.5.0
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -127,7 +127,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.2
 signing_key: 
 specification_version: 4
 summary: This gem is responsible to sanitize HTML fragments in Rails applications.