https://github.com/querateam/django-pwned
A collection of django password validators
https://github.com/querateam/django-pwned
django password python security
Last synced: 9 months ago
JSON representation
A collection of django password validators
- Host: GitHub
- URL: https://github.com/querateam/django-pwned
- Owner: QueraTeam
- License: mit
- Created: 2022-01-18T15:07:01.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-01-18T10:21:49.000Z (over 1 year ago)
- Last Synced: 2025-09-25T08:58:52.166Z (9 months ago)
- Topics: django, password, python, security
- Language: Python
- Homepage:
- Size: 51.8 KB
- Stars: 24
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# Django Pwned
[](https://pypi.python.org/pypi/django-pwned/)
[](https://github.com/QueraTeam/django-pwned/actions)
[](https://github.com/QueraTeam/django-pwned/actions)
[](https://github.com/QueraTeam/django-pwned/blob/master/LICENSE.txt)
[](https://github.com/psf/black)
A collection of django password validators.
## Compatibility
- Python: **3.8**, **3.9**, **3.10**, **3.11**, **3.12**
- Django: **4.2**, **5.0**
## Installation
```
pip install django-pwned
```
For translations to work, add `django_pwned` to `INSTALLED_APPS`.
## TL;DR:
```python
AUTH_PASSWORD_VALIDATORS = [
{"NAME": "django.contrib.auth.password_validation.UserAttributeSimilarityValidator"},
{"NAME": "django_pwned.validators.GitHubLikePasswordValidator"},
{"NAME": "django_pwned.validators.MinimumUniqueCharactersPasswordValidator"},
{"NAME": "django_pwned.validators.PwnedPasswordValidator"},
]
```
## Validators
### PwnedPasswordValidator(request_timeout=1.5, count_threshold=1)
This validator uses the [Pwned Passwords API] to check for compromised passwords.
Internally, this validator checks password with django's
`CommonPasswordValidator` and if password was not in django's list,
uses Pwned API to check password. So you can remove `CommonPasswordValidator`
if you're using this validator.
```python
AUTH_PASSWORD_VALIDATORS = [
# ...
# {"NAME": "django.contrib.auth.password_validation.CommonPasswordValidator"},
{"NAME": "django_pwned.validators.PwnedPasswordValidator"},
# ...
]
```
You can set the API request timeout with the `request_timeout` parameter (in seconds).
You can set the `count_threshold` to reject a password if it appears at least
a certain number of times in the Pwned Passwords data set.
By default, this threshold is set to `1`.
For instance, setting `count_threshold=2` means the password will be rejected
if it appears in the data set at least twice.
Example configuration:
```python
AUTH_PASSWORD_VALIDATORS = [
# ...
{
"NAME": "django_pwned.validators.PwnedPasswordValidator",
"OPTIONS": {
"request_timeout": 2,
"count_threshold": 5,
},
},
# ...
]
```
If for any reason (connection issues, timeout, ...) the request to Pwned API fails,
this validator skips checking password and logs a message.
### GitHubLikePasswordValidator(min_length=8, safe_length=15)
Validates whether the password is at least:
- 8 characters long, if it includes a number and a lowercase letter, or
- 15 characters long with any combination of characters
Based on GitHub's documentation about [creating a strong password].
You may want to disable Django's `NumericPasswordValidator`
and `MinimumLengthValidator` if you want to use
`GitHubLikePasswordValidator`.
The minimum number of characters can be customized with the `min_length`
parameter. The length at which we remove the restriction about
requiring both number and lowercase letter can be customized with the
`safe_length` parameter.
### MinimumUniqueCharactersPasswordValidator(min_unique_characters=4)
Validates whether the password contains at least 4 unique characters.
For example `aaaaaaaaaabbbbbbccc` is an invalid password, but `aAbB` is a valid password.
The minimum number of unique characters can be customized with the
`min_unique_characters` parameter.
## Development
- Create and activate a python virtualenv.
- Install development dependencies in your virtualenv: `pip install -e '.[dev]'`
- Install pre-commit hooks: `pre-commit install`
- Run tests with coverage: `py.test --cov`
## License
MIT
[pwned passwords api]: https://haveibeenpwned.com/API/v3#PwnedPasswords
[creating a strong password]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-strong-password