VaultX is a minimal, script-based password manager for the command line. It allows you to securely manage multiple isolated vaults, use strong encryption, perform password breach checks, export QR codes, and now log all major actions - all within a transparent and portable Bash script.

• Multiple Vaults: Separate storage areas (e.g., for personal, work, family, or clients)
• Master Password Protection: Each vault is protected by its own master password
• Strong Encryption: AES-256-CBC with PBKDF2 (200,000 iterations) and HMAC integrity
• Fuzzy Selection Menus: Interactive vault, action, and entry selection via fzf
• Clipboard Integration: Copied passwords are automatically cleared after 30 seconds
• Secure Password Generation: Random password creation with configurable length
• Optional Breach Check: Query Have I Been Pwned (HIBP) API using SHA-1 k-anonymity model
• Vault Backups: Vault directories are zipped with secure permissions (chmod 600)
• Vault List: Overview of stored entries with last-modified timestamps
• QR Code Export: Display password as ASCII QR code directly in the terminal
• Brute-Force Protection: Lockout mechanism with exponential backoff on repeated failures
• Secure Memory Cleanup: Temporary variables are zeroed and unset after usage
• script/cli mode: for add, get, delete, audit, Backup vault/ all vaults
• Action Logging: All major operations are logged with timestamps and user, including vault access, entry changes, Vault creation, password output actions (such as copying to clipboard or displaying as QR code — without logging or storing the password itself and the username of the associated website or service,) as well as failed authentications.
• Help function: Outputs a documentation.
• Optional RSA Layer: 2FA-style Double Encryption

Required tools:

• bash ≥ 4.0
• openssl
• htpasswd (from apache2-utils or httpd-tools) / argon2

Optional tools:

• xclip or wl-clipboard (clipboard support)
• qrencode (QR code rendering in the terminal)
• curl
• fzf

