Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
Z

zxcvbn-ruby

> 编程语言
Open source

Ruby port of Dropbox's zxcvbn javascript lib

352 stars0 likes2 views
WebsiteGitHub

About

Ruby port of Dropbox's zxcvbn javascript lib

zxcvbn-ruby

This is a Ruby port of Dropbox's zxcvbn.js JavaScript password strength estimator, providing zxcvbn.js v4 compatibility.

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:

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

Example usage:

…

Custom Testers

Zxcvbn.test reuses a shared Tester internally — dictionaries are loaded once and persist in memory. Use Zxcvbn.tester_builder.build to construct a standalone Tester you control:

…

To add custom word lists, chain add_word_list before build:

ruby
>> tester = Zxcvbn.tester_builder.add_word_list('company', %w[acme corp]).build
=> #
>> tester.test('acme').score
=> 0

Subsequent calls reuse the already-loaded dictionaries, so calc_time is significantly lower:

ruby
>> tester.test('@lfred2004', ['alfred']).calc_time
=> 0.0005759999621659517

[!WARNING] Scoring time grows with password length. For adversarial inputs such as short repeated sequences (e.g. "ab" * 500), the internal pattern-matching DP produces super-quadratic runtime. Both Zxcvbn.test and Zxcvbn::Tester#test raise Zxcvbn::PasswordTooLong for passwords longer than 256 characters (the default). Override the limit with the ZXCVBN_MAX_PASSWORD_LENGTH environment variable, but be aware that raising it re-exposes this runtime risk. The user_inputs parameter is not length-bounded; apply your own limit to those values.

[!WARNING] Storing the guesses or score for 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.

Limitations

The frequency lists bundled with this gem are English-only: English Wikipedia, US TV & film, English-derived names, and English-language password leaks. Passwords built from non-English words (e.g. "รหัสผ่าน", Thai for "password") are scored against bruteforce rather than a localised dictionary, so their score will often be higher than the real-world risk warrants. If your users primarily choose passwords in a non-English language, treat the scores as a lower bound on strength, not an absolute measure.

Migrating from 1.x

Version 2 aligns with the zxcvbn.js v4 algorithm and API. Scores will change for many passwords — this is expected. The sections below cover every breaking API change.

Ruby version

Ruby 3.3 or later is required.

Score field changes

The following attributes have been removed and will raise NoMethodError. Use the 2.x equivalents below:

Removed (1.x) 2.x equivalent
result.entropy Math.log2(result.guesses) or result.guesses_log10 * Math.log2(10)
result.crack_time result.crack_times_seconds["online_no_throttling_10_per_second"] (see Attack scenarios)
result.crack_time_display result.crack_times_display["online_no_throttling_10_per_second"]
result.match_sequence result.sequence

1.x crack_time used 10 guesses/second (unthrottled online), corresponding to the "online_no_throttling_10_per_second" scenario. The entropy formula gives the same log-scale difficulty value, but the number will differ from 1.x because the underlying guessing algorithm has been rewritten.

Score is now an immutable value object. Attribute setters (calc_time=, feedback=, etc.) have been removed. Use result.with to create a modified copy — with returns a new frozen object:

ruby
# 1.x
result.calc_time = 0.001

# 2.x
result = result.with(calc_time: 0.001)

Attack scenarios

crack_times_seconds and crack_times_display are both hashes keyed by attack scenario:

ruby
result.crack_times_display
# => {
#   "online_throttling_100_per_hour"       => "6 days",
#   "online_no_throttling_10_per_second"   => "25 minutes",
#   "offline_slow_hashing_1e4_per_second"  => "2 seconds",
#   "offline_fast_hashing_1e10_per_second" => "less than a second"
# }

Match field changes

The following attributes have been removed and will raise NoMethodError. Use the 2.x equivalents below:

