mirror of
https://github.com/domainaware/parsedmarc.git
synced 2026-10-30 22:25:43 +00:00
3.7.0
This commit is contained in:
Sean Whalen committed
1 parent
4a0cf63f25
commit
3ad97903e9
11 files changed
+449
-80
No files matched your search
+3
-3
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>Overview: module code — parsedmarc 3.6.0 documentation</title>
|
||||
<title>Overview: module code — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -177,7 +177,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'../',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+30
-21
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>parsedmarc — parsedmarc 3.6.0 documentation</title>
|
||||
<title>parsedmarc — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -188,7 +188,7 @@
|
||||
<span class="kn">import</span> <span class="nn">dateparser</span>
|
||||
<span class="kn">import</span> <span class="nn">mailparser</span>
|
||||
|
||||
<span class="n">__version__</span> <span class="o">=</span> <span class="s2">"3.6.0"</span>
|
||||
<span class="n">__version__</span> <span class="o">=</span> <span class="s2">"3.7.0"</span>
|
||||
|
||||
<span class="n">logger</span> <span class="o">=</span> <span class="n">logging</span><span class="o">.</span><span class="n">getLogger</span><span class="p">(</span><span class="vm">__name__</span><span class="p">)</span>
|
||||
<span class="n">logger</span><span class="o">.</span><span class="n">setLevel</span><span class="p">(</span><span class="n">logging</span><span class="o">.</span><span class="n">INFO</span><span class="p">)</span>
|
||||
@@ -245,22 +245,23 @@
|
||||
<span class="n">psl_path</span> <span class="o">=</span> <span class="s2">".public_suffix_list.dat"</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">download_psl</span><span class="p">():</span>
|
||||
<span class="n">fresh_psl</span> <span class="o">=</span> <span class="n">publicsuffix</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span>
|
||||
<span class="n">fresh_psl</span> <span class="o">=</span> <span class="n">publicsuffix</span><span class="o">.</span><span class="n">fetch</span><span class="p">()</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>
|
||||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">psl_path</span><span class="p">,</span> <span class="s2">"w"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span> <span class="k">as</span> <span class="n">fresh_psl_file</span><span class="p">:</span>
|
||||
<span class="n">fresh_psl_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">fresh_psl</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
|
||||
|
||||
<span class="k">return</span> <span class="n">publicsuffix</span><span class="o">.</span><span class="n">PublicSuffixList</span><span class="p">(</span><span class="n">fresh_psl</span><span class="p">)</span>
|
||||
<span class="n">fresh_psl_file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">fresh_psl</span><span class="p">)</span>
|
||||
|
||||
<span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">exists</span><span class="p">(</span><span class="n">psl_path</span><span class="p">):</span>
|
||||
<span class="n">psl</span> <span class="o">=</span> <span class="n">download_psl</span><span class="p">()</span>
|
||||
<span class="n">download_psl</span><span class="p">()</span>
|
||||
<span class="k">else</span><span class="p">:</span>
|
||||
<span class="n">psl_age</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">()</span> <span class="o">-</span> <span class="n">datetime</span><span class="o">.</span><span class="n">fromtimestamp</span><span class="p">(</span>
|
||||
<span class="n">os</span><span class="o">.</span><span class="n">stat</span><span class="p">(</span><span class="n">psl_path</span><span class="p">)</span><span class="o">.</span><span class="n">st_mtime</span><span class="p">)</span>
|
||||
<span class="k">if</span> <span class="n">psl_age</span> <span class="o">></span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">24</span><span class="p">):</span>
|
||||
<span class="n">psl</span> <span class="o">=</span> <span class="n">download_psl</span><span class="p">()</span>
|
||||
<span class="k">else</span><span class="p">:</span>
|
||||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">psl_path</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span> <span class="k">as</span> <span class="n">psl_file</span><span class="p">:</span>
|
||||
<span class="n">psl</span> <span class="o">=</span> <span class="n">publicsuffix</span><span class="o">.</span><span class="n">PublicSuffixList</span><span class="p">(</span><span class="n">psl_file</span><span class="p">)</span>
|
||||
<span class="k">try</span><span class="p">:</span>
|
||||
<span class="n">download_psl</span><span class="p">()</span>
|
||||
<span class="k">except</span> <span class="ne">Exception</span> <span class="k">as</span> <span class="n">error</span><span class="p">:</span>
|
||||
<span class="n">logger</span><span class="o">.</span><span class="n">warning</span><span class="p">(</span><span class="s2">"Failed to download an updated PSL - </span><span class="se">\</span>
|
||||
<span class="s2"> </span><span class="si">{0}</span><span class="s2">"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">error</span><span class="p">))</span>
|
||||
<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">psl_path</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span> <span class="k">as</span> <span class="n">psl_file</span><span class="p">:</span>
|
||||
<span class="n">psl</span> <span class="o">=</span> <span class="n">publicsuffix</span><span class="o">.</span><span class="n">PublicSuffixList</span><span class="p">(</span><span class="n">psl_file</span><span class="p">)</span>
|
||||
|
||||
<span class="k">return</span> <span class="n">psl</span><span class="o">.</span><span class="n">get_public_suffix</span><span class="p">(</span><span class="n">domain</span><span class="p">)</span>
|
||||
|
||||
@@ -531,11 +532,15 @@
|
||||
<span class="n">new_record</span><span class="p">[</span><span class="s2">"auth_results"</span><span class="p">][</span><span class="s2">"spf"</span><span class="p">]</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">new_result</span><span class="p">)</span>
|
||||
|
||||
<span class="k">if</span> <span class="s2">"envelope_from"</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"identifiers"</span><span class="p">]:</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"auth_results"</span><span class="p">][</span><span class="s2">"spf"</span><span class="p">][</span><span class="o">-</span><span class="mi">1</span><span class="p">][</span><span class="s2">"domain"</span><span class="p">]</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"auth_results"</span><span class="p">][</span><span class="s2">"spf"</span><span class="p">][</span><span class="o">-</span><span class="mi">1</span><span class="p">][</span><span class="s2">"domain"</span><span class="p">]</span>
|
||||
<span class="k">if</span> <span class="n">envelope_from</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">envelope_from</span><span class="p">)</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||||
<span class="n">new_record</span><span class="p">[</span><span class="s2">"identifiers"</span><span class="p">][</span><span class="s2">"envelope_from"</span><span class="p">]</span> <span class="o">=</span> <span class="n">envelope_from</span>
|
||||
|
||||
<span class="k">elif</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"identifiers"</span><span class="p">][</span><span class="s2">"envelope_from"</span><span class="p">]</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"auth_results"</span><span class="p">][</span><span class="s2">"spf"</span><span class="p">][</span><span class="o">-</span><span class="mi">1</span><span class="p">][</span><span class="s2">"domain"</span><span class="p">]</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="n">new_record</span><span class="p">[</span><span class="s2">"auth_results"</span><span class="p">][</span><span class="s2">"spf"</span><span class="p">][</span><span class="o">-</span><span class="mi">1</span><span class="p">][</span><span class="s2">"domain"</span><span class="p">]</span>
|
||||
<span class="k">if</span> <span class="n">envelope_from</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
|
||||
<span class="n">envelope_from</span> <span class="o">=</span> <span class="nb">str</span><span class="p">(</span><span class="n">envelope_from</span><span class="p">)</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||||
<span class="n">new_record</span><span class="p">[</span><span class="s2">"identifiers"</span><span class="p">][</span><span class="s2">"envelope_from"</span><span class="p">]</span> <span class="o">=</span> <span class="n">envelope_from</span>
|
||||
|
||||
<span class="n">envelope_to</span> <span class="o">=</span> <span class="kc">None</span>
|
||||
@@ -728,6 +733,10 @@
|
||||
<span class="sd"> Returns:</span>
|
||||
<span class="sd"> str: Parsed aggregate report data in flat CSV format, including headers</span>
|
||||
<span class="sd"> """</span>
|
||||
|
||||
<span class="k">def</span> <span class="nf">to_str</span><span class="p">(</span><span class="n">obj</span><span class="p">):</span>
|
||||
<span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">obj</span><span class="p">)</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span>
|
||||
|
||||
<span class="n">fields</span> <span class="o">=</span> <span class="p">[</span><span class="s2">"xml_schema"</span><span class="p">,</span> <span class="s2">"org_name"</span><span class="p">,</span> <span class="s2">"org_email"</span><span class="p">,</span>
|
||||
<span class="s2">"org_extra_contact_info"</span><span class="p">,</span> <span class="s2">"report_id"</span><span class="p">,</span> <span class="s2">"begin_date"</span><span class="p">,</span> <span class="s2">"end_date"</span><span class="p">,</span>
|
||||
<span class="s2">"errors"</span><span class="p">,</span> <span class="s2">"domain"</span><span class="p">,</span> <span class="s2">"adkim"</span><span class="p">,</span> <span class="s2">"aspf"</span><span class="p">,</span> <span class="s2">"p"</span><span class="p">,</span> <span class="s2">"sp"</span><span class="p">,</span> <span class="s2">"pct"</span><span class="p">,</span> <span class="s2">"fo"</span><span class="p">,</span>
|
||||
@@ -801,9 +810,9 @@
|
||||
<span class="k">if</span> <span class="s2">"selector"</span> <span class="ow">in</span> <span class="n">dkim_result</span><span class="p">:</span>
|
||||
<span class="n">dkim_selectors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dkim_result</span><span class="p">[</span><span class="s2">"selector"</span><span class="p">])</span>
|
||||
<span class="n">dkim_results</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dkim_result</span><span class="p">[</span><span class="s2">"result"</span><span class="p">])</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_domains"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dkim_domains</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_selectors"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dkim_selectors</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_results"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">dkim_results</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_domains"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">dkim_domains</span><span class="p">))</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_selectors"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">dkim_selectors</span><span class="p">))</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"dkim_results"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">dkim_results</span><span class="p">))</span>
|
||||
<span class="n">spf_domains</span> <span class="o">=</span> <span class="p">[]</span>
|
||||
<span class="n">spf_scopes</span> <span class="o">=</span> <span class="p">[]</span>
|
||||
<span class="n">spf_results</span> <span class="o">=</span> <span class="p">[]</span>
|
||||
@@ -811,9 +820,9 @@
|
||||
<span class="n">spf_domains</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">spf_result</span><span class="p">[</span><span class="s2">"domain"</span><span class="p">])</span>
|
||||
<span class="n">spf_scopes</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">spf_result</span><span class="p">[</span><span class="s2">"scope"</span><span class="p">])</span>
|
||||
<span class="n">spf_results</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">spf_result</span><span class="p">[</span><span class="s2">"result"</span><span class="p">])</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_domains"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">spf_domains</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_scopes"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">spf_scopes</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_results"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">spf_results</span><span class="p">)</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_domains"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">spf_domains</span><span class="p">))</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_scopes"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">spf_scopes</span><span class="p">))</span>
|
||||
<span class="n">row</span><span class="p">[</span><span class="s2">"spf_results"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">","</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">to_str</span><span class="p">,</span> <span class="n">dkim_results</span><span class="p">))</span>
|
||||
|
||||
<span class="n">writer</span><span class="o">.</span><span class="n">writerow</span><span class="p">(</span><span class="n">row</span><span class="p">)</span>
|
||||
<span class="n">csv_file_object</span><span class="o">.</span><span class="n">flush</span><span class="p">()</span>
|
||||
@@ -1618,7 +1627,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'../',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>parsedmarc.elastic — parsedmarc 3.6.0 documentation</title>
|
||||
<title>parsedmarc.elastic — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -545,7 +545,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'../../',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+194
-19
@@ -16,18 +16,29 @@ 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
|
||||
* 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
|
||||
========
|
||||
@@ -102,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 <https://domainaware.github.io/checkdmarc/>`_.
|
||||
check out the sister project,
|
||||
`checkdmarc <https://domainaware.github.io/checkdmarc/>`_.
|
||||
|
||||
Sample aggregate report output
|
||||
==============================
|
||||
@@ -254,6 +266,10 @@ Elasticsearch and Kibana
|
||||
|
||||
To set up visual dashboards of DMARC data, install Elasticsearch and Kibana.
|
||||
|
||||
.. note::
|
||||
|
||||
Elasticsearch/Kibana 6+ is required
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo apt-get install -y openjdk-8-jre apt-transport-https
|
||||
@@ -398,17 +414,17 @@ Om the same system as Elasticsearch, pass ``--save-aggregate`` and/or
|
||||
.. warning::
|
||||
|
||||
``--save-aggregate`` and ``--save-forensic`` are separate options because
|
||||
you may not want to save forensic reports to your Elasticsearch instance,
|
||||
particularly if you are in a highly-regulated industry that handles
|
||||
sensitive data, such as healthcare or finance. If your legitimate outgoing
|
||||
email fails DMARC, it is possible that email may appear later in a
|
||||
forensic report.
|
||||
you may not want to save forensic reports (also known as failure reports)
|
||||
to your Elasticsearch instance, particularly if you are in a
|
||||
highly-regulated industry that handles sensitive data, such as healthcare
|
||||
or finance. If your legitimate outgoing email fails DMARC, it is possible
|
||||
that email may appear later in a forensic report.
|
||||
|
||||
Forensic reports contain the original headers of an email that failed a
|
||||
DMARC check, and sometimes may also include the full message body,
|
||||
depending on the policy of the reporting organisation.
|
||||
depending on the policy of the reporting organization.
|
||||
|
||||
Most reporting organisations do not send forensic reports of any kind for
|
||||
Most reporting organizations do not send forensic reports of any kind for
|
||||
privacy reasons. While aggregate DMARC reports are sent at least daily,
|
||||
it is normal to receive very few forensic reports.
|
||||
|
||||
@@ -483,14 +499,6 @@ Create the service configuration file
|
||||
|
||||
sudo nano /etc/systemd/system/parsedmarc.service
|
||||
|
||||
Edit the command line options of ``parsedmarc`` in the service's ``ExecStart``
|
||||
setting to suit your needs.
|
||||
|
||||
.. note::
|
||||
|
||||
Always pass the ``--watch`` option to ``parsedmarc`` when running it as a
|
||||
service. Use ``--silent`` to only log errors.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[Unit]
|
||||
@@ -505,6 +513,23 @@ setting to suit your needs.
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
Edit the command line options of ``parsedmarc`` in the service's ``ExecStart``
|
||||
setting to suit your needs.
|
||||
|
||||
.. note::
|
||||
|
||||
Always pass the ``--watch`` option to ``parsedmarc`` when running it as a
|
||||
service. Use ``--silent`` to only log errors.
|
||||
|
||||
.. warning::
|
||||
|
||||
As mentioned earlier, forensic/failure reports contain copies of emails
|
||||
that failed DMARC, including emails that may be legitimate and contain
|
||||
sensitive customer or business information. For privacy and/or regulatory
|
||||
reasons, you may not want to use the ``--save-forensic`` flag included in
|
||||
the example service configuration ``ExecStart`` setting, which would save
|
||||
these samples to Elasticsearch.
|
||||
|
||||
Then, enable the service
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -518,6 +543,154 @@ 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
|
||||
===========================
|
||||
|
||||
The Kibana DMARC dashboards are a human-friendly way to understand the results
|
||||
from incoming DMARC reports.
|
||||
|
||||
.. note::
|
||||
|
||||
The default dashboard is DMARC Summary. To switch between dashboards,
|
||||
click on the Dashboard link in the left side menu of Kibana.
|
||||
|
||||
|
||||
DMARC Summary
|
||||
-------------
|
||||
|
||||
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 should not be considered malicious just because they failed to pass
|
||||
DMARC; especially if you have just started collecting data. It may be a
|
||||
legitimate 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. 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 businesses who send from reverse DNS addressees of
|
||||
parent, subsidiary, and outdated brands.
|
||||
|
||||
|
||||
Further down the dashboard, you can filter by source country or source IP
|
||||
address.
|
||||
|
||||
Tables showing SPF and DKIM alignment details are located under the IP address
|
||||
table.
|
||||
|
||||
.. note::
|
||||
|
||||
Previously, the alignment tables were included in a separate dashboard
|
||||
called DMARC Alignment Failures. That dashboard has been consolidated into
|
||||
the DMARC Summary dashboard. To view failures only, use the pie chart.
|
||||
|
||||
Any other filters work the same way. You can also add your own custom temporary
|
||||
filters by clicking on Add Filter at the upper right of the page.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
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@news.example.com``), and then create
|
||||
separate SPF and DMARC records on ``news.example.com``, and set
|
||||
``p=none`` in that DMARC record.
|
||||
|
||||
.. warning ::
|
||||
|
||||
Do not alter the ``p`` or ``sp`` values of the DMARC record on the
|
||||
Top-Level Domain (TLD) – that would leave you vulnerable to spoofing of
|
||||
your TLD and/or any subdomain.
|
||||
|
||||
API
|
||||
===
|
||||
|
||||
@@ -545,6 +718,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
|
||||
@@ -1,6 +1,6 @@
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
|
||||
VERSION: '3.6.0',
|
||||
VERSION: '3.7.0',
|
||||
LANGUAGE: 'None',
|
||||
COLLAPSE_INDEX: false,
|
||||
FILE_SUFFIX: '.html',
|
||||
|
||||
+3
-3
@@ -9,7 +9,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>Index — parsedmarc 3.6.0 documentation</title>
|
||||
<title>Index — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -57,7 +57,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -310,7 +310,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'./',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+207
-22
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>Welcome to parsedmarc’s documentation! — parsedmarc 3.6.0 documentation</title>
|
||||
<title>Welcome to parsedmarc’s documentation! — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -84,6 +84,7 @@
|
||||
<div class="local-toc"><ul>
|
||||
<li><a class="reference internal" href="#">Welcome to parsedmarc’s documentation!</a><ul>
|
||||
<li><a class="reference internal" href="#features">Features</a></li>
|
||||
<li><a class="reference internal" href="#resources">Resources</a></li>
|
||||
<li><a class="reference internal" href="#cli-help">CLI help</a></li>
|
||||
<li><a class="reference internal" href="#spf-and-dmarc-record-validation">SPF and DMARC record validation</a></li>
|
||||
<li><a class="reference internal" href="#sample-aggregate-report-output">Sample aggregate report output</a><ul>
|
||||
@@ -99,6 +100,13 @@
|
||||
<li><a class="reference internal" href="#running-parsedmarc-as-a-systemd-service">Running parsedmarc as a systemd service</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#using-the-kibana-dashboards">Using the Kibana dashboards</a><ul>
|
||||
<li><a class="reference internal" href="#dmarc-summary">DMARC Summary</a></li>
|
||||
<li><a class="reference internal" href="#dmarc-forensic-samples">DMARC Forensic Samples</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#dmarc-alignment-guide">DMARC Alignment Guide</a></li>
|
||||
<li><a class="reference internal" href="#what-if-a-sender-won-t-support-dkim-dmarc">What if a sender won’t support DKIM/DMARC?</a></li>
|
||||
<li><a class="reference internal" href="#module-parsedmarc">API</a><ul>
|
||||
<li><a class="reference internal" href="#module-parsedmarc.elastic">parsedmarc.elastic</a></li>
|
||||
</ul>
|
||||
@@ -174,18 +182,28 @@
|
||||
<h1>Welcome to parsedmarc’s documentation!<a class="headerlink" href="#welcome-to-parsedmarc-s-documentation" title="Permalink to this headline">¶</a></h1>
|
||||
<p><a class="reference external" href="https://travis-ci.org/domainaware/parsedmarc"><img alt="Build Status" src="https://travis-ci.org/domainaware/parsedmarc.svg?branch=master" /></a></p>
|
||||
<a class="reference external image-reference" href="_static/screenshots/dmarc-summary-charts.png"><img alt="A screenshot of DMARC summary charts in Kibana" class="align-center" src="_images/dmarc-summary-charts.png" style="width: 597.0px; height: 381.0px;" /></a>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> is a Python module and CLI utility for parsing DMARC reports.</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> 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.</p>
|
||||
<div class="section" id="features">
|
||||
<h2>Features<a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li>Parses draft and 1.0 standard aggregate reports</li>
|
||||
<li>Parses forensic reports</li>
|
||||
<li>Parses draft and 1.0 standard aggregate/rua reports</li>
|
||||
<li>Parses forensic/failure/ruf reports</li>
|
||||
<li>Can parse reports from an inbox over IMAP</li>
|
||||
<li>Transparently handles gzip or zip compressed reports</li>
|
||||
<li>Consistent data structures</li>
|
||||
<li>Simple JSON and/or CSV output</li>
|
||||
<li>Optionally email the results</li>
|
||||
<li>Optionally send the results to Elasticsearch, for use with premade Kibana dashboards</li>
|
||||
<li>Optionally send the results to Elasticsearch, for use with premade Kibana
|
||||
dashboards</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="resources">
|
||||
<h2>Resources<a class="headerlink" href="#resources" title="Permalink to this headline">¶</a></h2>
|
||||
<ul class="simple">
|
||||
<li><a class="reference external" href="https://seanthegeek.net/459/demystifying-dmarc/">Demystifying DMARC</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="cli-help">
|
||||
@@ -259,7 +277,8 @@
|
||||
<div class="section" id="spf-and-dmarc-record-validation">
|
||||
<h2>SPF and DMARC record validation<a class="headerlink" href="#spf-and-dmarc-record-validation" title="Permalink to this headline">¶</a></h2>
|
||||
<p>If you are looking for SPF and DMARC record validation and parsing,
|
||||
check out the sister project, <a class="reference external" href="https://domainaware.github.io/checkdmarc/">checkdmarc</a>.</p>
|
||||
check out the sister project,
|
||||
<a class="reference external" href="https://domainaware.github.io/checkdmarc/">checkdmarc</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="sample-aggregate-report-output">
|
||||
<h2>Sample aggregate report output<a class="headerlink" href="#sample-aggregate-report-output" title="Permalink to this headline">¶</a></h2>
|
||||
@@ -388,6 +407,10 @@ above commands.</p>
|
||||
<div class="section" id="elasticsearch-and-kibana">
|
||||
<h3>Elasticsearch and Kibana<a class="headerlink" href="#elasticsearch-and-kibana" title="Permalink to this headline">¶</a></h3>
|
||||
<p>To set up visual dashboards of DMARC data, install Elasticsearch and Kibana.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Elasticsearch/Kibana 6+ is required</p>
|
||||
</div>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo apt-get install -y openjdk-8-jre apt-transport-https
|
||||
wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch <span class="p">|</span> sudo apt-key add -
|
||||
<span class="nb">echo</span> <span class="s2">"deb https://artifacts.elastic.co/packages/6.x/apt stable main"</span> <span class="p">|</span> sudo tee -a /etc/apt/sources.list.d/elastic-6.x.list
|
||||
@@ -499,15 +522,15 @@ it.</p>
|
||||
<div class="admonition warning">
|
||||
<p class="first admonition-title">Warning</p>
|
||||
<p><code class="docutils literal notranslate"><span class="pre">--save-aggregate</span></code> and <code class="docutils literal notranslate"><span class="pre">--save-forensic</span></code> are separate options because
|
||||
you may not want to save forensic reports to your Elasticsearch instance,
|
||||
particularly if you are in a highly-regulated industry that handles
|
||||
sensitive data, such as healthcare or finance. If your legitimate outgoing
|
||||
email fails DMARC, it is possible that email may appear later in a
|
||||
forensic report.</p>
|
||||
you may not want to save forensic reports (also known as failure reports)
|
||||
to your Elasticsearch instance, particularly if you are in a
|
||||
highly-regulated industry that handles sensitive data, such as healthcare
|
||||
or finance. If your legitimate outgoing email fails DMARC, it is possible
|
||||
that email may appear later in a forensic report.</p>
|
||||
<p>Forensic reports contain the original headers of an email that failed a
|
||||
DMARC check, and sometimes may also include the full message body,
|
||||
depending on the policy of the reporting organisation.</p>
|
||||
<p class="last">Most reporting organisations do not send forensic reports of any kind for
|
||||
depending on the policy of the reporting organization.</p>
|
||||
<p class="last">Most reporting organizations do not send forensic reports of any kind for
|
||||
privacy reasons. While aggregate DMARC reports are sent at least daily,
|
||||
it is normal to receive very few forensic reports.</p>
|
||||
</div>
|
||||
@@ -543,13 +566,6 @@ arrive.</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo nano /etc/systemd/system/parsedmarc.service
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Edit the command line options of <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> in the service’s <code class="docutils literal notranslate"><span class="pre">ExecStart</span></code>
|
||||
setting to suit your needs.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Always pass the <code class="docutils literal notranslate"><span class="pre">--watch</span></code> option to <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> when running it as a
|
||||
service. Use <code class="docutils literal notranslate"><span class="pre">--silent</span></code> to only log errors.</p>
|
||||
</div>
|
||||
<div class="highlight-ini notranslate"><div class="highlight"><pre><span></span><span class="k">[Unit]</span>
|
||||
<span class="na">Description</span><span class="o">=</span><span class="s">parsedmarc mailbox watcher</span>
|
||||
<span class="na">Documentation</span><span class="o">=</span><span class="s">https://domainaware.github.io/parsedmarc/</span>
|
||||
@@ -563,6 +579,22 @@ service. Use <code class="docutils literal notranslate"><span class="pre">--sile
|
||||
<span class="na">WantedBy</span><span class="o">=</span><span class="s">multi-user.target</span>
|
||||
</pre></div>
|
||||
</div>
|
||||
<p>Edit the command line options of <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> in the service’s <code class="docutils literal notranslate"><span class="pre">ExecStart</span></code>
|
||||
setting to suit your needs.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Always pass the <code class="docutils literal notranslate"><span class="pre">--watch</span></code> option to <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> when running it as a
|
||||
service. Use <code class="docutils literal notranslate"><span class="pre">--silent</span></code> to only log errors.</p>
|
||||
</div>
|
||||
<div class="admonition warning">
|
||||
<p class="first admonition-title">Warning</p>
|
||||
<p class="last">As mentioned earlier, forensic/failure reports contain copies of emails
|
||||
that failed DMARC, including emails that may be legitimate and contain
|
||||
sensitive customer or business information. For privacy and/or regulatory
|
||||
reasons, you may not want to use the <code class="docutils literal notranslate"><span class="pre">--save-forensic</span></code> flag included in
|
||||
the example service configuration <code class="docutils literal notranslate"><span class="pre">ExecStart</span></code> setting, which would save
|
||||
these samples to Elasticsearch.</p>
|
||||
</div>
|
||||
<p>Then, enable the service</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo systemctl daemon-reload
|
||||
sudo systemctl <span class="nb">enable</span> parsedmarc.service
|
||||
@@ -574,8 +606,161 @@ sudo service parsedmarc restart
|
||||
<p class="last">You must also run the above commands whenever you edit
|
||||
<code class="docutils literal notranslate"><span class="pre">parsedmarc.service</span></code>.</p>
|
||||
</div>
|
||||
<p>Use this command to check the status of the service:</p>
|
||||
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>sudo service parsedmarc status
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="using-the-kibana-dashboards">
|
||||
<h2>Using the Kibana dashboards<a class="headerlink" href="#using-the-kibana-dashboards" title="Permalink to this headline">¶</a></h2>
|
||||
<p>The Kibana DMARC dashboards are a human-friendly way to understand the results
|
||||
from incoming DMARC reports.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">The default dashboard is DMARC Summary. To switch between dashboards,
|
||||
click on the Dashboard link in the left side menu of Kibana.</p>
|
||||
</div>
|
||||
<div class="section" id="dmarc-summary">
|
||||
<h3>DMARC Summary<a class="headerlink" href="#dmarc-summary" title="Permalink to this headline">¶</a></h3>
|
||||
<p>As the name suggests, this dashboard is the best place to start reviewing your
|
||||
aggregate DMARC data.</p>
|
||||
<p>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.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Messages should not be considered malicious just because they failed to pass
|
||||
DMARC; especially if you have just started collecting data. It may be a
|
||||
legitimate service that needs SPF and DKIM configured correctly.</p>
|
||||
</div>
|
||||
<p>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.</p>
|
||||
<p>Underneath the pie charts. you can see graphs of DMARC passage and message
|
||||
disposition over time.</p>
|
||||
<p>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.</p>
|
||||
<p>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. With that information, you can contact them and
|
||||
have them set up DKIM.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">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 businesses who send from reverse DNS addressees of
|
||||
parent, subsidiary, and outdated brands.</p>
|
||||
</div>
|
||||
<p>Further down the dashboard, you can filter by source country or source IP
|
||||
address.</p>
|
||||
<p>Tables showing SPF and DKIM alignment details are located under the IP address
|
||||
table.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">Previously, the alignment tables were included in a separate dashboard
|
||||
called DMARC Alignment Failures. That dashboard has been consolidated into
|
||||
the DMARC Summary dashboard. To view failures only, use the pie chart.</p>
|
||||
</div>
|
||||
<p>Any other filters work the same way. You can also add your own custom temporary
|
||||
filters by clicking on Add Filter at the upper right of the page.</p>
|
||||
</div>
|
||||
<div class="section" id="dmarc-forensic-samples">
|
||||
<h3>DMARC Forensic Samples<a class="headerlink" href="#dmarc-forensic-samples" title="Permalink to this headline">¶</a></h3>
|
||||
<p>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.</p>
|
||||
<div class="admonition note">
|
||||
<p class="first admonition-title">Note</p>
|
||||
<p class="last">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.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="dmarc-alignment-guide">
|
||||
<h2>DMARC Alignment Guide<a class="headerlink" href="#dmarc-alignment-guide" title="Permalink to this headline">¶</a></h2>
|
||||
<p>DMARC ensures that SPF and DKM authentication mechanisms actually authenticate
|
||||
against the same domain that the end user sees.</p>
|
||||
<p>A message passes a DMARC check by passing DKIM or SPF, <strong>as long as the related
|
||||
indicators are also in alignment</strong>.</p>
|
||||
<table border="1" class="docutils">
|
||||
<colgroup>
|
||||
<col width="33%" />
|
||||
<col width="33%" />
|
||||
<col width="33%" />
|
||||
</colgroup>
|
||||
<tbody valign="top">
|
||||
<tr class="row-odd"><td> </td>
|
||||
<td><strong>DKIM</strong></td>
|
||||
<td><strong>SPF</strong></td>
|
||||
</tr>
|
||||
<tr class="row-even"><td><strong>Passing</strong></td>
|
||||
<td>The signature in the
|
||||
DKIM header is
|
||||
validated using a
|
||||
public key that is
|
||||
published as a DNS
|
||||
record of the domain
|
||||
name specified in the
|
||||
signature</td>
|
||||
<td>The mail server’s IP
|
||||
address is listed in
|
||||
the SPF record of the
|
||||
domain in the SMTP
|
||||
envelope’s mail from
|
||||
header</td>
|
||||
</tr>
|
||||
<tr class="row-odd"><td><strong>Alignment</strong></td>
|
||||
<td>The signing domain
|
||||
aligns with the
|
||||
domain in the
|
||||
message’s from header</td>
|
||||
<td>The domain in the
|
||||
SMTP envelope’s mail
|
||||
from header aligns
|
||||
with the domain in
|
||||
the message’s from
|
||||
header</td>
|
||||
</tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="section" id="what-if-a-sender-won-t-support-dkim-dmarc">
|
||||
<h2>What if a sender won’t support DKIM/DMARC?<a class="headerlink" href="#what-if-a-sender-won-t-support-dkim-dmarc" title="Permalink to this headline">¶</a></h2>
|
||||
<ol class="arabic simple">
|
||||
<li>Some vendors don’t know about DMARC yet; ask about SPF and DKIM/email
|
||||
authentication.</li>
|
||||
<li>Check if they can send through your email relays instead of theirs.</li>
|
||||
<li>Do they really need to spoof your domain? Why not use the display
|
||||
name instead?</li>
|
||||
<li>Worst case, have that vendor send email as a specific subdomain of
|
||||
your domain (e.g. <code class="docutils literal notranslate"><span class="pre">noreply@news.example.com</span></code>), and then create
|
||||
separate SPF and DMARC records on <code class="docutils literal notranslate"><span class="pre">news.example.com</span></code>, and set
|
||||
<code class="docutils literal notranslate"><span class="pre">p=none</span></code> in that DMARC record.</li>
|
||||
</ol>
|
||||
<blockquote>
|
||||
<div><div class="admonition warning">
|
||||
<p class="first admonition-title">Warning</p>
|
||||
<p class="last">Do not alter the <code class="docutils literal notranslate"><span class="pre">p</span></code> or <code class="docutils literal notranslate"><span class="pre">sp</span></code> values of the DMARC record on the
|
||||
Top-Level Domain (TLD) – that would leave you vulnerable to spoofing of
|
||||
your TLD and/or any subdomain.</p>
|
||||
</div>
|
||||
</div></blockquote>
|
||||
</div>
|
||||
<div class="section" id="module-parsedmarc">
|
||||
<span id="api"></span><h2>API<a class="headerlink" href="#module-parsedmarc" title="Permalink to this headline">¶</a></h2>
|
||||
<p>A Python package for parsing DMARC reports</p>
|
||||
@@ -1059,7 +1244,7 @@ to a callback function</p>
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'./',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
# Sphinx inventory version 2
|
||||
# Project: parsedmarc
|
||||
# Version: 3.6.0
|
||||
# Version: 3.7.0
|
||||
# The remainder of this file is compressed using zlib.
|
||||
xÚ”KNÃ0†÷=…lSÑmw©‹HU‹ÄÒríibÉŽ-{RRV\ƒëqì$¥¥°ˆ ;kòÿx ±e΃ÐÌqb÷smD£€ÜY h§juÝDz’Mì—xº(òåƒsÆE Z¥©Éì”<Gê SRäeé d+°Æa2_ä«» ÙGã ö’§âËxt‰õ®‹§Ô�b eâ(hš+Lì×l"9å”�vBð‘ß65 �û�•²Ãh©ëLÑÐAà!¨«Ël·ÃÔþÏ�VÆcB™šIòûF¥P-:Æ‘¶Z�fÊp·î4TëéÖ æ²1m’ÉЬWiGcU£YMQjðÈ´��aš10Ú£;þÜ„TöHicoq¶9‰ô�¶›ýehzÕâGÙ>Ž�û]ªÏYíÉ6ݯg´Íø¾½0äÕ˜]-¡î"Ä£˜+¶E²9D; YÄãä(†Gщâ7a7Ñ�ã%>ÞÞ= ÚFC�,¦¿š„‡ó—tvŸ >ô~Eÿæö‰‡·åÑÇzñºÿ¾d%L>%;¤ë
|
||||
+3
-3
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>Python Module Index — parsedmarc 3.6.0 documentation</title>
|
||||
<title>Python Module Index — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -59,7 +59,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -200,7 +200,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'./',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+3
-3
@@ -8,7 +8,7 @@
|
||||
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
|
||||
<title>Search — parsedmarc 3.6.0 documentation</title>
|
||||
<title>Search — parsedmarc 3.7.0 documentation</title>
|
||||
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@
|
||||
|
||||
|
||||
<div class="version">
|
||||
3.6.0
|
||||
3.7.0
|
||||
</div>
|
||||
|
||||
|
||||
@@ -188,7 +188,7 @@
|
||||
<script type="text/javascript">
|
||||
var DOCUMENTATION_OPTIONS = {
|
||||
URL_ROOT:'./',
|
||||
VERSION:'3.6.0',
|
||||
VERSION:'3.7.0',
|
||||
LANGUAGE:'None',
|
||||
COLLAPSE_INDEX:false,
|
||||
FILE_SUFFIX:'.html',
|
||||
|
||||
+1
-1
@@ -1 +1 @@
|
||||
Search.setIndex({docnames:["index"],envversion:53,filenames:["index.rst"],objects:{"":{parsedmarc:[0,0,0,"-"]},"parsedmarc.elastic":{AlreadySaved:[0,1,1,""],create_indexes:[0,2,1,""],save_aggregate_report_to_elasticsearch:[0,2,1,""],save_forensic_report_to_elasticsearch:[0,2,1,""],set_hosts:[0,2,1,""]},parsedmarc:{IMAPError:[0,1,1,""],InvalidAggregateReport:[0,1,1,""],InvalidDMARCReport:[0,1,1,""],InvalidForensicReport:[0,1,1,""],ParserError:[0,1,1,""],SMTPError:[0,1,1,""],elastic:[0,0,0,"-"],email_results:[0,2,1,""],extract_xml:[0,2,1,""],get_dmarc_reports_from_inbox:[0,2,1,""],get_report_zip:[0,2,1,""],human_timestamp_to_datetime:[0,2,1,""],parse_aggregate_report_file:[0,2,1,""],parse_aggregate_report_xml:[0,2,1,""],parse_forensic_report:[0,2,1,""],parse_report_email:[0,2,1,""],parse_report_file:[0,2,1,""],parsed_aggregate_reports_to_csv:[0,2,1,""],parsed_forensic_reports_to_csv:[0,2,1,""],save_output:[0,2,1,""],watch_inbox:[0,2,1,""]}},objnames:{"0":["py","module","Python module"],"1":["py","exception","Python exception"],"2":["py","function","Python function"]},objtypes:{"0":"py:module","1":"py:exception","2":"py:function"},terms:{"50m":0,"break":0,"byte":0,"default":0,"float":0,"function":0,"import":0,"int":0,"null":0,"public":0,"return":0,"true":0,"while":0,DNS:0,For:0,OLE:0,The:0,Then:0,Use:0,_input:0,abl:0,abov:0,access:0,acm:0,actual:0,add:0,add_head:0,address:0,adkim:0,administr:0,adsl:0,aes256:0,after:0,age:0,aggregate_report:0,alreadysav:0,also:0,alwai:0,ani:0,answer:0,apache2:0,appear:0,appendix:0,apt:0,archiv:0,archive_fold:0,argument:0,arriv:0,arrival_d:0,artifact:0,ask:0,aspf:0,attach:0,attachment_filenam:0,auth_bas:0,auth_basic_user_fil:0,auth_result:0,authent:0,avail:0,base_domain:0,basic:0,becaus:0,been:0,begin_d:0,bellsouth:0,below:0,bin:0,bodi:0,bool:0,callback:0,can:0,cert:0,certif:0,chac:0,chacha20:0,check:0,checkdmarc:0,chmod:0,chown:0,click:0,cloudflar:0,com:0,command:0,commerci:0,common:0,compress:0,configur:0,connect:0,consist:0,contact:0,contain:0,content:0,context:0,control:0,convert:0,could:0,count:0,countri:0,creat:0,create_index:0,crt:0,csr:0,daemon:0,dai:0,daili:0,dashboard:0,data:0,date_rang:0,datetim:0,deb:0,debian:0,debug:0,delet:0,descript:0,develop:0,dhparam:0,directli:0,directori:0,disabl:0,disposit:0,dkim:0,dkim_align:0,dkim_domain:0,dkim_result:0,dkim_selector:0,dmarc_aggreg:0,dmarc_forens:0,dns_timeout:0,doe:0,domain:0,domainawar:0,don:0,download:0,draft:0,ecdh:0,ecdsa:0,echo:0,edit:0,elasticsearch_host:0,els:0,email:0,email_result:0,enabl:0,encount:0,end_dat:0,envelope_from:0,envelope_to:0,error:0,etc:0,even:0,exampl:0,exampleus:0,except:0,execstart:0,exist:0,exit:0,extract:0,extract_xml:0,fail:0,fals:0,feedback:0,feedback_report:0,fetch:0,few:0,field:0,file:0,file_path:0,filenam:0,fill:0,financ:0,first:0,flat:0,folder:0,foobar:0,forensic_report:0,format:0,forward:0,found:0,fqdn:0,frame:0,from:0,full:0,gcm:0,gener:0,get:0,get_dmarc_reports_from_inbox:0,get_report_zip:0,git:0,github:0,give:0,given:0,gpg:0,gzip:0,handl:0,has:0,have:0,header:0,header_from:0,healthcar:0,here:0,highli:0,host:0,hostnam:0,htpasswd:0,http2:0,http:0,httpasswd:0,human:0,human_timestamp:0,human_timestamp_to_datetim:0,identifi:0,idl:0,imap:0,imaperror:0,inbox:0,includ:0,includesubdomain:0,incom:0,index:0,industri:0,inform:0,input:0,input_:0,instanc:0,invalid:0,invalidaggregatereport:0,invaliddmarcreport:0,invalidforensicreport:0,ip_address:0,issu:0,its:0,jre:0,kei:0,keyout:0,kibana_saved_object:0,kind:0,later:0,latest:0,least:0,legitim:0,libemail:0,like:0,line:0,link:0,linux:0,list:0,listen:0,local:0,localhost:0,locat:0,log:0,login:0,look:0,maco:0,mai:0,mail:0,mail_from:0,mail_to:0,mailbox:0,main:0,manag:0,match:0,max:0,mechan:0,messag:0,mfrom:0,microsoft:0,mkdir:0,modul:0,more:0,most:0,move:0,msg:0,msgconvert:0,multi:0,must:0,name:0,nameserv:0,nano:0,need:0,net:0,newkei:0,newli:0,next:0,nginx:0,node:0,none:0,norepli:0,normal:0,nosniff:0,now:0,number:0,object:0,occur:0,off:0,office365:0,older:0,onc:0,one:0,onli:0,openjdk:0,openssl:0,ordereddict:0,org:0,org_email:0,org_extra_contact_info:0,org_nam:0,organis:0,origin:0,other:0,out:0,outgo:0,outgoing_attach:0,outgoing_from:0,outgoing_host:0,outgoing_messag:0,outgoing_password:0,outgoing_subject:0,outgoing_to:0,outgoing_us:0,outlook:0,output_directori:0,over:0,overrid:0,overwrit:0,own:0,pack:0,packag:0,page:0,paramet:0,pars:0,parse_aggregate_report_fil:0,parse_aggregate_report_xml:0,parse_forensic_report:0,parse_report_email:0,parse_report_fil:0,parsed_aggregate_reports_to_csv:0,parsed_forensic_reports_to_csv:0,parser:0,parsererror:0,particularli:0,pasedmarc:[],pass:0,password:0,patch:0,path:0,pattern:0,pct:0,pem:0,perl:0,permiss:0,pip3:0,pip:0,place:0,plain:0,pleas:0,polici:0,policy_evalu:0,policy_override_com:0,policy_override_reason:0,policy_publish:0,poly1305:0,port:0,posit:0,possibl:0,preload:0,premad:0,print:0,privaci:0,process:0,produc:0,program:0,project:0,prompt:0,provid:0,proxi:0,proxy_add_x_forwarded_for:0,proxy_pass:0,proxy_set_head:0Line truncated
|
||||
Search.setIndex({docnames:["index"],envversion:53,filenames:["index.rst"],objects:{"":{parsedmarc:[0,0,0,"-"]},"parsedmarc.elastic":{AlreadySaved:[0,1,1,""],create_indexes:[0,2,1,""],save_aggregate_report_to_elasticsearch:[0,2,1,""],save_forensic_report_to_elasticsearch:[0,2,1,""],set_hosts:[0,2,1,""]},parsedmarc:{IMAPError:[0,1,1,""],InvalidAggregateReport:[0,1,1,""],InvalidDMARCReport:[0,1,1,""],InvalidForensicReport:[0,1,1,""],ParserError:[0,1,1,""],SMTPError:[0,1,1,""],elastic:[0,0,0,"-"],email_results:[0,2,1,""],extract_xml:[0,2,1,""],get_dmarc_reports_from_inbox:[0,2,1,""],get_report_zip:[0,2,1,""],human_timestamp_to_datetime:[0,2,1,""],parse_aggregate_report_file:[0,2,1,""],parse_aggregate_report_xml:[0,2,1,""],parse_forensic_report:[0,2,1,""],parse_report_email:[0,2,1,""],parse_report_file:[0,2,1,""],parsed_aggregate_reports_to_csv:[0,2,1,""],parsed_forensic_reports_to_csv:[0,2,1,""],save_output:[0,2,1,""],watch_inbox:[0,2,1,""]}},objnames:{"0":["py","module","Python module"],"1":["py","exception","Python exception"],"2":["py","function","Python function"]},objtypes:{"0":"py:module","1":"py:exception","2":"py:function"},terms:{"50m":0,"break":0,"byte":0,"case":0,"default":0,"float":0,"function":0,"import":0,"int":0,"long":0,"new":0,"null":0,"public":0,"return":0,"switch":0,"true":0,"while":0,DNS:0,For:0,OLE:0,That:0,The:0,Then:0,These:0,Use:0,With:0,_input:0,abl:0,about:0,abov:0,access:0,account:0,acm:0,across:0,actual:0,add:0,add_head:0,address:0,addresse:0,adkim:0,administr:0,adsl:0,aes256:0,after:0,against:0,agari:0,age:0,aggregate_report:0,all:0,alreadysav:0,also:0,alter:0,altern:0,alwai:0,ani:0,answer:0,apache2:0,appear:0,appendix:0,apt:0,archiv:0,archive_fold:0,argument:0,arriv:0,arrival_d:0,artifact:0,ask:0,aspf:0,attach:0,attachment_filenam:0,auth_bas:0,auth_basic_user_fil:0,auth_result:0,authent:0,avail:0,avoid:0,b2c:0,base:0,base_domain:0,basic:0,becaus:0,been:0,begin_d:0,bellsouth:0,below:0,best:0,between:0,bin:0,bodi:0,bool:0,brand:0,busi:0,call:0,callback:0,can:0,caus:0,center:0,cert:0,certif:0,chac:0,chacha20:0,chang:0,chart:0,check:0,checkdmarc:0,chines:0,chmod:0,chown:0,click:0,cloudflar:0,collect:0,com:0,come:0,command:0,commerci:0,common:0,compress:0,configur:0,connect:0,consid:0,consist:0,consolid:0,consum:0,contact:0,contain:0,content:0,context:0,control:0,convert:0,copi:0,correctli:0,could:0,count:0,countri:0,creat:0,create_index:0,crt:0,csr:0,custom:0,daemon:0,dai:0,daili:0,dashboard:[],data:0,date_rang:0,datetim:0,deb:0,debian:0,debug:0,delet:0,demystifi:0,descript:0,detail:0,develop:0,dhparam:0,differ:0,directli:0,directori:0,disabl:0,displai:0,disposit:0,dkim:[],dkim_align:0,dkim_domain:0,dkim_result:0,dkim_selector:0,dkm:0,dmarc_aggreg:0,dmarc_forens:0,dmarcian:0,dns_timeout:0,doe:0,domain:0,domainawar:0,don:0,down:0,download:0,draft:0,earlier:0,ecdh:0,ecdsa:0,echo:0,edit:0,elasticsearch_host:0,els:0,email:0,email_result:0,enabl:0,encount:0,end:0,end_dat:0,ensur:0,entir:0,envelop:0,envelope_from:0,envelope_to:0,error:0,especi:0,etc:0,even:0,exampl:0,exampleus:0,except:0,execstart:0,exist:0,exit:0,extract:0,extract_xml:0,fail:0,failur:0,fals:0,feedback:0,feedback_report:0,fetch:0,few:0,field:0,file:0,file_path:0,filenam:0,fill:0,filter:0,financ:0,find:0,first:0,flag:0,flat:0,folder:0,foobar:0,forensic_report:0,format:0,forward:0,found:0,fqdn:0,frame:0,friendli:0,from:0,full:0,further:0,gcm:0,gener:0,get:0,get_dmarc_reports_from_inbox:0,get_report_zip:0,git:0,github:0,give:0,given:0,glass:0,gmail:0,googl:0,gpg:0,graph:0,group:0,gzip:0,handl:0,has:0,have:0,header:0,header_from:0,healthcar:0,here:0,high:0,highli:0,host:0,hostnam:0,hover:0,htpasswd:0,http2:0,http:0,httpasswd:0,human:0,human_timestamp:0,human_timestamp_to_datetim:0,icon:0,identifi:0,idl:0,imap:0,imaperror:0,inbox:0,includ:0,includesubdomain:0,incom:0,index:0,industri:0,inform:0,input:0,input_:0,instanc:0,instead:0,invalid:0,invalidaggregatereport:0,invaliddmarcreport:0,invalidforensicreport:0,ip_address:0,issu:0,its:0,jre:0,just:0,kei:0,keyout:0,kibana_saved_object:0,kind:0,know:0,known:0,later:0,latest:0,leak:0,least:0,leav:0,left:0,legitim:0,level:0,libemail:0,like:0,line:0,link:0,linux:0,list:0,listen:0,local:0,localhost:0,locat:0,log:0,login:0,look:0,lot:0,maco:0,magnifi:0,mai:0,mail:0,mail_from:0,mail_to:0,mailbox:0,main:0,malici:0,manag:0,market:0,match:0,max:0,mechan:0,mention:0,menu:0,messag:0,mfrom:0,microsoft:0,might:0,mkdir:0,modul:0,more:0,most:0,mous:0,move:0,msg:0,msgconvert:0,multi:0,must:0,name:0,nameserv:0,nano:0,need:0,net:0,newkei:0,newli:0,next:0,nginx:0,node:0,none:0,norepli:0,normal:0,nosniff:0,notabl:0,now:0,number:0,object:0,observ:0,occur:0,off:0,office365:0,often:0,old:0,older:0,onc:0,ondmarc:0,one:0,onli:0,open:0,openjdk:0,openssl:0,ordereddict:0,org:0,org_email:0,org_extra_contact_info:0,org_nam:0,organ:0,organis:[],origin:0,other:0,our:0,out:0,outdat:0,outgo:0,outgoing_attach:0,outgoing_from:0,outgoing_host:0,outgoing_messag:0,outgoing_password:0,outgoing_subject:0,outgoing_to:0,outgLine truncated
|
||||
Reference in new issue
Block a user