formigarafa / zxcvbn-rb

Low-Budget Password Strength Estimation written in Ruby

Zxcvbn

Ruby port of Dropbox's zxcvbn.js JavaScript library running completely in Ruby (no need to load execjs or libv8).

Goals:

• Exact same results as dropbox/zxcvbn.js (Version 4.4.2). If result compatibility is found or made different a major version will be bumped so no one is caught off guard.
• Parity of features to dropbox/zxcvbn.js (Version 4.4.2) interface.
• 100% native Ruby solution: No Javascript Runtime.

Compatible with zxcvbn-js and zxcvbn-ruby

This gem include compatibility interfaces so it can be used as a drop-in substitution both of the most popular alternatives zxcvbn-js and zxcvbn-ruby). Besides Zxcvbn.zxcvbn you can just call Zxcvbn.test or use Zxcvbn::Tester.new the same way as you would if you were using any of them.

	zxcvbn-rb	zxcvbn-js	zxcvbn-ruby
Results match zxcvbn.js (V4.4.2)	✅ yes	✅ yes	❌ no
Run without Javascript Runtime	✅ yes	❌ no	✅ yes
Interface compatibility with others	✅ yes	❌ no	❌ no

Installation

Add this line to your application's Gemfile:

gem 'zxcvbn'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install zxcvbn

Usage

Zxcvbn.zxcvbn("password")
=> {
  "password" => "password",
  "guesses" => 3,
  "guesses_log10" => 0.47712125471966244,
  "sequence" => [
    {
      "pattern" => "dictionary",
      "i" => 0,
      "j" => 7,
      "token" => "password",
      "matched_word" => "password",
      "rank" => 2,
      "dictionary_name" => "passwords",
      "reversed" => false,
      "l33t" => false,
      "base_guesses" => 2,
      "uppercase_variations" => 1,
      "l33t_variations" => 1,
      "guesses" => 2,
      "guesses_log10" => 0.3010299956639812
    }
  ],
  "calc_time" => 1,
  "crack_times_seconds" => {
    "online_throttling_100_per_hour" => 108.0,
    "online_no_throttling_10_per_second" => 0.3,
    "offline_slow_hashing_1e4_per_second" => 0.0003,
    "offline_fast_hashing_1e10_per_second" => 3.0e-10},
  "crack_times_display" => {
    "online_throttling_100_per_hour" => "2 minutes",
    "online_no_throttling_10_per_second" => "less than a second",
    "offline_slow_hashing_1e4_per_second" => "less than a second",
    "offline_fast_hashing_1e10_per_second" => "less than a second"
  },
  "score" => 0,
  "feedback" => {
    "warning" => "This is a top-10 common password",
    "suggestions" => [
      "Add another word or two. Uncommon words are better."
    ]
  }
}

Note about translations (i18n, gettext, etc...)

Check the wiki for more details on how to handle translations.

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.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/formigarafa/zxcvbn-rb. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

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

Code of Conduct

Everyone interacting in the Zxcvbn project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

zxcvbn-rb's Issues

Thread safety issue

Hi there, and thanks for building this gem. It's great to have something in native Ruby that's fully compatible with the JS version!

It seems that the gem isn't currently thread-safe. Specifically, mutating the constant Matching::RANKED_DICTIONARIES in

zxcvbn-rb/lib/zxcvbn/matching.rb

Lines 198 to 202 in 024828e

	def self.user_input_dictionary=(ordered_list)
	ranked_dict = build_ranked_dict(ordered_list.dup)
	RANKED_DICTIONARIES["user_inputs"] = ranked_dict
	RANKED_DICTIONARIES_MAX_WORD_SIZE["user_inputs"] = ranked_dict.keys.max_by(&:size)&.size || 0
	end

which is called from https://github.com/formigarafa/zxcvbn-rb/blob/master/lib/zxcvbn.rb#L21 can result in RANKED_DICTIONARIES containing data for a different thread if 2 threads call zxcvbn in parallel.

This is only an issue when the user_inputs argument to Zxcvbn.zxcvbn() is used. When it's always the default value of [], then it won't matter.

I'm guessing this comes from the original JS code, which isn't concerned about multi-thread access while running in a browser.

My first thought would be to rework parts of Matching to no longer be a singleton, so that @user_inputs could be stored separately per caller. Alternatively, the call to Zxcvbn.zxcvbn() itself can be wrapped with a Mutex (which is also a viable workaround for the existing gem version).

Translation of feedback messages

What is the standard approach for translating the feedback messages? Apart from forking and editing the source file lib/zxcvbn/feedback.rb.

Also, are PR submissions accepted for this? We prefer the gettext syntax, although I18n would work too (although a new gem dependency is apparently required in both cases).

P.S. Thanks for this ruby port.

[Solved] Known issues to tackle (Matching results JS vs Ruby)

List of passwords known to be a challenge to match results from js library.

• bitzesty/devise_zxcvbn#11

  • qwER43@!
  • Obama!123

• envato/zxcvbn-ruby#18

  • chenlu0525
  • rtrtrt
  • rtrtrtrt
  • rtrtrtrtrt
  • my_new_password

• bitzesty/devise_zxcvbn#11

  • qwER43@!
  • Obama!123

• envato/zxcvbn-ruby#27

  • vika20021994

Spaces on password: limitation on original dropbox zxcvbn implementation

I saw a reference to dropbox/zxcvbn#227 here: https://github.com/18F/identity-idp/blob/main/spec/support/shared_examples/password_strength.rb#L46 which made me curious.

It seem the js source lib have an annoying limitation when the password being checked include spaces.

Annoying only be the fact they no longer update (or publish updates for) it.

I am wondering what can I do to improve the results without breaking compatibility.

DOS Exploit

Hey, just wanted to let you know I've gotten reports from users of my library: Nbvcxz that are getting a DOS every so often by specifically crafted passwords.

I found a tool created by a government contractor used for issuing a DOS against programs using libraries containing the vulnerable (to combination explosion) algorithms from the original zxcvbn implementation:

• https://github.com/twosixlabs/acsploit
• GoSimpleLLC/nbvcxz#60

I've solved this by implementing a maxLength type configuration...but that isn't totally done yet as I feel like I still need to have it do dictionary checks against the full-length password without any transformations. Working on finishing that feature and putting out a release. I just wanted to mention it to you, since this is also often run server-side rather than client-side.