🔐 Secure Password Generator

A robust, powerful, and secure command-line utility for generating cryptographically strong passwords. Built with Python's secrets module, this tool supports Argon2id password hashing and Base64-encoded AES-GCM-SIV encryption with customizable character sets, password metadata organization, and advanced search capabilities.

---

✨ Features

• Cryptographically Secure randomness via Python's secrets module
• Two-Factor Encryption - master password (something you know) XOR'd with encryption.key (something you have)
• AES-GCM-SIV Encryption with Base64-encoded storage for misuse-resistant authenticated encryption
• Argon2id Hashing with unique 256-bit salt per password and a separate 256-bit pepper key
• Secure File Deletion - uses Linux shred -vuxzn when available, with overwrite+unlink fallback
• Restrictive Permissions - all files created with 0600 (owner read/write only); warns if permissions drift
• Flexible Character Policies - uppercase, lowercase, digits, symbols, blanks, custom symbol sets, exclude similar characters, prevent consecutive duplicates, minimum per-type requirements
• Pattern-Based Generation - define exact character type positions (l=lower, u=upper, d=digit, s=symbol, b=blank, *=any)
• Password Strength Meter - entropy-based scoring, character diversity bonuses, expected-uniqueness penalties, pattern detection (1-10 scale)
• Metadata & Organization - labels, categories, comma-separated tags, automatic timestamps
• History Management - ASCII table view, search by label/category/tags, filter by strength/category/date, entry deletion
• Config File Support - load defaults from YAML or JSON config files; CLI args always override
• Clipboard Support - copy passwords via pyperclip or xclip (RHEL/Fedora Linux) with configurable auto-clear (CLIPBOARD_CLEAR_SECONDS, default 60s)
• Performance Optimized - clipboard method caching, encryption key caching, pre-validation of generation constraints, shared charset builder

---

🚀 Getting Started

🔍 Prerequisites

• Python 3.13+
• cryptography library (for encryption)
• PyYAML library (for YAML config file support)
• pyperclip or xclip (optional, for clipboard support on RHEL/Fedora Linux)

🛠️ Installation

1. Clone this repository to your local machine:

   git clone https://github.com/jayissi/Secure-Password-Generator.git

2. Install required dependencies:

   pip3 install -r requirements.txt

3. Make the script executable:

   chmod +x Secure-Password-Generator/password_generator.py

4. (Optional) Move it to your local bin folder:

   sudo mv Secure-Password-Generator/password_generator.py /usr/local/bin/password_generator

That's it! You're ready to generate passwords.

---

💻 Usage

Run the script from your terminal using password_generator with your desired options.
If you run the script with no arguments or with the -h flag, it will display the help menu.

password_generator -h

⚙️ Command-Line Arguments

Basic Options

Argument	Short	Description	Default
--length	-L	Password length (min: 8)	12
--count	-c	Number of passwords to generate	1
--passphrase	-P	Custom passphrase (supersedes other options)	None
--config	-f	Load defaults from YAML/JSON config file	None
--clipboard	-X	Copy password to clipboard (auto-clears)	False
--unlock	-U	Explicitly unlock vault with master password	False
--master-password		Master password for scripting/CI	None
--set-master-password		Configure/change master password + re-encrypt	False
--help	-h	Show help message	N/A

Character Type Options