Removed (1.x) 2.x equivalent
match.entropy match.guesses_log10 * Math.log2(10)
match.base_entropy Math.log2(match.base_guesses) (dictionary matches only — base_guesses is nil for other patterns)
match.uppercase_entropy Math.log2(match.uppercase_variations) (dictionary matches only — uppercase_variations is nil for other patterns)
match.l33t_entropy Math.log2(match.l33t_variations) (dictionary matches only — l33t_variations is nil for other patterns)
match.repeated_char match.base_token (now supports multi-character repeating units e.g. "abcabc")
match.to_hash match.to_h — note: keys are now symbols (not strings), all 28 attributes are included (not just those that were set), and key order follows member definition rather than alphabetical. To replicate old behaviour: match.to_h.transform_keys(&:to_s).compact.sort.to_h

These translations give a log-scale difficulty value but are not numerically equivalent to 1.x — the underlying guess estimation formulas have been rewritten.

Match is now an immutable value object. Attribute setters have been removed. Use match.with(attr: value) to derive a modified copy. Any code that splatted a match (**match) or passed it to Hash() will now raise TypeError — use match.to_h explicitly instead.

Feedback changes

Feedback#warning now returns '' instead of nil when no warning applies. Update nil checks accordingly:

ruby
# 1.x
if result.feedback.warning
  show_warning(result.feedback.warning)
end

# 2.x
unless result.feedback.warning.empty?
  show_warning(result.feedback.warning)
end

Also update any || defaults on warning — '' is truthy so the fallback no longer fires:

ruby
# 1.x — worked because nil is falsy
label = result.feedback.warning || "No issues"

# 2.x
label = result.feedback.warning.empty? ? "No issues" : result.feedback.warning

The "This is similar to a commonly used password" warning is now only emitted when `match.guesses_log10 72 # bcrypt's 72-byte limit result = Zxcvbn.test(password)


To use a different limit for a specific tester without touching the environment:

```ruby
tester = Zxcvbn.tester_builder.max_password_length(128).build
result = tester.test(password)

To adjust the process-wide default, set ZXCVBN_MAX_PASSWORD_LENGTH in the process environment before the process starts:

bash
ZXCVBN_MAX_PASSWORD_LENGTH=1024 bundle exec rails server

The variable is read when TesterBuilder#build is called. For the shared tester backing Zxcvbn.test, that is the first call to Zxcvbn.test.

Or export it from your shell profile, process manager, or platform environment config (Heroku, Docker, etc.). Note that raising the limit re-exposes the super-quadratic runtime for adversarial inputs to the password argument.

Custom word lists

Tester#add_word_lists and the word_lists: argument to Zxcvbn.test have been removed. Use the Zxcvbn.tester_builder builder instead:

ruby
# 1.x — no longer works
result = Zxcvbn.test(password, user_inputs, word_lists: { 'company' => %w[acme corp] })
tester.add_word_lists('company' => %w[acme corp])

# 2.x
tester = Zxcvbn.tester_builder.add_word_list('company', %w[acme corp]).build
result = tester.test(password, user_inputs)

Zxcvbn::Tester.new is no longer a public construction path — it now requires data: and max_password_length: keyword arguments with no defaults. Use Zxcvbn.tester_builder.build (or the fluent builder) instead:

ruby
# 1.x
tester = Zxcvbn::Tester.new

# 2.x
tester = Zxcvbn.tester_builder.build

Score values will change

The scoring algorithm has been rewritten to match zxcvbn.js v4. It now minimises total guesses rather than entropy bits. Bruteforce cardinality is fixed at 10 regardless of the character classes in the password (previously 10–95 depending on which character classes were present). Scores (0–4) for many passwords will differ from 1.x — this is expected and intentional.

Audit any code that gates on result.score (e.g. form validation thresholds), persists scores in a database, or asserts on score values in tests — these will need review after upgrading.

Contact

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

Authors

  • Steve Hodgkiss
  • Matthieu Aussaguel
  • Orien Madgwick
  • 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. Perhaps 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.

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Ruby

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言