PwnedPassCheck

Check passwords and hashes against the haveibeenpwned.com Pwned Passwords API using PowerShell. Also supports third party equivalent APIs.

Background

The Pwned Passwords portion of Troy Hunt's Have I Been Pwned site is a collection of over half a billion passwords compiled from various data breaches over the years. It's both downloadable and searchable via a free API. This module makes it easy to check existing passwords or hashes against the API to see whether they've been compromised and how many times they've been seen in breaches.

The beauty of the API design is that it implements a k-Anonymity model which ensures that neither your password or full hash is ever sent to the API server. Only the first 5 characters of the hash are sent and the server returns a list of compromised hashes starting with that prefix. The client then compares the returned list against the full hash locally to see if it was compromised.

TO REITERATE: All passwords are hashed locally and only the first 5 characters of a hash are sent to the API which makes it impossible for API server owners to know, log, or crack your password hashes.

Install

Release

The latest release version can found in the PowerShell Gallery or the GitHub releases page. Installing from the gallery is easiest using Install-Module from the PowerShellGet module. See Installing PowerShellGet if you don't already have it installed.

# install for all users (requires elevated privs)
Install-Module -Name PwnedPassCheck -Scope AllUsers

# install for current user
Install-Module -Name PwnedPassCheck -Scope CurrentUser

Development

To install the latest development version from the git main branch, use the following command.

# (optional) set less restrictive execution policy
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force

# install latest dev version
iex (irm https://raw.githubusercontent.com/rmbolger/PwnedPassCheck/main/instdev.ps1)

Quick Start

The easiest function to start with is Get-PwnedPassword. You can supply a plaintext password to it as either a String, SecureString, or PSCredential object.

# Using a regular string like this is super easy, but not recommended for
# real passwords because it can be saved in your command history
Get-PwnedPassword 'password'

# Instead, use Read-Host to interactively collect the password as a SecureString
$secPass = Read-Host -AsSecureString -Prompt 'Enter Password'
Get-PwnedPassword $secPass

# You can do the same thing with a PSCredential (Username is ignored)
$credential = Get-Credential
Get-PwnedPassword $credential

The output should look like this where Hash is the hash of the password that was checked and SeenCount is the number of times that hash was seen in data breaches. If the number is zero, that means the hash has never been see in a data breach.

Hash                                     SeenCount
----                                     ---------
5BAA61E4C9B93F3F0682250B6CF8331B7EE68FD8   3861493

If you want to bulk test passwords, just pass them all in via the pipeline like this.

'password',$secPass,$credential | Get-PwnedPassword

If you have existing hashes to check, you can use Get-PwnedHash. However, the official API only supports SHA1 hashes.

$hash = '70CCD9007338D6D81DD3B6271621B9CF9A97EA00' # SHA1 hash of "Password1"
Get-PwnedHash $hash

Test-PwnedPassword, Test-PwnedHash, and Test-PwnedHashBytes also exist which are similar to their Get-Pwned* equivalents except they return a True/False result instead of the more details Hash/SeenCount data. True indicates the password/hash was seen in at least one breach. Otherwise, False.

Because the Pwned Password data is freely downloadable, it's possible to setup your own local copy of the API or use one hosted by a third party. Use the ApiRoot parameter to override the default API URL you test against.

Get-PwnedPassword 'password' -ApiRoot 'https://pwnpass.example.com/range/'

In addition to the SHA1 hashed copy of the data, an NTLM hashed copy is available. This can be incredibly useful for auditing passwords in an Active Directory environment. If you are testing against an NTLM version of the API, use the HashType parameter to make sure the function calculates the correct hash value.

Get-PwnedPassword 'password' -HashType 'NTLM' -ApiRoot 'https://pwnntlm.example.com/range/'

Requirements and Platform Support

• Supports Windows PowerShell 3.0 or later (a.k.a. Desktop edition).
• Supports Powershell Core 6.0 or later (a.k.a. Core edition) on all supported OS platforms.

Changelog

See CHANGELOG.md