API Reference

Exposes completely defined types and frozen dataclass fields.

View API Details & Fields →
Field Type Description
score int Calculated strength score mapping to a 0–100 scale.
strength str Matching category tier description matching entropy levels.
entropy.theoretical_bits float Baseline entropy assuming random choices and full set pools.
entropy.effective_bits float Pattern adjusted final bit calculations after deductions.
dictionary_matches list[DictionaryMatchResult] Instances of detected dictionary substrings and replacements.
recommendations list[Recommendation] Deduplicated list of warnings and improvement guidelines.

Default Attack Profiles

Profile Speed Description / Scenario
Online throttled 10 / sec Rate-limiting systems preventing quick sequences.
Online unthrottled 1,000 / sec Login processes without standard timeout protections.
Offline slow hash 10,000 / sec Security schemes using Argon2, bcrypt, or scrypt.
Offline fast hash 10,000,000,000 / sec GPU rigs checking algorithms like MD5 or SHA-1.

Project Structure

A standardized Python package src layout.

src/passguard/
analyzer.py # Pipeline context manager
context.py # AnalysisContext instance state
models.py # Public frozen dataclasses
analysis/
charset.py # Set pooling classifications
entropy.py # Theoretical bit math
effective_entropy.py # Pattern penalty mathematics
recommendations.py # Context tip generators

Verification & Test Results

PassGuard is built with test-driven development from day one. Below are the verified metrics from our test pipeline.

✓ 49 Unit Tests Passed
✓ 100% Statement Coverage
✓ Mypy Strict Checked
✓ Ruff Lints Clean (0 Warnings)
View Coverage Report by Module →
Module Name Statements Missed Coverage
passguard/analysis/charset.py250100%
passguard/analysis/entropy.py250100%
passguard/analysis/effective_entropy.py590100%
passguard/analysis/scoring.py220100%
passguard/analysis/mutations.py150100%
passguard/analysis/recommendations.py300100%
passguard/analysis/pattern/engine.py150100%
passguard/analysis/pattern/keyboard.py290100%
passguard/analysis/pattern/repeated.py830100%
passguard/analysis/pattern/sequence.py370100%
passguard/analysis/dictionary/analyzer.py260100%
passguard/analysis/cracktime/analyzer.py150100%

Full Integration Example

Below is a fully functional script demonstrating custom configurations, dictionary matches, and full report parsing.

from passguard import PasswordAnalyzer
from passguard.analysis.dictionary.provider import SetDictionaryProvider
from passguard.analysis.cracktime.models import AttackProfile

# 1. Custom dictionary setup (banned company / brand names)
banned_words = {"corporate", "lokesh", "passguard"}
custom_dict = SetDictionaryProvider(banned_words)

# 2. Configured custom attack vectors
attack_scenarios = [
    AttackProfile("Attacker Supercomputer", 500_000_000_000),
    AttackProfile("Attacker RTX 4090", 25_000_000_000),
]

# 3. Instantiate analyzer and execute pass analysis
analyzer = PasswordAnalyzer(
    dictionary_provider=custom_dict, 
    attack_profiles=attack_scenarios
)
report = analyzer.analyze("L0k3sh_PassGuard_123!")

# 4. Parse output models and inspect properties
print(f"Analyzed Password:  {report.password}")
print(f"Overall Score:      {report.score}/100")
print(f"Security Strength:  {report.strength}")
print(f"Theoretical Bits:   {report.entropy.theoretical_bits:.2f} bits")
print(f"Effective Bits:     {report.entropy.effective_bits:.2f} bits")

# 5. Loop through identified dictionary words
if report.dictionary_matches:
    print("\nDictionary Matches:")
    for match in report.dictionary_matches:
        print(f"  - '{match.word}' at index [{match.start}:{match.end}]")

# 6. Print actionable recommendations
if report.recommendations:
    print("\nActionable Recommendations:")
    for rec in report.recommendations:
        print(f"  - [{rec.severity}] {rec.message}")