observatory

README

Observatory

A small and convenient Go client to consume HTTP Observatory api.

Install:

go get -u github.com/tigerwill90/observatory

Example

c := observatory.NewClient()
result, err := c.Analyze(context.TODO(), "observatory.mozilla.org", option.ForceRescan(true), option.WaitFinished(true, 5*time.Second))
if err != nil {
    panic(err)
}
fmt.Printf("Grade: %s, Score: %d\n", result.Grade, result.Score)
// Grade: A+, Score: 125

detail, err := c.GetTestResults(context.TODO(), result.ScanID)
if err != nil {
    panic(err)
}

fmt.Printf(
    "Name: %s, Pass: %t, Expectation: %s\n",
    detail.ContentSecurityPolicy.Name,
    detail.ContentSecurityPolicy.Pass,
    detail.ContentSecurityPolicy.Expectation,
)
// Name: content-security-policy, Pass: true, Expectation: csp-implemented-with-no-unsafe

Disclaimer

Breaking change may happen before v1.0.0.

Documentation

Overview

Package observatory provide a small client to consume HTTP Observatory api, which is used to test the state of security for websites on the public internet.

Example (Analyze)

c := NewClient()
result, err := c.Analyze(context.TODO(), "observatory.mozilla.org", option.ForceRescan(true), option.WaitFinished(true, 5*time.Second))
if err != nil {
	panic(err)
}
fmt.Printf("Grade: %s, Score: %d\n", result.Grade, result.Score)

detail, err := c.GetTestResults(context.TODO(), result.ScanID)
if err != nil {
	panic(err)
}

fmt.Printf(
	"Name: %s, Pass: %t, Expectation: %s\n",
	detail.ContentSecurityPolicy.Name,
	detail.ContentSecurityPolicy.Pass,
	detail.ContentSecurityPolicy.Expectation,
)

Output:
Grade: A+, Score: 125
Name: content-security-policy, Pass: true, Expectation: csp-implemented-with-no-unsafe

Index

• Constants
• Variables
• type Client
  • func NewClient() *Client
  • func NewCustomClient(c *http.Client, url string) *Client
  • func (c *Client) Analyze(ctx context.Context, host string, opts ...option.Option) (*types.ScannerResult, error)
  • func (c *Client) GetAssessment(ctx context.Context, host string) (*types.ScannerResult, error)
  • func (c *Client) GetGradeDistribution(ctx context.Context) (*types.ScannerGradeDistribution, error)
  • func (c *Client) GetRecentScans(ctx context.Context, opt option.ScanOption) (types.ScannerRecentScans, error)
  • func (c *Client) GetScanHistory(ctx context.Context, host string) ([]*types.ScannerHostHistory, error)
  • func (c *Client) GetTestResults(ctx context.Context, scanID types.ScanID) (*types.ScannerTestResult, error)

Examples

• Package (Analyze)

Constants

const (
	Aborted  = "ABORTED"
	Failed   = "FAILED"
	Finished = "FINISHED"
	Pending  = "PENDING"
	Starting = "STARTING"
	Running  = "RUNNING"
)

const (
	ApiCallGetGradeDistribution = "getGradeDistribution"
	ApiCallAnalyze              = "analyze"
	ApiCallGetScanResults       = "getScanResults"
	ApiCallGetHostHistory       = "getHostHistory"
	ApiCallGetRecentScans       = "getRecentScans"
)

const Endpoint = "https://http-observatory.security.mozilla.org/api/v1"

Variables

var (
	ErrScannerAborted = errors.New("scan aborted")
	ErrScannerFailed  = errors.New("scan failed")
)

Types

type Client

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

Client is an http.Client wrapper for HTTP Observatory api.

func NewClient

func NewClient() *Client

NewClient return a preconfigured HTTP Observatory client. Use NewCustomClient to use an existing http.Client.

func NewCustomClient

func NewCustomClient(c *http.Client, url string) *Client

NewCustomClient return an HTTP Observatory client from an http.Client and an url.

func (*Client) Analyze

func (c *Client) Analyze(ctx context.Context, host string, opts ...option.Option) (*types.ScannerResult, error)

Analyze is used to invoke a new scan of a website. By default, Analyze will return a cached site result if the site has been scanned anytime in the previous 24 hours. Use option.ForceRescan to ignore cached result and start a new scan. Regardless of the state of option.ForceRescan, HTTP Observatory can not be scanned at a frequency greater than every 3 minutes and Analyze will return a cached result if it is the case. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#invoke-assessment

func (*Client) GetAssessment

func (c *Client) GetAssessment(ctx context.Context, host string) (*types.ScannerResult, error)

GetAssessment is used to retrieve the results of an existing, ongoing or completed scan. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#retrieve-assessment

func (*Client) GetGradeDistribution

func (c *Client) GetGradeDistribution(ctx context.Context) (*types.ScannerGradeDistribution, error)

GetGradeDistribution retrieve each possible grade in the HTTP Observatory, as well as how many scans have fallen into that grade. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#retrieve-overall-grade-distribution

func (*Client) GetRecentScans

func (c *Client) GetRecentScans(ctx context.Context, opt option.ScanOption) (types.ScannerRecentScans, error)

GetRecentScans retrieve the ten most recent scans that fall withing a given score range. Use option.WithMaxScore to set the upper limit or option.WithMinScore to set the lower limit. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#retrieve-recent-scans

func (*Client) GetScanHistory

func (c *Client) GetScanHistory(ctx context.Context, host string) ([]*types.ScannerHostHistory, error)

GetScanHistory retrieve the ten most recent scans for the given host. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#retrieve-hosts-scan-history

func (*Client) GetTestResults

func (c *Client) GetTestResults(ctx context.Context, scanID types.ScanID) (*types.ScannerTestResult, error)

GetTestResults returns the detailed test result of a scan. The results of all these tests can bet retrieved once the scan's state has been placed in the FINISHED state. https://github.com/mozilla/http-observatory/blob/master/httpobs/docs/api.md#retrieve-test-results