diff --git a/docs/index.rst b/docs/index.rst index 14ab04f5..f09f0aaf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -27,7 +27,15 @@ Features * Consistent data structures * Simple JSON and/or CSV output * Optionally email the results -* Optionally send the results to Elasticsearch, for use with premade Kibana dashboards +* Optionally send the results to Elasticsearch, for use with premade Kibana +dashboards + +Resources +========= + +* Demystifying DMARC_ + + CLI help ======== @@ -518,6 +526,78 @@ Then, enable the service You must also run the above commands whenever you edit ``parsedmarc.service``. + +Using the Kibana dashboards +=========================== + +The Kibana DMARC dashboards are a human-friendly way to understand the results +from incoming DMARC reports. + +DMARC Summary +------------- + + Start by using the DMARC summary dashboard. As the name suggests, this + dashboard is the best place to start reviewing your aggregate DMARC data. + +Across the top of the dashboard, three pie charts display the percentage of +alignment pass/fail for SPF, DKIM, and DMARC. Clicking on any chart segment +will filter for that value. + +.. note:: + + Messages failing DMARC should not be considered malicious just because they + failed to pass DMARC; especially if you have just started collecting data. + In may be a service that needs SPF and DKIM configured correctly. + +Start by filtering the results to only show failed DKIM alignment. While DMARC +passes if a message passes SPF or DKIM alignment, only DKIM alignment remains +valid when a message is forwarded without changing the from address, which is +often caused by a mailbox forwarding rule. This is because DKIM signatures are +part of the message headers, whereas SPF relies on SMTP session headers. + +Underneath the pie charts. you can see graphs of DMARC passage and message +disposition over time. + +Under the graphs you will find the most useful data tables on the dashboard. On +the left, there is a list of organizations that are sending you DMARC reports. +In the center, there is a list of sending servers grouped by the base domain +in their reverse DNS. On the right, there is a list of email from domains, +sorted by message volume. + +By hovering your mouse over a data table value and using the magnifying glass +icons, you can filter on our filter out different values. Start by looking at +the Message Sources by Reverse DNS table. Find a sender that you recognize, +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. + +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 + +DMARC Failures +------------- + +The DMARC Failures dashboard contains data tables showing the details of +misaligned SPF and DKIM results, which may be useful for identifying the +specific application or service that is generating failing email messages. + +DMARC Forensic Samples +---------------------- + +The DMARC Forensic Samples dashboard contains information on DMARC forensic +reports (also known as failure reports or ruf reports). These reports contain +samples of emails that have failed to pass DMARC. + +.. note:: + + Most recipients do not send forensic/failure/ruf reports at all to avoid + privacy leaks. Some recipients (notably Chinese webmail services) will only + supply the headers of sample emails. Very few provide the entire email. + + API === @@ -545,6 +625,8 @@ Indices and tables .. |Build Status| image:: https://travis-ci.org/domainaware/parsedmarc.svg?branch=master :target: https://travis-ci.org/domainaware/parsedmarc +.. _Demystifying DMARC: https://seanthegeek.net/459/demystifying-dmarc/ + .. _X-Pack: https://www.elastic.co/products/x-pack .. _kibana_saved_objects.json: https://raw.githubusercontent.com/domainaware/parsedmarc/master/kibana/kibana_saved_objects.json