Merge pull request #1 from wneessen/breaches

v0.1.2: Introducing Breaches

breach.go

@@ -0,0 +1,184 @@
+package hibp
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+)
+
+// BreachApi is a HIBP breaches API client
+type BreachApi struct {
+	hibp *Client // References back to the parent HIBP client
+
+	domain       string // Filter for a specific breach domain
+	disableTrunc bool   // Controls the truncateResponse parameter for the breaches API (defaults to false)
+	noUnverified bool   // Controls the includeUnverified parameter for the breaches API (defaults to false)
+}
+
+// Breach represents a JSON response structure of the breaches API
+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"`
+}
+
+// BreachOption is an additional option the can be set for the BreachApiClient
+type BreachOption func(*BreachApi)
+
+// ApiDate is a date string without time returned by the API represented as time.Time type
+type ApiDate time.Time
+
+// Breaches returns a list of all breaches in the HIBP system
+func (b *BreachApi) Breaches(options ...BreachOption) ([]*Breach, *http.Response, error) {
+	queryParms := map[string]string{
+		"truncateResponse":  "true",
+		"includeUnverified": "true",
+	}
+	apiUrl := fmt.Sprintf("%s/breaches", BaseUrl)
+
+	for _, opt := range options {
+		opt(b)
+	}
+
+	if b.domain != "" {
+		queryParms["domain"] = b.domain
+	}
+
+	if b.disableTrunc {
+		queryParms["truncateResponse"] = "false"
+	}
+
+	if b.noUnverified {
+		queryParms["includeUnverified"] = "false"
+	}
+
+	hreq, err := b.hibp.HttpReq(http.MethodGet, apiUrl, queryParms)
+	if err != nil {
+		return nil, nil, err
+	}
+	hr, err := b.hibp.hc.Do(hreq)
+	if err != nil {
+		return nil, hr, err
+	}
+	if hr.StatusCode != 200 {
+		return nil, hr, fmt.Errorf("API responded with non HTTP-200: %s", hr.Status)
+	}
+	defer func() {
+		_ = hr.Body.Close()
+	}()
+
+	hb, err := io.ReadAll(hr.Body)
+	if err != nil {
+		return nil, hr, err
+	}
+
+	var breachList []*Breach
+	if err := json.Unmarshal(hb, &breachList); err != nil {
+		return nil, hr, err
+	}
+
+	return breachList, hr, nil
+}
+
+// WithDomain sets the domain filter for the breaches API
+func WithDomain(d string) BreachOption {
+	return func(b *BreachApi) {
+		b.domain = d
+	}
+}
+
+// WithoutTruncate disables the truncateResponse parameter in the breaches API
+func WithoutTruncate() BreachOption {
+	return func(b *BreachApi) {
+		b.disableTrunc = true
+	}
+}
+
+// UnmarshalJSON for the ApiDate type converts a give date string into a time.Time type
+func (d *ApiDate) UnmarshalJSON(s []byte) error {
+	ds := string(s)
+	ds = strings.ReplaceAll(ds, `"`, ``)
+	if ds == "null" {
+		return nil
+	}
+
+	pd, err := time.Parse("2006-01-02", ds)
+	if err != nil {
+		return fmt.Errorf("failed to convert API date string to time.Time type: %s", err)
+	}
+
+	*(*time.Time)(d) = pd
+	return nil
+}
+
+// Time adds a Time() method to the ApiDate converted time.Time type
+func (d ApiDate) Time() time.Time {
+	return time.Time(d)
+}

breach_test.go

@@ -0,0 +1,64 @@
+package hibp
+
+import (
+	"testing"
+)
+
+// TestBreaches tests the Breaches() method of the breaches API
+func TestBreaches(t *testing.T) {
+	hc := New()
+	if hc == nil {
+		t.Errorf("hibp client creation failed")
+		return
+	}
+
+	breachList, _, err := hc.BreachApi.Breaches()
+	if err != nil {
+		t.Error(err)
+	}
+	if breachList != nil && len(breachList) <= 0 {
+		t.Error("breaches list returned 0 results")
+	}
+}
+
+// TestBreachesWithDomain tests the Breaches() method of the breaches API for a specific domain
+func TestBreachesWithDomain(t *testing.T) {
+	testTable := []struct {
+		testName   string
+		domain     string
+		isBreached bool
+	}{
+		{"adobe.com is breached", "adobe.com", true},
+		{"example.com is not breached", "example.com", false},
+	}
+
+	hc := New()
+	if hc == nil {
+		t.Error("failed to create HIBP client")
+		return
+	}
+
+	for _, tc := range testTable {
+		t.Run(tc.testName, func(t *testing.T) {
+			breachList, _, err := hc.BreachApi.Breaches(WithDomain(tc.domain))
+			if err != nil {
+				t.Error(err)
+			}
+
+			if breachList == nil && tc.isBreached {
+				t.Errorf("domain %s is expected to be breached, but returned 0 results.",
+					tc.domain)
+			}
+
+			breachLen := len(breachList)
+			if tc.isBreached && breachLen <= 0 {
+				t.Errorf("domain %s is expected to be breached, but returned 0 results.",
+					tc.domain)
+			}
+			if !tc.isBreached && breachLen != 0 {
+				t.Errorf("domain %s is expected to be not breached, but returned %d results.",
+					tc.domain, breachLen)
+			}
+		})
+	}
+}

