secure-password-manager 1.8.3

A secure local password manager with strong encryption

🔐 Secure Password Manager

A local-first Password Manager built with Python that securely stores your passwords using strong encryption.

Current version: see VERSION.txt (v1.8.0)

🆕 What's New in v1.8.0:

• KDF versioning for future-proof key derivation
• Optional key protection with master password (encrypt secret.key)
• Export integrity HMAC to detect tampering
• Bulk import transactions for faster, lock-free restore
• See v1.8.0 improvements for details

🚀 Features

• Secure Storage: All passwords encrypted with Fernet symmetric encryption
• Password Management: Add, view, edit, and delete passwords
• Security Analysis: Password strength evaluation and suggestions
• Password Generator: Create strong, random passwords
• Master Password: Protect access with a master password
• Two-Factor Authentication: Additional security with TOTP (Time-based One-Time Password)
• Categorization: Organize passwords by category
• Security Audit: Find weak, reused, expired, or breached passwords
• Backup & Restore: Export/import functionality
• Password Expiration: Set expiry dates for passwords
• Command-Line Interface: User-friendly CLI with color formatting
• GUI Interface: Optional PyQt5 graphical interface
• Activity Logging: Track all important actions

📚 Documentation

Comprehensive project documentation is organized in the docs/ folder:

For Users

• Documentation Index - Complete documentation overview

For Developers

• Architecture - System architecture and design
• Security Model - Security implementation details
• Database Schema - Database structure
• Contributing Guide - Development guide
• Roadmap - Future plans

Build Documentation

• Build Guide - Building from source
• Linux Build - Linux-specific instructions

🛠️ Installation

Option 1: Install from PyPI (Recommended)

The simplest way to install Secure Password Manager:

pip install secure-password-manager

After installation, you can run the application with:

# For the command-line interface
password-manager

# For the graphical interface
password-manager-gui

Option 2: Install from Source

1. Clone the repository:

   git clone https://github.com/ArcheWizard/password-manager.git
   cd password-manager
   

2. Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate   # On Windows: venv\Scripts\activate
   

3. Install the package in development mode:

   pip install -e .
   

4. If upgrading from an older version, run the migration script:

   python scripts/migrate_to_new_structure.py
   

   This will move existing data files to the new .data/ directory.

🛡️ Requirements

• Python 3.8+
• Core dependencies (installed automatically):
  • cryptography: For secure encryption
  • PyQt5: For the GUI interface
  • zxcvbn: For password strength analysis
  • pillow: For image processing
  • Additional dependencies as listed in requirements.txt

📂 Project Structure

The project follows PEP 517 src/ layout for better packaging and distribution:

password-manager/
├── src/                   # Source code (PEP 517 layout)
│   └── secure_password_manager/
│       ├── __init__.py    # Package initialization
│       ├── apps/          # Application entry points
│       │   ├── app.py     # CLI application
│       │   └── gui.py     # GUI application
│       └── utils/         # Core utilities
│           ├── auth.py            # Authentication
│           ├── backup.py          # Import/export
│           ├── crypto.py          # Encryption/decryption
│           ├── database.py        # Database operations
│           ├── interactive.py     # CLI input utilities
│           ├── logger.py          # Logging facilities
│           ├── password_analysis.py # Password evaluation
│           ├── paths.py           # Path management (XDG)
│           ├── security_analyzer.py # Breach checking
│           ├── security_audit.py  # Security auditing
│           ├── two_factor.py      # 2FA implementation
│           └── ui.py              # UI formatting
├── tests/                 # Unit & integration tests
├── docs/                  # Documentation
│   ├── development/       # Technical documentation
│   ├── build/             # Build instructions
│   └── releases/          # Release notes
├── scripts/               # Build and utility scripts
├── assets/                # Static assets
│   ├── icons/             # Application icons
│   └── screenshots/       # UI screenshots
├── .data/                 # Development data (gitignored)
└── pyproject.toml         # Project configuration

Data Storage

The application uses XDG Base Directory Specification for organized data storage:

Development Mode (when running from source):

• All data stored in .data/ directory in project root

Production Mode (when installed via pip):

• Data files: ~/.local/share/secure-password-manager/
• Config files: ~/.config/secure-password-manager/
• Cache files: ~/.cache/secure-password-manager/
• Log files: ~/.local/share/secure-password-manager/logs/

📸 Screenshots

First Time Setup

Login

Home Screen

Password Management

Categories

Security Audit

Backup & Restore

Settings & Logs

🔒 How It Works

Security Model

This Password Manager uses a multi-layered security approach:

1. Master Password: Access to the application is protected by a master password that is never stored directly. Instead, a salted hash is stored using PBKDF2 with 100,000 iterations.

2. Encryption: All passwords are encrypted using Fernet symmetric encryption (AES-128-CBC + HMAC integrity, via cryptography).

3. Key Management: The encryption key is stored locally and is used for encrypting/decrypting the stored passwords.

4. Database: Passwords are stored in a local SQLite database, with the password values stored as encrypted binary data.

5. Backup Protection: When exporting passwords, the entire backup file is encrypted using the same strong encryption.

Data Flow

1. When adding a password:

   • Password is encrypted using the local key
   • Encrypted data is stored in the SQLite database

2. When viewing passwords:

   • Encrypted data is retrieved from the database
   • Each password is decrypted for display

3. When exporting passwords:

   • All passwords are decrypted
   • The entire password list is serialized to JSON
   • The JSON is encrypted and written to a file

🧪 Testing

pytest -q

Notes:

• Integration tests use temporary databases and patch DB_FILE
• Network-dependent breach checks are limited and resilient to failures
• SQLite can lock under concurrent operations; tests include small delays/workarounds

🗺️ Roadmap (excerpt)

See docs/roadmap.md for the full plan. Highlights:

• Derive or protect secret.key using the master password (or OS keyring)
• Stronger KDF defaults (Argon2id/scrypt) with parameter versioning
• Improved import/restore reliability and integrity verification
• Clipboard auto-clear and additional UX hardening

📝 Changelog

See CHANGELOG.md for release notes.

📚 Future Improvements (historical)

• ✅ Master Password authentication
• ✅ Password strength evaluation and generator
• ✅ Unit tests for critical functions
• ✅ Backup and restore functionality
• ✅ Search
• ✅ Categories/tags
• ✅ Password expiration notifications
• ✅ GUI version (PyQt)
• ✅ Package available on PyPI
• ✅ Two-factor authentication (TOTP)
• Password history tracking
• Cross-platform desktop application (PyInstaller)
• Docker support

👨‍💻 Author

• ArcheWizard – GitHub Profile

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

For security considerations and design details, start with docs/security.md and docs/architecture.md.