6.0.2

2026-10-30 22:25:43 +00:00 · 2019-02-10 13:15:55 -05:00
1 parent 8c593a2b22
commit 71d2581c35
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>Overview: module code &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>Overview: module code &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>parsedmarc &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>parsedmarc &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -183,7 +183,7 @@
 <span class="kn">from</span> <span class="nn">parsedmarc.utils</span> <span class="k">import</span> <span class="n">timestamp_to_human</span><span class="p">,</span> <span class="n">human_timestamp_to_datetime</span>
 <span class="kn">from</span> <span class="nn">parsedmarc.utils</span> <span class="k">import</span> <span class="n">parse_email</span>

-<span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;6.0.1&quot;</span>
+<span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;6.0.2&quot;</span>

 <span class="n">logging</span><span class="o">.</span><span class="n">basicConfig</span><span class="p">(</span>
    <span class="nb">format</span><span class="o">=</span><span class="s1">&#39;</span><span class="si">%(levelname)8s</span><span class="s1">:</span><span class="si">%(filename)s</span><span class="s1">:</span><span class="si">%(lineno)d</span><span class="s1">:&#39;</span>
@@ -1140,7 +1140,10 @@
                    <span class="n">raw_msg</span> <span class="o">=</span> <span class="n">raw_msg</span><span class="p">[</span><span class="n">msg_key</span><span class="p">]</span>

                <span class="k">except</span> <span class="p">(</span><span class="ne">ConnectionResetError</span><span class="p">,</span> <span class="n">socket</span><span class="o">.</span><span class="n">error</span><span class="p">,</span>
-                        <span class="ne">TimeoutError</span><span class="p">)</span> <span class="k">as</span> <span class="n">error</span><span class="p">:</span>
+                        <span class="ne">TimeoutError</span><span class="p">,</span>
+                        <span class="n">imapclient</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">IMAPClientError</span><span class="p">)</span> <span class="k">as</span> <span class="n">error</span><span class="p">:</span>
+                    <span class="n">error</span> <span class="o">=</span> <span class="n">error</span><span class="o">.</span><span class="fm">__str__</span><span class="p">()</span><span class="o">.</span><span class="n">lstrip</span><span class="p">(</span><span class="s2">&quot;b&#39;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s2">&quot;&#39;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span>
+                        <span class="s2">&quot;.&quot;</span><span class="p">)</span>
                    <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s2">&quot;IMAP error: </span><span class="si">{0}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">error</span><span class="o">.</span><span class="fm">__str__</span><span class="p">()))</span>
                    <span class="n">logger</span><span class="o">.</span><span class="n">debug</span><span class="p">(</span><span class="s2">&quot;Reconnecting to IMAP&quot;</span><span class="p">)</span>
                    <span class="k">try</span><span class="p">:</span>
@@ -1172,12 +1175,6 @@
                <span class="k">elif</span> <span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;report_type&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s2">&quot;forensic&quot;</span><span class="p">:</span>
                    <span class="n">forensic_reports</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">parsed_email</span><span class="p">[</span><span class="s2">&quot;report&quot;</span><span class="p">])</span>
                    <span class="n">forensic_report_msg_uids</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">msg_uid</span><span class="p">)</span>
