Metadata-Version: 2.1
Name: dmarc-metrics-exporter
Version: 0.2.3
Summary: Export Prometheus metrics from DMARC reports.
Home-page: https://github.com/jgosmann/dmarc-metrics-exporter/
License: MIT
Keywords: DMARC,DKIM,SPF,Prometheus
Author: Jan Gosmann
Author-email: jan@hyper-world.de
Requires-Python: >=3.7,<3.9
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Communications :: Email
Classifier: Topic :: System :: Monitoring
Requires-Dist: aioimaplib (>=0.7.18,<0.8.0)
Requires-Dist: dataclasses-serialization (>=1.3.1,<2.0.0)
Requires-Dist: prometheus_client (>=0.9.0,<0.10.0)
Requires-Dist: uvicorn[standard] (>=0.13.2,<0.14.0)
Requires-Dist: xsdata (>=20.12,<21.0)
Project-URL: Repository, https://github.com/jgosmann/dmarc-metrics-exporter/
Description-Content-Type: text/x-rst

.. image:: https://travis-ci.com/jgosmann/dmarc-metrics-exporter.svg?branch=main
  :target: https://travis-ci.com/jgosmann/dmarc-metrics-exporter
  :alt: Travis-CI build
.. image:: https://codecov.io/gh/jgosmann/dmarc-metrics-exporter/branch/main/graph/badge.svg?token=O4M05YWNQK
  :target: https://codecov.io/gh/jgosmann/dmarc-metrics-exporter
  :alt: Codecov coverage
.. image:: https://img.shields.io/pypi/v/dmarc-metrics-exporter
  :target: https://pypi.org/project/dmarc-metrics-exporter/
  :alt: PyPI
.. image:: https://img.shields.io/pypi/pyversions/dmarc-metrics-exporter
  :target: https://pypi.org/project/dmarc-metrics-exporter/
  :alt: PyPI - Python Version
.. image:: https://img.shields.io/pypi/l/dmarc-metrics-exporter
  :target: https://pypi.org/project/dmarc-metrics-exporter/
  :alt: PyPI - License

dmarcs-metrics-exporter
=======================

Export metrics derived from DMARC aggregate reports to Prometheus.
This exporter regularly polls
for new aggregate report emails
via IMAP.
The following metrics will be collected
and exposed at an HTTP endpoint
for Prometheus:

* ``dmarc_total``: Total number of reported messages.
* ``dmarc_compliant_total``: Total number of DMARC compliant messages.
* ``dmarc_quarantine_total``: Total number of quarantined messages.
* ``dmarc_reject_total``: Total number of rejected messages.
* ``dmarc_spf_aligned_total``: Total number of SPF algined messages.
* ``dmarc_spf_pass_total``: Total number of messages with raw SPF pass.
* ``dmarc_dkim_aligned_total``: Total number of DKIM algined messages.
* ``dmarc_dkim_pass_total``: Total number of messages with raw DKIM pass.

Each of these metrics is subdivided by the following labels:

* ``reporter``: Domain from which a DMARC aggregate report originated.
* ``from_domain``: Domain from which the evaluated email originated.
* ``dkim_domain``: Domain the DKIM signature is for.
* ``spf_domain``: Domain used for the SPF check.


Installation
------------

This describes the manual setup fo dmarc-metrics-exporter.
An Ansible role for automated deployment is provided in ``roles``.
Further instructions for Ansible are given in the readme file
provided in that directory.

It is best to run dmarc-metrics-exporter under a separate system user account.
Create one for example with

.. code-block:: bash

    adduser --system --group dmarc-metrics

Then you can install dmarc-metrics-exporter with ``pip`` from PyPI for that
user:

.. code-block:: bash

    sudo -u dmarc-metrics pip3 install dmarc-metrics-exporter

You will need a location to store the ``metrics.db`` that is writable by that
user, for example:

.. code-block:: bash

    mkdir /var/lib/dmarc-metrics-exporter
    chown dmarc-metrics:dmarc-metrics /var/lib/dmarc-metrics-exporter


Configuration
-------------

To run dmarc-metrics-exporter a configuration file in JSON format is required.
The default location is ``/etc/dmarc-metrics-exporter.json``.

Because the configuration file will contain the IMAP password,
make sure to ensure proper permissions on it,
for example:

.. code-block:: bash

    chown root:dmarc-metrics /etc/dmarc-metrics-exporter.json
    chmod 640 /etc/dmarc-metrics-exporter.json

An example configuration file is provided in this repository in
``config/dmarc-metrics-exporter.sample.json``.

The following configuration options are available:

* ``listen_addr`` (string, default ``"127.0.0.1"``): Listen address for the HTTP endpoint.
* ``port`` (number, default ``9119``): Port to listen on for the HTTP endpoint.
* ``imap`` (object, required): IMAP configuration to check for aggregate reports.

  * ``host`` (string, default ``"localhost"``): Hostname of IMAP server to connect to.
  * ``port`` (number, default ``993``): Port of the IMAP server to connect to.
  * ``username`` (string, required): Login username for the IMAP connection.
  * ``password``: (string, required): Login password for the IMAP connection.

* ``folders`` (object):

  * ``inbox`` (string, default ``"INBOX"``): IMAP mailbox that is checked for incoming DMARC aggregate reports.
  * ``done`` (string, default ``"Archive"``): IMAP mailbox that successfully processed reports are moved to.
  * ``error``: (string, default ``"Invalid"``): IMAP mailbox that emails are moved to that could not be processed.

* ``metrics_db`` (string, default ``"/var/lib/dmarc-metrics-exporter/metrics.db"``):
  File to persist accumulated metrics information in.
* ``poll_interval_seconds`` (number, default ``60``): How often to poll the IMAP server in seconds.

Usage
-----

To run dmarc-metrics-exporter with the default configuration in
``/etc/dmarc-metrics-exporter.json``:

.. code-block:: bash

    sudo -u dmarc-metrics python3 -m dmarc_metrics_exporter

To use a different configuration file:

.. code-block:: bash

    sudo -u dmarc-metrics python3 -m dmarc_metrics_exporter --configuration <path>


systemd
^^^^^^^

Instead of manually starting the dmarc-metrics-exporter,
you likely want to have it run as a system service.
An example systemd service file is provided in this repository in
``config/dmarc-metrics-exporter.service``.
Make sure that the paths and user/group names match your configuration
and copy it to ``/etc/systemd/system`` to use it.
To have systemd pick it up a ``systemctl daemon-reload`` might be necessary.

You can than start/stop dmarc-metrics-exorter with:

.. code-block:: bash

    systemctl start dmarc-metrics-exporter
    systemctl stop dmarc-metrics-exporter

To have dmarc-metrics-exporter start on system boot:

.. code-block:: bash

    systemctl enable dmarc-metrics-exporter

