zxcvbn-ruby 0.1.0 → 1.2.0

data/lib/zxcvbn/entropy.rb

@@ -129,7 +129,7 @@ module Zxcvbn::Entropy
 
     # estimate the ngpumber of possible patterns w/ token length or less with number of turns or less.
     (2..token_length).each do |i|
-      possible_turns = [turns, i -1].min
+      possible_turns = [turns, i - 1].min
       (1..possible_turns).each do |j|
         possibilities += nCk(i - 1, j - 1) * starting_positions * average_degree ** j
       end

data/lib/zxcvbn/feedback.rb

@@ -0,0 +1,10 @@
+module Zxcvbn
+  class Feedback
+    attr_accessor :warning, :suggestions
+
+    def initialize(options = {})
+      @warning     = options[:warning]
+      @suggestions = options[:suggestions] || []
+    end
+  end
+end

data/lib/zxcvbn/feedback_giver.rb

@@ -0,0 +1,133 @@
+require 'zxcvbn/entropy'
+require 'zxcvbn/feedback'
+
+module Zxcvbn
+  class FeedbackGiver
+    NAME_DICTIONARIES = %w[surnames male_names female_names].freeze
+
+    DEFAULT_FEEDBACK = Feedback.new(
+      suggestions: [
+        'Use a few words, avoid common phrases',
+        'No need for symbols, digits, or uppercase letters'
+      ]
+    ).freeze
+
+    EMPTY_FEEDBACK = Feedback.new.freeze
+
+    def self.get_feedback(score, sequence)
+      # starting feedback
+      return DEFAULT_FEEDBACK if sequence.length.zero?
+
+      # no feedback if score is good or great.
+      return EMPTY_FEEDBACK if score > 2
+
+      # tie feedback to the longest match for longer sequences
+      longest_match = sequence[0]
+      for match in sequence[1..-1]
+        longest_match = match if match.token.length > longest_match.token.length
+      end
+
+      feedback = get_match_feedback(longest_match, sequence.length == 1)
+      extra_feedback = 'Add another word or two. Uncommon words are better.'
+
+      if feedback.nil?
+        feedback = Feedback.new(suggestions: [extra_feedback])
+      else
+        feedback.suggestions.unshift extra_feedback
+      end
+
+      feedback
+    end
+
+    def self.get_match_feedback(match, is_sole_match)
+      case match.pattern
+      when 'dictionary'
+        get_dictionary_match_feedback match, is_sole_match
+
+      when 'spatial'
+        layout = match.graph.upcase
+        warning = if match.turns == 1
+                    'Straight rows of keys are easy to guess'
+                  else
+                    'Short keyboard patterns are easy to guess'
+                  end
+
+        Feedback.new(
+          warning: warning,
+          suggestions: [
+            'Use a longer keyboard pattern with more turns'
+          ]
+        )
+
+      when 'repeat'
+        Feedback.new(
+          warning: 'Repeats like "aaa" are easy to guess',
+          suggestions: [
+            'Avoid repeated words and characters'
+          ]
+        )
+
+      when 'sequence'
+        Feedback.new(
+          warning: 'Sequences like abc or 6543 are easy to guess',
+          suggestions: [
+            'Avoid sequences'
+          ]
+        )
+
+      when 'date'
+        Feedback.new(
+          warning: 'Dates are often easy to guess',
+          suggestions: [
+            'Avoid dates and years that are associated with you'
+          ]
+        )
+      end
+    end
+
+    def self.get_dictionary_match_feedback(match, is_sole_match)
+      warning = if match.dictionary_name == 'passwords'
+                  if is_sole_match && !match.l33t && !match.reversed
+                    if match.rank <= 10
+                      'This is a top-10 common password'
+                    elsif match.rank <= 100
+                      'This is a top-100 common password'
+                    else
+                      'This is a very common password'
+                    end
+                  else
+                    'This is similar to a commonly used password'
+                  end
+                elsif NAME_DICTIONARIES.include? match.dictionary_name
+                  if is_sole_match
+                    'Names and surnames by themselves are easy to guess'
+                  else
+                    'Common names and surnames are easy to guess'
+                  end
+                end
+
+      suggestions = []
+      word = match.token
+
+      if word =~ Zxcvbn::Entropy::START_UPPER
+        suggestions.push "Capitalization doesn't help very much"
+      elsif word =~ Zxcvbn::Entropy::ALL_UPPER && word.downcase != word
+        suggestions.push(
+          'All-uppercase is almost as easy to guess as all-lowercase'
+        )
+      end
+
+      if match.l33t
+        suggestions.push(
+          "Predictable substitutions like '@' instead of 'a' \
+don't help very much"
+        )
+      end
+
+      Feedback.new(
+        warning: warning,
+        suggestions: suggestions
+      )
+    end
+  end
+end

