gopwned

README

goPwned

A golang library for HaveIBeenPwned REST API - https://haveibeenpwned.com/

Installation

go get github.com/mavjs/goPwned

Usage

Setup client with API token

Note: Have I Been Pwned API V3 requires an API Key for retrieveing all breaches and or pastes for an account. Please see here: https://haveibeenpwned.com/API/v3#Authorisation

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
    gopwned := gopwned.NewClient(nil, "APIKEY")
}

Breaches

Getting all breaches for an account

https://haveibeenpwned.com/API/v3#BreachesForAccount

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
	gopwned := gopwned.NewClient(nil, "APIKEY")

	acc_breaches, err := gopwned.GetAccountBreaches("foo@bar.com", "", false, true)
	if err != nil {
		panic(err)
	}
	for _, breach := range acc_breaches {
		fmt.Println(breach)
	}
}

Get all breaches for an account across a particular domain.

https://haveibeenpwned.com/API/v3#BreachesForAccount

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
    gopwned := gopwned.NewClient(nil, "APIKEY")

	acc_breaches, err := gopwned.GetAccountBreaches("foo@bar.com", "adobe.com", false, true)
	if err != nil {
		panic(err)
	}
	for _, breach := range acc_breaches {
		fmt.Println(breach)
	}
}

Getting all breached sites in the system

https://haveibeenpwned.com/API/v3#AllBreaches

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
	gopwned := gopwned.NewClient(nil, "")

	breaches, err := gopwned.GetBreachedSites("")
	if err != nil {
		panic(err)
	}
	for _, breach := range breaches {
		fmt.Println(breach)
	}
}

Getting a single breached site in the system

https://haveibeenpwned.com/API/v3#SingleBreach

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
	gopwned := gopwned.NewClient(nil, "")

	breached_site, err := gopwned.GetABreachedSite("adobe")
	if err != nil {
		panic(err)
	}
	fmt.Println(breached_site)
}

Getting all data classes in the system

https://haveibeenpwned.com/API/v3#AllDataClasses

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
	gopwned := gopwned.NewClient(nil, "")

	data_classes, err := gopwned.GetDataClasses()
	if err != nil {
		panic(err)
	}
	fmt.Println(data_classes)
}

Pastes

Getting all pastes for an account

https://haveibeenpwned.com/API/v3#PastesForAccount

import (
    gopwned "github.com/mavjs/goPwned"
)

func main() {
	gopwned := gopwned.NewClient(nil, "APIKEY")

	pastes, err := gopwned.GetAccountPastes("foo@bar.com")
	if err != nil {
		panic(err)
	}
	for _, paste := range pastes {
		fmt.Println(paste)
	}
}

Pwned Passwords

Searching by range

https://haveibeenpwned.com/API/v3#SearchingPwnedPasswordsByRange

import (
	"crypto/sha1"
	"fmt"
	"strconv"
	"strings"

	gopwned "github.com/mavjs/goPwned"
)

func fakeinput() string {
	inputPassword := "P@ssw0rd"
	h := sha1.New()
	h.Write([]byte(inputPassword))
	password := fmt.Sprintf("%X", h.Sum(nil)) // hash = "21BD12DC183F740EE76F27B78EB39C8AD972A757"

	return password
}

func main() {
	gopwned := gopwned.NewClient(nil, "")

	pwdhash := fakeinput()
	frange := pwdhash[0:5]
	lrange := pwdhash[5:40]

	karray, err := gopwned.GetPwnedPasswords(frange, false)
	if err != nil {
		panic("unable to get pwned passwords")
	}

	str_karray := string(karray)
	respArray := strings.Split(str_karray, "\r\n")

	var result int64
	for _, resp := range respArray {
		str_array := strings.Split(resp, ":")
		test := str_array[0]

		count, err := strconv.ParseInt(str_array[1], 0, 32)
		if err != nil {
			fmt.Printf("%#v", str_array[1])
			panic("unable to convert string into integer")
		}
		if test == lrange {
			result = count
		}
	}

	fmt.Println("This password has been seen:", result)
}

Development & Testing

• Get an API key at: https://haveibeenpwned.com/API/Key
• Set HIBP_API_KEY=<your api key> in .env file
• If using VS Code:
  • Use the Testing tab to run tests, it should pick up the API key as environement variable to run tests that require the API key.
• If others:
  • Use make tests

License

MIT

Documentation

Overview

Package gopwned implements the REST api of haveibeenpwned.com for easy querying. More specifically package gopwned implements the version 3 (V3) of the API.

Index