Argument	Short	Description	Default
--full	-F	Use all character types + no-repeats	False
--upper	-u	Include uppercase letters	False
--lower	-l	Include lowercase letters	False
--digits	-d	Include digits	False
--symbols	-s	Include symbols	False
--allowed-symbols	-a	Custom allowed symbols (implies --symbols)	None
--blank	-b	Include space (never first/last)	False
--pattern	-p	Pattern string (l/u/d/s/b/* codes)	None

Advanced Options

Argument	Short	Description	Default
--min	-m	Min chars per selected type	1
--no-repeats	-r	No consecutive duplicate chars	False
--exclude-similar	-e	Exclude similar-looking chars	False

Password Organization Options

Argument	Description	Default
--label	Label/name for this password	Unnamed
--category	Category for this password	General
--tags	Comma-separated tags	[]

History Search & Filter Options

Argument	Description
--search	Search history by label, category, or tags
--filter-strength	Show only passwords with strength >= value
--filter-category	Show only passwords in this category
--since	Show passwords since date (YYYY-MM-DD)
--delete-entry	Delete specific entry by index number
--limit	Limit number of history entries to display

File Operations

Argument	Short	Description	Default
--no-save-history	-n	Don't save to password history	False
--show-history	-H	Show password generation history	False
--cleanup	-C	Clean up password and key files	False

---

📝 Examples

1. Generate a strong password with all character types
Organize with labels, categories, and tags.

password_generator -F -L 16 --label "Gmail Account" --category "Email" --tags "work,important"

Generated Password 1: p@55W0rD Ex&mpl3
Strength: ████████░░ 8/10
[✓] Passwords securely saved to /home/user/.secure_passwords/vault.enc

2. Advanced requirements
Create (5x) 20-character passwords with at least 3 of each type, no similar characters, no consecutive duplicates, and a custom symbol set.

password_generator -c 5 -L 20 -u -l -d -m 3 -e -r -a '!@*#^ $&%\"' -n

3. Pattern-based generation
Define exact character type positions: l=lower, u=upper, d=digit, s=symbol, b=blank, *=any.

password_generator --pattern 'lluuddss' --label "Pattern Test" --category "Testing"
password_generator --pattern '****lluu' -n

4. Custom passphrase
Store a user-provided passphrase with metadata.

password_generator -P "MySecurePass123!" --label "Custom Pass" --category "Personal" --tags "manual"

5. View password history
Display saved passwords in a formatted table.

password_generator -H

┌─────┬───────────────┬──────────────────────┬──────────────┬────────────┬──────────────────────┐
│ #   │ Label         │ Password             │ Strength     │ Category   │ Created              │
├─────┼───────────────┼──────────────────────┼──────────────┼────────────┼──────────────────────┤
│ 1   │ Gmail Account │ C1l\|T3qZ7KfTqp8     │ 8/10         │ Email      │ 2025-11-15 08:56     │
│ 2   │ Bank Account  │ 16DB<dNrUb9{         │ 6/10         │ Banking    │ 2025-11-15 08:55     │
└─────┴───────────────┴──────────────────────┴──────────────┴────────────┴──────────────────────┘

6. Search and filter history
Search, filter by category/strength, and combine filters.

password_generator -H --search "Gmail"
password_generator -H --filter-category "Email" --filter-strength 7 --limit 5
password_generator --delete-entry 1

7. Config file usage
Load defaults from a YAML or JSON config file. CLI arguments always override config values.

password_generator -f config.yaml
password_generator -f config.json -L 32

8. Secure cleanup
Securely delete all password and key files (including master salt).

password_generator -C

9. Two-factor encryption (master password)
Configure a master password so the vault requires both something you know and the on-disk encryption.key.

# First-time setup (interactive prompts)
password_generator --set-master-password

# Unlock is automatic when master_salt.bin exists; -U is optional/self-documenting
password_generator -U -H

# Scripting/CI only (exposes password in process lists)
password_generator --master-password 'YourSecret' -H

---

📁 Config File

Load default settings from a YAML or JSON config file using -f. All fields are optional - omitted fields fall back to CLI defaults. Format is auto-detected by file extension (.yaml/.yml/.json).

Example config.yaml:

length: 24
upper: true
lower: true
digits: true
symbols: true
no_repeats: true
exclude_similar: false
min_chars: 2
allowed_symbols: "!@#$%^&*?`"
blank_space: false
save_history: true

# Optional metadata defaults
label: "My Default Label"
category: "General"
tags: "default,work"

Equivalent config.json:

{
  "length": 24,
  "upper": true,
  "lower": true,
  "digits": true,
  "symbols": true,
  "no_repeats": true,
  "exclude_similar": false,
  "min_chars": 2,
  "allowed_symbols": "!@#$%^&*?`",
  "blank_space": false,
  "save_history": true,
  "label": "My Default Label",
  "category": "General",
  "tags": "default,work"
}

Config Field Reference:

Field	Type	Description	Default
length	int	Password length (minimum: 8)	12
upper	bool	Include uppercase letters	false
lower	bool	Include lowercase letters	false
digits	bool	Include digits	false
symbols	bool	Include symbols	false
no_repeats	bool	Prevent consecutive duplicates	false
exclude_similar	bool	Exclude similar-looking characters	false
min_chars	int	Minimum characters per selected type	1
allowed_symbols	string	Custom symbol set	All symbols
blank_space	bool	Include space character	false
save_history	bool	Save password to encrypted history	true
label	string	Default label for passwords	"Unnamed"
category	string	Default category for passwords	"General"
tags	string	Comma-separated default tags	None

Note: Clipboard auto-clear timeout is controlled by the code-level constant CLIPBOARD_CLEAR_SECONDS (default 60) in password_generator.py, not by the config file. Master password setup is CLI-only (--set-master-password).

---

🛡️ Security Details

This tool is designed with security as a top priority. JSON Payload → Argon2id (Salt + Pepper) → Encrypt → Store

Storage Location

• Password Vault: ${HOME}/.secure_passwords/vault.enc
• Encryption Key: ${HOME}/.secure_passwords/encryption.key (256-bit key material)
• Pepper Key: ${HOME}/.secure_passwords/pepper.key (256-bit pepper for Argon2id)
• Master Salt: ${HOME}/.secure_passwords/master_salt.bin (32-byte salt for master-password KDF; created by --set-master-password)

Security Features

• Two-Factor Encryption: When a master password is configured, the final AES-256 key is Argon2id(master_password, master_salt) XOR encryption.key. Stealing the vault directory alone is not enough.
• Randomness: Uses Python's secrets module, not random, ensuring cryptographic quality randomness.
• Minimum Length: Enforces a minimum of 8 characters, with recommended defaults of 12+.
• AES-GCM-SIV Encryption: Provides misuse-resistant authenticated encryption; records are Base64-encoded per line to prevent newline corruption.
• Argon2id (Salt + Pepper) Hashing:
  • Each password uses a unique 256-bit salt per password
  • A separate 256-bit pepper key file provides additional protection
  • 512-bit digest output
  • Memory-hard algorithm resistant to GPU/ASIC attacks
• Timestamp: Each password entry is stamped with creation time.
• File Permissions: All files are created with 0600 file permissions (read/write) restricted to the file's owner. The tool warns if permissions drift.
• Secure Deletion: Prefers Linux shred -vuxzn (overwrite, exact size, zero final pass, then unlink). Falls back to manual overwrite+unlink when shred is unavailable. Note: shred cannot guarantee erasure on SSDs, CoW filesystems (btrfs/ZFS), or data-journaled filesystems.
• Clipboard Auto-Clear: Copied passwords are scheduled to clear after CLIPBOARD_CLEAR_SECONDS (default 60).

🔐 Argon2id (Salt + Pepper) + Two-Factor AES-GCM-SIV Encryption Flow

flowchart TD
    subgraph inputs [Inputs]
        payload["JSON Payload<br/>(password + metadata)"]
        salt["256-bit Salt<br/>(unique per password)"]
        pepper["256-bit Pepper<br/>(secret key file)"]
        masterPw["Master Password<br/>(something you know)"]
        masterSalt["master_salt.bin<br/>(32-byte salt)"]
        fileKey["encryption.key<br/>(something you have)"]
        nonce["96-bit Nonce<br/>(random)"]
    end

    subgraph hashing [Argon2id Hashing]
        argon2["Argon2id KDF"]
    end

    subgraph keyDerivation [Two-Factor Key Derivation]
        masterKdf["Argon2id<br/>(master password)"]
        xorOp["XOR"]
        finalKey["Final AES-256 Key"]
    end

    subgraph encryption [AES-GCM-SIV Encryption]
        aesgcm["AES-GCM-SIV"]
    end

    subgraph output [Stored Output]
        digest["512-bit Digest<br/>(Base64)"]
        ciphertext["Ciphertext + Auth Tag<br/>(Base64)"]
    end

    payload --> argon2
    salt --> argon2
    pepper --> argon2
    argon2 --> digest

    masterPw --> masterKdf
    masterSalt --> masterKdf
    masterKdf --> xorOp
    fileKey --> xorOp
    xorOp --> finalKey

    payload --> aesgcm
    finalKey --> aesgcm
    nonce --> aesgcm
    aesgcm --> ciphertext

Loading

Caution

You are responsible for the secure management of the ${HOME}/.secure_passwords/ directory and your master password.
Keep the master password secret (never share it). Do not store encryption.key / master_salt.bin insecurely, and do not share or back them up insecurely. Losing either factor may make the vault unrecoverable.

---

🧪 Testing

Integration Tests

The project includes a comprehensive integration test suite. Run tests directly:

bash tests/test_integration.sh

Or test in an isolated Podman container:

podman run --rm -v $(pwd):/workspace:Z fedora:latest bash -c "cd /workspace && dnf install -y python3 python3-pip > /dev/null 2>&1 && pip3 install -r requirements.txt > /dev/null 2>&1 && python3 -m pytest tests/test_strength_pytest.py -v && bash tests/test_integration.sh"

Exit Codes: On failure, the script exits with the test number that failed (e.g., exit code 15 means Test 15 failed). Exit code 0 indicates all tests passed.

Unit Tests

Pytest suite covering entropy-based strength scoring, consistency, edge cases, charset computation, and build_charset:

pytest tests/test_strength_pytest.py -v

Benchmark / Diagnostic Tool

A standalone CLI script for analyzing score distributions, standard deviation, and flicker across configurations:

python tests/benchmark_strength.py -n 200

---

🤝 Contributing

Contributions are welcome! Please open an issue or pull request for any improvements.

---

📜 License

This project is licensed under the MIT License. See the LICENSE file for more details.