data/lib/zxcvbn/matchers/l33t.rb

@@ -31,8 +31,8 @@ module Zxcvbn
               token = password[match.i..match.j]
               next if token.downcase == match.matched_word.downcase
               match_substitutions = {}
-              substitution.each do |substitution, letter|
-                match_substitutions[substitution] = letter if token.include?(substitution)
+              substitution.each do |s, letter|
+                match_substitutions[s] = letter if token.include?(s)
               end
               match.l33t = true
               match.token = password[match.i..match.j]

data/lib/zxcvbn/password_strength.rb

@@ -1,4 +1,5 @@
 require 'benchmark'
+require 'zxcvbn/feedback_giver'
 require 'zxcvbn/omnimatch'
 require 'zxcvbn/scorer'
 
@@ -17,6 +18,7 @@ module Zxcvbn
         result = @scorer.minimum_entropy_match_sequence(password, matches)
       end
       result.calc_time = calc_time
+      result.feedback = FeedbackGiver.get_feedback(result.score, result.match_sequence)
       result
     end
   end

data/lib/zxcvbn/score.rb

@@ -1,7 +1,7 @@
 module Zxcvbn
   class Score
     attr_accessor :entropy, :crack_time, :crack_time_display, :score, :pattern,
-                  :match_sequence, :password, :calc_time
+                  :match_sequence, :password, :calc_time, :feedback
 
     def initialize(options = {})
       @entropy            = options[:entropy]

data/lib/zxcvbn/tester.rb

@@ -1,5 +1,7 @@
-require 'zxcvbn/data'
-require 'zxcvbn/password_strength'
+# frozen_string_literal: true
+
+require "zxcvbn/data"
+require "zxcvbn/password_strength"
 
 module Zxcvbn
   # Allows you to test the strength of multiple passwords without reading and
@@ -21,15 +23,21 @@ module Zxcvbn
     end
 
     def test(password, user_inputs = [])
-      PasswordStrength.new(@data).test(password, user_inputs)
+      PasswordStrength.new(@data).test(password, sanitize(user_inputs))
     end
 
     def add_word_lists(lists)
-      lists.each_pair {|name, words| @data.add_word_list(name, words)}
+      lists.each_pair { |name, words| @data.add_word_list(name, sanitize(words)) }
     end
 
     def inspect
-      "#<#{self.class}:0x#{self.__id__.to_s(16)}>"
+      "#<#{self.class}:0x#{__id__.to_s(16)}>"
+    end
+
+    private
+
+    def sanitize(user_inputs)
+      user_inputs.select { |i| i.respond_to?(:downcase) }
     end
   end
 end

data/lib/zxcvbn/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Zxcvbn
-  VERSION = "0.1.0"
+  VERSION = '1.2.0'
 end

data/spec/dictionary_ranker_spec.rb

@@ -5,8 +5,8 @@ describe Zxcvbn::DictionaryRanker do
     it 'ranks word lists' do
       result = Zxcvbn::DictionaryRanker.rank_dictionaries({:test => ['ABC', 'def'],
                                                            :test2 => ['def', 'ABC']})
-      result[:test].should eq({'abc' => 1, 'def' => 2})
-      result[:test2].should eq({'def' => 1, 'abc' => 2})
+      expect(result[:test]).to eq({'abc' => 1, 'def' => 2})
+      expect(result[:test2]).to eq({'def' => 1, 'abc' => 2})
     end
   end
 end

data/spec/feedback_giver_spec.rb

