Tag Archives: PowerShellGallery

Have I Been Pwned PowerShell Module v3

Over the last few years I’ve written I few posts on a PowerShell module I created that allows users to directly talk to the Have I Been Pwned API service (https://haveibeenpwned.com) that Troy Hunt maintains. While those posts are a little old now, they are still a good read on what this PowerShell Module is about. I encourage you to read them if you are interested (links at the bottom).

A few months back Troy made a big change to the way his API service works by requiring authorisation in the form of an API key. This broke a lot of different scripts and services the community have created that leveraged his service, including my own PowerShell module. Troy has discussed at length why he has decided to take these steps. I won’t bother going into it here. Authentication and the Have I Been Pwned API

Shortly after this change took effect I received a number of comments from the community that my PowerShell module didn’t work anymore. One or two even said that it was failing because I wasn’t providing an API key with the module. So I wanted to spend a few minutes to explain some of the new changes in the way the latest version of the Have I Been Pwned PowerShell module works. And what you need to do if you want to use it.

Firstly I decided to version increment the PowerShell module from the previous latest version of v1.4.2 to v3 to match the API version used by HIBP. (Version 2 was a short lived version up on my GitHub page)

Now for the big breaking change. Where applicable, all the URIs in the module have been updated to the v3 API. And again, where applicable, have had a header added to them to include a hibp-api-key value/token. Not all URI endpoints require an API Key. Generally speaking if you want to check for a pwned email address you will need an API key.

So how does this work?
The two functions that require an API key to be specified are Get-PwnedAccount and Get-PwnedPasteAccount. In the past you would have typed something like --

Get-PwnedAccount -EmailAdddress [email protected]

This would have returned all breached instances of sites that this email address would have been compromised in. In version 3 you now require the use of an API key to do the same thing.

Get-PwnedAccount -EmailAdddress [email protected] -apiKey "hibp-api-key"

So in this above example you can input your API key directly in the command. Or you could store it in a variable and call it at a later stage in the command. For example

$myApiKey = "xxxxxxxxxxxxx"
Get-PwnedAccount -EmailAdddress [email protected] -apiKey $myApiKey 

If you also really wanted to, you could hard code your API key in the parameters section of these scripts. Certainly not recommended but the choice is yours.

So where do I get this API key?
To make it clear, not from this PowerShell module or from me. You will need to go to Troy Hunt’s site (https://haveibeenpwned.com/API/Key) and purchase one.

Once you do you, this will be yours, or your organisation’s, own personal key that you do not share out. How you protect it and how you want to use it will be up to you.

Where can I download the PowerShell Module?
PowerShellGallery: https://www.powershellgallery.com/packages/HaveIBeenPwned/
GitHub: https://github.com/originaluko/haveibeenpwned

Previous Posts
HaveIBeenPwned PowerShell Module
HaveIBeenPwned PowerShell Module Updates

HaveIBeenPwned PowerShell Module

If you haven’t heard of Have I Been Pwned, firstly what are you doing?  It’s a site created by fellow Aussie Troy Hunt.  Troy aggregates data breaches as they become public into a searchable database. One of the primary goals of Have I Been Pwned is to raise security awareness around data breaches to the public.

As a bit of a learning exercise to myself, I created a PowerShell Module that leverages the haveibeenpwned.com APIs.  The module contains five Functions, Get-PwnedAccount, Get-PwnedBreach, Get-PwnedDataClass, Get-PwnedPassword, and Get-PwnedPasteAccount. I like to think of the HaveIBeenPwned PowerShell Module as an Enabler. By itself it does nothing more than what the haveibeenpwned.com site does. But by leveraging the Power of PowerShell and returning the results in object format the data can be easily manipulated for many other purposes.

Installing and using the Module and Functions is very simple. Ideally you will be running PowerShell 5 or above which will allow you to easily download and install from the PowerShellGallery. If you’re not on PowerShell 5 I’d highly recommend you download the WMF 5.1 (Windows Management Framework) which includes PowerShell 5.

Installing the module is simply a matter of typing the following.

PS F:\Code> Install-Module -Name HaveIBeenPwned

Once installed you can view all the Functions available with the following command.

PS F:\Code> Get-Command -Module haveibeenpwned 

CommandType     Name                                               Version    Source                                                                               
-----------     ----                                               -------    ------                                                                               
Function        Get-PwnedAccount                                   1.1        HaveIBeenPwned                                                                       
Function        Get-PwnedBreach                                    1.1        HaveIBeenPwned                                                                       
Function        Get-PwnedDataClass                                 1.1        HaveIBeenPwned                                                                       
Function        Get-PwnedPassword                                  1.1        HaveIBeenPwned                                                                       
Function        Get-PwnedPasteAccount                              1.1        HaveIBeenPwned      

The two main Functions are Get-PwnedAccount and Get-PwnedPassword.

The first, Get-PwnedAccount, will enumerate if an account, based off an email address, has been found in the Have I Been Pwned list of data breaches.

PS F:\Code> Get-PwnedAccount -EmailAddress [email protected]

In the above example all breaches are listed where the account used [email protected] as the email address. Which is huge by the way.

The second and slightly more controversial, Get-PwnedPassword, will take a password and confirm if it has been identified in a data breach.  Get-PwnedPassword will accept a password in three different formats.  Plain text, Secure String, and SHA1 hash.

PS F:\Code> Get-PwnedPassword -SHA1 AB87D24BDC7452E55738DEB5F868E1F16DEA5ACE

In the above example a SHA1 hash was generated offline using Quick Hash GUI.  Get-PwnedPassword will then send that Password or SHA1 hash in the body of a HTTPS request to Have I Been Pwned.  Now, obviously, what can been see as the controversial part off this is not only do you have to trust Have I Been Pwned but also this PowerShell Function.

All Functions come with Help and Examples which can be view using Get-Help.  For example.

PS F:\Code> Get-Help Get-PwnedPassword -Examples

The Module and all Functions can be found in the PowerShellGallery for download.  The Module can also been found in my public GitHub Project https://github.com/originaluko/haveibeenpwned.  All code can been view and sanity checked and is free to consume.

 

Lastly, I thought I might show how you can go one step further from simply enumerating an individual account. Many organisation’s IT departments create and manage accounts for their staff. They also provide security awareness training in protecting online accounts. An organisation could take a CSV list of their staff’s email addresses, import that list into PowerShell, and run it against the Get-PwnedAccount Function and identify if any of their staff have been involved in a data breach.

In the below example I import a small CSV file I have created with a list of email addresses. Then using half a dozen lines of code I iterate through the CSV list of email addresses and identify all the accounts that have been involved in a data breach. Using this information I can pro-actively notify staff to review these accounts.

$emails = Import-Csv F:\email_list.csv
foreach ($email in $emails) {
    $email = $email.accounts
    $results = Get-PwnedAccount -EmailAddress $email
    if ($results.status -ne 'Good') {
        foreach ($result in $results) { 
            $breach = $result.title
            Write-Output "Email address $email has been found in a $breach breach"
        }
    }
    Start-Sleep -Milliseconds 1500
}

And sample output after running the above code.

Email address [email protected] has been found in a Yahoo breach
Email address [email protected] has been found in a Youku breach
Email address [email protected] has been found in a Zomato breach
Email address [email protected] has been found in a 000webhost breach
Email address [email protected] has been found in a 17 breach
Email address [email protected] has been found in a Adobe breach
Email address [email protected] has been found in a Bell (2017 breach) breach

 

Also read the follow up post on new additions
HaveIBeenPwned PowerShell Module Updates -- https://blog.ukotic.net/2019/05/28/haveibeenpwned-powershell-module-updates/

Download Links
PowerShellGallery: https://www.powershellgallery.com/packages/HaveIBeenPwned/
GitHub: https://github.com/originaluko/haveibeenpwned