zxcvbn-pl

Polskie słowniki dla zxcvbn (port w Pythonie) — pospolite słowa, imiona, nazwiska i nazwy miejscowości.

Polish dictionaries for the Python port of zxcvbn — common words, first names, last names and place names. English below.

🇵🇱 Po polsku

Po co

zxcvbn szacuje, ile prób potrzeba do odgadnięcia hasła, rozpoznając w nim słowa ze słowników, powtórzenia, sekwencje, układy klawiatury i daty. Ma jednak tylko angielskie słowniki — polskie słowo to dla niego losowe litery. Przez to hasła łatwe do zgadnięcia dla każdego, kto ma polską listę słów, dostają najwyższą ocenę:

Frazy z kilku słów nadal są oceniane wysoko — tak jak zaleca NIST SP 800-63B. Spada ocena haseł z jednego pospolitego słowa, imienia, nazwiska lub nazwy miejscowości z dopiskiem. Efekt jest umiarkowany: słowa spoza ok. 50 tys. najczęstszych (np. kaczuszka2000!!) nadal są dla zxcvbn losowymi literami.

Port zxcvbn w JavaScripcie (zxcvbn-ts) ma pakiety językowe; port w Pythonie — nie. Ten pakiet wypełnia tę lukę danymi z @zxcvbn-ts/language-pl i dokłada nazwy miejscowości z urzędowego wykazu (TERYT).

Instalacja i użycie

pip install zxcvbn-pl

import zxcvbn_pl
from zxcvbn import zxcvbn

zxcvbn_pl.register()  # raz, np. przy starcie aplikacji; wielokrotne wywołanie nic nie psuje

wynik = zxcvbn("słoneczko123456")
wynik["score"]  # 2
[m.get("dictionary_name") for m in wynik["sequence"]]
# ['pl_common_words', 'passwords']

register() dokłada cztery słowniki do globalnego rejestru zxcvbn (zxcvbn.matching.RANKED_DICTIONARIES), więc działa dla każdego kolejnego wywołania zxcvbn() w procesie:

Nazwy wieloczłonowe są sklejone (Zielona Góra → zielonagora); człony nazw miast, które nie są pospolitymi słowami, są też osobno (bielsko, gorzow).

Każde słowo z polskimi znakami jest też w wariancie bez nich (żółw → zolw) z tą samą pozycją. Pomijane są wpisy krótsze niż 3 znaki.

Słowniki to indeksy marisa-trie czytane przez mmap (~1,2 MB na dysku, znikomy narzut RAM).

Uwaga o wątkach

zxcvbn trzyma słowniki — także user_inputs przekazane do zxcvbn() — w globalnym słowniku modułu. register() jest bezpieczne, ale jeśli wywołujesz zxcvbn(..., user_inputs=...) z wielu wątków, owiń wywołanie blokadą (to ograniczenie samego zxcvbn, nie tego pakietu).

Dane i licencje

Kod: MIT. Dane pochodzą z @zxcvbn-ts/language-pl i mają własne licencje — szczegóły w NOTICE.md:

• pospolite słowa: OPUS OpenSubtitles 2024 — ODC-BY (wymaga podania źródła),
• imiona i nazwiska: rejestr PESEL, dane.gov.pl — CC0 1.0,
• nazwy miejscowości: Wykaz urzędowych nazw miejscowości i ich części (MSWiA, stan na 1.01.2019), dane.gov.pl — CC0 1.0; kolejność miast: liczba ludności wg GUS, Bank Danych Lokalnych (stan na 31.12.2025) — CC BY 4.0.

Odbudowa słowników (deterministyczna, z weryfikacją sum kontrolnych pobieranych danych):

uv run python scripts/build_dictionaries.py

English

zxcvbn ships with English dictionaries only, so Polish words look like random letters to it and passwords such as słoneczko123456 or Katarzyna1985! get the top score. zxcvbn-pl adds Polish common words, first names, last names and place names (plus diacritics-free variants) to the Python port of zxcvbn:

import zxcvbn_pl
from zxcvbn import zxcvbn

zxcvbn_pl.register()
zxcvbn("słoneczko123456")["score"]  # 2 instead of 4

register() is idempotent and adds four dictionaries (pl_common_words, pl_first_names, pl_last_names, pl_places) to zxcvbn's global zxcvbn.matching.RANKED_DICTIONARIES. Multi-word passphrases still score high, in line with NIST SP 800-63B.

pl_places holds the names of Polish localities from the official list of place names (towns first, by population; then the other names by how many localities share them). Multi-word names are glued (zielonagora).

Common words, first and last names come from the @zxcvbn-ts/language-pl npm package: common words from OPUS OpenSubtitles 2024 (ODC-BY), first and last names from the Polish PESEL registry published on dane.gov.pl (CC0 1.0). Place names come from the official list of Polish place names (Ministry of the Interior and Administration, state as of 1 Jan 2019, dane.gov.pl, CC0 1.0), towns are ordered by population from Statistics Poland's Local Data Bank (31 Dec 2025, CC BY 4.0). See NOTICE.md. The code is MIT-licensed.