zxcvbn-ruby

1.2.0last stable release 4 years ago
Complexity Score
High
Open Issues
2
Dependent Projects
6
Weekly Downloadsglobal
42

License

  • MIT
    • Yesattribution
    • Permissivelinking
    • Permissivedistribution
    • Permissivemodification
    • Nopatent grant
    • Yesprivate use
    • Permissivesublicensing
    • Notrademark grant

Downloads

Readme

zxcvbn-ruby

This is a Ruby port of Dropbox’s zxcvbn.js JavaScript library.

Development status

zxcvbn-ruby is considered stable and is used in projects around Envato.

After checking out the repository, run bundle install to install dependencies. Then, run rake spec to run the tests.

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 tags, and push the .gem file to rubygems.org.

Getting started

Add the following to your project’s Gemfile:

gem 'zxcvbn-ruby', require: 'zxcvbn'

Example usage:

$ irb
>> require 'zxcvbn'
=> true
>> pp Zxcvbn.test('@lfred2004', ['alfred'])
#<Zxcvbn::Score:0x00007f7f590610c8
 @calc_time=0.0055760000250302255,
 @crack_time=0.012,
 @crack_time_display="instant",
 @entropy=7.895,
 @feedback=
  #<Zxcvbn::Feedback:0x00007f7f59060150
   @suggestions=
    ["Add another word or two. Uncommon words are better.",
     "Predictable substitutions like '@' instead of 'a' don't help very much"],
   @warning=nil>,
 @match_sequence=
  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
 @password="@lfred2004",
 @score=0>
=> #<Zxcvbn::Score:0x00007f7f59060150>
>> pp Zxcvbn.test('asdfghju7654rewq', ['alfred'])
#<Zxcvbn::Score:0x00007f7f5a9e9248
 @calc_time=0.007504999986849725,
 @crack_time=46159.451,
 @crack_time_display="14 hours",
 @entropy=29.782,
 @feedback=
  #<Zxcvbn::Feedback:0x00007f7f5a9e9130
   @suggestions=
    ["Add another word or two. Uncommon words are better.",
     "Use a longer keyboard pattern with more turns"],
   @warning="Short keyboard patterns are easy to guess">,
 @match_sequence=
  [#<Zxcvbn::Match pattern="spatial", i=0, j=15, token="asdfghju7654rewq", graph="qwerty", turns=5, shifted_count=0, entropy=29.7820508329166>],
 @password="asdfghju7654rewq",
 @score=2>
=> #<Zxcvbn::Score:0x00007f7f5a9e9248>

Testing Multiple Passwords

The dictionaries used for password strength testing are loaded each request to Zxcvbn.test. If you you’d prefer to persist the dictionaries in memory (approx 20MB RSS) to perform lots of password tests in succession then you can use the Zxcvbn::Tester API:

$ irb
>> require 'zxcvbn'
=> true
>> tester = Zxcvbn::Tester.new
=> #<Zxcvbn::Tester:0x3fe99d869aa4>
>> pp tester.test('@lfred2004', ['alfred'])
#<Zxcvbn::Score:0x00007f7f586fcf50
 @calc_time=0.00631899997824803,
 @crack_time=0.012,
 @crack_time_display="instant",
 @entropy=7.895,
 @feedback=
  #<Zxcvbn::Feedback:0x00007f7f586fcac8
   @suggestions=
    ["Add another word or two. Uncommon words are better.",
     "Predictable substitutions like '@' instead of 'a' don't help very much"],
   @warning=nil>,
 @match_sequence=
  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
 @password="@lfred2004",
 @score=0>
=> #<Zxcvbn::Score:0x00007f7f586fcf50>
>> pp tester.test('@lfred2004', ['alfred'])
#<Zxcvbn::Score:0x00007f7f56d57438
 @calc_time=0.001986999996006489,
 @crack_time=0.012,
 @crack_time_display="instant",
 @entropy=7.895,
 @feedback=
  #<Zxcvbn::Feedback:0x00007f7f56d56bf0
   @suggestions=
    ["Add another word or two. Uncommon words are better.",
     "Predictable substitutions like '@' instead of 'a' don't help very much"],
   @warning=nil>,
 @match_sequence=
  [#<Zxcvbn::Match matched_word="alfred", token="@lfred", i=0, j=5, rank=1, pattern="dictionary", dictionary_name="user_inputs", l33t=true, sub={"@"=>"a"}, sub_display="@ -> a", base_entropy=0.0, uppercase_entropy=0.0, l33t_entropy=1, entropy=1.0>,
   #<Zxcvbn::Match i=6, j=9, token="2004", pattern="year", entropy=6.894817763307944>],
 @password="@lfred2004",
 @score=0>
=> #<Zxcvbn::Score:0x00007f7f56d57438>

Note: Storing the entropy of an encrypted or hashed value provides information that can make cracking the value orders of magnitude easier for an attacker. For this reason we advise you not to store the results of Zxcvbn::Tester#test. Further reading: A Tale of Security Gone Wrong.

Contact

  • GitHub project
  • Bug reports and feature requests are welcome via GitHub Issues

Maintainers

  • Pete Johns
  • Steve Hodgkiss

Authors

  • Steve Hodgkiss
  • Matthieu Aussaguel
  • et al.

License

zxcvbn-ruby uses MIT license, the same as zxcvbn.js itself. See LICENSE.txt for details.

Code of Conduct

We welcome contribution from everyone. Read more about it in CODE_OF_CONDUCT.md.

Contributing

For bug fixes, documentation changes, and features:

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

For larger new features: Do everything as above, but first also make contact with the project maintainers to be sure your change fits with the project direction and you won’t be wasting effort going in the wrong direction.

About

This project is maintained by the Envato engineering team and funded by Envato.

Encouraging the use and creation of open source software is one of the ways we serve our community. See our other projects or come work with us where you’ll find an incredibly diverse, intelligent and capable group of people who help make our company succeed and make our workplace fun, friendly and happy.

Dependencies

No runtime dependency information found for this package.

CVE IssuesActive
0
Scorecards Score
4.60
Test Coverage
No Data
Follows Semver
Yes
Github Stars
314
Dependenciestotal
2
DependenciesOutdated
0
DependenciesDeprecated
0
Threat Modelling
No
Repo Audits
No

Learn how to distribute zxcvbn-ruby in your own private RubyGems registry

gem install zxcvbn-ruby
Processing...
Done

9 Releases

RubyGems on Cloudsmith

Getting started with RubyGems on Cloudsmith is fast and easy.