hibp

package module
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 9, 2022 License: MIT Imports: 13 Imported by: 2

README

go-hibp - Simple Go binding to the "Have I Been Pwned" API

GoDoc Go Report Card Build Status codecov Mentioned in Awesome Go buy ma a coffee

This Go library provides simple bindings to the excellent "Have I Been Pwned" (HIBP) API by Troy Hunt. It implements all 3 APIs that are provided by HIBP (Breaches, Pastes, Passwords). API key support for the private API endpoints are supported as well. go-hibp follows idiomatic Go style and best practice. It's only dependency is the Go Standard Library.

Usage

The library is fully documented using the execellent GoDoc functionality. Check out the GoDocs Reference for details on how to implement access to any of the 3 APIs with this package. You will also find GoDoc code examples there for each of those APIs.

Documentation

Overview

Package hibp provides Go binding to all 3 APIs of the "Have I Been Pwned" by Troy Hunt

Index

Examples

Constants

View Source 
const (
	// ErrPrefixLengthMismatch should be used if a given prefix does not match the
	// expected length
	ErrPrefixLengthMismatch = "password hash prefix must be 5 characters long"

	// ErrSHA1LengthMismatch should be used if a given SHA1 checksum does not match the
	// expected length
	ErrSHA1LengthMismatch = "SHA1 hash size needs to be 160 bits"
)
View Source 
const BaseUrl = "https://haveibeenpwned.com/api/v3"

BaseUrl is the base URL for the majority of API calls

View Source 
const DefaultUserAgent = `go-hibp v` + Version + ` (https://github.com/wneessen/go-hibp)`

DefaultUserAgent defines the default UA string for the HTTP client Currently the URL in the UA string is comment out, as there is a bug in the HIBP API not allowing multiple slashes

View Source 
const Version = "1.0.2"

Version represents the version of this package

Variables

This section is empty.

Functions

This section is empty.

Types

type ApiDate added in v0.1.2 

type ApiDate time.Time

ApiDate is a date string without time returned by the API represented as time.Time type

func (ApiDate) Time added in v0.1.2 

func (d ApiDate) Time() time.Time

Time adds a Time() method to the ApiDate converted time.Time type

func (*ApiDate) UnmarshalJSON added in v0.1.2 

func (d *ApiDate) UnmarshalJSON(s []byte) error

UnmarshalJSON for the ApiDate type converts a give date string into a time.Time type

type Breach added in v0.1.2 

type Breach struct {
	// Name is a pascal-cased name representing the breach which is unique across all other breaches.
	// This value never changes and may be used to name dependent assets (such as images) but should not
	// be shown directly to end users (see the "Title" attribute instead)
	Name string `json:"Name"`

	// Title is a descriptive title for the breach suitable for displaying to end users. It's unique across
	// all breaches but individual values may change in the future (i.e. if another breach occurs against
	// an organisation already in the system). If a stable value is required to reference the breach,
	// refer to the "Name" attribute instead
	Title string `json:"Title"`

	// Domain of the primary website the breach occurred on. This may be used for identifying other
	// assets external systems may have for the site
	Domain string `json:"Domain"`

	// BreachDate is the date (with no time) the breach originally occurred on in ISO 8601 format. This is not
	// always accurate — frequently breaches are discovered and reported long after the original incident. Use
	// this attribute as a guide only
	BreachDate *ApiDate `json:"BreachDate,omitempty"`

	// AddedDate represents the date and time (precision to the minute) the breach was added to the system
	// in ISO 8601 format
	AddedDate time.Time `json:"AddedDate"`

	// ModifiedDate is the date and time (precision to the minute) the breach was modified in ISO 8601 format.
	// This will only differ from the AddedDate attribute if other attributes represented here are changed or
	// data in the breach itself is changed (i.e. additional data is identified and loaded). It is always
	// either equal to or greater then the AddedDate attribute, never less than
	ModifiedDate time.Time `json:"ModifiedDate"`

	// PwnCount is the total number of accounts loaded into the system. This is usually less than the total
	// number reported by the media due to duplication or other data integrity issues in the source data
	PwnCount int `json:"PwnCount"`

	// Description contains an overview of the breach represented in HTML markup. The description may include
	// markup such as emphasis and strong tags as well as hyperlinks
	Description string `json:"Description"`

	// DataClasses describes the nature of the data compromised in the breach and contains an alphabetically ordered
	// string array of impacted data classes
	DataClasses []string `json:"DataClasses"`

	// IsVerified indicates that the breach is considered unverified. An unverified breach may not have
	// been hacked from the indicated website. An unverified breach is still loaded into HIBP when there's
	// sufficient confidence that a significant portion of the data is legitimate
	IsVerified bool `json:"IsVerified"`

	// IsFabricated indicates that the breach is considered fabricated. A fabricated breach is unlikely
	// to have been hacked from the indicated website and usually contains a large amount of manufactured
	// data. However, it still contains legitimate email addresses and asserts that the account owners
	// were compromised in the alleged breach
	IsFabricated bool `json:"IsFabricated"`

	// IsSensitive indicates if the breach is considered sensitive. The public API will not return any
	// accounts for a breach flagged as sensitive
	IsSensitive bool `json:"IsSensitive"`

	// IsRetired indicates if the breach has been retired. This data has been permanently removed and
	// will not be returned by the API
	IsRetired bool `json:"IsRetired"`

	// IsSpamList indicates
	IsSpamList bool `json:"IsSpamList"`

	// LogoPath represents a URI that specifies where a logo for the breached service can be found.
	// Logos are always in PNG format
	LogoPath string `json:"LogoPath"`
}

