Using Powershell to notify when an email is involved in a data breach.

This week I worked with the Have I been Pwned API. I came up with a pretty use full little script that monitors Email addresses and notifies you if one of them is signed up for a compromised service. Have I been Pwned offers a service for this Here. Which is nice for individual accounts but if your at a business with hundreds of employees you don’t want to be adding accounts manually or sometimes you want to be emailed if someones account is on a pwned. That is where these scripts come in.

The scripts can be found:
Monitor script designed to work with AD can be found on pastebin here.
Monitor script using an array of emails can be found on pastebin here.
Additional functions made from this project can be found on pastebin here.
And as always My github has the full collection.

There are two versions of the monitor script, one with an array you can configure the email addresses manually. The other that pulls directly from active directory. A note: the monitor scripts do not care about the age of the breach. If haveibeenpwned.com gets information on a new breach that happened in 2001 and a users email over laps the user will be notified. After a breach has been identified it is logged and the user isn’t bothered again. The script also “stacks” breaches into one email so as not to spam your users with 100’s of emails.

An email for multiple breaches looks like:

This email is customize-able in the configuration section of the script.

Other quick notes on the use of the script before I go into configuration details. I would suggest not running the script more than once a month, or once a week at the most. The breaches can be old at times and constantly hammering the API will not do any good. There is also a sleep 5 in the script. Feel free to adjust it, I left it in to make sure larger accounts wouldn’t constantly query the API causing issues.

Configuration options for these scripts:
#Make sure the path exists or you will spam your list every time the script runs:
$path_to_notified_file = ".\db\pwnd_list.csv"

This is the database file that keeps the script from spamming your users. Make sure it is correct and writable or your users will be notified repeatedly.

Do you even want to send an email? With $email_notify set to $false the script just generates a CSV file. This lets you build a basic database of old breaches without annoying your users OR determining how many user emails have been involved in breaches.
#SMTP settings:
$email_notify = $true

Customize the Email alert the users will get:
$from = "test@example.com"
$subject = "ATTN: Account was included in a data breach"
$body_html = "Hello,
It has been noticed by an automated system that your email address was included in the following data breaches:"
$body_signature = "
It is recommended you change your passwords on those systems

The $needs_email_creds option needs you to setup a password if set to $true. This works on gmail but I haven’t tested it on other systems.
First load the $cred_path variable and then copy and paste the read-host line without the comment like so:

The script doesn’t prompt for anything. Just type your password for the email account and press enter. The password will be stored in the file.

Last bit you need to configure is SMTP server settings:
#SMTP server to use
$smtp = "smtp.gmail.com"
$smtp_port = "587"

Configured for google, you’ll need to know your own SMTP server settings.Monitor script designed to work with AD can be found on pastebin here.
Monitor script using an array of emails can be found on pastebin here.Now your all set to monitor your corporate environment for breaches involving services your users may have signed up for on there email.

Additional functions made from this project can be found on pastebin here.

This function is what powers the notified script. In the script it does a “truncated response” you can get some interesting information from a none truncated response:
Command:
Get-breachedstatus test@example.com

The script has a few advantages I can think of:
1) Direct AD integration, so if the company rebrands/adds domains etc. You don’t need to remember to add TXT records and new domains to report.

2) Depending on how you set it up. A ticket can be sent to helpdesk and directly to the user rather than a monthley style report sent directly to helpdesk/one person/etc. With a bit of customization to the email it also allows for some internal branding.

3) No need to add a Txt record to the domain. Which means a helpdesk team can get this approved more readily than in some larger heavily silod environments.

But at the end of the day, it depends on your work flow, and your company if this particular method would be useful.