-
-            <span class="k">except</span> <span class="n">imapclient</span><span class="o">.</span><span class="n">exceptions</span><span class="o">.</span><span class="n">IMAPClientError</span> <span class="k">as</span> <span class="n">error</span><span class="p">:</span>
-                <span class="n">error</span> <span class="o">=</span> <span class="n">error</span><span class="o">.</span><span class="fm">__str__</span><span class="p">()</span><span class="o">.</span><span class="n">lstrip</span><span class="p">(</span><span class="s2">&quot;b&#39;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s2">&quot;&#39;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">rstrip</span><span class="p">(</span><span class="s2">&quot;.&quot;</span><span class="p">)</span>
-                <span class="n">error</span> <span class="o">=</span> <span class="s2">&quot;IMAP error: Skipping message UID </span><span class="si">{0}</span><span class="s2">: </span><span class="si">{1}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
-                    <span class="n">msg_uid</span><span class="p">,</span> <span class="n">error</span><span class="p">)</span>
-                <span class="n">logger</span><span class="o">.</span><span class="n">error</span><span class="p">(</span><span class="s2">&quot;IMAP error: </span><span class="si">{0}</span><span class="s2">&quot;</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">except</span> <span class="n">InvalidDMARCReport</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="n">error</span><span class="o">.</span><span class="fm">__str__</span><span class="p">())</span>
                <span class="k">if</span> <span class="ow">not</span> <span class="n">test</span><span class="p">:</span>
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>parsedmarc.elastic &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>parsedmarc.elastic &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>parsedmarc.splunk &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>parsedmarc.splunk &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>parsedmarc.utils &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>parsedmarc.utils &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -162,6 +162,7 @@
 <span class="kn">import</span> <span class="nn">hashlib</span>
 <span class="kn">import</span> <span class="nn">base64</span>
 <span class="kn">import</span> <span class="nn">platform</span>
+<span class="kn">import</span> <span class="nn">atexit</span>

 <span class="kn">import</span> <span class="nn">dateparser</span>
 <span class="kn">import</span> <span class="nn">dns.reversename</span>
@@ -172,7 +173,7 @@
 <span class="kn">import</span> <span class="nn">requests</span>
 <span class="kn">import</span> <span class="nn">publicsuffix</span>

-<span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;5.0.2&quot;</span>
+<span class="n">__version__</span> <span class="o">=</span> <span class="s2">&quot;6.0.2&quot;</span>

 <span class="n">USER_AGENT</span> <span class="o">=</span> <span class="s2">&quot;Mozilla/5.0 ((0 </span><span class="si">{1}</span><span class="s2">)) parsedmarc/</span><span class="si">{2}</span><span class="s2">&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span>
            <span class="n">platform</span><span class="o">.</span><span class="n">system</span><span class="p">(),</span>
@@ -183,6 +184,16 @@

 <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="s2">&quot;parsedmarc&quot;</span><span class="p">)</span>

+<span class="n">tempdir</span> <span class="o">=</span> <span class="n">tempfile</span><span class="o">.</span><span class="n">mkdtemp</span><span class="p">()</span>
+
+
+<span class="k">def</span> <span class="nf">_cleanup</span><span class="p">():</span>
+    <span class="sd">&quot;&quot;&quot;Remove temporary files&quot;&quot;&quot;</span>
+    <span class="n">shutil</span><span class="o">.</span><span class="n">rmtree</span><span class="p">(</span><span class="n">tempdir</span><span class="p">)</span>
+
+
+<span class="n">atexit</span><span class="o">.</span><span class="n">register</span><span class="p">(</span><span class="n">_cleanup</span><span class="p">)</span>
+

 <div class="viewcode-block" id="EmailParserError"><a class="viewcode-back" href="../../index.html#parsedmarc.utils.EmailParserError">[docs]</a><span class="k">class</span> <span class="nc">EmailParserError</span><span class="p">(</span><span class="ne">RuntimeError</span><span class="p">):</span>
    <span class="sd">&quot;&quot;&quot;Raised when an error parsing the email occurs&quot;&quot;&quot;</span></div>
@@ -224,7 +235,7 @@
 <span class="sd">        str: The base domain of the given domain</span>

 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="n">psl_path</span> <span class="o">=</span> <span class="s2">&quot;.public_suffix_list.dat&quot;</span>
+    <span class="n">psl_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">tempdir</span><span class="p">,</span> <span class="s2">&quot;public_suffix_list.dat&quot;</span><span class="p">)</span>

    <span class="k">def</span> <span class="nf">download_psl</span><span class="p">():</span>
        <span class="n">url</span> <span class="o">=</span> <span class="s2">&quot;https://publicsuffix.org/list/public_suffix_list.dat&quot;</span>
@@ -399,8 +410,6 @@
 <span class="sd">    Returns:</span>
 <span class="sd">        str: And ISO country code associated with the given IP address</span>
 <span class="sd">    &quot;&quot;&quot;</span>
-    <span class="n">db_filename</span> <span class="o">=</span> <span class="s2">&quot;.GeoLite2-Country.mmdb&quot;</span>
-
    <span class="k">def</span> <span class="nf">download_country_database</span><span class="p">(</span><span class="n">location</span><span class="o">=</span><span class="s2">&quot;.GeoLite2-Country.mmdb&quot;</span><span class="p">):</span>
        <span class="sd">&quot;&quot;&quot;Downloads the MaxMind Geolite2 Country database</span>