Breach represents a JSON response structure of the breaches API

type BreachApi added in v0.1.2 

type BreachApi struct {
	// contains filtered or unexported fields
}

BreachApi is a HIBP breaches API client

func (*BreachApi) BreachByName added in v0.1.3 

func (b *BreachApi) BreachByName(n string, options ...BreachOption) (*Breach, *http.Response, error)

BreachByName returns a single breached site based on its name

Example

ExampleBreachApi_BreachByName is a code example to show how to fetch a specific breach from the HIBP breaches API using the BreachByName method 

hc := New()
bd, _, err := hc.BreachApi.BreachByName("Adobe")
if err != nil {
	panic(err)
}
if bd != nil {
	fmt.Println("Details of the 'Adobe' breach:")
	fmt.Printf("\tDomain: %s\n", bd.Domain)
	fmt.Printf("\tBreach date: %s\n", bd.BreachDate.Time().Format("2006-01-02"))
	fmt.Printf("\tAdded to HIBP: %s\n", bd.AddedDate.String())
}

Output:

func (*BreachApi) BreachedAccount added in v0.1.4 

func (b *BreachApi) BreachedAccount(a string, options ...BreachOption) ([]*Breach, *http.Response, error)

BreachedAccount returns a single breached site based on its name

Example

ExampleBreachApi_BreachedAccount is a code example to show how to fetch a list of breaches for a specific site/account from the HIBP breaches API using the BreachedAccount method 

apiKey := os.Getenv("HIBP_API_KEY")
if apiKey == "" {
	panic("A API key is required for this API")
}
hc := New(WithApiKey(apiKey))
bd, _, err := hc.BreachApi.BreachedAccount("multiple-breaches@hibp-integration-tests.com")
if err != nil {
	panic(err)
}
for _, b := range bd {
	fmt.Printf("Your account was part of the %q breach\n", b.Name)
}

Output:

func (*BreachApi) Breaches added in v0.1.2 

func (b *BreachApi) Breaches(options ...BreachOption) ([]*Breach, *http.Response, error)

Breaches returns a list of all breaches in the HIBP system

Example (GetAllBreaches)

ExampleBreachApi_Breaches_getAllBreaches is a code example to show how to fetch all breaches from the HIBP breaches API 

hc := New()
bl, _, err := hc.BreachApi.Breaches()
if err != nil {
	panic(err)
}
if len(bl) != 0 {
	for _, b := range bl {
		fmt.Printf("Found breach:\n\tName: %s\n\tDomain: %s\n\tBreach date: %s\n\n",
			b.Name, b.Domain, b.BreachDate.Time().Format("Mon, 2. January 2006"))
	}
}

Output:
Example (GetAllBreachesNoUnverified)

ExampleBreachApi_Breaches_getAllBreachesNoUnverified is a code example to show how to fetch all breaches from the HIBP breaches API but ignoring unverified breaches 

hc := New()
bl, _, err := hc.BreachApi.Breaches()
if err != nil {
	panic(err)
}
if len(bl) != 0 {
	fmt.Printf("Found %d breaches total.\n", len(bl))
}

