1|Build Status|
2
3zxcvbn
4======
5
6A realistic password strength estimator.
7
8This is a Python implementation of the library created by the team at Dropbox.
9The original library, written for JavaScript, can be found
10`here <https://github.com/dropbox/zxcvbn>`__.
11
12While there may be other Python ports available, this one is the most up
13to date and is recommended by the original developers of zxcvbn at this
14time.
15
16
17Features
18--------
19- **Tested in Python versions 2.7, 3.3-3.6**
20- Accepts user data to be added to the dictionaries that are tested against (name, birthdate, etc)
21- Gives a score to the password, from 0 (terrible) to 4 (great)
22- Provides feedback on the password and ways to improve it
23- Returns time estimates on how long it would take to guess the password in different situations
24
25Installation
26------------
27
28Install the package using pip: ``pip install zxcvbn``
29
30Usage
31-----
32
33Pass a password as the first parameter, and a list of user-provided
34inputs as the ``user_inputs`` parameter (optional).
35
36.. code:: python
37
38 from zxcvbn import zxcvbn
39
40 results = zxcvbn('JohnSmith123', user_inputs=['John', 'Smith'])
41
42 print(results)
43
44Output:
45
46::
47
48 {
49 'password': 'JohnSmith123',
50 'score': 2,
51 'guesses': 2567800,
52 'guesses_log10': 6.409561194521849,
53 'calc_time': datetime.timedelta(0, 0, 5204)
54 'feedback': {
55 'warning': '',
56 'suggestions': [
57 'Add another word or two. Uncommon words are better.',
58 "Capitalization doesn't help very much"
59 ]
60 },
61 'crack_times_display': {
62 'offline_fast_hashing_1e10_per_second': 'less than a second'
63 'offline_slow_hashing_1e4_per_second': '4 minutes',
64 'online_no_throttling_10_per_second': '3 days',
65 'online_throttling_100_per_hour': '3 years',
66 },
67 'crack_times_seconds': {
68 'offline_fast_hashing_1e10_per_second': 0.00025678,
69 'offline_slow_hashing_1e4_per_second': 256.78
70 'online_no_throttling_10_per_second': 256780.0,
71 'online_throttling_100_per_hour': 92440800.0,
72 },
73 'sequence': [{
74 'matched_word': 'john',
75 'rank': 2,
76 'pattern': 'dictionary',
77 'reversed': False,
78 'token': 'John',
79 'l33t': False,
80 'uppercase_variations': 2,
81 'i': 0,
82 'guesses': 50,
83 'l33t_variations': 1,
84 'dictionary_name': 'male_names',
85 'base_guesses': 2,
86 'guesses_log10': 1.6989700043360185,
87 'j': 3
88 }, {
89 'matched_word': 'smith123',
90 'rank': 12789,
91 'pattern': 'dictionary',
92 'reversed': False,
93 'token': 'Smith123',
94 'l33t': False,
95 'uppercase_variations': 2,
96 'i': 4,
97 'guesses': 25578,
98 'l33t_variations': 1,
99 'dictionary_name': 'passwords',
100 'base_guesses': 12789,
101 'guesses_log10': 4.407866583030775,
102 'j': 11
103 }],
104 }
105
106
107Custom Ranked Dictionaries
108--------------------------
109
110In order to support more languages or just add password dictionaries of your own, there is a helper function you may use.
111
112.. code:: python
113
114 from zxcvbn.matching import add_frequency_lists
115
116 add_frequency_lists({
117 'my_list': ['foo', 'bar'],
118 'another_list': ['baz']
119 })
120
121These lists will be added to the current ones, but you can also overwrite the current ones if you wish.
122The lists you add should be in order of how common the word is used with the most common words appearing first.
123
124CLI
125~~~
126
127You an also use zxcvbn from the command line::
128
129 echo 'password' | zxcvbn --user-input <user-input> | jq
130
131You can also execute the zxcvbn module::
132
133 echo 'password' | python -m zxcvbn --user-input <user-input> | jq
134
135
136Contribute
137----------
138
139- Report an Issue: https://github.com/dwolfhub/zxcvbn-python/issues
140- Submit a Pull Request: https://github.com/dwolfhub/zxcvbn-python/pulls
141
142License
143-------
144
145The project is licensed under the MIT license.
146
147
148.. |Build Status| image:: https://travis-ci.org/dwolfhub/zxcvbn-python.svg?branch=master
149 :target: https://travis-ci.org/dwolfhub/zxcvbn-python
150
