Repository files navigation

DmarcRua is a simple .NET serializer for DMARC aggregate reports. Givenaggregate report XML,DmarcRua serializes the report into an object andprovides some convenience functions for identifying and exploring DMARCfailures.DmarcRua supports both v1 and v2 aggregate reports.

• Serialize DMARC aggregate report XML into .NET types and objects.
• Discover reported DMARC failures.
• Summarize or itemize DMARC failures by IP address.
• Summarize or itemize DMARC failures by From header.

Current Version:2.0.0

Target Framework:netstandard2.0

• None.

• Microsoft.NET.Test.SDK
• NUnit
• NUnit3TestAdapter

AggregateReport objects can be constructed with a stream of the report XMLor the report can be serialized later.

For example:

    using (var stream = File.OpenRead("\path\to\report.xml"))    {        var aggregateReport = new AggregateReport(stream);    }

Or:

    var aggregateReport = new AggregateReport();         using (var stream = File.OpenRead("\path\to\report.xml"))    {        aggregateReport.ReadAggregateReport(stream);    }

• AggregateReport.GetFailureRecords()
  • An enumeration of all report records that failed DMARC.
• AggregateReport.GetFailureCount()
  • Count of all report records that failed DMARC
• AggregateReport.SummarizeFailuresByIpAddress()
  • All report records that failed DMARC summarized by IP address.
• AggregateReport.SummarizeFailuresByHeaderFrom()
  • All report records that failed DMARC summarized by From header.
• AggregateReport.GetFailedRecordsByIpAddress(IPAddress ipAddress)
  • Itemized DMARC fail report records for a single IP address.
• AggregateReport.GetFailedRecordsByFromHeader(string fromHeader)
  • Itemized DMARC fail report records for a single From header.

Specifications on the DMARC aggregate report format were takenfromhttps://tools.ietf.org/html/rfc7489#appendix-C the specificationsfor version 2 come fromhttps://datatracker.ietf.org/doc/draft-ietf-dmarc-aggregate-reporting/.

Issues can be reported on theIssues page of the GitHub repo.If reporting an issue related to a report that won't parse, please attach ananonymized copy of the report.

Remove any references to your domain(s). These will appear in<domain></domain>and<header_from></header_from> elements throughout the report. They can be replaced withany dummy domain, e.g. phony-domain.com.

Remove any references to your IP(s). These will appear in the<source_ip></source_ip> elementsof the report. They should be replaced with a parseable IPv4 or IPv6 address, e.g. 127.0.0.1. Do notuselocalhost.

Contributions are always welcome.

1. Begin by forking and cloning the repository.
   • Go to theDmarcRua repository and click the "Fork" button.
   • Clone the repositorygit clone git@github.com:USERNAME/DmarcRua.git DmarcRua
2. Checkout the develop branch

   git checkout develop

3. Update the develop branch with the latest upstream changes.

   git pull upstream develop

4. Create a new branch

   git checkout -b fix-parse-for-xyz

5. Make your changes
   • If your changes involve parsing of a report, put an anonymized sample report in the/dev/testing/resources/dmarc/aggregate/ directory and make sure to run the ResourceTests in the DmarcRua.Testsproject. Refer to the Anonymizing Reports section above for anonymization details.
6. Add and commit your changes

   git add .git commit -m "Fixed enum value observed in report from xyz.com"

7. Push your local changes to the remote branch.

   git push origin fix-parse-for-xyz

8. Go to therepo and open a pull request. Please make sure to write adetailed explanation of your changes.

Project tests are inDmarcRua.Tests. When running theResourceTests make sure to set the environment variableAGGREGATE_REPORTS to the path of the sample reports.$ export AGGREGATE_REPORTS=/home/alice/projects/DmarcRua/dev/testing/resources/dmarc/aggregate/ $ dotnet test src/DmarcRua.Tests/DmarcRua.Tests.csproj