git clone https://github.com/rhjddjdbc/vaultx.git
cd vaultx
chmod +x vaultx.sh lib/*.sh

Optional: create a configuration file:

mkdir -p ~/.config/vaultx
nano ~/.config/vaultx/config.env

Example config.env:

# config.env
###################################################
#                                                 #
#                            _ _                  #
#          /\   /\__ _ _   _| | |___  __          #
#          \ \ / / _` | | | | | __\ \/ /          #
#           \ V / (_| | |_| | | |_ >  <           #
#            \_/ \__,_|\__,_|_|\__/_/\_\          #
#                                                 #
#                   V A U L T X                   #
#            Locked. Encrypted. Yours.            #
#                                                 #
###################################################
# Base directories
VAULT_DIR="$HOME/.vault"            # Directory where vaults are stored
VAULT_RSA="$HOME/.vault"            # RSA Key store Path
BACKUP_DIR="$HOME/vault_backups"    # Location for encrypted vault backups
LOG_FILE="$HOME/.vaultx.log"        # log file

# Hash algorithm: argon2 or bcrypt
MASTER_HASH_ALGO="argon2"

ARGON2_TIME=3                       # Iterations
ARGON2_MEMORY=16                    # 2^16 KiB = 64 MiB
ARGON2_THREADS=4                    # Threads
ARGON2_SALT_BYTES=32                # Salt length in bytes

PASSWORD_COST=16                    # Cost factor for bcrypt

# Password options
PASSWORD_LENGTH=36                  # Default length for generated passwords
HIBP_CHECK_CLI=false                # Auto breach check for cli mode

# Security settings
MAX_ATTEMPTS=5                      # Max allowed login attempts before lockout
LOCKOUT_DURATION=60                 # Seconds after max attempts
TAMPER_LOCKOUT_DURATION=30          # Lockout if lockout file is missing (tampering)
LOGGING_ENABLED=true                # enabeling logging
TWO_FA_ENABLED=true                 # enabeling secondary RSA encryption (2FA)

You can build and install VaultX directly from the provided PKGBUILD:

git clone https://github.com/rhjddjdbc/vaultx-arch-PKGBUILD.git
cd vaultx-arch-PKGBUILD
makepkg -si

./vaultx.sh --help
./vaultx.sh -h

Run the script:

./vaultx.sh

At startup, VaultX prompts you to select or create a vault, then shows the main menu:

1. Save New Entry

   • Enter an entry name (e.g. github), optional username, and password (manual or generated)
   • Optionally check for breaches using HIBP
   • The entry is encrypted and integrity-protected

2. Decrypt Entry

   • Select an entry via fzf

   • After master password verification and HMAC validation, you can:

     • Display, copy, or QR-export the password
     • Perform a breach check
     • Show the username (unless QR or breach mode is chosen)

3. Edit Existing Entry

   • Update username and/or password
   • The script re-encrypts and recalculates HMAC

4. Delete Entry

   • Removes the .bin and .hmac files after confirmation

5. Backup Vault

   • Creates a ZIP archive of the vault, timestamped and permission-restricted, in the configured backup directory

6. List Vault

   • Displays all entries with last-modified timestamps

7. Exit

   • Quit the script

~/.vault/
  ├── default/
  │   ├── github.bin
  │   ├── github.hmac
  │   ├── .master_hash
  │   ├── .fail_count
  │   └── .last_fail
  └── work/

The following settings are located in ~/.config/vaultx/config.env:

• Master Password

  • Stored using bcrypt (via htpasswd -B -C) or argon2
  • Lockout with exponential backoff on repeated failures

• Entry Encryption

  • AES-256-CBC with PBKDF2 (200,000 iterations), salt, and per-entry HMAC

• Clipboard and QR Safety

  • Automatic clearance after 30 seconds
  • QR codes are removed after display

• Breach Checking

  • Uses SHA-1 k-anonymity: only the hash prefix is communicated
  • Completely optional; no password leaves the system unless explicitly requested

VaultX includes a logging system that records all significant actions for auditing and debugging.

• Vault and entry operations (create, edit, decrypt, delete)
• Authentication attempts, including failures
• Timestamp for every event
• Vault and entry references (never the actual password or decrypted content)

VaultX does not log sensitive information such as plaintext passwords, decrypted content, or master passwords.

[2025-07-30 17:09:42] [user:user] Interactive: FAILED AUTHENTICATION by saving new password in Vault: 'default'.
[2025-07-30 17:09:59] [user:user] Interactive: Selected action: 'Decrypt entry', vault: 'default'.
[2025-07-30 17:10:12] [user:user] Interactive: FAILED AUTHENTICATION by decrypting '~/.vault/default/github.bin' in Vault: 'default'.
[2025-07-30 17:12:25] [user:user] Interactive: Selected action: 'List vault', vault: 'default'.
[2025-07-30 17:12:54] [user:user] Interactive: Selected action: 'Delete entry', vault: 'job' entry: '~/.vault/job/asdfjj.bin'
[2025-07-30 17:13:32] [user:user] Interactive: FAILED AUTHENTICATION by editing '~/.vault/job/slack.bin' in Vault: 'job'.
[2025-07-30 17:13:32] [user:user] Interactive: Selected action: 'Edit existing entry', vault: 'job' entry: '~/.vault/job/slack.bin'

It is currently still a work in progress.

VaultX includes a tamper-resistant lockout system that protects against brute-force attacks:

• After MAX_ATTEMPTS failed master password logins, the vault enters lockout for LOCKOUT_DURATION seconds.
• Each vault stores its own lockout metadata in:

~/.vault/<vault>/ 
  ├── .lockout_state      # Tracks failed attempts and last failure timestamp 
  ├── .lockout_secret     # HMAC key to verify lockout file integrity 
  └── .tamper_lock        # Temporary lock if tampering is detected

• .lockout_state is signed with an HMAC to detect file manipulation.
• If the signature is invalid or the file is missing, a one-time tamper lock is applied (duration: TAMPER_LOCKOUT_DURATION).
• Lockout files are set to chmod 600.

The user config file ~/.config/vaultx/config.env contains paths and security settings.

VaultX verifies and enforces:

• chmod 644 permissions
• Ownership by root:root
• If incorrect, VaultX uses sudo or doas to fix it automatically
• If neither is available, the script exits with an error

This ensures the config is readable only as intended and cannot be silently altered by other users.

• Argon2 offers greater flexibility in tuning memory, time, and parallelism, making it more resistant to specialized hardware attacks.
• bcrypt remains a solid, well-tested choice with widespread support but lacks fine-grained control over resource usage.
• VaultX lets you choose Argon2 for new vaults while still opening and verifying bcrypt vaults seamlessly.

VaultX now supports an optional second encryption layer using RSA public-key cryptography, similar to a two-factor model. When enabled, each entry is encrypted twice:

1. First with AES-256-CBC (standard VaultX encryption)
2. Then the resulting encrypted file is encrypted again using RSA with your public key (id_rsa_vault.pub.pem)

This ensures that even if the master password is compromised, entries cannot be decrypted without your private RSA key.

• VaultX performs layered encryption:

  • The password entry is first encrypted using AES-256-CBC with a derived key from your master password.
  • The resulting file is then RSA-encrypted as a whole using your configured RSA public key.

• To decrypt an entry, VaultX:

  1. Uses your private RSA key to decrypt the file,
  2. Then prompts for your master password to perform AES decryption.

This forms a double lock: RSA + AES.

1. Generate an RSA key pair (if not already present):

   openssl genpkey -algorithm RSA -out ~/.vault/id_rsa_vault.pem -pkeyopt rsa_keygen_bits:2048
   openssl rsa -pubout -in ~/.vault/id_rsa_vault.pem -out ~/.vault/id_rsa_vault.pub.pem

2. Secure your key files:

   chmod 600 ~/.vault/id_rsa_vault.pem
   chmod 644 ~/.vault/id_rsa_vault.pub.pem

3. Enable RSA encryption in your config (~/.config/vaultx/config.env):

   RSA_ENCRYPTION_ENABLED=true
   RSA_PUBLIC_KEY="$HOME/.vault/id_rsa_vault.pub.pem"
   RSA_PRIVATE_KEY="$HOME/.vault/id_rsa_vault.pem"

• VaultX performs full-file RSA encryption, not hybrid encryption.

• RSA-encrypted entries cannot be decrypted without both:

  • Your private key
  • Your master password

• If the private RSA key is missing or invalid, decryption will fail.

./vaultx.sh --cli --vault default --action get --entry github

VaultX supports a CLI mode that allows you to perform essential operations directly via command line flags without interactive menus.

Using manual password input:

./vaultx.sh --cli --vault default --action add --entry github --username your_username --method manual

Using automatically generated password:

./vaultx.sh --cli --vault default --action add --entry github --username your_username --method generate

Retrieve the username and password after master password prompt:

./vaultx.sh --cli --vault default --action get --entry github

Securely removes the specified entry:

./vaultx.sh --cli --vault default --action delete --entry github

Backup a single vault:

./vaultx.sh --cli --vault default --action backup

Backup all vaults using the --all flag:

./vaultx.sh --cli --action backup --all

Displays all entries with last-modified timestamps:

./vaultx.sh --cli --vault default --action list

Backup all vaults via cron job:

0 3 * * * /path/to/vaultx.sh --cli --action backup --all

VaultX is licensed under the GNU General Public License v3.0 (GPL‑3.0). See the LICENSE file for details.