@@ -422,22 +431,23 @@

    <span class="n">system_paths</span> <span class="o">=</span> <span class="p">[</span><span class="s2">&quot;/usr/local/share/GeoIP/GeoLite2-Country.mmdb&quot;</span><span class="p">,</span>
                    <span class="s2">&quot;/usr/share/GeoIP/GeoLite2-Country.mmdb&quot;</span><span class="p">]</span>
-    <span class="n">db_path</span> <span class="o">=</span> <span class="s2">&quot;&quot;</span>
+    <span class="n">db_path</span> <span class="o">=</span> <span class="kc">None</span>

    <span class="k">for</span> <span class="n">system_path</span> <span class="ow">in</span> <span class="n">system_paths</span><span class="p">:</span>
        <span class="k">if</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">system_path</span><span class="p">):</span>
            <span class="n">db_path</span> <span class="o">=</span> <span class="n">system_path</span>
            <span class="k">break</span>

-    <span class="k">if</span> <span class="n">db_path</span> <span class="o">==</span> <span class="s2">&quot;&quot;</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">db_filename</span><span class="p">):</span>
-            <span class="n">download_country_database</span><span class="p">(</span><span class="n">db_filename</span><span class="p">)</span>
+    <span class="k">if</span> <span class="n">db_path</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
+        <span class="n">db_path</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">tempdir</span><span class="p">,</span> <span class="s2">&quot;GeoLite2-Country.mmdb&quot;</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">db_path</span><span class="p">):</span>
+            <span class="n">download_country_database</span><span class="p">(</span><span class="n">db_path</span><span class="p">)</span>
        <span class="k">else</span><span class="p">:</span>
            <span class="n">db_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">db_filename</span><span class="p">)</span><span class="o">.</span><span class="n">st_mtime</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">db_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">db_age</span> <span class="o">&gt;</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">60</span><span class="p">):</span>
                <span class="n">download_country_database</span><span class="p">()</span>
-        <span class="n">db_path</span> <span class="o">=</span> <span class="n">db_filename</span>
+        <span class="n">db_path</span> <span class="o">=</span> <span class="n">db_path</span>

    <span class="n">db_reader</span> <span class="o">=</span> <span class="n">geoip2</span><span class="o">.</span><span class="n">database</span><span class="o">.</span><span class="n">Reader</span><span class="p">(</span><span class="n">db_path</span><span class="p">)</span>

@@ -137,7 +137,7 @@ The full set of configuration options are:
    - ``save_forensic`` - bool: Save forensic report data to the Elasticsearch and/or Splunk
    - ``strip_attachments_payloads`` - bool: Remove attachment payloads from results
    - ``output`` - str: Directory to place JSON and CSV files in
