dmarcdb

package
v0.0.11 Latest Latest
Warning

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

Go to latest
Published: Apr 30, 2024 License: MIT Imports: 37 Imported by: 3

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

Constants

This section is empty.

Variables

View Source
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
)
View Source
var (
	ReportsDBTypes = []any{DomainFeedback{}} // Types stored in DB.
	ReportsDB      *bstore.DB                // Exported for backups.

)

Functions

func AddEvaluation added in v0.0.8

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 EvaluationStats added in v0.0.8

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 added in v0.0.8

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 added in v0.0.8

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 added in v0.0.8

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

SuppressAdd adds an address to the suppress list.

func SuppressRemove added in v0.0.8

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

SuppressRemove removes a reporting address record from the suppress list.

func SuppressUpdate added in v0.0.8

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 added in v0.0.8

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 added in v0.0.8

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

Evaluations returns all evaluations in the database.

func EvaluationsDomain added in v0.0.8

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

EvaluationsDomain returns all evaluations for a domain.

func (Evaluation) ReportRecord added in v0.0.8

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

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

type EvaluationStat added in v0.0.8

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 added in v0.0.8

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 added in v0.0.8

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

SuppressList returns all reporting addresses on the suppress list.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL