Django DMARC

Managing DMARC aggregate and feedback reports

Designed to quickly and easily manage DMARC aggregate and feedback reports.

Contents

Documentation

Managing DMARC aggregate and feedback reports

Designed to quickly and easily manage DMARC aggregate and feedback reports.

Description

This Django DMARC project aims to ease implementating DMARC “Domain-based Message Authentication, Reporting & Conformance” and ongoing monitoring by importing aggregate and feedback reports about messages that pass and/or fail DMARC evaluation into a more easily digested format.

Perhaps one of the main reasons DMARC is gaining traction amongst organisations of all sizes is a desire to protect their people, brand and reputation. By defining and implementing a DMARC policy, an organization can help combat phishing, protect users and their reputation.

At beta stage, the application is stable, with most efforts on improving usability and documentation.

Choosing Django was an easy choice as it offers an easily built import mechanism and transformation from xml to database through to presentation.

Although it has options for importing either xml or email files, zero maintenance is achieved by fully automating import of feedback and reports.

Quick start

1. Install the app

2. Add “dmarc” to your INSTALLED_APPS setting:

   INSTALLED_APPS = (
       ...
       'dmarc',
   )
   

3. Add dmarc.urls to your urls:

   from dmarc import urls as dmarc_urls
   
   urlpatterns = [
       ...
       url(r"^dmarc/", include(dmarc_urls)),
   ]
   

4. Run ‘python manage.py migrate’ to create the database models.

5. Import a report with:

   python manage.py importdmarcreport --email
   

6. See your aggregated feedback reports from the Admin page at admin/dmarc

Usage

python manage.py importdmarcreport –email

You can choose to import an xml or email file, alternatively with “–email -” you can pipe an email and it will do the right thing.

Installation

Install the app

Configuration

Add “dmarc” to your INSTALLED_APPS setting:

INSTALLED_APPS = (
    ...
    'dmarc',
)

Add dmarc.urls to your urls:

from dmarc import urls as dmarc_urls

urlpatterns = [
    ...
    url(r"^dmarc/", include(dmarc_urls)),
]

DMARC reports are namespaced so if you’re using django version 1.8 you will need to add the namespace ‘dmarc’:

urlpatterns = [
    ...
    url(r"^dmarc/", include(dmarc_urls, namespace='dmarc')),
]

Install tables

Run ‘python manage.py migrate’ to create the database tables.

Import feedback report

Import an email DMARC aggregate report with:

python manage.py importdmarcreport --email

Alternatively the xml report can be imported with:

python manage.py importdmarcreport --xml

The process of importing DMARC aggregate reports can be fully automated. At Persistent Objects we use Exim and the configuration couldn’t be easier.

Router:

dmarcreports:
    driver = accept
    condition = ${if eq{$local_part}{dmarc_report}}
    transport = trans_dmarcreports

Transport:

trans_dmarcreports:
    driver = pipe
    command = "/usr/local/bin/python2.7 /path/to/manage.py importdmarcreport --email -"
    freeze_exec_fail = true
    return_fail_output = true

Congratulations, you have django-dmarc installed and ready to import DMARC aggregate feedback reports and start implementing DMARC and protecting your emails.

DMARC reporting

Aggregated feedback reports are available from the Admin page at admin/dmarc.

From the DMARC dashboard at ‘Site administration/DMARC’ where the intention is to highlight a summary of recent reports, there is one report ‘DMARC feedback reports’ and is available to any user with staff members authorization.

This is an example report, it can also be downloaded as a csv file suitable for importing into your favourite spreadsheet.

The report can be filtered by clicking on the filter and changing any of the reporting period, only showing errors/failures, disposition (quarantine, rejection or any) and by source ip address/reporting organisation.

These reports can help ease any DMARC implementation.

Maintenance

Although there is usually no need to remove old records, access to the report table is offered to allow for record deletion.

Dependencies

• Django 2.2+

Resources

• DMARC
• Django
• Google gmail DMARC
• Download from PyPI

Support

To report a security issue, please send an email privately to ahicks@p-o.co.uk. This gives us a chance to fix the issue and create an official release prior to the issue being made public.

For general questions or comments, please contact ahicks@p-o.co.uk.

Project website

Communications are expected to conform to the Django Code of Conduct.

Change Log

Managing DMARC aggregate and feedback reports

Designed to quickly and easily manage DMARC aggregate and feedback reports.

Change Log

Version 0.7.0 (2021-07-16)

Report default set to two days TypeError: string argument expected, got ‘bytes’ fixed Copyright updated to 2021

Version 0.6.0 (2020-06-10)

Updated for Django 2.2 Dropped support for Python 2.7 Updated test script Updated Copyright to 2020

Version 0.5.2 (2018-06-19)