-    - ``nameservers`` -  str: A comma separated list of DNS resolvers (Default: Cloudflare's public resolvers)
+    - ``nameservers`` -  str: A comma separated list of DNS resolvers (Default: `Cloudflare's public resolvers`_)
    - ``dns_timeout`` - float: DNS timeout period
    - ``debug`` - bool: Print debugging messages
    - ``silent`` - bool: Only print errors (Default: True)
@@ -185,6 +185,16 @@ The full set of configuration options are:
    - ``message`` - str: The email message (Default: Please see the attached parsedmarc report.)


+.. warning::
+
+    It is **strongly recommended** to **not** use the ``nameservers`` setting.
+    By default, ``parsedmarc`` uses `Cloudflare's public resolvers`_,
+    which are much faster and more reliable than Google, Cisco OpenDNS, or
+    even most local resolvers.
+
+    The ``nameservers`` option should only be used if your network blocks DNS
+    requests to outside resolvers.
+
 .. warning::

    ``save_aggregate`` and ``save_forensic`` are separate options because
@@ -203,10 +213,10 @@ The full set of configuration options are:
    it is normal to receive very few forensic reports.

   An alternative approach is to still collect forensic/failure/ruf reports
-   in your DMARC inbox, but run ``parsedmarc`` with ``save_forensic = True`` manually on a
-   separate IMAP folder (using the  ``reports_folder`` option), after you have manually
-   moved known samples you want to save to that folder (e.g. malicious
-   samples and non-sensitive legitimate samples).
+   in your DMARC inbox, but run ``parsedmarc`` with ``save_forensic = True``
+   manually on a separate IMAP folder (using the  ``reports_folder`` option),
+   after you have manually moved known samples you want to save to that
+   folder (e.g. malicious samples and non-sensitive legitimate samples).

 Sample aggregate report output
 ==============================
@@ -1164,6 +1174,46 @@ What if a sender won't support DKIM/DMARC?
     Top-Level Domain (TLD) – that would leave you vulnerable to spoofing of
     your TLD and/or any subdomain.

+What about mailing lists?
+=========================
+
+When you deploy DMARC on your domain, you might find that messages relayed by
+mailing lists are failing DMARC. This has two causes:
+
+#. You are not DKIM signing your mail like you should be
+#. The mailing list is altering emails in ways that are not DMARC compliant
+   before sending them
+
+`Joe Nelson`_ does a fantastic job of explaining exactly what mailing lists
+should and shouldn't do to be DMARC compliant. Rather than repeat his fine
+work, here's a TL;DR:
+
+If you run a mailing list
+-------------------------
+
+**Do**
+
+- Retain headers from the original message
+- Add `RFC 2369`_ List-Unsubscribe headers to outgoing messages, instead of
+  adding unsubscribe links to the body
+
+   ::
+
+      List-Unsubscribe: <https://list.example.com/unsubscribe-link>
+
+- Add `RFC 2919`_ List-Id headers instead of modifying the subject
+
+   ::
+
+      List-Id: Example Mailing List <list.example.com>
+
+**Do not**
+
+* Remove or modify any existing headers from the original message, including
+  From, Date, Subject, etc.
+* Add to or remove content from the message body, **including traditional
+  disclaimers and unsubscribe footers**
+
 API
 ===

@@ -1217,6 +1267,8 @@ Indices and tables

 .. _Demystifying DMARC: https://seanthegeek.net/459/demystifying-dmarc/

+.. _Cloudflare's public resolvers: https://1.1.1.1/
+
 .. _download the latest portable Linux version of pypy3: https://github.com/squeaky-pl/portable-pypy#portable-pypy-distribution-for-linux

 .. _Elasticsearch: https://www.elastic.co/guide/en/elasticsearch/reference/current/rpm.html
@@ -1232,3 +1284,9 @@ Indices and tables
 .. _HTTP Event collector (HEC): http://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHEC

 .. _XML files: https://github.com/domainaware/parsedmarc/tree/master/splunk
+
+.. _Joe Nelson: https://begriffs.com/posts/2018-09-18-dmarc-mailing-list.html
+
+.. _RFC 2369: https://tools.ietf.org/html/rfc2369
+
+.. _RFC 2919: https://tools.ietf.org/html/rfc2919
@@ -1,6 +1,6 @@
 var DOCUMENTATION_OPTIONS = {
    URL_ROOT: document.getElementById("documentation_options").getAttribute('data-url_root'),
-    VERSION: '6.0.1',
+    VERSION: '6.0.2',
    LANGUAGE: 'None',
    COLLAPSE_INDEX: false,
    FILE_SUFFIX: '.html',
@@ -9,7 +9,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>Index &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>Index &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -57,7 +57,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>parsedmarc documentation - Open source DMARC report analyzer and visualizer &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>parsedmarc documentation - Open source DMARC report analyzer and visualizer &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -125,6 +125,10 @@
 </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="#what-about-mailing-lists">What about mailing lists?</a><ul>
+<li><a class="reference internal" href="#if-you-run-a-mailing-list">If you run a mailing list</a></li>
+</ul>
+</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>
 <li><a class="reference internal" href="#parsedmarc-splunk">parsedmarc.splunk</a><ul>
@@ -320,7 +324,7 @@ lookalike domain monitoring, check out <a class="reference external" href="https
 <li><code class="docutils literal notranslate"><span class="pre">save_forensic</span></code> - bool: Save forensic report data to the Elasticsearch and/or Splunk</li>
 <li><code class="docutils literal notranslate"><span class="pre">strip_attachments_payloads</span></code> - bool: Remove attachment payloads from results</li>
 <li><code class="docutils literal notranslate"><span class="pre">output</span></code> - str: Directory to place JSON and CSV files in</li>
-<li><code class="docutils literal notranslate"><span class="pre">nameservers</span></code> -  str: A comma separated list of DNS resolvers (Default: Cloudflare’s public resolvers)</li>
+<li><code class="docutils literal notranslate"><span class="pre">nameservers</span></code> -  str: A comma separated list of DNS resolvers (Default: <a class="reference external" href="https://1.1.1.1/">Cloudflare’s public resolvers</a>)</li>
 <li><code class="docutils literal notranslate"><span class="pre">dns_timeout</span></code> - float: DNS timeout period</li>
 <li><code class="docutils literal notranslate"><span class="pre">debug</span></code> - bool: Print debugging messages</li>
 <li><code class="docutils literal notranslate"><span class="pre">silent</span></code> - bool: Only print errors (Default: True)</li>
@@ -403,6 +407,15 @@ lookalike domain monitoring, check out <a class="reference external" href="https
 </ul>
 <div class="admonition warning">
 <p class="first admonition-title">Warning</p>
+<p>It is <strong>strongly recommended</strong> to <strong>not</strong> use the <code class="docutils literal notranslate"><span class="pre">nameservers</span></code> setting.
+By default, <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> uses <a class="reference external" href="https://1.1.1.1/">Cloudflare’s public resolvers</a>,
+which are much faster and more reliable than Google, Cisco OpenDNS, or
+even most local resolvers.</p>
+<p class="last">The <code class="docutils literal notranslate"><span class="pre">nameservers</span></code> option should only be used if your network blocks DNS
+requests to outside resolvers.</p>
+</div>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
 <blockquote>
 <div><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 (also known as failure reports)
@@ -418,10 +431,10 @@ privacy reasons. While aggregate DMARC reports are sent at least daily,
 it is normal to receive very few forensic reports.</p>
 </div></blockquote>
 <p class="last">An alternative approach is to still collect forensic/failure/ruf reports
-in your DMARC inbox, but run <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> with <code class="docutils literal notranslate"><span class="pre">save_forensic</span> <span class="pre">=</span> <span class="pre">True</span></code> manually on a
-separate IMAP folder (using the  <code class="docutils literal notranslate"><span class="pre">reports_folder</span></code> option), after you have manually
-moved known samples you want to save to that folder (e.g. malicious
-samples and non-sensitive legitimate samples).</p>
+in your DMARC inbox, but run <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> with <code class="docutils literal notranslate"><span class="pre">save_forensic</span> <span class="pre">=</span> <span class="pre">True</span></code>
+manually on a separate IMAP folder (using the  <code class="docutils literal notranslate"><span class="pre">reports_folder</span></code> option),
+after you have manually moved known samples you want to save to that
+folder (e.g. malicious samples and non-sensitive legitimate samples).</p>
 </div>
 </div>
 <div class="section" id="sample-aggregate-report-output">
@@ -1245,6 +1258,49 @@ your TLD and/or any subdomain.</p>
 </div>
 </div></blockquote>
 </div>
+<div class="section" id="what-about-mailing-lists">
+<h2>What about mailing lists?<a class="headerlink" href="#what-about-mailing-lists" title="Permalink to this headline">¶</a></h2>
+<p>When you deploy DMARC on your domain, you might find that messages relayed by
+mailing lists are failing DMARC. This has two causes:</p>
+<ol class="arabic simple">
+<li>You are not DKIM signing your mail like you should be</li>
+<li>The mailing list is altering emails in ways that are not DMARC compliant
+before sending them</li>
+</ol>
+<p><a class="reference external" href="https://begriffs.com/posts/2018-09-18-dmarc-mailing-list.html">Joe Nelson</a> does a fantastic job of explaining exactly what mailing lists
+should and shouldn’t do to be DMARC compliant. Rather than repeat his fine
+work, here’s a TL;DR:</p>
+<div class="section" id="if-you-run-a-mailing-list">
+<h3>If you run a mailing list<a class="headerlink" href="#if-you-run-a-mailing-list" title="Permalink to this headline">¶</a></h3>
+<p><strong>Do</strong></p>
+<ul>
+<li><p class="first">Retain headers from the original message</p>
+</li>
+<li><p class="first">Add <a class="reference external" href="https://tools.ietf.org/html/rfc2369">RFC 2369</a> List-Unsubscribe headers to outgoing messages, instead of
+adding unsubscribe links to the body</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">List</span><span class="o">-</span><span class="n">Unsubscribe</span><span class="p">:</span> <span class="o">&lt;</span><span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="nb">list</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">unsubscribe</span><span class="o">-</span><span class="n">link</span><span class="o">&gt;</span>
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+<li><p class="first">Add <a class="reference external" href="https://tools.ietf.org/html/rfc2919">RFC 2919</a> List-Id headers instead of modifying the subject</p>
+<blockquote>
+<div><div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">List</span><span class="o">-</span><span class="n">Id</span><span class="p">:</span> <span class="n">Example</span> <span class="n">Mailing</span> <span class="n">List</span> <span class="o">&lt;</span><span class="nb">list</span><span class="o">.</span><span class="n">example</span><span class="o">.</span><span class="n">com</span><span class="o">&gt;</span>
+</pre></div>
+</div>
+</div></blockquote>
+</li>
+</ul>
+<p><strong>Do not</strong></p>
+<ul class="simple">
+<li>Remove or modify any existing headers from the original message, including
+From, Date, Subject, etc.</li>
+<li>Add to or remove content from the message body, <strong>including traditional
+disclaimers and unsubscribe footers</strong></li>
+</ul>
+</div>
+</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>
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>Python Module Index &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>Python Module Index &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -59,7 +59,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -8,7 +8,7 @@
  
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  
-  <title>Search &mdash; parsedmarc 6.0.1 documentation</title>
+  <title>Search &mdash; parsedmarc 6.0.2 documentation</title>
  

  
@@ -56,7 +56,7 @@
            
            
              <div class="version">
-                6.0.1
+                6.0.2
              </div>
            
          
@@ -1 +1 @@
-Search.setIndex({docnames:["index"],envversion:{"sphinx.domains.c":1,"sphinx.domains.changeset":1,"sphinx.domains.cpp":1,"sphinx.domains.javascript":1,"sphinx.domains.math":2,"sphinx.domains.python":1,"sphinx.domains.rst":1,"sphinx.domains.std":1,"sphinx.ext.todo":1,"sphinx.ext.viewcode":1,sphinx:55},filenames:["index.rst"],objects:{"":{parsedmarc:[0,0,0,"-"]},"parsedmarc.elastic":{AlreadySaved:[0,1,1,""],ElasticsearchError:[0,1,1,""],create_indexes:[0,2,1,""],migrate_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.splunk":{HECClient:[0,3,1,""],SplunkError:[0,1,1,""]},"parsedmarc.splunk.HECClient":{save_aggregate_reports_to_splunk:[0,4,1,""],save_forensic_reports_to_splunk:[0,4,1,""]},"parsedmarc.utils":{EmailParserError:[0,1,1,""],convert_outlook_msg:[0,2,1,""],decode_base64:[0,2,1,""],get_base_domain:[0,2,1,""],get_filename_safe_string:[0,2,1,""],get_ip_address_country:[0,2,1,""],get_ip_address_info:[0,2,1,""],get_reverse_dns:[0,2,1,""],human_timestamp_to_datetime:[0,2,1,""],human_timestamp_to_timestamp:[0,2,1,""],is_outlook_msg:[0,2,1,""],parse_email:[0,2,1,""],query_dns:[0,2,1,""],timestamp_to_datetime:[0,2,1,""],timestamp_to_human:[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_imap_capabilities:[0,2,1,""],get_report_zip:[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,""],splunk:[0,0,0,"-"],utils:[0,0,0,"-"],watch_inbox:[0,2,1,""]}},objnames:{"0":["py","module","Python module"],"1":["py","exception","Python exception"],"2":["py","function","Python function"],"3":["py","class","Python class"],"4":["py","method","Python method"]},objtypes:{"0":"py:module","1":"py:exception","2":"py:function","3":"py:class","4":"py:method"},terms:{"50m":0,"\u00fcbersicht":0,"break":0,"byte":0,"case":0,"class":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,And:0,For:0,OLE:0,One:[],TLS:0,That:0,The:0,Then:0,These:0,Use:0,Uses:0,With:0,_input:0,abl:0,about:0,abov:0,access_token:0,account:0,acm:0,across:0,action:0,actual:0,add:0,add_head:0,address:0,addresse:0,adkim:0,administr:0,adsl:0,aes128:0,aes256:0,after:0,against:0,agari:0,age:0,aggregate_index:0,aggregate_report:0,aggregate_top:0,all:0,allow:0,allowremot:0,along:[],alreadysav:0,also:0,alter:0,altern:0,although:0,alwai:0,ani:0,anonym:0,anoth:0,answer:0,apach:0,apache2:0,appear:0,append:[],appendix:0,appli:0,approach:0,approxim:0,apt:0,archiv:0,archive_fold:0,argument:0,arriv:0,arrival_d:0,arrival_date_utc:0,artifact:0,ask:0,asmx:0,aspf:0,assign:0,associ:0,attach:0,attachment_filenam:0,auth:0,auth_bas:0,auth_basic_user_fil:0,auth_failur:0,auth_result:0,authent:0,authentication_mechan:0,authentication_result:0,author:[],auto:0,autodetect:0,avail:0,avoid:0,b2c:0,backward:[],base64:0,base:0,base_domain:0,basic:0,bcc:0,bd6e1bb5:0,becaus:0,been:0,begin_d:0,behind:0,being:0,bellsouth:0,below:0,best:0,between:0,bin:0,binari:0,bind:0,bindaddress:0,bitbucket:0,bodi:0,bool:0,brand:0,busi:0,bz2:0,cach:0,call:0,callback:0,can:0,capabl:0,caus:0,center:0,cento:0,cert:0,cert_path:0,certif:0,cest:0,chacha20:0,chain:0,chang:0,charact:0,charset:0,chart:0,check:0,checkbox:0,checkdmarc:0,chines:0,chmod:0,chown:0,click:0,client:0,cloudflar:0,code:0,collect:0,collector:0,com:0,come:0,comma:0,command:0,comment:0,commerci:0,common:0,compat:[],complet:0,compli:0,compress:0,config:0,config_fil:0,configur:[],conform:0,connect:0,consid:0,consist:0,consolid:0,consum:0,contact:0,contain:0,content:0,context:0,control:0,convert:0,convert_outlook_msg:0,copi:0,correctli:0,could:0,count:0,countri:0,crash:0,creat:0,create_index:0,credenti:0,crt:0,csr:0,cumul:0,current:0,custom:0,daemon:0,dai:0,daili:0,dat:0,data:0,databas:0,date:0,date_utc:0,datetim:0,davmail:0,deb:0,debian:0,debug:0,decod:0,decode_base64:0,defens:0,delai:0,delet:0,delivery_result:0,demystifi:0,describ:0,descript:0,detail:0,develop:0,dict:0,dictionari:0,differ:0,directli:0,directori:0,dis:0,disabl:0,displai:0,display_nam:0,disposit:0,dkim_align:0,dkim_domain:0,dkim_result:0,dkim_selector:0,dkm:0,dmarc_aggreg:0,dmarc_forens:0,dmarcian:0,dmarcresport:0,dns_timeout:0,doctyp:0,doe:0,domainawar:0,don:0,done:0,down:0,download:0,draft:0,dtd:0,dure:0,each:0,earlier:0,easi:0,easier:0,easy_instal:0,ecdh:0,ecdsa:0,echo:0,edit:0,editor:0,effici:0,elasticsearch_host:[],elasticsearch_index_suffix:[],elasticsearch_ssl_cert_path:[],elasticsearcherror:0,els:0,email:0,email_result:0,emailparLine truncated
+Search.setIndex({docnames:["index"],envversion:{"sphinx.domains.c":1,"sphinx.domains.changeset":1,"sphinx.domains.cpp":1,"sphinx.domains.javascript":1,"sphinx.domains.math":2,"sphinx.domains.python":1,"sphinx.domains.rst":1,"sphinx.domains.std":1,"sphinx.ext.todo":1,"sphinx.ext.viewcode":1,sphinx:55},filenames:["index.rst"],objects:{"":{parsedmarc:[0,0,0,"-"]},"parsedmarc.elastic":{AlreadySaved:[0,1,1,""],ElasticsearchError:[0,1,1,""],create_indexes:[0,2,1,""],migrate_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.splunk":{HECClient:[0,3,1,""],SplunkError:[0,1,1,""]},"parsedmarc.splunk.HECClient":{save_aggregate_reports_to_splunk:[0,4,1,""],save_forensic_reports_to_splunk:[0,4,1,""]},"parsedmarc.utils":{EmailParserError:[0,1,1,""],convert_outlook_msg:[0,2,1,""],decode_base64:[0,2,1,""],get_base_domain:[0,2,1,""],get_filename_safe_string:[0,2,1,""],get_ip_address_country:[0,2,1,""],get_ip_address_info:[0,2,1,""],get_reverse_dns:[0,2,1,""],human_timestamp_to_datetime:[0,2,1,""],human_timestamp_to_timestamp:[0,2,1,""],is_outlook_msg:[0,2,1,""],parse_email:[0,2,1,""],query_dns:[0,2,1,""],timestamp_to_datetime:[0,2,1,""],timestamp_to_human:[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_imap_capabilities:[0,2,1,""],get_report_zip:[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,""],splunk:[0,0,0,"-"],utils:[0,0,0,"-"],watch_inbox:[0,2,1,""]}},objnames:{"0":["py","module","Python module"],"1":["py","exception","Python exception"],"2":["py","function","Python function"],"3":["py","class","Python class"],"4":["py","method","Python method"]},objtypes:{"0":"py:module","1":"py:exception","2":"py:function","3":"py:class","4":"py:method"},terms:{"50m":0,"\u00fcbersicht":0,"break":0,"byte":0,"case":0,"class":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,And:0,For:0,OLE:0,One:[],TLS:0,That:0,The:0,Then:0,These:0,Use:0,Uses:0,With:0,_input:0,abl:0,about:[],abov:0,access_token:0,account:0,acm:0,across:0,action:0,actual:0,add:0,add_head:0,adding:0,address:0,addresse:0,adkim:0,administr:0,adsl:0,aes128:0,aes256:0,after:0,against:0,agari:0,age:0,aggregate_index:0,aggregate_report:0,aggregate_top:0,all:0,allow:0,allowremot:0,along:[],alreadysav:0,also:0,alter:0,altern:0,although:0,alwai:0,ani:0,anonym:0,anoth:0,answer:0,apach:0,apache2:0,appear:0,append:[],appendix:0,appli:0,approach:0,approxim:0,apt:0,archiv:0,archive_fold:0,argument:0,arriv:0,arrival_d:0,arrival_date_utc:0,artifact:0,ask:0,asmx:0,aspf:0,assign:0,associ:0,attach:0,attachment_filenam:0,auth:0,auth_bas:0,auth_basic_user_fil:0,auth_failur:0,auth_result:0,authent:0,authentication_mechan:0,authentication_result:0,author:[],auto:0,autodetect:0,avail:0,avoid:0,b2c:0,backward:[],base64:0,base:0,base_domain:0,basic:0,bcc:0,bd6e1bb5:0,becaus:0,been:0,befor:0,begin_d:0,behind:0,being:0,bellsouth:0,below:0,best:0,between:0,bin:0,binari:0,bind:0,bindaddress:0,bitbucket:0,block:0,bodi:0,bool:0,brand:0,busi:0,bz2:0,cach:0,call:0,callback:0,can:0,capabl:0,caus:0,center:0,cento:0,cert:0,cert_path:0,certif:0,cest:0,chacha20:0,chain:0,chang:0,charact:0,charset:0,chart:0,check:0,checkbox:0,checkdmarc:0,chines:0,chmod:0,chown:0,cisco:0,click:0,client:0,cloudflar:0,code:0,collect:0,collector:0,com:0,come:0,comma:0,command:0,comment:0,commerci:0,common:0,compat:[],complet:0,compli:0,compliant:0,compress:0,config:0,config_fil:0,configur:[],conform:0,connect:0,consid:0,consist:0,consolid:0,consum:0,contact:0,contain:0,content:0,context:0,control:0,convert:0,convert_outlook_msg:0,copi:0,correctli:0,could:0,count:0,countri:0,crash:0,creat:0,create_index:0,credenti:0,crt:0,csr:0,cumul:0,current:0,custom:0,daemon:0,dai:0,daili:0,dat:0,data:0,databas:0,date:0,date_utc:0,datetim:0,davmail:0,deb:0,debian:0,debug:0,decod:0,decode_base64:0,defens:0,delai:0,delet:0,delivery_result:0,demystifi:0,deploi:0,describ:0,descript:0,detail:0,develop:0,dict:0,dictionari:0,differ:0,directli:0,directori:0,dis:0,disabl:0,disclaim:0,displai:0,display_nam:0,disposit:0,dkim_align:0,dkim_domain:0,dkim_result:0,dkim_selector:0,dkm:0,dmarc_aggreg:0,dmarc_forens:0,dmarcian:0,dmarcresport:0,dns_timeout:0,doctyp:0,doe:0,domainawar:0,don:0,done:0,down:0,download:0,draft:0,dtd:0,dure:0,each:0,earlier:0,easi:0,easier:0,easy_instal:0,ecdh:0,ecdsa:0,echo:0,edit:0,editor:0,effici:0,elasticsearch_host:[],elasticsearch_index_suffix:[],elasticsearch_ssl_cert_Line truncated