report

README

go-dmarc-report

📧 A DMARC Report library written in Go

Based on the work of https://github.com/tierpod/dmarc-report-converter

Documentation

Overview

Package report is a DMARC Report library written in Go to decode dmarc aggregate reports

Example

package main

import (
	"fmt"
	"log"
	"os"

	report "github.com/oliverpool/go-dmarc-report"
)

func main() {
	f, err := os.Open("testdata/test_report.xml.gz")
	if err != nil {
		log.Panic(err)
	}
	defer f.Close()
	agg, err := report.DecodeGzip(f)
	if err != nil {
		log.Panic(err)
	}
	// You can now read the report
	fmt.Println(agg.Err())
}

Output:

Some record failed:
	* Failure for source IP 10.1.1.1:
		* DKIM is not aligned
		* SPF is not aligned
		* DKIM authentication failed
		* SPF authentication failed

Index

• type Aggregate
  • func Decode(r io.Reader) (*Aggregate, error)
  • func DecodeFile(filename string, r io.Reader) (*Aggregate, error)
  • func DecodeGzip(r io.Reader) (*Aggregate, error)
  • func DecodeZip(r io.ReaderAt, size int64) (*Aggregate, error)
  • func (agg Aggregate) Err() error
• type AuthResults
• type DKIMAuthResult
• type DateRange
• type Identifiers
• type Metadata
• type PolicyEvaluated
• type PolicyPublished
• type Record
  • func (r Record) DKIMAligned() bool
  • func (r Record) DKIMSuccess() bool
  • func (r Record) Err() error
  • func (r Record) FinalDispositionSuccess() bool
  • func (r Record) SPFAligned() bool
  • func (r Record) SPFSuccess() bool
• type Row
• type SPFAuthResult
• type Time
  • func (t *Time) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

Examples

• Package
• DecodeFile

Types

type Aggregate

type Aggregate struct {
	XMLName         xml.Name        `xml:"feedback"`
	Metadata        Metadata        `xml:"report_metadata"`
	PolicyPublished PolicyPublished `xml:"policy_published"`
	Records         []Record        `xml:"record"`
}

Aggregate represents a dmarc aggregate report

func Decode

func Decode(r io.Reader) (*Aggregate, error)

Decode a dmarc aggregate report

func DecodeFile

func DecodeFile(filename string, r io.Reader) (*Aggregate, error)

DecodeFile decodes dmarc aggregate report based on its name

Example

package main

import (
	"fmt"
	"log"
	"os"

	report "github.com/oliverpool/go-dmarc-report"
)

func main() {
	// Usually you will get the filename and the reader from an E-Mail
	f, err := os.Open("testdata/test_report.zip")
	if err != nil {
		log.Panic(err)
	}
	defer f.Close()

	agg, err := report.DecodeFile("testdata/test_report.zip", f)
	if err != nil {
		log.Panic(err)
	}

	// You can now read the report
	fmt.Println(agg.Err())
}

Output:

Some record failed:
	* Failure for source IP 10.1.1.1:
		* DKIM is not aligned
		* SPF is not aligned
		* DKIM authentication failed
		* SPF authentication failed

func DecodeGzip

func DecodeGzip(r io.Reader) (*Aggregate, error)

DecodeGzip decodes a gzipped dmarc aggregate report

func DecodeZip

func DecodeZip(r io.ReaderAt, size int64) (*Aggregate, error)

DecodeZip decodes a zipped dmarc aggregate report

func (Aggregate) Err

func (agg Aggregate) Err() error

Err returns a non-nil error if any of the record as an Err

type AuthResults

type AuthResults struct {
	DKIM DKIMAuthResult `xml:"dkim"`
	SPF  SPFAuthResult  `xml:"spf"`
}

AuthResults represents feedback>record>auth_results section

type DKIMAuthResult

type DKIMAuthResult struct {
	Domain   string `xml:"domain"`
	Result   string `xml:"result"`
	Selector string `xml:"selector"`
}

DKIMAuthResult represents feedback>record>auth_results>dkim sections

type DateRange

type DateRange struct {
	Begin Time `xml:"begin" json:"begin"`
	End   Time `xml:"end" json:"end"`
}

DateRange represents feedback>report_metadata>date_range section

type Identifiers

type Identifiers struct {
	HeaderFrom string `xml:"header_from"`
}

Identifiers represents feedback>record>identifiers section

type Metadata

type Metadata struct {
	OrgName          string    `xml:"org_name"`
	Email            string    `xml:"email"`
	ExtraContactInfo string    `xml:"extra_contact_info"`
	ReportID         string    `xml:"report_id"`
	DateRange        DateRange `xml:"date_range"`
}

Metadata represents feedback>report_metadata section

type PolicyEvaluated

type PolicyEvaluated struct {
	Disposition string `xml:"disposition"`
	DKIM        string `xml:"dkim"`
	SPF         string `xml:"spf"`
}

PolicyEvaluated represents feedback>record>row>policy_evaluated section

type PolicyPublished

type PolicyPublished struct {
	Domain     string `xml:"domain"`
	ADKIM      string `xml:"adkim"`
	ASPF       string `xml:"aspf"`
	Policy     string `xml:"p"`
	SPolicy    string `xml:"sp"`
	Percentage *int   `xml:"pct"`
}

PolicyPublished represents feedback>policy_published section

type Record

type Record struct {
	Row         Row         `xml:"row"`
	Identifiers Identifiers `xml:"identifiers"`
	AuthResults AuthResults `xml:"auth_results"`
	Timestamp   time.Time   `xml:"-"`
}

Record represents feedback>record section

func (Record) DKIMAligned

func (r Record) DKIMAligned() bool

DKIMAligned returns true if the DKIM is aligned: Domain in the RFC5322.From header matches the domain in the "d=" tag in the DKIM signature.

func (Record) DKIMSuccess

func (r Record) DKIMSuccess() bool

DKIMSuccess returns true if the DKIM authenticated was successful.

func (Record) Err

func (r Record) Err() error

Err returns a non-nil error if any of the DMARC policy failed (or is missing)

func (Record) FinalDispositionSuccess

func (r Record) FinalDispositionSuccess() bool

FinalDispositionSuccess is the result of the domain’s policy combined with the DKIM and SPF aligned policy results.

func (Record) SPFAligned

func (r Record) SPFAligned() bool

SPFAligned returns true if the SPF is aligned: Domain in the RFC5322.From header matches the domain in the RFC5321.MailFrom field

func (Record) SPFSuccess

func (r Record) SPFSuccess() bool

SPFSuccess returns true if the SPF authenticated was successful.

type Row

type Row struct {
	SourceIP        string          `xml:"source_ip"`
	Count           int             `xml:"count"`
	PolicyEvaluated PolicyEvaluated `xml:"policy_evaluated"`
}

Row represents feedback>record>row section

type SPFAuthResult

type SPFAuthResult struct {
	Domain string `xml:"domain"`
	Result string `xml:"result"`
	Scope  string `xml:"scope"`
}

SPFAuthResult represents feedback>record>auth_results>spf section

type Time

type Time struct {
	time.Time
}

Time is the custom time for DateRange.Begin and DateRange.End values

func (*Time) UnmarshalXML

func (t *Time) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error

UnmarshalXML unmarshals unix timestamp to time.Time