dmarcdb

Documentation

Overview

Package dmarcdb stores incoming DMARC aggrate reports and evaluations for outgoing aggregate reports.

With DMARC, a domain can request reports with DMARC evaluation results to be sent to a specified address. Mox parses such reports, stores them in its database and makes them available through its admin web interface. Mox also keeps track of the evaluations it does for incoming messages and sends reports to mail servers that request reports.

Only aggregate reports are stored and sent. Failure reports about individual messages are not implemented.

Index

• Variables
• func AddEvaluation(ctx context.Context, aggregateReportingIntervalSeconds int, e *Evaluation) error
• func AddReport(ctx context.Context, f *dmarcrpt.Feedback, fromDomain dns.Domain) error
• func Close() error
• func EvaluationStats(ctx context.Context) (map[string]EvaluationStat, error)
• func Init() error
• func RemoveEvaluationsDomain(ctx context.Context, domain dns.Domain) error
• func Start(resolver dns.Resolver)
• func SuppressAdd(ctx context.Context, ba *SuppressAddress) error
• func SuppressRemove(ctx context.Context, id int64) error
• func SuppressUpdate(ctx context.Context, id int64, until time.Time) error
• type DomainFeedback
  • func RecordID(ctx context.Context, id int64) (DomainFeedback, error)
  • func Records(ctx context.Context) ([]DomainFeedback, error)
  • func RecordsPeriodDomain(ctx context.Context, start, end time.Time, domain string) ([]DomainFeedback, error)
• type Evaluation
  • func Evaluations(ctx context.Context) ([]Evaluation, error)
  • func EvaluationsDomain(ctx context.Context, domain dns.Domain) ([]Evaluation, error)
  • func (e Evaluation) ReportRecord(count int) dmarcrpt.ReportRecord
• type EvaluationStat
• type SuppressAddress
  • func SuppressList(ctx context.Context) ([]SuppressAddress, error)

Variables

var (
	EvalDBTypes = []any{Evaluation{}, SuppressAddress{}} // Types stored in DB.
	// Exported for backups. For incoming deliveries the SMTP server adds evaluations
	// to the database. Every hour, a goroutine wakes up that gathers evaluations from
	// the last hour(s), sends a report, and removes the evaluations from the database.
	EvalDB *bstore.DB
)

var (
	ReportsDBTypes = []any{DomainFeedback{}} // Types stored in DB.
	ReportsDB      *bstore.DB                // Exported for backups.
)

Functions

func AddEvaluation

func AddEvaluation(ctx context.Context, aggregateReportingIntervalSeconds int, e *Evaluation) error

AddEvaluation adds the result of a DMARC evaluation for an incoming message to the database.

AddEvaluation sets Evaluation.IntervalHours based on aggregateReportingIntervalSeconds.

func AddReport

func AddReport(ctx context.Context, f *dmarcrpt.Feedback, fromDomain dns.Domain) error

AddReport adds a DMARC aggregate feedback report from an email to the database, and updates prometheus metrics.

fromDomain is the domain in the report message From header.

func Close

func Close() error

func EvaluationStats

func EvaluationStats(ctx context.Context) (map[string]EvaluationStat, error)

EvaluationStats returns evaluation counts and report-sending status per domain.

func Init

func Init() error

Init opens the databases.

The incoming reports and evaluations for outgoing reports are in separate databases for simpler file-based handling of the databases.

func RemoveEvaluationsDomain

func RemoveEvaluationsDomain(ctx context.Context, domain dns.Domain) error

RemoveEvaluationsDomain removes evaluations for domain so they won't be sent in an aggregate report.

func Start

func Start(resolver dns.Resolver)

Start launches a goroutine that wakes up at each whole hour (plus jitter) and sends DMARC reports to domains that requested them.

func SuppressAdd

func SuppressAdd(ctx context.Context, ba *SuppressAddress) error

SuppressAdd adds an address to the suppress list.

func SuppressRemove

func SuppressRemove(ctx context.Context, id int64) error

SuppressRemove removes a reporting address record from the suppress list.

func SuppressUpdate

func SuppressUpdate(ctx context.Context, id int64, until time.Time) error

