diff --git a/docs/index.rst b/docs/index.rst index f514fe1..70d8f7c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -16,12 +16,15 @@ Welcome to parsedmarc's documentation! :target: _static/screenshots/dmarc-summary-charts.png ``parsedmarc`` is a Python module and CLI utility for parsing DMARC reports. +When used with Elasticsearch and Kibana, it works as a self-hosted open source +alternative to commercial DMARC report processing services such as Agari, +Dmarcian, and OnDMARC. Features ======== -* Parses draft and 1.0 standard aggregate reports -* Parses forensic reports +* Parses draft and 1.0 standard aggregate/rua reports +* Parses forensic/failure/ruf reports * Can parse reports from an inbox over IMAP * Transparently handles gzip or zip compressed reports * Consistent data structures @@ -110,7 +113,8 @@ SPF and DMARC record validation =============================== If you are looking for SPF and DMARC record validation and parsing, -check out the sister project, `checkdmarc `_. +check out the sister project, +`checkdmarc `_. Sample aggregate report output ============================== @@ -526,6 +530,11 @@ Then, enable the service You must also run the above commands whenever you edit ``parsedmarc.service``. +Use this command to check the status of the service: + +.. code-block:: bash + + sudo service parsedmarc status Using the Kibana dashboards =========================== @@ -577,11 +586,22 @@ such as an email marketing service, hover over it, and click on the plus (+) magnifying glass icon, to add a filter that only shows results for that sender. Now, look at the Message From Header table to the right. That shows you the domains that a sender is sending as, which might tell you which brand/business -is using a particular service, you can contact them and have them set up DKIM. +is using a particular service. With that information, you can contact them and +have them set up DKIM. + +.. note:: + + If you have a lot of B2C customers, you may see a high volume of emails as + your domains coming from consumer email services, such as Google/Gmail and + Yahoo! This occurs when customers have mailbox rules in place that forward + emails from an old account to a new account, which is why DKIM + authentication is so important, as mentioned earlier. Similar patterns may + be observed with business customers who rebrand. + Any other filters work the same way. Further down the dashboard, you can filter by source country or source IP address. You can also add your own custom -temporary filters +temporary filters by clicking on Add Filter at the upper right of the page. DMARC Failures -------------- @@ -604,6 +624,54 @@ samples of emails that have failed to pass DMARC. supply the headers of sample emails. Very few provide the entire email. +DMARC Alignment Guide +===================== + +DMARC ensures that SPF and DKM authentication mechanisms actually authenticate +against the same domain that the end user sees. + +A message passes a DMARC check by passing DKIM or SPF, **as long as the related +indicators are also in alignment**. + ++-----------------------+-----------------------+-----------------------+ +| | **DKIM** | **SPF** | ++-----------------------+-----------------------+-----------------------+ +| **Passing** | The signature in the | The mail server’s IP | +| | DKIM header is | address is listed in | +| | validated using a | the SPF record of the | +| | public key that is | domain in the SMTP | +| | published as a DNS | envelope’s mail from | +| | record of the domain | header | +| | name specified in the | | +| | signature | | ++-----------------------+-----------------------+-----------------------+ +| **Alignment** | The signing domain | The domain in the | +| | aligns with the | SMTP envelope’s mail | +| | domain in the | from header aligns | +| | message’s from header | with the domain in | +| | | the message’s from | +| | | header | ++-----------------------+-----------------------+-----------------------+ + + +What if a sender won't support DKIM/DMARC? +========================================== + +#. Some vendors don’t know about DMARC yet; ask about SPF and DKIM/email + authentication. +#. Check if they can send through your email relays instead of theirs. +#. Do they really need to spoof your domain? Why not use the display + name instead? +#. Worst case, have that vendor send email as a specific subdomain of + your domain (e.g. ``noreply@marketing.example.com``), and then create + separate SPF and DMARC records on ``marketing.example.com``, and set + ``p=none`` in that DMARC record + + .. warning :: + + **Do not** alter the ``p`` **or**``sp`` values for the TLD – **that + would leave you vulnerable to spoofing of any subdomain**. + API ===