ssllabs

package module
v0.14.2 Latest Latest
Warning

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

 Go to latest Published: Dec 3, 2019 License: BSD-2-Clause-Views Imports: 9 Imported by: 3

README

ssllabs

GitHub release GitHub issues Go Version Build Status GoDoc SemVer License Go Report Card

Go wrapper for the SSLLabs API for testing TLS parameters of a given website.

Requirements

  • Go >= 1.10

github.com/keltia/ssllabs is a Go module (you can use either Go 1.10 with vgo or 1.11+). The API exposed follows the Semantic Versioning scheme to guarantee a consistent API compatibility.

  • jq (optional) — you can find it there

Installation

You need to install this module if you are using Go 1.10.x or earlier.

go get github.com/keltia/proxy

With Go 1.11+ and its modules support, it should work out of the box with

go get github.com/keltia/ssllabs/cmd/...

if you have the GO111MODULE environment variable set on on.

USAGE

There is a small example program included in cmd/ssllabs to either show the grade of a given site or JSON dump of the detailed report.

You can use jq to display the output of ssllabs -d <site> in a colorised way:

ssllabs -d www.ssllabs.com | jq .

API Usage

As with many API wrappers, you will need to first create a client with some optional configuration, then there are two main functions:

    // Simplest way
    c, _ := ssllabs.NewClient()
    grade, err := c.GetScore("example.com")
    if err != nil {
        log.Fatalf("error: %v", err)
    }

With options:

    // With some options, timeout at 15s, caching for 10s and debug-like verbosity
    cnf := ssllabs.Config{
        Timeout:15,
        Retries:3,
        Log:2,
    }
    c, err := ssllabs.NewClient(cnf)
    report, err := c.GetScore("example.com")
    if err != nil {
        log.Fatalf("error: %v", err)
    }

OPTIONS

Option Type Description
Timeout int time for connections (default: 10s)
Log int 1: verbose, 2: debug (default: 0)
Retries int Number of retries when not FINISHED (default: 5)
Refresh bool Force refresh of the sites (default: false)
Force bool Force SSLLabs to rescan the site (default: false)

The easiest call is GetGrade:

    grade, err := c.GetGrade("ssllabs.com")
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    fmt.Printf("Grade for ssllabs.com: %s\n", grade)

For the Analyze() & GetEndpointData calls, the raw JSON object will be returned (and presumably handled by jq).

    // Simplest way
    c, _ := ssllabs.NewClient()
    report, err := c.Analyze("example.com")
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    fmt.Printf("Full report:\n%v\n", report)

Most of the calls can have some options modified from the defaults by passing a second parameter as a map:

    opts["fromCache"] = "on"

    grade, err := c.GetGrade("ssllabs.com", opts)
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    fmt.Printf("Grade for ssllabs.com: %s\n", grade)

You also have the more general (i.e. not tied to a site) calls:

GetStatusCodes():

    scodes, err := c.GetStatusCodes()
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    fmt.Printf("Full status codes:\n%v\n", scodes)

Info():

    info, err := c.Info()
    if err != nil {
        log.Fatalf("error: %v", err)
    }
    fmt.Printf("SSLLabs Engine version:\n%s\n", info.EngineVersion)

Using behind a web Proxy

Dependency: proxy support is provided by my github.com/keltia/proxy module.