• type Breach
• type Client
  • func NewClient(httpClient *http.Client, token string) *Client
  • func (c *Client) GetABreachedSite(site string) (*Breach, error)
  • func (c *Client) GetAccountBreaches(account, domain string, truncate, unverified bool) ([]*Breach, error)
  • func (c *Client) GetAccountPastes(email string) ([]*Paste, error)
  • func (c *Client) GetBreachedSites(domainFilter string) ([]*Breach, error)
  • func (c *Client) GetDataClasses() (*DataClasses, error)
  • func (c *Client) GetPwnedPasswords(chars string, addPadding bool) ([]byte, error)
• type DataClasses
• type Paste

Types

type Breach

type Breach struct {
	Name         string       `json:"Name,omitempty"`
	Title        string       `json:"Title,omitempty"`
	Domain       string       `json:"Domain,omitempty"`
	BreachDate   string       `json:"BreachDate,omitempty"`
	AddedDate    string       `json:"AddedDate,omitempty"`
	ModifiedDate string       `json:"ModifiedDate,omitempty"`
	PwnCount     int          `json:"PwnCount,omitempty"`
	Description  string       `json:"Description,omitempty"`
	DataClasses  *DataClasses `json:"DataClasses,omitempty"`
	IsVerified   bool         `json:"IsVerified,omitempty"`
	IsFabricated bool         `json:"IsFabricated,omitempty"`
	IsSensitive  bool         `json:"IsSensitive,omitempty"`
	IsRetired    bool         `json:"IsRetired,omitempty"`
	IsSpamList   bool         `json:"IsSpamList,omitempty"`
	LogoPath     string       `json:"LogoPath,omitempty"`
}

Breach holds all breach information returned from the API.

type Client

type Client struct {
	Token     string
	UserAgent string
	BaseURL   *url.URL
	PwnPwdURL *url.URL
	// contains filtered or unexported fields
}

Client represents a client interfact to the haveibeenpwned.com API.

func NewClient

func NewClient(httpClient *http.Client, token string) *Client

NewClient creates a new haveibeenpwned.com API client. It expects 2 arguments 1) a `http.Client` 2) an API key

Currently, the 1st argument will default to `http.DefaultClient` if no arguments are given. The 2nd argument will default to an empty string, which means the client will not be able to call certain endpoints as per the API version changes in V3. For more information: https://haveibeenpwned.com/API/v3

func (*Client) GetABreachedSite

func (c *Client) GetABreachedSite(site string) (*Breach, error)

GetABreachedSite - returns all details of a single breach by its breach "name". This breach "name" is a stable value in the haveibeenpwned.com data-sets. An example of a breach "name" would be "Adobe" instead of "adobe.com".

func (*Client) GetAccountBreaches

func (c *Client) GetAccountBreaches(account, domain string, truncate, unverified bool) ([]*Breach, error)

GetAccountBreaches - returns a list of all breaches of a particular account has been involved in. This function checks if an HIBP API key is provided, if not it will throw an error. The function accepts 4 arguments, with 1 of them being required. They are:

• account - The account is not case sensitive and is URL encoded before sending to the endpoint. (required)
• domain - Filters the result set to only breaches against the domain specified. (e.g. adobe.com)
• truncate - Instructs the API to return the full breach data instead of, by default, only the name of the breach.
• unverified - Instructs the API not to include unverified breaches instead of, by default, returning both verified and unverified.

func (*Client) GetAccountPastes

func (c *Client) GetAccountPastes(email string) ([]*Paste, error)

GetAccountPastes - returns a list of pastes based on the email provided. This function checks if an HIBP API key is provided, if not it will throw an error.

func (*Client) GetBreachedSites

func (c *Client) GetBreachedSites(domainFilter string) ([]*Breach, error)

GetBreachedSites - returns a list of all details of each breach. A breach: an instance of a system having been compromised and data disclosed. This function accepts an option argument which can be used to filter on a specific breached domain (e.g. adobe.com) which may not be the same as the breach "Title"

func (*Client) GetDataClasses

func (c *Client) GetDataClasses() (*DataClasses, error)

GetDataClasses - returns an alphabetically ordered list of data classes exposed during a breach. A "data class" is an attribute of a record compromised in a breach. E.g. "Email addresses" and "Passwords"

func (*Client) GetPwnedPasswords

func (c *Client) GetPwnedPasswords(chars string, addPadding bool) ([]byte, error)

GetPwnedPasswords - returns a list of suffixes that has a similar prefix hash, i.e., the first 5 characters of SHA-1 hash of the password and the count of how many times that suffix has been seen in the data set. This function requires exactly 1 argument which is the 1st 5 characters of the hash of the password as a string.

type DataClasses

type DataClasses []string

DataClasses holds all data classes exposed from breaches returned from the API.

type Paste

type Paste struct {
	Source     string `json:"Source,omitempty"`
	ID         string `json:"Id,omitempty"`
	Title      string `json:"Title,omitempty"`
	Date       string `json:"Date,omitempty"`
	EmailCount int    `json:"EmailCount,omitempty"`
}

Paste holds all paste information returned from the API.