disinfect_url 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fe51acef20c9a6e1ddf2648f9d242e6d23d5225bb626d48c42bed908c0eea734
+  data.tar.gz: 0a39172196fa928c1eb10b606c08af12d1d2fd9b624b54aabf8b4ed4b18cc9c8
+SHA512:
+  metadata.gz: e65bdbe96f9ff1f2f25fa988ec2c94f7f16418ee2b42767f6e6029a8dedc61c1c02854f1f112a36629a62bfcbe3613b6970a7f40949ed074b5caa679d9a86dfb
+  data.tar.gz: bebc66b0ca7aba77c83589ef64403c9fb0673519096fec2d1cd2f635237d30ecfb24b78f2c7105b525cb3725214a299bea20b17141dcccfe8055b64b2ff35d94

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## [0.1.0] - 2023-07-04
+
+### Added
+
+- Implemented sanitization on URLs and HTML `href` attributes in `<a>` tags.
+- Added RSpec tests for the sanitization functionality.

data/README.md

@@ -0,0 +1,94 @@
+# DisinfectUrl
+
+This gem was _heavily_ influenced by Braintree's [sanitize-url](https://github.com/braintree/sanitize-url/tree/main)
+
+## Installation
+
+```ruby
+gem 'disinfect_url'
+```
+
+## Usage
+
+### Requirements
+
+This gem requires Ruby 2.5+
+
+### Basic Usage
+
+Convert bad urls to "about:blank"
+
+```ruby
+DisinfectUrl.sanitize("https://example.com")
+# => https://example.com
+
+DisinfectUrl.sanitize("http://example.com")
+# => http://example.com
+
+DisinfectUrl.sanitize("www.example.com")
+# => www.example.com
+
+DisinfectUrl.sanitize("mailto:hello@example.com")
+# => mailto:hello@example.com
+
+DisinfectUrl.sanitize("https&#0000058//example.com")
+# => https://example.com
+
+DisinfectUrl.sanitize("javascript:alert(document.domain)")
+DisinfectUrl.sanitize("jAvasCrIPT:alert(document.domain)")
+DisinfectUrl.sanitize("JaVaScRiP%0at:alert(document.domain)")
+# => about:blank
+
+#HTML encoded javascript:alert('XSS')
+DisinfectUrl.sanitize("&#0000106&#0000097&#0000118&#0000097&#0000115&#0000099&#0000114&#0000105&#0000112&#0000116&#0000058&#0000097&#0000108&#0000101&#0000114&#0000116&#0000040&#0000039&#0000088&#0000083&#0000083&#0000039&#0000041")
+# => about:blank
+
+# Works the same way for href attribute within <a> tags
+DisinfectUrl.sanitize(%q(<a href="javascript:alert('attack')">Example</a>))
+# => <a href="about:blank">Example</a>
+```
+
+### ActiveRecord Callbacks
+
+```ruby
+before_validation :disinfect_website_url
+before_validation :disinfect_biography
+
+private
+
+  def disinfect_website_url
+    self.website_url = DisinfectUrl.sanitize(self.website_url)
+  end
+
+  def disinfect_biography
+    self.biography = DisinfectUrl.sanitize(self.biography)
+  end
+```
+
+### Validation Note
+
+This gem doesn't perform any validation for differentiating HTML vs URL. You may need to perform additional validation.
+
+```ruby
+  def disinfect_website_url
+    self.website_url = DisinfectUrl.sanitize(%q(<a href="https://example.com">Example</a>))
+  end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/stevenjcumming/disinfect_url. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/stevenjcumming/disinfect_url/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the DisinfectUrl project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/stevenjcumming/disinfect_url/blob/main/CODE_OF_CONDUCT.md).

data/lib/disinfect_url/html_sanitizer.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "disinfect_url"
+
+# A class responsible for sanitizing HTML by cleaning up URLs within <a> tags.
+# Not recommended to be used directly
+module DisinfectUrl
+  class HTMLSanitizer
+    class << self
+      # Sanitizes the given HTML by cleaning up URLs in href attributes within <a> tags.
+      #
+      # @param html [String] The HTML to sanitize.
+      # @return [String] The sanitized HTML.
+      def sanitize(html)
+        return nil if html.nil? || html.to_s.strip.empty?
+
+        fragment = Nokogiri::HTML.fragment(html)
+
+        fragment.css("a").each do |link|
+          link["href"] = DisinfectUrl::URLSanitizer.sanitize(link["href"])
+        end
+
+        fragment.to_html
+      end
+    end
+  end
+end

data/lib/disinfect_url/url_sanitizer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+# A class responsible for sanitizing URLs.
+# Not recommended to be used directly
+module DisinfectUrl
+  class URLSanitizer
+    INVALID_PROTOCOL_REGEX = /^([^\w]*)(javascript|data|vbscript)/im.freeze
+    HTML_ENTITIES_REGEX = /&#(\w+)(?!\w|;)?/.freeze
+    HTML_CTRL_ENTITY_REGEX = /&(newline|tab);/i.freeze
+    CTRL_CHARACTERS_REGEX = /[\u0000-\u001F\u007F-\u009F\u2000-\u200D\uFEFF]/m.freeze
+    URL_SCHEME_REGEX = /^.+(:|:)/mi.freeze
+    RELATIVE_FIRST_CHARACTERS = [".", "/"].freeze
+
+    class << self
+      # Sanitizes the given URL by removing invalid parts and characters.
+      #
+      # @param url [String] The URL to sanitize.
+      # @return [String] The sanitized URL.
+      def sanitize(url)
+        return nil if url.nil? || url.to_s.strip.empty?
+
+        sanitized_url = decode_html_characters(url || "")
+                        .gsub(HTML_CTRL_ENTITY_REGEX, "")
+                        .gsub(CTRL_CHARACTERS_REGEX, "")
+                        .strip
+
+        return "about:blank" if sanitized_url.empty?
+
+        return sanitized_url if relative_url_without_protocol?(sanitized_url)
+
+        url_scheme_parse_results = sanitized_url.match(URL_SCHEME_REGEX)
+
+        return sanitized_url unless url_scheme_parse_results
+
+        url_scheme = url_scheme_parse_results[0]
+
+        return "about:blank" if INVALID_PROTOCOL_REGEX.match(url_scheme)
+
+        sanitized_url
+      end
+
+      private
+
+      # Checks if the URL is a relative URL without a protocol.
+      #
+      # @param url [String] The URL to check.
+      # @return [Boolean] `true` if the URL is a relative URL without a protocol, `false` otherwise.
+      def relative_url_without_protocol?(url)
+        RELATIVE_FIRST_CHARACTERS.include?(url[0])
+      end
+
+      # Decodes HTML entities in the given string.
+      #
+      # @param str [String] The string to decode.
+      # @return [String] The decoded string.
+      def decode_html_characters(str)
+        str = CGI.unescapeHTML(str)
+        str.gsub(HTML_ENTITIES_REGEX) { |match| match[2..-1].to_i.chr }
+      end
+    end
+  end
+end

data/lib/disinfect_url/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DisinfectUrl
+  VERSION = "0.2.0"
+end

data/lib/disinfect_url.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "disinfect_url/version"
+require_relative "disinfect_url/html_sanitizer"
+require_relative "disinfect_url/url_sanitizer"
+
+# Sanitizes a URL or an HTML string depending on the input.
+module DisinfectUrl
+  class << self
+    # If the input is a URL (a string), it sanitizes the URL by removing
+    # potentially dangerous elements and characters.
+    #
+    # If the input is an HTML string (a string), it sanitizes the URLs within
+    # <a> tags by removing potentially dangerous elements and attributes.
+    #
+    # @param input [String] The URL or HTML string to be sanitized.
+    # @return [String, nil] The sanitized URL or HTML string, or nil if the input is not a String.
+    def sanitize(input)
+      return unless input.is_a?(String)
+
+      HTMLSanitizer.sanitize(URLSanitizer.sanitize(input))
+    end
+  end
+end

metadata

@@ -0,0 +1,138 @@
+--- !ruby/object:Gem::Specification
+name: disinfect_url
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- stevenjcumming
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2023-07-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: rubocop-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.22'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.34
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.34
+description: A gem to sanitize URLs or HTML href attributes within <a> tags to help
+  prevent XSS attacks.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- README.md
+- lib/disinfect_url.rb
+- lib/disinfect_url/html_sanitizer.rb
+- lib/disinfect_url/url_sanitizer.rb
+- lib/disinfect_url/version.rb
+homepage: https://github.com/stevenjcumming/disinfect_url
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stevenjcumming/disinfect_url
+  documentation_uri: https://rubydoc.info/github/stevenjcumming/disinfect_url
+  changelog_uri: https://github.com/stevenjcumming/disinfect_url/blob/main/CHANGELOG.md
+  source_code_uri: https://github.com/stevenjcumming/disinfect_url
+  bug_tracker_uri: https://github.com/stevenjcumming/disinfect_url/issues
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.6
+signing_key:
+specification_version: 4
+summary: A gem to sanitize URLs or HTML
+test_files: []