Add dashboard documentation

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