Update docs

This commit is contained in:
Sean Whalen
2023-05-14 20:42:35 -04:00
parent 592447f4b1
commit e5173a5e6f
26 changed files with 50 additions and 46 deletions
+1 -1
View File
@@ -94,7 +94,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+8 -2
View File
@@ -335,7 +335,9 @@
<span class="s2">&quot;email&quot;</span><span class="p">]</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">&quot;@&quot;</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span>
<span class="n">org_name</span> <span class="o">=</span> <span class="n">report_metadata</span><span class="p">[</span><span class="s2">&quot;org_name&quot;</span><span class="p">]</span>
<span class="k">if</span> <span class="n">org_name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span> <span class="s2">&quot; &quot;</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">org_name</span><span class="p">:</span>
<span class="n">org_name</span> <span class="o">=</span> <span class="n">get_base_domain</span><span class="p">(</span><span class="n">org_name</span><span class="p">)</span>
<span class="n">new_org_name</span> <span class="o">=</span> <span class="n">get_base_domain</span><span class="p">(</span><span class="n">org_name</span><span class="p">)</span>
<span class="k">if</span> <span class="n">new_org_name</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
<span class="n">org_name</span> <span class="o">=</span> <span class="n">new_org_name</span>
<span class="n">new_report_metadata</span><span class="p">[</span><span class="s2">&quot;org_name&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">org_name</span>
<span class="n">new_report_metadata</span><span class="p">[</span><span class="s2">&quot;org_email&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">report_metadata</span><span class="p">[</span><span class="s2">&quot;email&quot;</span><span class="p">]</span>
<span class="n">extra</span> <span class="o">=</span> <span class="kc">None</span>
@@ -348,6 +350,10 @@
<span class="s2">&quot;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="s2">&quot;&gt;&quot;</span><span class="p">,</span> <span class="s2">&quot;&quot;</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s2">&quot;@&quot;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
<span class="n">new_report_metadata</span><span class="p">[</span><span class="s2">&quot;report_id&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">report_id</span>
<span class="n">date_range</span> <span class="o">=</span> <span class="n">report</span><span class="p">[</span><span class="s2">&quot;report_metadata&quot;</span><span class="p">][</span><span class="s2">&quot;date_range&quot;</span><span class="p">]</span>
<span class="k">if</span> <span class="p">(</span><span class="nb">int</span><span class="p">(</span><span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;end&quot;</span><span class="p">])</span> <span class="o">-</span> <span class="nb">int</span><span class="p">(</span><span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;begin&quot;</span><span class="p">])</span> <span class="o">&gt;</span> <span class="mi">2</span><span class="o">*</span><span class="mi">86400</span><span class="p">):</span>
<span class="k">raise</span> <span class="n">InvalidAggregateReport</span><span class="p">(</span><span class="s2">&quot;The begin and end fields span too </span><span class="se">\</span>
<span class="s2"> many hours, should be max 24 hours </span><span class="se">\</span>
<span class="s2"> according to RFC 7489 section 7.2&quot;</span><span class="p">)</span>
<span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;begin&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">timestamp_to_human</span><span class="p">(</span><span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;begin&quot;</span><span class="p">])</span>
<span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;end&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">timestamp_to_human</span><span class="p">(</span><span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;end&quot;</span><span class="p">])</span>
<span class="n">new_report_metadata</span><span class="p">[</span><span class="s2">&quot;begin_date&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">date_range</span><span class="p">[</span><span class="s2">&quot;begin&quot;</span><span class="p">]</span>
@@ -1543,7 +1549,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -639,7 +639,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -250,7 +250,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -646,7 +646,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+3 -3
View File
@@ -29,7 +29,7 @@ which will cause it to crash under a heavy load. To fix this, increase the
minimum and maximum JVM heap sizes in `/etc/elasticsearch/jvm.options` to
more reasonable levels, depending on your server's resources.
Make sure the system has at least 2 GB more RAM then the assigned JVM
Make sure the system has at least 2 GB more RAM than the assigned JVM
heap size.
Always set the minimum and maximum JVM heap sizes to the same
@@ -180,7 +180,7 @@ sudo systemctl restart elasticsearch
Now that Elasticsearch is up and running, use `parsedmarc` to send data to
it.
Download (right click the link and click save as) [export.ndjson].
Download (right-click the link and click save as) [export.ndjson].
Connect to kibana using the "elastic" user and the password you previously provide
on the console ("End Kibana configuration" part).
@@ -219,7 +219,7 @@ Kibana index patterns with versions that match the upgraded indexes:
index patterns
4. Click Delete
5. Click Delete on the conformation message
6. Download (right click the link and click save as)
6. Download (right-click the link and click save as)
the latest version of [export.ndjson]
7. Import `export.ndjson` by clicking Import from the Kibana
Saved Objects page
+3 -4
View File
@@ -28,8 +28,7 @@ https_proxy=https://prox-server:3128
ftp_proxy=http://prox-server:3128
```
This will set the the proxy up for use system-wide, including for
`parsedmarc`.
This will set the proxy up for use system-wide, including for `parsedmarc`.
:::
:::{warning}
@@ -49,7 +48,7 @@ Starting in `parsedmarc` 7.1.0, a static copy of the
`parsedmarc`, under the terms of the
[Creative Commons Attribution 4.0 International License].
as a fallback if the [MaxMind GeoLite2 Country database] is not
installed However, `parsedmarc` cannot install updated versions of
installed. However, `parsedmarc` cannot install updated versions of
these databases as they are released, so MaxMind's databases and the
[geoipupdate] tool is still the preferable solution.
@@ -91,7 +90,7 @@ regulations][to comply with various privacy regulations].
Start by [registering for a free GeoLite2 account], and signing in.
Then, navigate the to the [License Keys] page under your account,
Then, navigate to the [License Keys] page under your account,
and create a new license key for the version of
`geoipupdate` that was installed.
+1 -1
View File
@@ -6,7 +6,7 @@ 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.
click on the Dashboard link on the left side menu of Kibana.
:::
## DMARC Summary
+1 -1
View File
@@ -6,7 +6,7 @@ list is spoofing your from address, and modifying the subject,
footer, or other part of the message, thereby breaking the
DKIM signature.
### Mailing list list best practices
### Mailing list best practices
Ideally, a mailing list should forward messages without altering the
headers or body content at all. [Joe Nelson] does a fantastic job of
+1 -1
View File
@@ -89,7 +89,7 @@ draft,acme.com,noreply-dmarc-support@acme.com,http://acme.com/dmarc/support,9391
## Sample forensic report output
Thanks to Github user [xennn](https://github.com/xennn) for the anonymized
Thanks to GitHub user [xennn](https://github.com/xennn) for the anonymized
[forensic report email sample](<https://github.com/domainaware/parsedmarc/raw/master/samples/forensic/DMARC%20Failure%20Report%20for%20domain.de%20(mail-from%3Dsharepoint%40domain.de%2C%20ip%3D10.10.10.10).eml>).
### JSON forensic report
+1 -1
View File
@@ -1045,7 +1045,7 @@ with the given IPv4 or IPv6 address</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -107,7 +107,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -266,7 +266,7 @@ config file:</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+4 -4
View File
@@ -65,7 +65,7 @@
<li class="toctree-l2"><a class="reference internal" href="#dmarc-alignment-guide">DMARC Alignment Guide</a></li>
<li class="toctree-l2"><a class="reference internal" href="#what-if-a-sender-wont-support-dkim-dmarc">What if a sender wont support DKIM/DMARC?</a></li>
<li class="toctree-l2"><a class="reference internal" href="#what-about-mailing-lists">What about mailing lists?</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#mailing-list-list-best-practices">Mailing list list best practices</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#mailing-list-best-practices">Mailing list best practices</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#do">Do</a></li>
<li class="toctree-l4"><a class="reference internal" href="#do-not">Do not</a></li>
<li class="toctree-l4"><a class="reference internal" href="#mailman-2">Mailman 2</a></li>
@@ -203,8 +203,8 @@ relayed by mailing lists are failing DMARC, most likely because the mailing
list is spoofing your from address, and modifying the subject,
footer, or other part of the message, thereby breaking the
DKIM signature.</p>
<section id="mailing-list-list-best-practices">
<h3>Mailing list list best practices<a class="headerlink" href="#mailing-list-list-best-practices" title="Permalink to this heading"></a></h3>
<section id="mailing-list-best-practices">
<h3>Mailing list best practices<a class="headerlink" href="#mailing-list-best-practices" title="Permalink to this heading"></a></h3>
<p>Ideally, a mailing list should forward messages without altering the
headers or body content at all. <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 shouldnt do to be
@@ -485,7 +485,7 @@ the original sender.</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+4 -4
View File
@@ -115,7 +115,7 @@ sudo<span class="w"> </span>apt-get<span class="w"> </span>install<span class="w
which will cause it to crash under a heavy load. To fix this, increase the
minimum and maximum JVM heap sizes in <code class="docutils literal notranslate"><span class="pre">/etc/elasticsearch/jvm.options</span></code> to
more reasonable levels, depending on your servers resources.</p>
<p>Make sure the system has at least 2 GB more RAM then the assigned JVM
<p>Make sure the system has at least 2 GB more RAM than the assigned JVM
heap size.</p>
<p>Always set the minimum and maximum JVM heap sizes to the same
value.</p>
@@ -229,7 +229,7 @@ sudo<span class="w"> </span>systemctl<span class="w"> </span>restart<span class=
</div>
<p>Now that Elasticsearch is up and running, use <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> to send data to
it.</p>
<p>Download (right click the link and click save as) <a class="reference external" href="https://raw.githubusercontent.com/domainaware/parsedmarc/master/kibana/export.ndjson">export.ndjson</a>.</p>
<p>Download (right-click the link and click save as) <a class="reference external" href="https://raw.githubusercontent.com/domainaware/parsedmarc/master/kibana/export.ndjson">export.ndjson</a>.</p>
<p>Connect to kibana using the “elastic” user and the password you previously provide
on the console (“End Kibana configuration” part).</p>
<p>Import <code class="docutils literal notranslate"><span class="pre">export.ndjson</span></code> the Saved Objects tab of the Stack management
@@ -254,7 +254,7 @@ Kibana index patterns with versions that match the upgraded indexes:</p>
index patterns</p></li>
<li><p>Click Delete</p></li>
<li><p>Click Delete on the conformation message</p></li>
<li><p>Download (right click the link and click save as)
<li><p>Download (right-click the link and click save as)
the latest version of <a class="reference external" href="https://raw.githubusercontent.com/domainaware/parsedmarc/master/kibana/export.ndjson">export.ndjson</a></p></li>
<li><p>Import <code class="docutils literal notranslate"><span class="pre">export.ndjson</span></code> by clicking Import from the Kibana
Saved Objects page</p></li>
@@ -280,7 +280,7 @@ check out the Elastic guide to <a class="reference external" href="https://www.e
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -341,7 +341,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -187,7 +187,7 @@ premade dashboards</p></li>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+4 -5
View File
@@ -115,8 +115,7 @@ proxy details there, for example:</p>
<span class="nv">ftp_proxy</span><span class="o">=</span>http://prox-server:3128
</pre></div>
</div>
<p>This will set the the proxy up for use system-wide, including for
<code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code>.</p>
<p>This will set the proxy up for use system-wide, including for <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code>.</p>
</div>
</div>
<div class="admonition warning">
@@ -139,7 +138,7 @@ least:</p>
<code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code>, under the terms of the
[Creative Commons Attribution 4.0 International License].
as a fallback if the <a class="reference external" href="https://dev.maxmind.com/geoip/geolite2-free-geolocation-data">MaxMind GeoLite2 Country database</a> is not
installed However, <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> cannot install updated versions of
installed. However, <code class="docutils literal notranslate"><span class="pre">parsedmarc</span></code> cannot install updated versions of
these databases as they are released, so MaxMinds databases and the
<a class="reference external" href="https://github.com/maxmind/geoipupdate">geoipupdate</a> tool is still the preferable solution.</p>
<p>The location of the database file can be overridden by using the
@@ -170,7 +169,7 @@ access the free Geolite2 databases, in order <a class="reference external" href=
comply with various privacy
regulations</a>.</p>
<p>Start by <a class="reference external" href="https://www.maxmind.com/en/geolite2/signup">registering for a free GeoLite2 account</a>, and signing in.</p>
<p>Then, navigate the to the <a class="reference external" href="https://www.maxmind.com/en/accounts/current/license-key">License Keys</a> page under your account,
<p>Then, navigate to the <a class="reference external" href="https://www.maxmind.com/en/accounts/current/license-key">License Keys</a> page under your account,
and create a new license key for the version of
<code class="docutils literal notranslate"><span class="pre">geoipupdate</span></code> that was installed.</p>
<div class="admonition warning">
@@ -259,7 +258,7 @@ Outlook (i.e. OLE .msg files), install <code class="docutils literal notranslate
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+2 -2
View File
@@ -95,7 +95,7 @@ results from incoming DMARC reports.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>The default dashboard is DMARC Summary. To switch between dashboards,
click on the Dashboard link in the left side menu of Kibana.</p>
click on the Dashboard link on the left side menu of Kibana.</p>
</div>
<section id="dmarc-summary">
<h2>DMARC Summary<a class="headerlink" href="#dmarc-summary" title="Permalink to this heading"></a></h2>
@@ -179,7 +179,7 @@ supply the headers of sample emails. Very few provide the entire email.</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+3 -3
View File
@@ -89,8 +89,8 @@ relayed by mailing lists are failing DMARC, most likely because the mailing
list is spoofing your from address, and modifying the subject,
footer, or other part of the message, thereby breaking the
DKIM signature.</p>
<section id="mailing-list-list-best-practices">
<h2>Mailing list list best practices<a class="headerlink" href="#mailing-list-list-best-practices" title="Permalink to this heading"></a></h2>
<section id="mailing-list-best-practices">
<h2>Mailing list best practices<a class="headerlink" href="#mailing-list-best-practices" title="Permalink to this heading"></a></h2>
<p>Ideally, a mailing list should forward messages without altering the
headers or body content at all. <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 shouldnt do to be
@@ -367,7 +367,7 @@ the original sender.</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+2 -2
View File
@@ -186,7 +186,7 @@ draft,acme.com,noreply-dmarc-support@acme.com,http://acme.com/dmarc/support,9391
</section>
<section id="sample-forensic-report-output">
<h2>Sample forensic report output<a class="headerlink" href="#sample-forensic-report-output" title="Permalink to this heading"></a></h2>
<p>Thanks to Github user <a class="reference external" href="https://github.com/xennn">xennn</a> for the anonymized
<p>Thanks to GitHub user <a class="reference external" href="https://github.com/xennn">xennn</a> for the anonymized
<a class="reference external" href="https://github.com/domainaware/parsedmarc/raw/master/samples/forensic/DMARC%20Failure%20Report%20for%20domain.de%20(mail-from%3Dsharepoint%40domain.de%2C%20ip%3D10.10.10.10).eml">forensic report email sample</a>.</p>
<section id="json-forensic-report">
<h3>JSON forensic report<a class="headerlink" href="#json-forensic-report" title="Permalink to this heading"></a></h3>
@@ -298,7 +298,7 @@ auth-failure,Lua/1.0,1.0,,sharepoint@domain.de,peter.pan@domain.de,&quot;Mon, 01
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -125,7 +125,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -103,7 +103,7 @@
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
File diff suppressed because one or more lines are too long
+1 -1
View File
@@ -113,7 +113,7 @@ easier and more flexible filtering options.</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
+1 -1
View File
@@ -565,7 +565,7 @@ as well as the current process (newest to oldest), run:</p>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2018, Sean Whalen.</p>
<p>&#169; Copyright 2018 - 2023, Sean Whalen and contributors.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a