diff --git a/CHANGELOG.md b/CHANGELOG.md index 1630e77..d10549b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,8 @@ 6.0.2 ---- -- Use temp directory for temp files (fixes issue #54) +- IMAP connectivity improvements (issue #53) +- Use a temp directory for temp files (issue #54) 6.0.1 ----- diff --git a/README.rst b/README.rst index c5014e5..e827f45 100644 --- a/README.rst +++ b/README.rst @@ -133,7 +133,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) @@ -181,6 +181,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 @@ -199,10 +209,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 ============================== @@ -413,3 +423,5 @@ https://github.com/domainaware/parsedmarc/issues :target: https://travis-ci.org/domainaware/parsedmarc .. _Demystifying DMARC: https://seanthegeek.net/459/demystifying-dmarc/ + +.. _Cloudflare's public resolvers: https://1.1.1.1/ diff --git a/docs/index.rst b/docs/index.rst index a67e9fe..b0f7c2f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 + + .. code-block:: + + List-Unsubscribe: + +- Add `RFC 2919`_ List-Id headers instead of modifying the subject + + .. code-block:: + + List-Id: Example Mailing List + +**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