A Go Library for “HaveIBeenPwned” REST API

HaveIBeenPwned is a free resource for anyone to quickly assess if they may have been put at risk due to an online account of theirs having been compromised or “pwned” in a data breach.

REST API v2

The API allows the list of pwned accounts (email addresses and usernames) to be quickly searched via a RESTful service.

Base URL

This method can easily be invoked directly by requesting the URL and does not require any request header manipulation.

https://haveibeenpwned.com/api/v2/{service}/{parameter}

Service: Getting all breaches for an account

A “breach” is an incident where a hacker illegally obtains data from a vulnerable system, usually by exploiting weaknesses in the software. All the data on the site HaveIBeenPwned comes from publicly leaked “breaches” or in other words, personal account data that has been illegally accessed then released into the public domain. HaveIBeenPwned aggregates it and makes it readily searchable.

The most common use of the API is to return a list of all breaches a particular account has been involved in. The API takes a single parameter which is the account to be searched for. The account is not case sensitive and will be trimmed of leading or trailing white spaces. The account should always be URL encoded.

As such, you can test this API directly in the browser, for example type:

https://haveibeenpwned.com/api/v2/breachedaccount/satish.talim@gmail.com

The result set can also be filtered by passing one of the following query strings:

https://haveibeenpwned.com/api/v2/breachedaccount/satish.talim@gmail.com?domain=adobe.com

The above filters the result set to only breaches against the domain specified.

You will see some JSON output in your browser which can be stored in a Go struct as follows:

The breach model

Each breach contains a number of attributes describing the incident. In the future, these attributes may expand without the API being versioned. The current attributes are:

Specifying the user agent

Each request to the API must be accompanied by a user agent request header. Typically this should be the name of the app consuming the service, for example “Pwnage-Checker-For-Android”. A missing user agent will result in an HTTP 403 response. A valid request would look like:

https://haveibeenpwned.com/api/{service}/{parameter}
User-Agent: Pwnage-Checker-For-Android

The user agent should accurately describe the nature of the API consumer such that it can be clearly identified in the request.

Rate limiting

Requests to the breaches and pastes APIs are limited to one per every 1500 milliseconds each from any given IP address (an address may request both APIs within this period). Any request that exceeds the limit will receive an HTTP 429 “Too many requests” response.

Service: Getting all breached sites in the system

A “breach” is an instance of a system having been compromised by an attacker and the data disclosed. For example, Adobe was a breach, Gawker was a breach etc. It is possible to return the details of each of breach in the system.

You can test this directly in the browser, for example type:

https://haveibeenpwned.com/api/v2/breaches

The result set can also be filtered by passing one of the following query strings:

https://haveibeenpwned.com/api/v2/breaches?domain=adobe.com

Service: Getting a single breached site

Sometimes just a single breach is required and this can be retrieved by the breach “name”. This is the stable value which may or may not be the same as the breach “title” (which can change).

You can test this directly in the browser, for example type:

https://haveibeenpwned.com/api/v2/breach/Adobe

Service: Getting all data classes in the system

A “data class” is an attribute of a record compromised in a breach. For example, many breaches expose data classes such as “Email addresses” and “Passwords”. The values returned by this service are ordered alphabetically in a string array and will expand over time as new breaches expose previously unseen classes of data.

You can test this directly in the browser, for example type:

https://haveibeenpwned.com/api/v2/dataclasses

The paste model

Often when online services are compromised, the first signs of it appear on “paste” sites like Pastebin. Attackers frequently publish either samples or complete dumps of compromised data on these services. Monitoring and reporting on the presence of email addresses on the likes of Pastebin can give impacted users a head start on mitigating the potential fallout from a breach.

When you search for an email address on this site, both known data breaches and pastes are searched simultaneously. After the results are returned, they both appear side by side with an indication of where the address was found in a breach versus in a paste.

Each paste contains a number of attributes describing it. In the future, these attributes may expand without the API being versioned. The current attributes are:

Service: Getting all pastes for an account

The API takes a single parameter which is the email address to be searched for. Unlike searching for breaches, usernames that are not email addresses cannot be searched for. The email is not case sensitive and will be trimmed of leading or trailing white spaces. The email should always be URL encoded.

You can test this directly in the browser, for example type:

https://haveibeenpwned.com/api/v2/pasteaccount/test@example.com

The Go program

Let’s write our Go package ‘pwned.go’ in the folder:

C:\go_projects\go\src\github.com\SatishTalim\pwned

Here’s the full code:

pwned.go

We shall now write a Go program ‘pwnedtest.go’ that will use this library. I have stored ‘pwnedtest.go’ in the folder:

C:\go_projects\go\src\github.com\SatishTalim\pwnedtest

Here’s the code:

pwnedtest.go

What next?

• You could extend the ‘pwnedtest.go’ program to extract relevant information from the returned string.
• You could write a Heroku app that accepts user input and displays the output on the user browser.
• Do optimize the ‘pwned.go’ program and send me the link in the comments section.

Have fun!