UNIX/Linux:

    export HTTP_PROXY=[http://]host[:port] (sh/bash/zsh)
    setenv HTTP_PROXY [http://]host[:port] (csh/tcsh)

Windows:

    set HTTP_PROXY=[http://]host[:port]

The rules of Go's ProxyFromEnvironment apply (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, lowercase variants allowed).

If your proxy requires you to authenticate, please create a file named .netrc in your HOME directory with permissions either 0400 or 0600 with the following data:

machine proxy user <username> password <password>

and it should be picked up. On Windows, the file will be located at

%LOCALAPPDATA%\ssllabs\netrc

License

The BSD 2-Clause license.

Contributing

This project is an open Open Source project, please read CONTRIBUTING.md.

References

SSLLabs API documentation

Feedback

We welcome pull requests, bug fixes and issue reports.

Before proposing a large change, first please discuss your change by raising an issue.

Documentation

Overview

Package ssllabs contains SSLLabs-related functions.

Package ssllabs These are the types used by SSLLabs/Qualys

This is for API v3

Index

Constants

View Source 
const (

	// DefaultWait is the timeout
	DefaultWait = 10 * time.Second

	// DefaultRetry is the number of retries we allow
	DefaultRetry = 5

	// MyVersion is the API version
	MyVersion = "0.14.2"

	// MyName is the name used for the configuration
	MyName = "ssllabs"
)
View Source 
const (
	HttpRetryLater = 529
)

Variables

This section is empty.

Functions

func AddQueryParameters 

func AddQueryParameters(baseURL string, queryParams map[string]string) string

AddQueryParameters adds query parameters to the URL.

func Version 

func Version() string

Version returns the API wrapper info

Types

type CaaPolicy added in v0.2.0 

type CaaPolicy struct {
	PolicyHostname string      `json:"policyHostname"`
	CaaRecords     []CaaRecord `json:"caaRecords"`
}

CaaPolicy is the policy around CAA usage

type CaaRecord added in v0.2.0 

type CaaRecord struct {
	Tag   string
	Value string
	Flags int
}

CaaRecord describe the DNS CAA record content

type Cert added in v0.2.0 

type Cert struct {
	ID                     string
	Subject                string
	SerialNumber           string    `json:"serialNumber"`
	CommonNames            []string  `json:"commonNames"`
	AltNames               []string  `json:"altNames"`
	NotBefore              int64     `json:"notBefore"`
	NotAfter               int64     `json:"notAfter"`
	IssuerSubject          string    `json:"issuerSubject"`
	SigAlg                 string    `json:"sigAlg"`
	RevocationInfo         int       `json:"revocationInfo"`
	CrlURIs                []string  `json:"crlURIs"`
	OcspURIs               []string  `json:"ocspURIs"`
	RevocationStatus       int       `json:"revocationStatus"`
	CrlRevocationStatus    int       `json:"crlRevocationStatus"`
	OcspRevocationStatus   int       `json:"ocspRevocationStatus"`
	DNSCaa                 bool      `json:"dnsCaa"`
	CaaPolicy              CaaPolicy `json:"caaPolicy"`
	MustStaple             bool      `json:"mustStaple"`
	Sgc                    int
	ValidationType         string `json:"validationType"`
	Issues                 int
	Sct                    bool
	SHA1Hash               string `json:"sha1Hash"`
	SHA256Hash             string `json:"sha256Hash"`
	PinSHA256              string `json:"pinSha256"`
	KeyAlg                 string `json:"keyAlg"`
	KeySize                int    `json:"keySize"`
	KeyStrength            int    `json:"keyStrength"`
	KeyKnownDebianInsecure bool   `json:"keyKnownDebianInsecure"`
	Raw                    string `json:"raw"`
}

Cert describes an X.509 certificate

type CertificateChain added in v0.2.0 

type CertificateChain struct {
	ID         string
	CertIds    []string    `json:"certIds"`
	Trustpaths []TrustPath `json:"trustpaths"`
	Issues     int
	NoSni      bool `json:"noSni"`
}

CertificateChain is the list of certificates

type Client 

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

Client is the main datatype for requests

func NewClient 

func NewClient(cnf ...Config) (*Client, error)

NewClient create the context for new connections

func (*Client) Analyze 

func (c *Client) Analyze(site string, force bool, myopts ...map[string]string) (*Host, error)

Analyze submit the given host for checking

func (*Client) GetDetailedReport 

func (c *Client) GetDetailedReport(site string, myopts ...map[string]string) (Host, error)

GetDetailedReport returns the full report

func (*Client) GetEndpointData 

func (c *Client) GetEndpointData(site string, myopts ...map[string]string) (*Endpoint, error)

GetEndpointData returns the endpoint data, no analyze run if not available

func (*Client) GetGrade 

func (c *Client) GetGrade(site string, myopts ...map[string]string) (string, error)

GetGrade is the basic call — equal to getEndpointData and extracting just the grade.

func (*Client) GetStatusCodes 

func (c *Client) GetStatusCodes() (*StatusCodes, error)

GetStatusCodes returns all codes & their translation

func (*Client) Info 

func (c *Client) Info() (*Info, error)

Info implements the Info() API call

type Config 

type Config struct {
	BaseURL string
	Log     int
	Timeout int
	Retries int
	Force   bool // set fromCache to "off"
}

Config is for the client configuration

type DrownHost added in v0.2.0 

type DrownHost struct {
	IP      string `json:"ip"`
	Export  bool
	Port    int
	Special bool
	SSLv2   bool `json:"sslv2"`
	Status  string
}

DrownHost describes a potentially Drown-weak site

type Endpoint added in v0.2.0 

type Endpoint struct {
	IPAddress            string `json:"ipAddress"`
	ServerName           string `json:"serverName"`
	StatusMessage        string `json:"statusMessage"`
	StatusDetails        string `json:"statusDetails"`
	StatusDetailsMessage string `json:"statusDetailsMessage"`
	Grade                string
	GradeTrustIgnored    string `json:"gradeTrustIgnored"`
	FutureGrade          string `json:"futureGrade"`
	HasWarnings          bool   `json:"hasWarnings"`
	IsExceptional        bool   `json:"isExceptional"`
	Progress             int
	Duration             int
	Eta                  int
	Delegation           int
	Details              EndpointDetails `json:"details,omitempty"`
}

Endpoint is an Endpoint (IPv4, IPv6)

type EndpointDetails added in v0.2.0 

type EndpointDetails struct {
	HostStartTime                  int64              `json:"hostStartTime"`
	CertChains                     []CertificateChain `json:"certChains"`
	Protocols                      []Protocol
	Suites                         []ProtocolSuites
	NoSniSuites                    ProtocolSuites `json:"noSniSuites"`
	NamedGroups                    NamedGroups    `json:"namedGroups"`
	ServerSignature                string         `json:"serverSignature"`
	PrefixDelegation               bool           `json:"prefixDelegation"`
	NonPrefixDelegation            bool           `json:"nonPrefixDelegation"`
	VulnBeast                      bool           `json:"vulnBeast"`
	RenegSupport                   int            `json:"renegSupport"`
	SessionResumption              int            `json:"sessionResumption"`
	CompressionMethods             int            `json:"compressionMethods"`
	SupportsNpn                    bool           `json:"supportsNpn"`
	NpnProcotols                   string         `json:"npnProtocols"`
	SupportsAlpn                   bool           `json:"supportsAlpn"`
	AlpnProtocols                  string
	SessionTickets                 int    `json:"sessionTickets"`
	OcspStapling                   bool   `json:"ocspStapling"`
	StaplingRevocationStatus       int    `json:"staplingRevocationStatus"`
	StaplingRevocationErrorMessage string `json:"staplingRevocationErrorMessage"`
	SniRequired                    bool   `json:"sniRequired"`
	HTTPStatusCode                 int    `json:"httpStatusCode"`
	HTTPForwarding                 string `json:"httpForwarding"`
	SupportsRC4                    bool   `json:"supportsRc4"`
	RC4WithModern                  bool   `json:"rc4WithModern"`
	RC4Only                        bool   `json:"rc4Only"`
	ForwardSecrecy                 int    `json:"forwardSecrecy"`
	ProtocolIntolerance            int    `json:"protocolIntolerance"`
	MiscIntolerance                int    `json:"miscIntolerance"`
	Sims                           SimDetails
	Heartbleed                     bool
	Heartbeat                      bool
	OpenSSLCcs                     int `json:"openSslCcs"`
	OpenSSLLuckyMinus20            int `json:"openSSLLuckyMinus20"`
	Ticketbleed                    int `json:"ticketbleed"`
	Bleichenbacher                 int `json:"bleichenbacher"`
	ZombiePoodle                   int `json:"zombiePoodle"`
	GoldenPoodle                   int `json:"goldenPoodle"`
	ZeroLengthPaddingOracle        int `json:"zeroLengthPaddingOracle"`
	SleepingPoodle                 int `json:"sleepingPoodle"`
	Poodle                         bool
	PoodleTLS                      int  `json:"poodleTLS"`
	FallbackScsv                   bool `json:"fallbackScsv"`
	Freak                          bool
	HasSct                         int      `json:"hasSct"`
	DhPrimes                       []string `json:"dhPrimes"`
	DhUsesKnownPrimes              int      `json:"dhUsesKnownPrimes"`
	DhYsReuse                      bool     `json:"dhYsReuse"`
	EcdhParameterReuse             bool     `json:"ecdhParameterReuse"`
	Logjam                         bool
	ChaCha20Preference             bool
	HstsPolicy                     HstsPolicy        `json:"hstsPolicy"`
	HstsPreloads                   []HstsPreload     `json:"hstsPreloads"`
	HpkpPolicy                     HpkpPolicy        `json:"hpkpPolicy"`
	HpkpRoPolicy                   HpkpPolicy        `json:"hpkpRoPolicy"`
	StaticPkpPolicy                SPkpPolicy        `json:"staticPkpPolicy"`
	HTTPTransactions               []HTTPTransaction `json:"httpTransactions"`
	DrownHosts                     []DrownHost       `json:"drownHosts"`
	DrownErrors                    bool              `json:"drownErrors"`
	DrownVulnerable                bool              `json:"drownVulnerable"`
}

EndpointDetails gives the details of a given Endpoint

type HTTPHeader added in v0.2.0 

type HTTPHeader struct {
	Name  string
	Value string
}

HTTPHeader is obvious

type HTTPTransaction added in v0.2.0 

type HTTPTransaction struct {
	RequestURL        string       `json:"requestUrl"`
	StatusCode        int          `json:"statusCode"`
	RequestLine       string       `json:"requestLine"`
	RequestHeaders    []string     `json:"requestHeaders"`
	ResponseLine      string       `json:"responseLine"`
	ResponseRawHeader []string     `json:"responseRawHeader"`
	ResponseHeader    []HTTPHeader `json:"responseHeader"`
	FragileServer     bool         `json:"fragileServer"`
}

HTTPTransaction gives the entire request/response

type Host added in v0.2.0 

type Host struct {
	Host            string
	Port            int
	Protocol        string
	IsPublic        bool `json:"isPublic"`
	Status          string
	StatusMessage   string   `json:"statusMessage"`
	StartTime       int64    `json:"startTime"`
	TestTime        int64    `json:"testTime"`
	EngineVersion   string   `json:"engineVersion"`
	CriteriaVersion string   `json:"criteriaVersion"`
	CacheExpiryTime int64    `json:"cacheExpiryTime"`
	CertHostnames   []string `json:"certHostnames"`
	Endpoints       []Endpoint
	Certs           []Cert `json:"certs,omitempty"`
}

Host is a one-site report

func ParseResults 

func ParseResults(content []byte) (r []Host, err error)

ParseResults unmarshals the json payload

type Hosts added in v0.2.0 

type Hosts []Host

Hosts is a shortcut to all Host

type HpkpDirective added in v0.2.0 

type HpkpDirective struct {
	Name  string
	Value string
}

HpkpDirective is related to HPKP handling

type HpkpPin added in v0.2.0 

type HpkpPin struct {
	HashFunction string `json:"hashFunction"`
	Value        string
}

HpkpPin is for pinned keys

type HpkpPolicy added in v0.2.0 

type HpkpPolicy struct {
	Header            string
	Status            string
	Error             string
	MaxAge            int64 `json:"maxAge"`
	IncludeSubDomains bool  `json:"includeSubDomains"`
	ReportURI         string
	Pins              []HpkpPin
	MatchedPins       []HpkpPin `json:"matchedPins"`
	Directives        []HpkpDirective
}

HpkpPolicy describes the HPKP policy

type HstsPolicy added in v0.2.0 

type HstsPolicy struct {
	LongMaxAge        int64 `json:"LONG_MAX_AGE"`
	Header            string
	Status            string
	Error             string
	MaxAge            int64 `json:"maxAge"`
	IncludeSubDomains bool  `json:"includeSubDomains"`
	Preload           bool
	Directives        map[string]string
}

HstsPolicy describes the HSTS policy

type HstsPreload added in v0.2.0 

type HstsPreload struct {
	Source     string
	HostName   string `json:"hostName"`
	Status     string
	Error      string
	SourceTime int64 `json:"sourceTime"`
}

HstsPreload is for HSTS preloading

type Info 

type Info struct {
	EngineVersion        string `json:"engineVersion"`
	CriteriaVersion      string `json:"criteriaVersion"`
	MaxAssessments       int    `json:"maxAssessments"`
	CurrentAssessments   int    `json:"currentAssessments"`
	NewAssessmentCoolOff int64  `json:"newAssessmentCoolOff"`
	Messages             []string
}

Info describes the current SSLLabs engine used

type LabsError 

type LabsError struct {
	Field   string
	Message string
}

LabsError is for whatever error we get from SSLLabs

type LabsErrorResponse 

type LabsErrorResponse struct {
	ResponseErrors []LabsError `json:"errors"`
}

LabsErrorResponse is a set of errors

func (LabsErrorResponse) Error 

func (e LabsErrorResponse) Error() string

Error() implements the interface

type LabsResults 

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

LabsResults are all the result of a run w/ 1 or more sites

type NamedGroup added in v0.2.0 

type NamedGroup struct {
	ID   int
	Name string
	Bits int
}

NamedGroup is a group

type NamedGroups added in v0.2.0 

type NamedGroups struct {
	List       []NamedGroup
	Preference bool
}

NamedGroups is for groups

type Protocol added in v0.2.0 

type Protocol struct {
	ID               int `json:"id"`
	Name             string
	Version          string
	V2SuitesDisabled bool `json:"v2SuitesDisabled"`
	Q                int
}

Protocol describes the HTTP protocols

type ProtocolSuites added in v0.2.0 

type ProtocolSuites struct {
	Protocol   int
	List       []Suite
	Preference bool
}

ProtocolSuites is a set of protocols

type SPkpPolicy added in v0.2.0 

type SPkpPolicy struct {
	Status               string   `json:"status"`
	Error                string   `json:"error"`
	IncludeSubDomains    bool     `json:"includeSubDomains"`
	ReportURI            string   `json:"reportUri"`
	Pins                 []string `json:"pins"`
	MatchedPins          []string `json:"matchedPins"`
	ForbiddenPins        []string `json:"forbiddenPins"`
	MatchedForbiddenPins []string `json:"matchedForbiddenPins"`
}

SPkpPolicy descries the Static PkpPolicy

type SimClient added in v0.2.0 

type SimClient struct {
	ID          int `json:"id"`
	Name        string
	Platform    string
	Version     string
	IsReference bool `json:"isReference"`
}

SimClient is a simulated client

type SimDetails added in v0.2.0 

type SimDetails struct {
	Results []Simulation
}

SimDetails are the result of simulation

type Simulation added in v0.2.0 

type Simulation struct {
	Client         SimClient
	ErrorCode      int    `json:"errorCode"`
	ErrorMessage   string `json:"errorMessage"`
	Attempts       int
	CertChainID    string `json:"certChainId"`
	ProtocolID     int    `json:"protocolId"`
	SuiteID        int    `json:"suiteId"`
	SuiteName      string `json:"suiteName"`
	KxType         string `json:"kxType"`
	KxStrength     int    `json:"kxStrength"`
	DhBits         int    `json:"dhBits"`
	DHP            int    `json:"dhP"`
	DHG            int    `json:"dhG"`
	DHYs           int    `json:"dhYs"`
	NamedGroupBits int    `json:"namedGroupBits"`
	NamedGroupID   int    `json:"namedGroupId"`
	NamedGroupName string `json:"namedGroupName"`
	AlertType      int    `json:"alertType"`
	AlertCode      int    `json:"alertCode"`
	KeyAlg         string `json:"keyAlg"`
	KeySize        int    `json:"keySize"`
	SigAlg         string `json:"sigAlg"`
}

Simulation describes the simulation of a given client

type StatusCodes 

type StatusCodes struct {
	StatusDetails map[string]string `json:"statusDetails"`
}

StatusCodes describes all possible status code & translations

type Suite added in v0.2.0 

type Suite struct {
	ID             int `json:"id"`
	Name           string
	CipherStrength int    `json:"cipherStrength"`
	KxType         string `json:"kxType"`
	KxStrength     int    `json:"kxStrength"`
	DHP            int    `json:"dhP"`
	DHG            int    `json:"dhG"`
	DHYs           int    `json:"dhYs"`
	NamedGroupBits int    `json:"namedGroupBits"`
	NamedGroupID   int    `json:"namedGroupId"`
	NamedGroudName string `json:"namedGroupName"`
	Q              int
}

Suite describes a single protocol

type Trust added in v0.2.0 

type Trust struct {
	RootStore         string `json:"rootStore"`
	IsTrusted         bool   `json:"isTrusted"`
	TrustErrorMessage string `json:"trustErrorMessage"`
}

Trust identifies the cert store for trust

type TrustPath added in v0.2.0 

type TrustPath struct {
	CertIds       []string `json:"certIds"`
	Trust         []Trust  `json:"trust"`
	IsPinned      bool     `json:"isPinned"`
	MatchedPins   int      `json:"matchedPins"`
	UnMatchedPins int      `json:"unMatchedPins"`
}

TrustPath defines the path of trust in cert chain

Source Files

View all Source files

Directories

Path Synopsis
cmd
ssllabs command
This is just a very short example.
 This is just a very short example.

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.