@@ -0,0 +1,212 @@
+require 'spec_helper'
+
+describe Zxcvbn::FeedbackGiver do
+  # NOTE: We go in via the tester because the `FeedbackGiver` relies on both
+  #       Omnimatch and the Scorer, which are troublesome to wire up for tests
+  let(:tester) { Zxcvbn::Tester.new }
+
+  describe '.get_feedback' do
+    it "gives empty feedback when a password's score is good" do
+      feedback = tester.test('5815A30BE798').feedback
+
+      expect(feedback).to be_a Zxcvbn::Feedback
+      expect(feedback.warning).to be_nil
+      expect(feedback.suggestions).to be_empty
+    end
+
+    it 'gives general feedback when a password is empty' do
+      feedback = tester.test('').feedback
+
+      expect(feedback).to be_a Zxcvbn::Feedback
+      expect(feedback.warning).to be_nil
+      expect(feedback.suggestions).to contain_exactly(
+        'Use a few words, avoid common phrases',
+        'No need for symbols, digits, or uppercase letters'
+      )
+    end
+
+    it "gives general feedback when a password is poor but doesn't match any heuristics" do
+      feedback = tester.test(':005:0').feedback
+
+      expect(feedback).to be_a Zxcvbn::Feedback
+      expect(feedback.warning).to be_nil
+      expect(feedback.suggestions).to contain_exactly(
+        'Add another word or two. Uncommon words are better.'
+      )
+    end
+
+    describe 'gives specific feedback' do
+      describe 'for dictionary passwords' do
+        it 'that are extremely common' do
+          feedback = tester.test('password').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql('This is a top-10 common password')
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+        end
+
+        it 'that are very, very common' do
+          feedback = tester.test('letmein').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql('This is a top-100 common password')
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+        end
+
+        it 'that are very common' do
+          feedback = tester.test('playstation').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql('This is a very common password')
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+        end
+
+        it 'that are common and you tried to use l33tsp33k' do
+          feedback = tester.test('pl4yst4ti0n').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'This is similar to a commonly used password'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.',
+            "Predictable substitutions like '@' instead of 'a' don't help very much"
+          )
+        end
+
+        it 'that are common and you capitalised the start' do
+          feedback = tester.test('Password').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'This is a top-10 common password'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.',
+            "Capitalization doesn't help very much"
+          )
+        end
+
+        it 'that are common and you capitalised the whole thing' do
+          feedback = tester.test('PASSWORD').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'This is a top-10 common password'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.',
+            'All-uppercase is almost as easy to guess as all-lowercase'
+          )
+        end
+
+        it 'that contain a common first name or last name' do
+          feedback = tester.test('jessica').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'Names and surnames by themselves are easy to guess'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+
+          feedback = tester.test('smith').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'Names and surnames by themselves are easy to guess'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+        end
+
+        it 'that contain a common name and surname' do
+          feedback = tester.test('jessica smith').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'Common names and surnames are easy to guess'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.'
+          )
+        end
+      end
+
+      describe 'for spatial passwords' do
+        it 'that contain a straight keyboard row' do
+          feedback = tester.test('1qaz').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'Straight rows of keys are easy to guess'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.',
+            'Use a longer keyboard pattern with more turns'
+          )
+        end
+
+        it 'that contain a keyboard pattern with one turn' do
+          feedback = tester.test('zaqwer').feedback
+
+          expect(feedback).to be_a Zxcvbn::Feedback
+          expect(feedback.warning).to eql(
+            'Short keyboard patterns are easy to guess'
+          )
+          expect(feedback.suggestions).to contain_exactly(
+            'Add another word or two. Uncommon words are better.',
+            'Use a longer keyboard pattern with more turns'
+          )
+        end
+      end
+
+      it 'for passwords with repeated characters' do
+        feedback = tester.test('zzz').feedback
+
+        expect(feedback).to be_a Zxcvbn::Feedback
+        expect(feedback.warning).to eql(
+          'Repeats like "aaa" are easy to guess'
+        )
+        expect(feedback.suggestions).to contain_exactly(
+          'Add another word or two. Uncommon words are better.',
+          'Avoid repeated words and characters'
+        )
+      end
+
+      it 'for passwords with sequential characters' do
+        feedback = tester.test('pqrpqrpqr').feedback
+
+        expect(feedback).to be_a Zxcvbn::Feedback
+        expect(feedback.warning).to eql(
+          'Sequences like abc or 6543 are easy to guess'
+        )
+        expect(feedback.suggestions).to contain_exactly(
+          'Add another word or two. Uncommon words are better.',
+          'Avoid sequences'
+        )
+      end
+
+      it 'for passwords containing dates' do
+        feedback = tester.test('testing02\12\1997').feedback
+
+        expect(feedback).to be_a Zxcvbn::Feedback
+        expect(feedback.warning).to eql(
+          'Dates are often easy to guess'
+        )
+        expect(feedback.suggestions).to contain_exactly(
+          'Add another word or two. Uncommon words are better.',
+          'Avoid dates and years that are associated with you'
+        )
+      end
+    end
+  end
+end