bl, _, err = hc.BreachApi.Breaches(WithoutUnverified())
if err != nil {
	panic(err)
}
if len(bl) != 0 {
	fmt.Printf("Found %d verified breaches total.\n", len(bl))
}

Output:

func (*BreachApi) DataClasses added in v0.1.4 

func (b *BreachApi) DataClasses() ([]string, *http.Response, error)

DataClasses are attribute of a record compromised in a breach. This method returns a list of strings with all registered data classes known to HIBP

type BreachOption added in v0.1.2 

type BreachOption func(*BreachApi)

BreachOption is an additional option the can be set for the BreachApiClient

func WithDomain added in v0.1.2 

func WithDomain(d string) BreachOption

WithDomain sets the domain filter for the breaches API

func WithoutTruncate added in v0.1.2 

func WithoutTruncate() BreachOption

WithoutTruncate disables the truncateResponse parameter in the breaches API This option only influences the BreachedAccount method

func WithoutUnverified added in v0.1.3 

func WithoutUnverified() BreachOption

WithoutUnverified suppress unverified breaches from the query

type Client added in v0.1.1 

type Client struct {
	PwnedPassApi     *PwnedPassApi         // Reference to the PwnedPassApi API
	PwnedPassApiOpts *PwnedPasswordOptions // Additional options for the PwnedPassApi API

	BreachApi *BreachApi // Reference to the BreachApi
	PasteApi  *PasteApi  // Reference to the PasteApi
	// contains filtered or unexported fields
}

Client is the HIBP client object

func New added in v0.1.1 

func New(options ...Option) Client

New creates and returns a new HIBP client object

func (*Client) HttpReq added in v0.1.1 

func (c *Client) HttpReq(m, p string, q map[string]string) (*http.Request, error)

HttpReq performs an HTTP request to the corresponding API

func (*Client) HttpResBody added in v1.0.0 

func (c *Client) HttpResBody(m string, p string, q map[string]string) ([]byte, *http.Response, error)

HttpResBody performs the API call to the given path and returns the response body as byte array

type Match added in v0.1.1 

type Match struct {
	Hash  string // SHA1 hash of the matching password
	Count int64  // Represents the number of leaked accounts that hold/held this password
}

Match represents a match in the Pwned Passwords API

type Option added in v0.1.1 

type Option func(*Client)

Option is a function that is used for grouping of Client options.

func WithApiKey added in v0.1.1 

func WithApiKey(k string) Option

WithApiKey set the optional API key to the Client object

func WithHttpTimeout added in v0.1.1 

func WithHttpTimeout(t time.Duration) Option

WithHttpTimeout overrides the default http client timeout

func WithPwnedPadding added in v0.1.2 

func WithPwnedPadding() Option

WithPwnedPadding enables padding-mode for the PwnedPasswords API client

func WithRateLimitSleep added in v1.0.0 

func WithRateLimitSleep() Option

WithRateLimitSleep let's the HTTP client sleep in case the API rate limiting hits (Defaults to fail)

func WithUserAgent added in v0.1.4 

func WithUserAgent(a string) Option

WithUserAgent sets a custom user agent string for the HTTP client

type Paste added in v1.0.0 

type Paste struct {
	// Source is the paste service the record was retrieved from. Current values are: Pastebin,
	// Pastie, Slexy, Ghostbin, QuickLeak, JustPaste, AdHocUrl, PermanentOptOut, OptOut
	Source string `json:"Source"`

	// Id of the paste as it was given at the source service. Combined with the "Source" attribute, this
	// can be used to resolve the URL of the paste
	Id string `json:"Id"`

	// Title of the paste as observed on the source site. This may be null and if so will be omitted from
	// the response
	Title string `json:"Title"`

	// Date is the date and time (precision to the second) that the paste was posted. This is taken directly
	// from the paste site when this information is available but may be null if no date is published
	Date time.Time `json:"Date"`

	// EmailCount is number of emails that were found when processing the paste. Emails are extracted by
	// using the regular expression \b[a-zA-Z0-9\.\-_\+]+@[a-zA-Z0-9\.\-_]+\.[a-zA-Z]+\b
	EmailCount int `json:"EmailCount"`
}

Paste represents a JSON response structure of the pastes API

type PasteApi added in v1.0.0 

type PasteApi struct {
	// contains filtered or unexported fields
}

PasteApi is a HIBP pastes API client

func (*PasteApi) PastedAccount added in v1.0.0 

func (p *PasteApi) PastedAccount(a string) ([]*Paste, *http.Response, error)

