VaultX - Secure Command-Line Password Manager

March 12, 2026 · View on GitHub

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.

Features

  • 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

Requirements

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

Installation

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)

Installation for Arch Linux Users

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

Usage

Help function

./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 Structure

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

Configurable Settings

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

VariableDescription
VAULT_DIRDirectory where all vaults are stored
VAULT_RSADirectory for RSA keys (public/private)
BACKUP_DIRDirectory where encrypted vault backups are stored
LOG_FILEPath to the log file
MASTER_HASH_ALGOHash algorithm for the master password: argon2 or bcrypt
ARGON2_TIMENumber of iterations for Argon2
ARGON2_MEMORYMemory cost in KiB (e.g., 2162^{16} = 64 MiB) for Argon2
ARGON2_THREADSNumber of threads (parallelism) for Argon2
ARGON2_SALT_BYTESSalt length in bytes for Argon2
PASSWORD_COSTCost factor for bcrypt hashing
PASSWORD_LENGTHDefault length for generated passwords
HIBP_CHECK_CLIEnables or disables the "Have I Been Pwned" check for passwords in CLI mode
MAX_ATTEMPTSMaximum allowed failed login attempts before lockout
LOCKOUT_DURATIONLockout duration in seconds after max failed attempts
TAMPER_LOCKOUT_DURATIONAdditional lockout if lockout file is missing (tampering)
LOGGING_ENABLEDEnables or disables logging of actions
TWO_FA_ENABLEDEnables or disables two-factor authentication (2FA)

Security Overview

  • 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

Logging Feature

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

What is logged

  • 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)

Security Note

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

Example log output

[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'

Lockout

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.

config.env Security

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/Bcrypt

FeatureArgon2bcrypt
Memory HardnessHighly configurable via ARGON2_MEMORY (e.g., 64 MiB or more)Fixed, low memory usage
ParallelismAdjustable with ARGON2_THREADSSingle-threaded
Time CostTunable via ARGON2_TIME iterationsControlled by PASSWORD_COST (2^cost)
Salt LengthCustomizable (ARGON2_SALT_BYTES, e.g., 32 bytes)Built-in 16 bytes
PHC String FormatStandardized, exact string comparison with -eStandard $2y$… prefix comparison
Resistance to GPU AttacksStrong, due to high memory requirementsModerate
Adoption & ToolsWidely supported in modern toolingVery mature, broad compatibility

Key Points

  • 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.

Optional RSA Layer (2FA-style Double Encryption)

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.

How It Works

  • 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.

Setup Instructions

  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"

Security Notes

  • 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.

Benefits

FeatureDescription
Layered encryptionAES-256 + RSA encryption on the full file
2FA-style accessRequires both a password and a private key

Example (CLI Mode)

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

CLI Mode Usage

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

General Options

FlagDescription
--cliEnables CLI mode
-v, --vaultSpecify the vault name (e.g., default)
-a, --actionAction to perform: add, get, delete, backup, audit
-e, --entryEntry name (required for add, get, delete)
-u, --usernameUsername for the entry (used with add)
-m, --methodPassword method for add: manual or generate
--allFlag for the backup action: backup all vaults

1. Add a new entry

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

2. Get an entry

Retrieve the username and password after master password prompt:

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

3. Delete an entry

Securely removes the specified entry:

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

4. Backup vault

Backup a single vault:

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

Backup all vaults using the --all flag:

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

5. List vault

Displays all entries with last-modified timestamps:

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

Example

Backup all vaults via cron job:

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

License

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