Categorygithub.com/EFForg/starttls-backendchecker
package
0.0.0-20200601210633-2d6eab052d90
Repository: https://github.com/efforg/starttls-backend.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
19
Dependents
6
Files
865 SLOC

# README

STARTTLS Check

Evaluates an @mail domain on how secure its TLS settings are. First retrieves all MX records for the domain, then performs a series of checks on each discovered hostname's port 25.

If $HOSTNAME environment variable is set, this is used in the SMTP hello.

What does it check?

For each hostname found via a MX lookup, we check:

  • Can connect (over SMTP) on port 25
  • STARTTLS support
  • Presents a valid certificate
  • TLS version up-to-date
  • Secure TLS ciphers

Build

As a library

go get github.com/efforg/starttls-backend/checker

or if you want to use it as a bin command

go get github.com/efforg/starttls-backend/checker/cmd/starttls-check

NOTE: many ISPs block outbound port 25 to mitigate botnet e-mail spam. If you are on a residential IP, you might not be able to run this tool!

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.

Command Line Usage

starttls-check -domain <email domain>

For instance, running ./starttls-check -domain gmail.com will check for the TLS configurations (over SMTP) on port 25 for all the MX domains for gmail.com.

Results

From a preliminary STARTTLS scan on the top 1000 alexa domains, performed 3/8/2018, we found:

  • 20.19% of 421 unique MX hostnames don't support STARTTLS.
  • 36.01% of the servers which support STARTTLS didn't present valid certificates.
    • We're not sure how to define valid certificates. On manual inspection, although many certificates are self-signed, it seems that many of these certs are issued for other subdomains owned by the same entity.

Seems like an improvement from results in 2014, but we can do better!

TODO

  • Check DANE
  • Present recommendations for issues
  • Tests

# Packages

No description provided by the author

# Functions

FullCheckHostname performs a series of checks against a hostname for an email domain.
MakeMTASTSResult constructs a base result object and returns its pointer.
MakeResult constructs a base result object and returns its pointer.
MakeSimpleCache creates a cache with a SimpleStore backing it.
NewSampleDomainResult returns a sample successful domain result for testing.
NoopCheckHostname returns a fake error result containing `domain` and `hostname`.
PolicyMatches return true iff a given mx matches an array of patterns.
SetStatus the resulting status of combining old & new.

# Constants

IDs for checks that can be run.
IDs for checks that can be run.
In order of precedence.
In order of precedence.
In order of precedence.
In order of precedence.
In order of precedence.
In order of precedence.
In order of precedence.
Values for Result Status.
Values for Result Status.
LocalSource labels aggregated scan data for users of the web frontend.
IDs for checks that can be run.
IDs for checks that can be run.
IDs for checks that can be run.
IDs for checks that can be run.
IDs for checks that can be run.
Values for Result Status.
TopDomainsSource labels aggregated scans of the top million domains.
IDs for checks that can be run.
Values for Result Status.

# Structs

AggregatedScan compiles aggregated stats across domains.
A Checker is used to run checks against SMTP domains and hostnames.
DomainResult wraps all the results for a particular mail domain.
HostnameResult wraps the results of a security check against a particular hostname.
MTASTSResult represents the result of a check for inbound MTA-STS support.
Result is the result of a singular check.
ScanCache wraps a scan storage object.
SimpleStore is simple HostnameResult storage backed by map.

# Interfaces

ResultHandler processes domain results.
ScanStore is an interface for using and retrieving scan results.

# Type aliases

DomainStatus indicates the overall status of a single domain.
Status is an enum encoding the status of the overall check.