PastedAccount returns a single breached site based on its name

Example

ExamplePasteApi_PastedAccount is a code example to show how to fetch a specific paste based on its name from the HIBP pastes API using the PastedAccount() method 

apiKey := os.Getenv("HIBP_API_KEY")
if apiKey == "" {
	panic("A API key is required for this API")
}
hc := New(WithApiKey(apiKey))
pd, _, err := hc.PasteApi.PastedAccount("account-exists@hibp-integration-tests.com")
if err != nil {
	panic(err)
}
for _, p := range pd {
	fmt.Printf("Your account was part of the %q paste\n", p.Title)
}

Output:

type PwnedPassApi added in v0.1.2 

type PwnedPassApi struct {
	// contains filtered or unexported fields
}

PwnedPassApi is a HIBP Pwned Passwords API client

func (*PwnedPassApi) CheckPassword added in v0.1.2 

func (p *PwnedPassApi) CheckPassword(pw string) (*Match, *http.Response, error)

CheckPassword checks the Pwned Passwords database against a given password string

Example

ExamplePwnedPassApi_CheckPassword is a code example to show how to check a given password against the HIBP passwords API 

hc := New()
m, _, err := hc.PwnedPassApi.CheckPassword("test")
if err != nil {
	panic(err)
}
if m != nil && m.Count != 0 {
	fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
		m.Hash, m.Count)
	

Output:

Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB
Example (WithPadding)

ExamplePwnedPassApi_CheckPassword_withPadding is a code example to show how to check a given password against the HIBP passwords API with the WithPadding() option set 

hc := New(WithPwnedPadding())
m, _, err := hc.PwnedPassApi.CheckPassword("test")
if err != nil {
	panic(err)
}
if m != nil && m.Count != 0 {
	fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
		m.Hash, m.Count)
	

Output:

Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB

func (*PwnedPassApi) CheckSHA1 added in v0.1.2 

func (p *PwnedPassApi) CheckSHA1(h string) (*Match, *http.Response, error)

CheckSHA1 checks the Pwned Passwords database against a given SHA1 checksum of a password string

Example

ExamplePwnedPassApi_CheckSHA1 is a code example to show how to check a given password SHA1 hash against the HIBP passwords API using the CheckSHA1() method 

hc := New()
pwHash := "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" // represents the PW: "test"
m, _, err := hc.PwnedPassApi.CheckSHA1(pwHash)
if err != nil {
	panic(err)
}
if m != nil && m.Count != 0 {
	fmt.Printf("Your password with the hash %q was found %d times in the pwned passwords DB\n",
		m.Hash, m.Count)
	

Output:

Your password with the hash "a94a8fe5ccb19ba61c4c0873d391e987982fbbd3" was found 86453 times in the pwned passwords DB

func (*PwnedPassApi) ListHashesPassword added in v1.0.3 

func (p *PwnedPassApi) ListHashesPassword(pw string) ([]Match, *http.Response, error)

ListHashesPassword checks the Pwned Password API endpoint for all hashes based on a given password string and returns the a slice of Match as well as the http.Response

NOTE: If the `WithPwnedPadding` option is set to true, the returned list will be padded and might contain junk data

func (*PwnedPassApi) ListHashesPrefix added in v1.0.3 

func (p *PwnedPassApi) ListHashesPrefix(pf string) ([]Match, *http.Response, error)

ListHashesPrefix checks the Pwned Password API endpoint for all hashes based on a given SHA1 checksum prefix and returns the a slice of Match as well as the http.Response

NOTE: If the `WithPwnedPadding` option is set to true, the returned list will be padded and might contain junk data

func (*PwnedPassApi) ListHashesSHA1 added in v1.0.3 

func (p *PwnedPassApi) ListHashesSHA1(h string) ([]Match, *http.Response, error)

ListHashesSHA1 checks the Pwned Password API endpoint for all hashes based on a given SHA1 checksum and returns the a slice of Match as well as the http.Response

NOTE: If the `WithPwnedPadding` option is set to true, the returned list will be padded and might contain junk data

type PwnedPasswordOptions added in v0.1.2 

type PwnedPasswordOptions struct {
	// WithPadding controls if the PwnedPassword API returns with padding or not
	// See: https://haveibeenpwned.com/API/v3#PwnedPasswordsPadding
	WithPadding bool
}

PwnedPasswordOptions is a struct of additional options for the PP API

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.