Skip to content

watson0x90/PasswordAtTheDisco

BranchesTags

Repository files navigation

Password!AtTheDisco

"I crack passwords, and explain the chaos"

License Python Version

Password!AtTheDisco is a comprehensive password security auditing tool designed to evaluate and enhance password security across Active Directory environments. It combines password complexity analysis with BloodHound privilege data and Have I Been Pwned breach correlation to provide risk-based security insights that help organizations prioritize remediation efforts.

🎯 Key Features

  • 🔒 CVSS-Style Risk Scoring: Three-component scoring system (Base/Temporal/Environmental) with 0-10 risk scale
  • 🩸 BloodHound Integration: Identifies Domain Admin pathways and privilege escalation risks
  • 🔐 HIBP Breach Correlation: Checks 1.3 billion breached password hashes with 7-tier categorization
  • 📊 Interactive Reports: HTML dashboards with FlexSearch (<100ms), Excel actionable reports, CSV exports
  • 🌐 Multi-Domain Analysis: Cross-domain password sharing and lateral movement detection
  • 📈 Advanced Analytics: Password complexity, policy compliance, similarity detection, pattern matching
  • ⚡ High Performance: Parallel processing, indexed HIBP lookups, intelligent caching

🚀 Quick Start

Installation

# Clone repository with submodules
git clone --recurse-submodules https://github.com/watson0x90/PasswordAtTheDisco.git
cd PasswordAtTheDisco

# Install dependencies
pip install -r requirements.txt

# Configure BloodHound
cp config/bloodhound.json.example config/bloodhound.json
# Edit with your BloodHound API credentials

# Test BloodHound connection
python main.py --test-bh

First Audit

# Generate password files with Hashcat
hashcat -m 1000 --show --username --potfile-path audit.pot hashes.txt > cracked.txt
hashcat -m 1000 --left --username --potfile-path audit.pot hashes.txt > uncracked.txt

# Run audit
python main.py -d "CORP.INT:cracked.txt:uncracked.txt"

# View interactive reports
python main.py -s  # Opens browser to http://localhost:8008

🎉 Done! View comprehensive password security analysis with risk scores, remediation priorities, and interactive dashboards.

📖 Documentation

Getting Started

User Documentation

Reference Material

Developer Documentation

📚 Full Documentation Index: docs/README.md

🔧 System Requirements

Minimum:

  • Python 3.9+ (3.11+ recommended)
  • 4GB RAM (8GB+ recommended with HIBP)
  • Linux, macOS, or Windows with WSL

Optional:

  • BloodHound Enterprise instance (for privilege analysis)
  • HIBP NTLM database (~2GB, for breach detection)
  • Hashcat 7.0+ (for password cracking)
  • Pandoc (for PDF generation)

📊 What It Does

Password Analysis

  • Complexity Assessment: Character sets, length, entropy
  • Pattern Detection: Dictionary words, keyboard patterns, common passwords
  • Policy Compliance: Organizational password policy enforcement
  • Similarity Analysis: Password reuse and variation detection

BloodHound Integration

  • Privilege Analysis: Domain Admin pathways, controlled objects
  • Account Properties: Enabled status, last logon, password expiry
  • Risk Amplification: Privilege-based environmental scoring

HIBP Correlation

  • Breach Detection: 1.3 billion breached NTLM hashes
  • Tier System: 7-level categorization (0: clean → 6: critical)
  • Performance: Three-tier lookup (cache → index → file)
  • Dual Impact: Base tier scoring + environmental multiplier

Risk Scoring (CVSS-Style)

Base Score (0-10)
  ↓ Temporal Factors (age, policy, expiration)
Temporal Score
  ↓ Environmental Factors (privilege, sharing, HIBP, domain)
Environmental Score = Final Risk Score
  ↓ Threshold Mapping
Risk Level (Critical/High/Medium/Low)

Special Rule: Any account with Domain Admin pathway = Critical (regardless of score)

Report Formats

Format Use Case Key Features
HTML Interactive analysis FlexSearch, filtering, visualizations, dark mode
Excel Actionable remediation Prioritized sheets, formulas, recommended actions
CSV Data export Raw data, SIEM integration
Markdown Documentation Detailed analysis, PDF conversion
PDF Executive reports Professional formatting, printable