hibp.go

@@ -1,15 +1,20 @@
 package hibp
 
 import (
+	"bytes"
 	"crypto/tls"
 	"fmt"
+	"io"
 	"net/http"
 	"net/url"
 	"time"
 )
 
 // Version represents the version of this package
-const Version = "0.1.1"
+const Version = "0.1.2"
+
+// BaseUrl is the base URL for the majority of API calls
+const BaseUrl = "https://haveibeenpwned.com/api/v3"
 
 // Client is the HIBP client object
 type Client struct {
@@ -17,7 +22,10 @@ type Client struct {
 	to time.Duration // HTTP client timeout
 	ak string        // HIBP API key
 
-	PwnedPassword *PwnedPassword // Reference to the PwnedPassword API
+	PwnedPassApi     *PwnedPassApi         // Reference to the PwnedPassApi API
+	PwnedPassApiOpts *PwnedPasswordOptions // Additional options for the PwnedPassApi API
+
+	BreachApi *BreachApi // Reference to the BreachApi API
 }
 
 // Option is a function that is used for grouping of Client options.
@@ -29,6 +37,7 @@ func New(options ...Option) *Client {
 
 	// Set defaults
 	c.to = time.Second * 5
+	c.PwnedPassApiOpts = &PwnedPasswordOptions{}
 
 	// Set additional options
 	for _, opt := range options {
@@ -39,7 +48,8 @@ func New(options ...Option) *Client {
 	c.hc = httpClient(c.to)
 
 	// Associate the different HIBP service APIs with the Client
-	c.PwnedPassword = &PwnedPassword{hc: c}
+	c.PwnedPassApi = &PwnedPassApi{hibp: c}
+	c.BreachApi = &BreachApi{hibp: c}
 
 	return c
 }
@@ -58,22 +68,52 @@ func WithApiKey(k string) Option {
 	}
 }
 
+// WithPwnedPadding enables padding-mode for the PwnedPasswords API client
+func WithPwnedPadding() Option {
+	return func(c *Client) {
+		c.PwnedPassApiOpts.WithPadding = true
+	}
+}
+
 // HttpReq performs an HTTP request to the corresponding API
-func (c *Client) HttpReq(m, p string) (*http.Request, error) {
+func (c *Client) HttpReq(m, p string, q map[string]string) (*http.Request, error) {
 	u, err := url.Parse(p)
 	if err != nil {
 		return nil, err
 	}
 
+	if m == http.MethodGet {
+		uq := u.Query()
+		for k, v := range q {
+			uq.Add(k, v)
+		}
+		u.RawQuery = uq.Encode()
+	}
+
 	hr, err := http.NewRequest(m, u.String(), nil)
 	if err != nil {
 		return nil, err
 	}
+
+	if m == http.MethodPost {
+		pd := url.Values{}
+		for k, v := range q {
+			pd.Add(k, v)
+		}
+
+		rb := io.NopCloser(bytes.NewBufferString(pd.Encode()))
+		hr.Body = rb
+	}
+
 	hr.Header.Set("Accept", "application/json")
 	hr.Header.Set("User-Agent", fmt.Sprintf("go-hibp v%s - https://github.com/wneessen/go-hibp", Version))
 
 	if c.ak != "" {
-		hr.Header["hibp-api-key"] = []string{c.ak}
+		hr.Header.Set("hibp-api-key", c.ak)
+	}
+
+	if c.PwnedPassApiOpts.WithPadding {
+		hr.Header.Set("Add-Padding", "true")
 	}
 
 	return hr, nil

hibp_test.go

@@ -1,6 +1,7 @@
 package hibp
 
 import (
+	"os"
 	"testing"
 	"time"
 )
@@ -13,7 +14,7 @@ func TestNew(t *testing.T) {
 	}
 }
 
-// TestNewWithHttpTimeout tests the New() function
+// TestNewWithHttpTimeout tests the New() function with the http timeout option
 func TestNewWithHttpTimeout(t *testing.T) {
 	hc := New(WithHttpTimeout(time.Second * 10))
 	if hc == nil {
@@ -25,3 +26,30 @@ func TestNewWithHttpTimeout(t *testing.T) {
 			time.Second*10, hc.to)
 	}
 }
+
+// TestNewWithPwnedPadding tests the New() function with the PwnedPadding option
+func TestNewWithPwnedPadding(t *testing.T) {
+	hc := New(WithPwnedPadding())
+	if hc == nil {
+		t.Errorf("hibp client creation failed")
+		return
+	}
+	if !hc.PwnedPassApiOpts.WithPadding {
+		t.Errorf("hibp client pwned padding option was not set properly. Expected %v, got: %v",
+			true, hc.PwnedPassApiOpts.WithPadding)
+	}
+}
+
+// TestNewWithApiKey tests the New() function with the API key set
+func TestNewWithApiKey(t *testing.T) {
+	apiKey := os.Getenv("HIBP_API_KEY")
+	hc := New(WithApiKey(apiKey))
+	if hc == nil {
+		t.Errorf("hibp client creation failed")
+		return
+	}
+	if hc.ak != apiKey {
+		t.Errorf("hibp client API key was not set properly. Expected %s, got: %s",
+			apiKey, hc.ak)
+	}
+}

password.go

@@ -9,25 +9,32 @@ import (
 	"strings"
 )
 
-// PwnedPassword is a HIBP Pwned Passwords API client
-type PwnedPassword struct {
-	hc *Client
+// PwnedPassApi is a HIBP Pwned Passwords API client
+type PwnedPassApi struct {
+	hibp *Client // References back to the parent HIBP client
 }
 
 // Match represents a match in the Pwned Passwords API
 type Match struct {
-	Hash  string
-	Count int64
+	Hash  string // SHA1 hash of the matching password
+	Count int64  // Represents the number of leaked accounts that hold/held this password
+}
+
+// PwnedPasswordOptions is a struct of additional options for the PP API
+type PwnedPasswordOptions struct {
+	// WithPadding controls if the PwnedPassword API returns with padding or not
+	// See: https://haveibeenpwned.com/API/v3#PwnedPasswordsPadding
+	WithPadding bool
 }
 
 // CheckPassword checks the Pwned Passwords database against a given password string
-func (p *PwnedPassword) CheckPassword(pw string) (*Match, *http.Response, error) {
+func (p *PwnedPassApi) CheckPassword(pw string) (*Match, *http.Response, error) {
 	shaSum := fmt.Sprintf("%x", sha1.Sum([]byte(pw)))
 	return p.CheckSHA1(shaSum)
 }
 
 // CheckSHA1 checks the Pwned Passwords database against a given SHA1 checksum of a password
-func (p *PwnedPassword) CheckSHA1(h string) (*Match, *http.Response, error) {
+func (p *PwnedPassApi) CheckSHA1(h string) (*Match, *http.Response, error) {
 	pwMatches, hr, err := p.apiCall(h)
 	if err != nil {
 		return &Match{}, hr, err
@@ -44,13 +51,14 @@ func (p *PwnedPassword) CheckSHA1(h string) (*Match, *http.Response, error) {
 
 // apiCall performs the API call to the Pwned Password API endpoint and returns
 // the http.Response
-func (p *PwnedPassword) apiCall(h string) ([]Match, *http.Response, error) {
+func (p *PwnedPassApi) apiCall(h string) ([]Match, *http.Response, error) {
 	sh := h[:5]
-	hreq, err := p.hc.HttpReq(http.MethodGet, fmt.Sprintf("https://api.pwnedpasswords.com/range/%s", sh))
+	hreq, err := p.hibp.HttpReq(http.MethodGet, fmt.Sprintf("https://api.pwnedpasswords.com/range/%s", sh),
+		nil)
 	if err != nil {
 		return nil, nil, err
 	}
-	hr, err := p.hc.hc.Do(hreq)
+	hr, err := p.hibp.hc.Do(hreq)
 	if err != nil {
 		return nil, nil, err
 	}

password_test.go

@@ -19,7 +19,7 @@ func TestPwnedPasswordString(t *testing.T) {
 
 	for _, tc := range testTable {
 		t.Run(tc.testName, func(t *testing.T) {
-			m, _, err := hc.PwnedPassword.CheckPassword(tc.pwString)
+			m, _, err := hc.PwnedPassApi.CheckPassword(tc.pwString)
 			if err != nil {
 				t.Error(err)
 			}
@@ -47,12 +47,17 @@ func TestPwnedPasswordHash(t *testing.T) {
 			"90efc095c82eab44e882fda507cfab1a2cd31fc0", false},
 	}
 	hc := New()
+	if hc == nil {
+		t.Error("failed to create HIBP client")
+		return
+	}
 
 	for _, tc := range testTable {
 		t.Run(tc.testName, func(t *testing.T) {
-			m, _, err := hc.PwnedPassword.CheckSHA1(tc.pwHash)
+			m, _, err := hc.PwnedPassApi.CheckSHA1(tc.pwHash)
 			if err != nil {
 				t.Error(err)
+				return
 			}
 			if m == nil && tc.isLeaked {
 				t.Errorf("password is expected to be leaked but 0 leaks were returned in Pwned Passwords DB")