KPUnlock

KeePassXC Access Recovery via CLI Password Candidate Testing

---

Table of Contents

• Overview
• Warning
• Prerequisites
• Installation
• Remote Execution (irm/iex)
• Parameters
• Configuration via .env
• Examples
• Expected Output
• Exit Codes
• How to Prepare the Wordlist
• Project Structure
• Limitations
• Contributing

---

Overview

KPUnlock is a PowerShell script that tests a list of password candidates against a .kdbx database file, using keepassxc-cli as the verification engine.

Useful for regaining access to your own KeePass database when the master password has been forgotten and a list of candidates is available. No Administrator privileges required — runs locally or directly from the internet via irm | iex.

---

Warning

This tool is intended exclusively for recovering access to your own database. Using it against third-party databases without explicit authorization may constitute a criminal offense under applicable law.

---

Prerequisites

• Windows 10 / Windows Server 2016 or later
• Windows PowerShell 5.1+ or PowerShell 7+
• KeePassXC installed (provides keepassxc-cli.exe)
• A .kdbx database file (target)
• A .txt file with password candidates (one per line, UTF-8 encoding)

---

Installation

1. Clone the repository or download the script:

git clone https://forge.itamarcampos.com.br/itamcampos/kpunlock.git
cd kpunlock

2. Copy the example file and configure it:

Copy-Item .env.example .env

KEEPASSXC_CLI_PATH=C:\Program Files\KeePassXC\keepassxc-cli.exe
WORDLIST_PATH=

3. The script locates keepassxc-cli.exe in the following priority order:

• KEEPASSXC_CLI_PATH key in the .env file
• C:\Program Files\KeePassXC\keepassxc-cli.exe (default installation path)
• Any directory listed in the PATH environment variable

If needed, provide the path manually via the -CliPath parameter.

---

Remote Execution (irm/iex)

Run the script directly from the internet without cloning the repository:

irm https://forge.itamarcampos.com.br/itamcampos/kpunlock/raw/branch/main/src/KpUnlock.ps1 | iex

To pass parameters during remote execution, use the expanded script block form:

& ([scriptblock]::Create((irm https://forge.itamarcampos.com.br/itamcampos/kpunlock/raw/branch/main/src/KpUnlock.ps1))) -KdbxPath "C:\vault.kdbx" -WordlistPath "C:\passwords.txt"

Security notice: Always review script contents before running them via iex. Inspect the source at https://forge.itamarcampos.com.br/itamcampos/kpunlock.

---

Parameters

Parameter	Required	Description
-KdbxPath	Yes	Full path to the .kdbx database file
-WordlistPath	No	Path to the .txt file with password candidates
-CliPath	No	Path to keepassxc-cli.exe when not available in PATH

---

Configuration via .env

Create a .env file in the project root to set default paths:

# Path to the KeePassXC CLI executable
KEEPASSXC_CLI_PATH=C:\Program Files\KeePassXC\keepassxc-cli.exe

# Default wordlist path (used when -WordlistPath is not provided)
WORDLIST_PATH=C:\Users\user\passwords.txt

The .env file is optional. When omitted, the script falls back to the default KeePassXC installation path and the wordlist at dictionary\Password-Dictionary.txt.

The wordlist is resolved in the following order:

1. -WordlistPath parameter
2. WORDLIST_PATH key in the .env file
3. <ProjectRoot>\dictionary\Password-Dictionary.txt

---

Examples

Database only — wordlist and CLI resolved from .env:

.\KPUnlock.ps1 -KdbxPath "C:\vault.kdbx"

Providing the wordlist explicitly:

.\KPUnlock.ps1 -KdbxPath "C:\vault.kdbx" -WordlistPath "C:\passwords.txt"

Providing the CLI path manually:

.\KPUnlock.ps1 -KdbxPath "C:\vault.kdbx" -WordlistPath "C:\passwords.txt" -CliPath "D:\apps\KeePassXC\keepassxc-cli.exe"

---

Expected Output

When the password is found:

[*] KDBX file : C:\vault.kdbx
[*] Wordlist  : C:\passwords.txt (42 passwords)
[*] Starting attempts...

[+] PASSWORD FOUND!
[+] Password : mypassword123
[+] Attempt  : 7 of 42
[+] Time     : 00:00:03

When no password works:

[-] No password from the list worked.
[-] Attempts : 42
[-] Time     : 00:00:18

---

Exit Codes

Code	Meaning
0	Password found successfully
1	Configuration error (CLI not found, invalid file, etc.)
2	No password from the wordlist worked

---

How to Prepare the Wordlist

• Plain text file (.txt), one password per line
• UTF-8 encoding (important for passwords with accented or special characters)
• Blank lines are ignored automatically

Example passwords.txt:

password123
MyP@ssw0rd2020
keePass!
personal_vault

---

Project Structure

KPUnlock\
├── .env                          # Local configuration (do not commit)
├── .env.example                  # Configuration template
├── dictionary\
│   └── Password-Dictionary.txt   # Default wordlist (fallback)
└── src\
    └── KPUnlock.ps1

---

Limitations

• Tests passwords sequentially — performance depends on keepassxc-cli response speed
• Does not support key file authentication in this version
• Does not support databases protected by YubiKey or other hardware devices

---

Contributing

Suggestions and improvements are welcome. Open an issue or submit a pull request.

---

_{Made by itamcampos}