homographic_spoofing 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0271afba8ca392a2898b76894ca4be2cf4eb024f14fea0ea4e2467265b88c7e5
+  data.tar.gz: f77b9ca4563b4e7e59264cbd83b60d38ae89417fddad193dc0a1c39993bd4535
+SHA512:
+  metadata.gz: f2639bca34a87a1b3f0e121608684fa37d50f83b125efab25baeef85fa111151a7e5ae8e40e4207b4fdfd5dfe8c502965834468190dc4efc7d9ad433c6a1916c
+  data.tar.gz: 351fe4d4b0c22105838d99404056e848cbe3f5f0b7bcfa8f9b770a651ac8c942d73f18bc0b709b5aa074d73670fd56a997afb44b6d4f6877e96cde5eda640970

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2024 37signals, LLC
+
+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.md

@@ -0,0 +1,117 @@
+# HomographicSpoofing
+
+Toolkit to both detect and sanitize [homographic spoofing attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack) in URLs and Email addresses.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "homographic_spoofing"
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install homographic_spoofing
+```
+## Configuration
+
+If `HomographicSpoofing.logger` is set to a Logger instance, the gem will log all the violations found. If you're using Rails,
+it is automatically configured to use `Rails.logger`, otheriwse you can set it manually:
+
+```ruby
+HomographicSpoofing.logger = Logger.new("log/homographic_spoofing.log")
+```
+
+## Usage
+
+### IDN
+
+[What is an IDN](https://en.wikipedia.org/wiki/Internationalized_domain_name)
+
+**Check if an IDN is an homographic spoof**
+
+```ruby
+HomographicSpoofing.idn_spoof?("www.basecаmp.com")
+# => true, uses cyrillic 'а' instead of latin 'a'
+HomographicSpoofing.idn_spoof?("www.basecamp.com")
+# => false
+```
+
+**Sanitize an IDN**
+
+The library can also sanitize an IDN by converting all confusable characters to their punycode representation.
+
+```ruby
+HomographicSpoofing.sanitize_idn("www.basecаmp.com")
+# => "www.xn--basecmp-6fg.com"
+HomographicSpoofing.sanitize_idn("www.basecamp.com")
+# => "www.basecamp.com"
+```
+
+### Email addresses
+
+An email address is formed from three main parts:
+
+"Jacopo Beschi" <<jacopo.beschi@basecamp.com>>
+
+- The domain-part is "basecamp.com"
+- The local-part is "jacopo.beschi"
+- The quoted-string-part is "Jacopo Beschi"
+
+**Check if an email_address is an homographic spoof**
+
+```ruby
+HomographicSpoofing.email_address_spoof?(%{"Jacopo Beschi" <jacopo.beschi@basecаmp.com>})
+# => true, uses cyrillic 'а' instead of latin 'a'
+```
+
+**Sanitize an email_address**
+
+```ruby
+>> HomographicSpoofing.sanitize_email_address(%{"Jacopo Beschi" <jacopo.beschi@basecаmp.com>})
+# => "\"Jacopo Beschi\" <jacopo.beschi@xn--basecmp-6fg.com>"
+```
+
+**Check if an email_address local-part is an homographic spoof**
+
+```ruby
+HomographicSpoofing.email_local_spoof?("jacopo.beschi")
+# => false
+```
+
+**Check if an email_address quoted-string-part is an homographic spoof**
+
+```ruby
+HomographicSpoofing.email_name_spoof?("Jacopo Beschi")
+# => false
+```
+
+**Sanitize an email_address quoted-string-part**
+
+```ruby
+HomographicSpoofing.sanitize_email_name("Jacopo Beschi")
+# => "Jacopo Beschi"
+```
+
+## Development
+
+To experiment, start the console with `bin/console`.
+Run the test via `bin/test`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/basecamp/homographic_spoofing.
+
+## License
+
+The IDN spoof detection algorithms are inspired by Chromium's [spoof_check](https://source.chromium.org/chromium/chromium/src/+/main:components/url_formatter/spoof_checks/) source code.
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/homographic_spoofing/detector/base.rb

@@ -0,0 +1,41 @@
+class HomographicSpoofing::Detector::Base
+  def self.detected?(label)
+    new(label).detected?
+  end
+
+  def self.detections(label)
+    new(label).detections
+  end
+
+  def initialize(label)
+    @label = label
+  end
+
+  def detected?
+    detections.any?
+  end
+
+  def detections
+    rules.select(&:attack_detected?).map do |rule|
+      HomographicSpoofing::Detector::Detection.new(rule.reason, rule.label)
+    end
+  rescue Encoding::CompatibilityError
+    # String must be in Unicode.
+    [ HomographicSpoofing::Detector::Detection.new("invalid_unicode", label) ]
+  end
+
+  private
+    attr_reader :label
+
+    def rules
+      @rules ||= rule_classes.map { |klass| klass.new(context) }
+    end
+
+    def rule_classes
+      raise NotImplementedError, "subclasses must override this"
+    end
+
+    def context
+      @context ||= HomographicSpoofing::Detector::Rule::Context.new(label:)
+    end
+end

data/lib/homographic_spoofing/detector/detection.rb

@@ -0,0 +1,2 @@
+class HomographicSpoofing::Detector::Detection < Struct.new(:reason, :label)
+end

data/lib/homographic_spoofing/detector/email_address.rb

@@ -0,0 +1,40 @@
+class HomographicSpoofing::Detector::EmailAddress
+  def self.detected?(email_address)
+    new(email_address).detected?
+  end
+
+  def self.detections(email_address)
+    new(email_address).detections
+  end
+
+  def initialize(email_address)
+    @email_address = email_address
+  end
+
+  def detected?
+    detections.any?
+  end
+
+  def detections
+    mail_address = mail_address_wrap(email_address)
+    [].tap do |result|
+      result.concat detector_for(part: mail_address.name,   type: "quoted_string").detections if mail_address.name
+      result.concat detector_for(part: mail_address.local,  type: "local").detections if mail_address.local
+      result.concat detector_for(part: mail_address.domain, type: "idn").detections if mail_address.domain
+    end
+  rescue Mail::Field::FieldError
+    # Do not analyse invalid email addresses.
+    []
+  end
+
+  private
+    attr_reader :email_address
+
+    def detector_for(type:, part:)
+      "HomographicSpoofing::Detector::#{type.camelize}".constantize.new(part)
+    end
+
+    def mail_address_wrap(email_address)
+      email_address.is_a?(Mail::Address) ? email_address : Mail::Address.new(email_address)
+    end
+end

data/lib/homographic_spoofing/detector/idn.rb

@@ -0,0 +1,78 @@
+# Detects IDN Spoofing homographic attacks (See https://en.wikipedia.org/wiki/IDN_homograph_attack).
+#
+# The implementation follows Google Chrome IDN policy
+# (See https://chromium.googlesource.com/chromium/src.git/+/master/docs/idn.md#google-chrome_s-idn-policy)
+# but with some limitations:
+#  - It doesn't rely on ICU4C uspoof.h (https://unicode-org.github.io/icu-docs/apidoc/released/icu4c/uspoof_8h.html)
+#    hence the script confusable detection is not as precise.
+#  - It doesn't implement 13. of Google IDN policy.
+class HomographicSpoofing::Detector::Idn
+  def self.detected?(domain)
+    new(domain).detected?
+  end
+
+  def self.detections(domain)
+    new(domain).detections
+  end
+
+  def initialize(domain)
+    @domain = domain.downcase
+  end
+
+  def detected?
+    detections.any?
+  end
+
+  def detections
+    rules.select(&:attack_detected?).map do |rule|
+      HomographicSpoofing::Detector::Detection.new(rule.reason, rule.label)
+    end
+  rescue PublicSuffix::Error
+    # Invalid IDN is a spoof.
+    [ HomographicSpoofing::Detector::Detection.new("invalid_domain", domain) ]
+  end
+
+  private
+    attr_reader :domain
+
+    def rules
+      @rules ||= contexts.flat_map { |ctx| rules_for(ctx) }
+    end
+
+    def rules_for(context)
+      [
+        HomographicSpoofing::Detector::Rule::DisallowedCharacters,
+        HomographicSpoofing::Detector::Rule::MixedScripts,
+        HomographicSpoofing::Detector::Rule::MixedDigits,
+        HomographicSpoofing::Detector::Rule::Idn::InvisibleCharacters,
+        HomographicSpoofing::Detector::Rule::Idn::UnsafeMiddleDot,
+        HomographicSpoofing::Detector::Rule::Idn::ScriptConfusable,
+        HomographicSpoofing::Detector::Rule::Idn::Digits,
+        HomographicSpoofing::Detector::Rule::Idn::DangerousPattern,
+        HomographicSpoofing::Detector::Rule::Idn::ScriptSpecific,
+        HomographicSpoofing::Detector::Rule::Idn::DeviationCharacters
+      ].map { |klass| klass.new(context) }
+    end
+
+    def contexts
+      [ public_suffix.sld, public_suffix.trd ].compact.map do |label|
+        HomographicSpoofing::Detector::Rule::Idn::Context.new(label: label, tld: public_suffix.tld)
+      end
+    end
+
+    def public_suffix
+      @public_suffix ||= icann_domain || non_icann_domain
+    end
+
+    def icann_domain
+      PublicSuffix.parse(domain, ignore_private: true) if PublicSuffix.valid?(domain)
+    end
+
+    def non_icann_domain
+      if PublicSuffix::List.default.find(domain, default: nil, ignore_private: true).present?
+        PublicSuffix::Domain.new(domain)
+      else
+        raise PublicSuffix::DomainInvalid
+      end
+    end
+end

data/lib/homographic_spoofing/detector/local.rb

@@ -0,0 +1,14 @@
+# Detects spoofing homographic attacks for the Local-Part of an email address.
+#
+# The implementation strictly follows Unicode guidelines for Email Security Profiles for Identifiers.
+#
+# See http://www.unicode.org/reports/tr39/#Email_Security_Profiles.
+class HomographicSpoofing::Detector::Local < HomographicSpoofing::Detector::Base
+  private
+    def rule_classes
+      [ HomographicSpoofing::Detector::Rule::Local::Nfkc,
+        HomographicSpoofing::Detector::Rule::MixedScripts,
+        HomographicSpoofing::Detector::Rule::MixedDigits,
+        HomographicSpoofing::Detector::Rule::Local::DotAtomText ]
+    end
+end

data/lib/homographic_spoofing/detector/quoted_string.rb

@@ -0,0 +1,13 @@
+# Detects spoofing homographic attacks for the Quoted-String-Part of an email address.
+#
+# The implementation strictly follows Unicode guidelines for Email Security Profiles for Identifiers.
+#
+# See http://www.unicode.org/reports/tr39/#Email_Security_Profiles.
+class HomographicSpoofing::Detector::QuotedString < HomographicSpoofing::Detector::Base
+  private
+    def rule_classes
+      [ HomographicSpoofing::Detector::Rule::QuotedString::Nfc,
+        HomographicSpoofing::Detector::Rule::QuotedString::BidiControl,
+        HomographicSpoofing::Detector::Rule::QuotedString::NonspacingMarks ]
+    end
+end

data/lib/homographic_spoofing/detector/rule/base.rb

@@ -0,0 +1,15 @@
+class HomographicSpoofing::Detector::Rule::Base
+  delegate :scripts, :label, :label_set, to: :@context
+
+  def initialize(context)
+    @context = context
+  end
+
+  def attack_detected?
+    raise NotImplementedError, "subclasses must override this"
+  end
+
+  def reason
+    self.class.name.demodulize.underscore
+  end
+end

data/lib/homographic_spoofing/detector/rule/context.rb

@@ -0,0 +1,19 @@
+class HomographicSpoofing::Detector::Rule::Context
+  attr_reader :label
+
+  def initialize(label:)
+    @label = label
+  end
+
+  SCRIPT_COMMON = "Common"
+  SCRIPT_INHERITED = "Inherited"
+  IGNORED_SCRIPTS = Set[SCRIPT_COMMON, SCRIPT_INHERITED]
+
+  def scripts
+    @scripts ||= Unicode::Scripts.scripts(label).to_set - IGNORED_SCRIPTS
+  end
+
+  def label_set
+    @label_set ||= label.chars.to_set
+  end
+end