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