💡 Usage Examples

Single Domain Audit

python main.py -d "CORP.INT:corp_cracked.txt:corp_uncracked.txt"

Multi-Domain Audit

python main.py \
  -d "PROD.CORP.INT:prod_cracked.txt:prod_uncracked.txt" \
     "DEV.CORP.INT:dev_cracked.txt:dev_uncracked.txt" \
     "DMZ.CORP.INT:dmz_cracked.txt:dmz_uncracked.txt"

Serve HTML Reports

python main.py -s  # Starts server on http://localhost:8008

Generate PDFs

python main.py --pdf  # Converts Markdown reports to PDF

Test BloodHound Connection

python main.py --test-bh

🔐 HIBP Integration Setup (Optional but Recommended)

HIBP integration identifies passwords exposed in data breaches, adding critical context to risk scoring.

Quick Setup

# 1. Initialize HIBP downloader submodule (included with this repo)
git submodule update --init --recursive

# 2. Install .NET SDK (required to build downloader)
# Linux: sudo apt-get install dotnet-sdk-8.0
# macOS: brew install dotnet-sdk
# Windows: Download from https://dotnet.microsoft.com/download/dotnet/8.0

# 3. Build the HIBP downloader
cd PwnedPasswordsDownloader/src/HaveIBeenPwned.PwnedPasswords.Downloader
dotnet restore
dotnet build -c Release
cd ../../

# 4. Download HIBP NTLM database (~2GB download, ~42GB uncompressed)
dotnet run --project src/HaveIBeenPwned.PwnedPasswords.Downloader \
  -c Release -- \
  -o pwnedpasswords_ntlm.txt \
  -f ntlm

# This downloads 1.3 billion breached NTLM hashes (30-60 min)

# 5. Return to project root and configure
cd ../../
cp config/hibp.json.example config/hibp.json
# Edit ntlm_hash_file path (default: PwnedPasswordsDownloader/pwnedpasswords_ntlm.txt)

# 6. First run builds index (5-10 minutes, one-time)
python main.py -d "DOMAIN:cracked.txt:uncracked.txt"
# Subsequent runs: index loads in 1-2 seconds

What HIBP Provides:

  • Identifies passwords in 1.3 billion breached hashes
  • Shows breach count (how many times hash appears)
  • 7-tier risk categorization (0: clean → 6: 100k+ breaches)
  • Dual impact: Base score contribution + environmental multiplier (1.0x-1.5x)

Performance:

  • Cache hits: <1ms (90%+ hit rate)
  • Index lookups: 10-50ms
  • Configurable cache size (default: 1M hashes = ~50MB RAM)

To Disable: Set "enable_lookup": false in config/hibp.json

🩸 BloodHound Integration Setup

BloodHound enriches password analysis with Active Directory privilege data.

Configuration

# 1. Copy example config
cp config/bloodhound.json.example config/bloodhound.json

# 2. Edit with your credentials
{
  "domain": "bloodhound.company.com",
  "port": 443,
  "scheme": "https",
  "token_id": "your-token-id",
  "token_key": "your-token-key",
  "search_limit": 1,
  "controllables_limit": 10
}

# 3. Test connection
python main.py --test-bh

What BloodHound Provides:

  • Domain Admin pathway detection (auto-elevates to Critical risk)
  • Controlled object counts (privilege-based risk amplification)
  • Account properties (enabled, last logon, password expiry)
  • Cross-domain privilege analysis

API Token Setup: See BloodHound API Documentation

Prerequisites: SharpHound data collection completed and imported into BloodHound

⚙️ Configuration

Password Policy

Customize password requirements in lists/password_policy.json:

Single Domain:

{
  "default": {
    "policy": {
      "min_length": 14,
      "require_uppercase": true,
      "require_lowercase": true,
      "require_digits": true,
      "require_special": true,
      "max_password_age_days": 90
    }
  }
}

Multi-Domain (different policies per domain):

{
  "default": { "policy": { ... } },
  "PRODUCTION.CORP.INT": { "policy": { "min_length": 16, ... } },
  "DEV.CORP.INT": { "policy": { "min_length": 12, ... } }
}

