Password Manager CLI

A lightweight command-line password manager written in Python.

This project was developed and tested on Python 3.12.10 on Windows 11. While it has not been thoroughly tested on Linux or macOS, it should function on all platforms due to the use of cross-platform libraries. ⚠️ Non-Windows platform support may be limited. Please review the Important Security Notes before use.

Warning: This application has no backup or recovery features. Use at your own risk.

---

Table of Contents

• Installation
• Usage
• Features
• Menu Navigation
• Data Storage
• Security Features
• Important Security Notes
• Pre-Run Logging
• Log Files
• Troubleshooting

---

Installation

1. Create & activate a virtual environment (recommended)

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux/macOS
source .venv/bin/activate

2. Install dependencies

pip install -r requirements.txt

Required packages

• argon2-cffi — Secure master password hashing
• cryptography — Fernet encryption (AES-128)
• pyclip — Clipboard support
• regex — Unicode-aware matching

---

Usage

Run the application:

python main.py

First Launch

You will be asked to create a master password that:

• Has ≥ 8 characters
• Contains uppercase, lowercase, digits, and special characters

Upon creation, the following files are generated in:

<USER_HOME>/PasswordManager

File	Description
master.key	Argon2 hash of the master password (hidden)
salt.bin	Cryptographic salt (hidden)
user_db.enc	Encrypted password database
pm_log.txt	Application activity log

Subsequent Launches

You will be required to enter your master password. You have three attempts before the application exits.

---

Features

• AES-128 Encryption using Fernet
• PBKDF2-HMAC-SHA256 key derivation (480k iterations)
• Argon2id master password hashing
• Password generator with strong entropy
• Clipboard auto-clear (10 seconds)
• Session-based logging
• Unicode support
• Best-effort secure memory wiping
• Hidden and read-only security files

---

Menu Navigation

Main Menu

=== Password Manager ===
1. Add Record
2. View Records
3. Edit Record
4. Exit

---

1. Add Record

Fields:

• Record name (required)

• Username (optional)

• Email (optional, validated)

• Password

  • Enter manually (must meet complexity requirements)
  • OR auto-generate

• URL (optional)

• Notes (optional)

Password requirements

• ≥ 8 characters
• 1+ uppercase
• 1+ lowercase
• 1+ digit
• 1+ special character (!@#$%^&*()_+{}[]:;"'<,>.?/~-)

---

2. View Records

• Filter records (optional keyword)

• Select record to view

• Passwords are masked as ********

• Option to copy password to clipboard

  • Requires re-authentication
  • Auto-clears after 10 seconds

---

3. Edit Record

Options:

1. Update username
2. Update email
3. Update password (requires re-authentication)
4. Update URL
5. Update notes
6. Rename record
7. Delete record (requires re-authentication)

---

4. Exit

• Secure key wipe
• Graceful program shutdown

---

Data Storage

All data is stored in a hidden folder:

Windows

C:\Users\<USERNAME>\PasswordManager

Linux/macOS

~/PasswordManager

Files Created

File	Purpose	Security
master.key	Argon2 password hash	Hidden, Read-only
salt.bin	Cryptographic salt	Hidden, Read-only
user_db.enc	Encrypted DB	Encrypted
pm_log.txt	Logs (non-sensitive)	Standard file

---

Security Features

Master Password

• Hashing using Argon2id

Encryption

• Fernet (AES-128-CBC + HMAC)
• Key derived from PBKDF2-HMAC-SHA256 (480,000 iterations)

File Permissions

• Windows: Hidden + read-only
• Linux/macOS: 600 permissions

Input Sanitization

• Max length limits
• Control-character filtering
• Email validation
• Unicode normalization

Memory Safety

• Best-effort memory clearing
• Sensitive data zeroed before exiting

Clipboard Security

• Auto-clear after 10 seconds
• Background clearing thread

Re-Authentication Required For:

• Copying passwords
• Updating passwords
• Deleting records

---

⚠️ Important Security Notes

Salt File Loss = Permanent Data Loss

If salt.bin is deleted or modified, your database becomes unrecoverable, even with the correct master password.

Key = PBKDF2(MasterPassword + Salt)

If the salt changes, the derived key changes → decryption becomes impossible.

Always back up:

• salt.bin
• user_db.enc
• Entire PasswordManager directory (recommended)

---

Master Password Cannot Be Reset (yet)

If forgotten:

• There is no recovery
• All stored credentials are lost

---

Database Corruption

If user_db.enc becomes corrupted:

• The application will refuse to load it
• Data may be permanently lost
• Keep backups to avoid catastrophic loss

---

Pre-Run Logging

A pre-run log is generated only the first time the script is launched:

Location: <script_directory>/pm_prerun.log.txt

Contains startup diagnostics helpful for debugging.

---

Log Files

Application Log

Location: <USER_HOME>/PasswordManager/pm_log.txt

Format

YYYY-MM-DD HH:MM:SS | LEVEL | [SESSION_ID] LABEL | details

• Does not contain passwords, emails, or other sensitive values
• Uses generic labels (e.g., "record 1")

---

Troubleshooting

“No master password or security files found”

You're launching for the first time or deleted essential files. Create a new master password.

Passwords inaccessible after restart

Likely:

• Modified salt
• Corrupted DB

→ Restore from backup (if no backup exists, data is unrecoverable).

Unexpected exit

Check:

• pm_prerun.log.txt (startup issues)
• pm_log.txt (runtime issues)
• Dependencies
• Disk space

Session IDs

Each run generates a random 8-character session ID used for log grouping.