checker

README

Install

At the top of your Go file:

    import "github.com/sydneyli/starttls-check/checker"

API

The most important API that we provide is checker.CheckDomain(domain string, mxHostnames []string) DomainResult; which performs all associated checks for a particular domain.

This first performs an MX lookup, then performs checks on each of the resulting hostnames. The Status of DomainResult is inherited from the check status of the MX records with the highest priority. So, the Status is set to Success only when all high priority hostnames also have the Success status.

The reason we only require the highest-priority mailservers to pass is because many deploy dummy mailservers as a spam mitigation.

We do, however, provide the check information for the additional hostnames-- they just don't affect the status of the primary domain check.

Documentation

Index

• type CheckResult
  • func (c CheckResult) Error(format string, a ...interface{}) CheckResult
  • func (c CheckResult) Failure(format string, a ...interface{}) CheckResult
  • func (c CheckResult) Success() CheckResult
  • func (c CheckResult) Warning(format string, a ...interface{}) CheckResult
• type CheckStatus
  • func SetStatus(oldStatus CheckStatus, newStatus CheckStatus) CheckStatus
• type DomainResult
  • func CheckDomain(domain string, mxHostnames []string) DomainResult
• type DomainStatus
• type HostnameResult
  • func CheckHostname(domain string, hostname string, mxHostnames []string) HostnameResult

Types

type CheckResult

type CheckResult struct {
	Name     string      `json:"name"`
	Status   CheckStatus `json:"status"`
	Messages []string    `json:"messages,omitempty"`
}

CheckResult the result of a singular check. It's agnostic to the nature of the check performed, and simply stores a reference to the check's name, a summary of what the check should do, as well as any error, failure, or warning messages associated.

func (CheckResult) Error

func (c CheckResult) Error(format string, a ...interface{}) CheckResult

Error adds an error message to this check result. The Error status will override any other existing status for this check. Typically, when a check encounters an error, it stops executing.

func (CheckResult) Failure

func (c CheckResult) Failure(format string, a ...interface{}) CheckResult

Failure adds a failure message to this check result. The Failure status will override any Status other than Error. Whenever Failure is called, the entire check is failed.

func (CheckResult) Success

func (c CheckResult) Success() CheckResult

Success simply sets the status of CheckResult to a Success. Status is set if no other status has been declared on this check.

func (CheckResult) Warning

func (c CheckResult) Warning(format string, a ...interface{}) CheckResult

Warning adds a warning message to this check result. The Warning status only supercedes the Success status.

type CheckStatus

type CheckStatus int32

CheckStatus is an enum encoding the status of the overall check.

const (
	Success CheckStatus = 0
	Warning CheckStatus = 1
	Failure CheckStatus = 2
	Error   CheckStatus = 3
)

Values for CheckStatus

func SetStatus

func SetStatus(oldStatus CheckStatus, newStatus CheckStatus) CheckStatus

SetStatus the resulting status of combining old & new. The order of priority for CheckStatus goes: Error > Failure > Warning > Success

type DomainResult

type DomainResult struct {
	// Domain being checked against.
	Domain string `json:"domain"`
	// Message if a failure or error occurs on the domain lookup level.
	Message string `json:"message,omitempty"`
	// Status of this check, inherited from the results of preferred hostnames.
	Status DomainStatus `json:"status"`
	// Results of this check, on each hostname.
	HostnameResults map[string]HostnameResult `json:"results"`
	// The list of hostnames which impact the Status of this result.
	// Determined by the hostnames with the lowest MX priority.
	PreferredHostnames []string `json:"preferred_hostnames"`
	// Expected MX hostnames supplied by the caller of CheckDomain.
	MxHostnames []string `json:"mx_hostnames,omitempty"`
	// Extra global results
	ExtraResults map[string]CheckResult `json:"extra_results,omitempty"`
}

DomainResult wraps all the results for a particular mail domain.

func CheckDomain

func CheckDomain(domain string, mxHostnames []string) DomainResult

CheckDomain performs all associated checks for a particular domain. First performs an MX lookup, then performs subchecks on each of the resulting hostnames.

The status of DomainResult is inherited from the check status of the MX records with highest priority. This check succeeds only if the hostname checks on the highest priority mailservers succeed.

`domain` is the mail domain to perform the lookup on.
`mxHostnames` is a list of expected hostnames for certificate validation.

type DomainStatus

type DomainStatus int32

const (
	DomainSuccess           DomainStatus = 0
	DomainWarning           DomainStatus = 1
	DomainFailure           DomainStatus = 2
	DomainError             DomainStatus = 3
	DomainNoSTARTTLSFailure DomainStatus = 4
	DomainCouldNotConnect   DomainStatus = 5
)

In order of precedence.

type HostnameResult

type HostnameResult struct {
	Domain      string                 `json:"domain"`
	Hostname    string                 `json:"hostname"`
	MxHostnames []string               `json:"mx_hostnames,omitempty"`
	Status      CheckStatus            `json:"status"`
	Checks      map[string]CheckResult `json:"checks"`
}

HostnameResult wraps the results of a security check against a particular hostname.

func CheckHostname

func CheckHostname(domain string, hostname string, mxHostnames []string) HostnameResult

CheckHostname performs a series of checks against a hostname for an email domain. `domain` is the mail domain that this server serves email for. `hostname` is the hostname for this server. `mxHostnames` is a list of MX patterns that `hostname` (and the associated TLS certificate)

can be valid for. If this is nil, then defaults to [`domain`, `hostname`].