See lists/README.md for complete policy documentation.

Word Lists

Customize detection lists in lists/:

  • forbidden_words.txt - Organization-specific banned terms (⭐⭐⭐⭐⭐ CRITICAL to customize)
  • common_passwords.txt - Weak password list (~10,000 entries)
  • dictionary_words.txt - English dictionary (~479,000 words)
  • keyboard_patterns.txt - Common keyboard patterns (~45 entries)

Quick Start:

# Add your company-specific terms
echo "YourCompany" >> lists/forbidden_words.txt
echo "YourProduct" >> lists/forbidden_words.txt
echo "YourLocation" >> lists/forbidden_words.txt

See lists/README.md for complete customization guide.

📁 Input File Format

Password files must be in hashcat format with usernames:

user@DOMAIN.INT:RID:LMhash:NTLMhash:::password

Generate with Hashcat:

# Cracked passwords
hashcat -m 1000 --show --username --potfile-path audit.pot hashes.txt > cracked.txt

# Uncracked hashes
hashcat -m 1000 --left --username --potfile-path audit.pot hashes.txt > uncracked.txt

Username Format: Must be UPN format (user@DOMAIN.INT) for BloodHound integration

📊 Output Structure

reports/DOMAIN-2025-10-21-143022/
├── csv/                              # CSV data exports
│   ├── DOMAIN_report.csv
│   └── DOMAIN_detailed_report.json
├── excel/                            # Excel actionable reports
│   └── DOMAIN_actionable.xlsx
│       ├── Risk Summary
│       ├── Top 100 Risks
│       ├── DA Pathways               # Critical accounts
│       ├── Top Controllables
│       ├── HIBP Breached
│       ├── Non-Expiring
│       ├── Out of Compliance
│       ├── Similar Passwords
│       └── All Accounts
├── html/                             # Interactive HTML reports
│   ├── main.html                     # Dashboard
│   ├── search.html                   # Global search (FlexSearch)
│   ├── DOMAIN_report.html
│   └── password_data.json            # Embedded search data
├── markdown/                         # Markdown reports
│   ├── DOMAIN_report.md
│   └── combined_report.md
├── pdf/                              # PDF reports
│   └── DOMAIN_report.pdf
└── metadata.json                     # Audit run metadata

reports/latest -> DOMAIN-2025-10-21-143022/  # Symlink to latest

🎯 Risk Levels

Risk Level Score Range Color Action Timeline
Critical 8.0-10.0 🔴 Red Immediate (24 hours)
High 6.0-7.9 🟠 Orange Priority (1 week)
Medium 4.0-5.9 🟡 Yellow Scheduled (1 month)
Low 0.0-3.9 🟢 Green Monitor

Special Rule: Any account with Domain Admin pathway = Critical (regardless of score)

🔬 Testing

Comprehensive test suite available:

# Test HIBP integration
python scripts/test_hibp_integration.py

# Test with cleanup
python scripts/test_hibp_integration.py --cleanup

See TESTING.md for complete testing documentation.

🤝 Contributing

We welcome contributions! Please see our Development Guide for:

  • Development environment setup
  • Coding standards (PEP 8, Black, flake8)
  • Testing requirements
  • Pull request process
  • Git workflow

Quick Start:

# Fork and clone
git clone https://github.com/YOUR_USERNAME/PasswordAtTheDisco.git
cd PasswordAtTheDisco

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Make changes, test, commit
git checkout -b feature/your-feature
# ... make changes ...
pytest  # Run tests
git commit -m "feat(scope): description"
git push origin feature/your-feature

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

🙏 Acknowledgments

📞 Support

🗺️ Roadmap

  • Advanced hashcat integration (automated cracking workflows)
  • Additional report formats (SIEM integrations)
  • Machine learning-based pattern detection
  • Real-time monitoring capabilities
  • Azure AD / Entra ID support
  • Custom plugin system

⭐ Star History

If you find Password!AtTheDisco useful, please consider starring the repository!

Password!AtTheDisco - Comprehensive password security auditing for Active Directory environments.

"I crack passwords, and explain the chaos"

About

Python based domain and multi-domain password audit.

Resources

Readme

License

Apache-2.0 license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Languages