The project is in a healthy, maintained state
A toolkit to both detect and sanitize homographic spoofing attacks in URLs and Email addresses
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

HomographicSpoofing

Toolkit to both detect and sanitize homographic spoofing attacks in URLs and Email addresses.

Installation

Add this line to your application's Gemfile:

gem "homographic_spoofing"

And then execute:

$ bundle

Or install it yourself as:

$ 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:

HomographicSpoofing.logger = Logger.new("log/homographic_spoofing.log")

Usage

IDN

What is an IDN

Check if an IDN is an homographic spoof

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.

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

HomographicSpoofing.email_address_spoof?(%{"Jacopo Beschi" <jacopo.beschi@basecаmp.com>})
# => true, uses cyrillic 'а' instead of latin 'a'

Sanitize an email_address

>> 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

HomographicSpoofing.email_local_spoof?("jacopo.beschi")
# => false

Check if an email_address quoted-string-part is an homographic spoof

HomographicSpoofing.email_name_spoof?("Jacopo Beschi")
# => false

Sanitize an email_address quoted-string-part

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 source code.

The gem is available as open source under the terms of the MIT License.