A Rust CLI that provides a variety of ways to check the "health" of a given KeePass database, including checking passwords against the Have I Been Pwned password list.
WARNING: I wrote this program mostly for personal use and to learn Rust. Use on real passwords at your own risk!
I'll note here that KeePassXC, as of version 2.6.0, has a lot of the same features as Medic, some of which are accessible through its easy-to-use graphical interface. I understand that you can also use the KeePassXC CLI tool to check your database against an offline list of password hashed.
What this tool does
Medic can check the passwords of a given KeePass database in four ways:
- Check passwords against the HaveIBeenPwned password database, via the HaveIBeenPwned API
- Check passwords against a file of password hashes. This requires users to download a large list of SHA-1 hashes of breached or compromised passwords. I tailored it to work with the Pwned Passwords lists from HaveIBeenPwned, which anyone can download here. Medic will then display a list of any passwords from the given KeePass database that also appear in the list of breached passwords.
- Check for weak passwords, using zxcvbn
- Check for duplicate passwords
If you're familiar with 1Password's Watchtower feature, Medic aims to accomplish similar functionality for KeePass databases (with the additional benefit of optionally working entirely offline).
USAGE: medic [FLAGS] [OPTIONS] <KEEPASS DATABASE FILE> FLAGS: -d, --duplicate Check database for duplicate passwords -w, --weak Check database for weak passwords --help Prints help information --online Check passwords against breached passwords online via the HaveIBeenPwned API. More info here: https://www.troyhunt.com/ive- just-launched-pwned-passwords-version-2/#cloudflareprivacyandkanonymity -V, --version Prints version information -v, --verbose Give verbose output OPTIONS: -h, --hashfile <hash_file> Provide password hash file to check database against. To download a copy of very large list of password hashes from HaveIBeenPwned, go to: https://haveibeenpwned.com/Passwords -k, --keyfile <keyfile> Provide key file, if unlocking the KeePass databases requires one -o, --output <output> Print results of health check to a file ARGS: <KEEPASS DATABASE FILE> KeePass database to check. Can either be a kdbx file or an exported CSV version of a KeePass database.
medic --online passwords.kdbxchecks the passwords of
passwords.kdbxusing the HaveIBeenPwned API. Prints report to the terminal.
medic --online -dw passwords.kdbxchecks the passwords of
passwords.kdbxusing the HaveIBeenPwned API, as well as looks for weak and duplicate passwords. Prints report to the terminal.
medic --online -dw --output=./report.txt passwords.kdbxchecks the passwords of
passwords.kdbxusing the HaveIBeenPwned API, as well as looks for weak and duplicate passwords. Prints result not to the terminal, but to a new text file
medic --online -w -k=test-files/test_key_file test-files/test_db.kdbxchecks the passwords of
test_db.kdbx-- which requires key file
test_key_file-- using the HaveIBeenPwned API, as well as looks for weak passwords. Prints results to terminal.
medic -h=../pwned-passwords-sha1-ordered-by-count-v4.txt my_db.kdbxchecks the passwords of
my_db.kdbxagainst the password hashes found in
../pwned-passwords-sha1-ordered-by-count-v4.txt, which is a large text file of password hashes. Medic will display any of the accounts in the
my_db.kdbxwith passwords that appear in the list to the terminal.
medic -dw passwords.kdbxchecks the passwords of
passwords.kdbxfor weak and duplicate passwords.
medic -dw passwords.kdbx --output=./password-report.txtchecks the passwords of
passwords.kdbxfor weak and duplicate passwords. Results are printed to a text file located at
medic -d -h=pwnedpasswords.txt kp_database_exported_csv_file.csvchecks an exported csv file against the hashes in
pwnedpasswords.txt, as well as searches for duplicate passwords.
- Install Rust if you haven't already
cargo install --git https://github.com/sts10/medic --branch mainor for better performance decrypting AES KeePass databases (see below), run:
RUSTFLAGS='-C target-cpu=native' cargo install --git https://github.com/sts10/medic --branch main
- Optional: If you'd like to check if any of your passwords have been breached without sending any information about them over the internet, you'll need to download the Pwned Passwords list, ideally via torrent (see below). Choose the SHA-1 version, the one ordered by prevalence. You'll need about 35 GB of space free to do this. The torrent downloads a
.7zcompressed file. Double click it to extract it to a ~22 GB text file. That's what this program will need to work with.
On Debian-based distros like Ubuntu, Medic may require libssl-dev. Install with:
sudo apt-get install libssl-dev.
Downloading breached passwords from HaveIBeenPwned via torrent
If you're new to torrents, Transmission is a decent choice for an application to download torrents, which apparently works on Mac and Windows. (Personally, on Kubuntu, I used KTorrent.) Once you have Transmission or another torrent-handling application installed, click the green "torrent" button on the Pwned Passwords site. Save the (very small)
.torrent file to your computer, then open that file with your torrent-downloading software. You may have to click "OK" or "Start", but once you do you'll be (probably slowly) downloading hundreds of millions of hashed passwords.
A note on KeePass databases that use an AES KDF (key derivation function)
By default, if your KeePass database uses an AES KDF (key derivation function) Medic will not use your CPU to decrypt your KeePass database. That means that if your databases is locked with a high number of AES key transformation rounds, it will take a while for Medic to open your database.
To solve this, either switch your database's KDF from "AES-KDF" to "Argon2", or install Medic by running this command:
RUSTFLAGS='-C target-cpu=native' cargo install --git https://github.com/sts10/medic --branch main. If you've already installed Medic without the RUSTFLAG, try running
RUSTFLAGS='-C target-cpu=native' cargo install --force --git https://github.com/sts10/medic --branch main
How I choose to use this tool
- Download the PwnedPasswords list in the SHA-1 format, ordered by prevalence (this text file will be about 11 GB compressed, 22GB extracted).
- Open your KeePass database in KeePassXC or whatever desktop app you use to open your database.
- Export your KeePass database to a CSV file (In KeePassXC:
Databasemenu > "Export to CSV...") (Heads up, this file includes your passwords, so be careful).
- Lock your KeePass database.
- Install Medic using instructions above.
- Run Medic by entering the following command:
medic -h=pwnedpasswords.txt -dw <my-exported-database>.csv. Note any compromised passwords and change them ASAP.
- When finished, securely delete that exported CSV file. If on MacOS, run
srm <my-exported-database>.csv. On Ubuntu-based Linux distributions, try
shred -ufv --iterations=60 <my-exported-database>.csv. Your sensitive data should now be safely deleted, but feel free to securely delete Medic itself if so inclined.
cargo test --release, though you'll need a file with a list of hashed passwords to pass one of the tests.
Checking for security vulnerabilities in Medic's dependencies
You can programmatically check Medic's dependencies for security vulnerabilities with cargo audit.
If you find vulnerabilities that concerns you, you can attempt to update the offending dependent crate yourself in the
Cargo.toml file. Also, please open an issue on this repo.
See Issues on GitHub for more, but here are some broad ideas:
- Better error handling (especially if user gets CLI arguments wrong or is using an incompatible KDF)
- Write more tests
- Have the program be able to use multiple threads
- Offer real packaging / installation options?
- Offer an option to check for similar passwords (maybe using zxcvbn?)
- Design/commission a logo?!
- Troy Hunt blog post about the password database
- The Rust crate Medic uses to open and read KeePass databases: keepass-rs
- A KeePass extension for checking against HaveIBeenPwned
- HIBPOfflineCheck - A Keepass plugin that performs offline checks against the haveibeenpwned passwords file
Useful projects in Rust
The CLI crate I used
I used structopt.