SuppressUpdate updates the until field of a reporting address record.

Types

type DomainFeedback

type DomainFeedback struct {
	ID int64
	// Domain where DMARC DNS record was found, could be organizational domain.
	Domain string `bstore:"index"`
	// Domain in From-header.
	FromDomain string `bstore:"index"`
	dmarcrpt.Feedback
}

DomainFeedback is a single report stored in the database.

func RecordID

func RecordID(ctx context.Context, id int64) (DomainFeedback, error)

RecordID returns the report for the ID.

func Records

func Records(ctx context.Context) ([]DomainFeedback, error)

Records returns all reports in the database.

func RecordsPeriodDomain

func RecordsPeriodDomain(ctx context.Context, start, end time.Time, domain string) ([]DomainFeedback, error)

RecordsPeriodDomain returns the reports overlapping start and end, for the given domain. If domain is empty, all records match for domain.

type Evaluation

type Evaluation struct {
	ID int64

	// Domain where DMARC policy was found, could be the organizational domain while
	// evaluation was for a subdomain. Unicode. Same as domain found in
	// PolicyPublished. A separate field for its index.
	PolicyDomain string `bstore:"index"`

	// Time of evaluation, determines which report (covering whole hours) this
	// evaluation will be included in.
	Evaluated time.Time `bstore:"default now"`

	// If optional, this evaluation is not a reason to send a DMARC report, but it will
	// be included when a report is sent due to other non-optional evaluations. Set for
	// evaluations of incoming DMARC reports. We don't want such deliveries causing us to
	// send a report, or we would keep exchanging reporting messages forever. Also set
	// for when evaluation is a DMARC reject for domains we haven't positively
	// interacted with, to prevent being used to flood an unsuspecting domain with
	// reports.
	Optional bool

	// Effective aggregate reporting interval in hours. Between 1 and 24, rounded up
	// from seconds from policy to first number that can divide 24.
	IntervalHours int

	// "rua" in DMARC record, we only store evaluations for records with aggregate reporting addresses, so always non-empty.
	Addresses []string

	// Policy used for evaluation. We don't store the "fo" field for failure reporting
	// options, since we don't send failure reports for individual messages.
	PolicyPublished dmarcrpt.PolicyPublished

	// For "row" in a report record.
	SourceIP        string
	Disposition     dmarcrpt.Disposition
	AlignedDKIMPass bool
	AlignedSPFPass  bool
	OverrideReasons []dmarcrpt.PolicyOverrideReason

	// For "identifiers" in a report record.
	EnvelopeTo   string
	EnvelopeFrom string
	HeaderFrom   string

	// For "auth_results" in a report record.
	DKIMResults []dmarcrpt.DKIMAuthResult
	SPFResults  []dmarcrpt.SPFAuthResult
}

Evaluation is the result of an evaluation of a DMARC policy, to be included in a DMARC report.

func Evaluations

func Evaluations(ctx context.Context) ([]Evaluation, error)

Evaluations returns all evaluations in the database.

func EvaluationsDomain

func EvaluationsDomain(ctx context.Context, domain dns.Domain) ([]Evaluation, error)

EvaluationsDomain returns all evaluations for a domain.

func (Evaluation) ReportRecord

func (e Evaluation) ReportRecord(count int) dmarcrpt.ReportRecord

ReportRecord turns an evaluation into a record that can be included in a report.

type EvaluationStat

type EvaluationStat struct {
	Domain       dns.Domain
	Dispositions []string
	Count        int
	SendReport   bool
}

EvaluationStat summarizes stored evaluations, for inclusion in an upcoming aggregate report, for a domain.

type SuppressAddress

type SuppressAddress struct {
	ID               int64
	Inserted         time.Time `bstore:"default now"`
	ReportingAddress string    `bstore:"unique"`
	Until            time.Time `bstore:"nonzero"`
	Comment          string
}

SuppressAddress is a reporting address for which outgoing DMARC reports will be suppressed for a period.

func SuppressList

func SuppressList(ctx context.Context) ([]SuppressAddress, error)

SuppressList returns all reporting addresses on the suppress list.