Updated for Django 2.0 Updated Copyright to 2018 Updated links for tls Changed report icon font from glyphicons to fontawesome

Version 0.5.1 (2017-02-10)

Updated documentation

Version 0.5.0 (2017-01-19)

Added capturing of feedback reports Updated Copyright to 2017

Version 0.4.7 (2016-11-30)

Added Glossary and FAQ’s

Version 0.4.6 (2016-11-24)

Order report Fix date filtering

Version 0.4.5 (2016-11-23)

Add colour_code and dkim/spf domain columns thanks to Edward Newman

Version 0.4.4 (2016-11-22)

Fix SQL typo (remove public.) and add back domain (Edward Newman)

Version 0.4.3 (2016-11-22)

Update documentation

Version 0.4.2 (2016-11-22)

Add sql filtering checks Add filtering by Disposition suggestion from Edward Newman

Show and filter by organisation name Version 0.4.1 (2016-11-22) —————————

Show and filter by organisation name

Version 0.4.0 (2016-11-21)

Create prototype admin dashboard Create admin Report model editing Update report to use ajax load Create Download report option Database agnostic filter Use base admin templates

Version 0.3.3 (2016-11-05)

Add csv export

Version 0.3.2 (2016-09-13)

Improve mimepart debug message

Version 0.3.1 (2016-09-08)

Add application/gzip

Version 0.3.0 (2016-09-07)

• Bump version to 0.3.0
• Add gzip handling
• Refactor to use argparse
• Refactor code

Note change to arguments requiring email or xml and either can be - for stdin

Version 0.2.2 (2016-08-31)

• Bump version to 0.2.2
• Remove dependency on django.conf.urls.patterns

Version 0.2.1 (2016-08-31)

• Bump minimum Django version to 1.8
• Improve processing descriptions

Version 0.2.0 (2016-08-03)

Add error checking and saving for bad zipfile

Version 0.1.10 (2015-04-22)

• Added reference to Bootstrap styles (Thanks Jan (linjan))
• Add sample report

Version 0.1.9 (2015-03-28)

Fix AttributeError: ‘Element’ object has no attribute ‘getroot’

Version 0.1.8 (2015-03-27)

• Fix reference before assignment
• Add save original XML report

Version 0.1.7 (2015-03-17)

• Save XML with test
• Add Logging
• Supress email errors

Version 0.1.6 (2015-03-13)

Fix missing self (Lukas Pühringer)

Version 0.1.5 (2015-03-11)

• Optimise prefetch

Version 0.1.4 (2015-03-10)

• Fix report closing tags

Version 0.1.3 (2015-03-07)

• Allow duplicate Records

Version 0.1.2 (2015-03-03)

• Added a dmarc report

Version 0.1.1 (2015-03-01)

• Improved documentation

Version 0.1.0 (2015-02-28)

• Project created

Copyright

Django DMARC and this documentation is Copyright (c) 2015-2021, Persistent Objects Ltd. All rights reserved.

License

This documentation is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit http://creativecommons.org/licenses/by/4.0/.

Copyright (c) 2015-2021, Persistent Objects Ltd. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY PERSISTENT OBJECTS LTD AND CONTRIBUTORS ‘AS IS’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Persistent Objects Ltd.

Description

This Django DMARC project aims to ease implementating DMARC “Domain-based Message Authentication, Reporting & Conformance” and ongoing monitoring by importing aggregate and feedback reports about messages that pass and/or fail DMARC evaluation into a more easily digested format.

Perhaps one of the main reasons DMARC is gaining traction amongst organisations of all sizes is a desire to protect their people, brand and reputation. By defining and implementing a DMARC policy, an organization can help combat phishing, protect users and their reputation.

This project is stable, with most efforts on improving usability and documentation.

Choosing Django was an easy choice as it offers an easily built import mechanism and transformation from xml to database through to presentation.

Although there are options for importing either xml or email files, zero maintenance is achieved by fully automating import of feedback and reports.

Copyright

Django DMARC and this documentation is Copyright (c) 2015-2021, Persistent Objects Ltd. All rights reserved.

Contributors

This list is not complete and not in any useful order, but I would like to thank everybody who contributed in any way, with code, hints, bug reports, ideas, moral support, endorsement, or even complaints… You have made django-dmarc what it is today.

Thank you,

Alan Hicks

• Alan Hicks
• Edward Newman

License

This documentation is licensed under the Creative Commons Attribution 4.0 International License. To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.

The software is licensed under the BSD two clause license.

Copyright (c) 2015-2021, Persistent Objects Ltd. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY PERSISTENT OBJECTS LTD AND CONTRIBUTORS ‘AS IS’ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD PROJECT OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those of the authors and should not be interpreted as representing official policies, either expressed or implied, of Persistent Objects Ltd.