2 files changed, 211 insertions, 0 deletions

diff --git a/src/mailman/rules/docs/dmarc-moderation.rst b/src/mailman/rules/docs/dmarc-moderation.rst
new file mode 100644
index 000000000..e0bfe6b07
--- /dev/null
+++ b/src/mailman/rules/docs/dmarc-moderation.rst
@@ -0,0 +1,210 @@
+================
+DMARC moderation
+================
+
+This rule is different from others in that it never matches bucause a match
+would cause the message to be held.  The rule looks at the list's
+dmarc_moderation_policy and if it is other than 'none', it checks the domain
+of the From: address for a DMARC policy and depending on settings may reject
+or discard the message or just flag in for the dmarc handler to apply DMARC
+mitigations to the message.
+
+    >>> mlist = create_list('_xtest@example.com')
+    >>> rule = config.rules['dmarc-moderation']
+    >>> print(rule.name)
+    dmarc-moderation
+
+A message From: a domain without a DMARC policy does not set any flags.
+
+    >>> from mailman.interfaces.mailinglist import DMARCModerationAction
+    >>> mlist.dmarc_moderation_action = DMARCModerationAction.munge_from
+    >>> msg = message_from_string("""\
+    ... From: aperson@example.org
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata == {}
+    True
+
+Even if the From: domain publishes p=reject, no flags are set if the list's
+action is none.
+
+    >>> mlist.dmarc_moderation_action = DMARCModerationAction.none
+    >>> msg = message_from_string("""\
+    ... From: aperson@yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata == {}
+    True
+
+But with a different list setting, the message is flagged.
+
+    >>> mlist.dmarc_moderation_action = DMARCModerationAction.munge_from
+    >>> msg = message_from_string("""\
+    ... From: aperson@yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata['dmarc']
+    True
+
+Subdomains which don't have a policy will check the organizational domain.
+
+    >>> msg = message_from_string("""\
+    ... From: aperson@sub.domain.yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata['dmarc']
+    True
+
+The list's action can also be set to immediately discard or reject the
+message.
+
+    >>> mlist.dmarc_moderation_action = DMARCModerationAction.discard
+    >>> msg = message_from_string("""\
+    ... From: aperson@yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata['dmarc']
+    True
+
+The above needs to test that the message was discarded.
+
+We can reject the message with a default reason.
+
+    >>> mlist.dmarc_moderation_action = DMARCModerationAction.reject
+    >>> msg = message_from_string("""\
+    ... From: aperson@yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata['dmarc']
+    True
+
+There is now a reject message in the virgin queue.
+
+    >>> from mailman.testing.helpers import get_queue_messages
+    >>> messages = get_queue_messages('virgin')
+    >>> len(messages)
+    1
+    >>> print(messages[0].msg.as_string())
+    Subject: A posted message
+    From: _xtest-owner@example.com
+    To: aperson@yahoo.com
+    MIME-Version: 1.0
+    Content-Type: multipart/mixed; boundary="..."
+    Message-ID: <...>
+    Date: ...
+    Precedence: bulk
+    <BLANKLINE>
+    --...
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: 7bit
+    <BLANKLINE>
+    <BLANKLINE>
+    Your message to the _xtest mailing-list was rejected for the following
+    reasons:
+    <BLANKLINE>
+    You are not allowed to post to this mailing list From: a domain which
+    publishes a DMARC policy of reject or quarantine, and your message has
+    been automatically rejected.  If you think that your messages are
+    being rejected in error, contact the mailing list owner at $listowner.
+    <BLANKLINE>
+    The original message as received by Mailman is attached.
+    <BLANKLINE>
+    --...
+    Content-Type: message/rfc822
+    MIME-Version: 1.0
+    <BLANKLINE>
+    From: aperson@yahoo.com
+    To: _xtest@example.com
+    Subject: A posted message
+    X-Mailman-Rule-Hits: dmarc-moderation
+    <BLANKLINE>
+    <BLANKLINE>
+    --...--
+    <BLANKLINE>
+
+And, we can reject with a custom message.
+
+    >>> mlist.dmarc_moderation_notice = 'A silly reason'
+    >>> msg = message_from_string("""\
+    ... From: aperson@yahoo.com
+    ... To: _xtest@example.com
+    ... Subject: A posted message
+    ...
+    ... """)
+    >>> msgdata = {}
+    >>> rule.check(mlist, msg, msgdata)
+    False
+    >>> msgdata['dmarc']
+    True
+
+Check the the virgin queue.
+
+    >>> messages = get_queue_messages('virgin')
+    >>> len(messages)
+    1
+    >>> print(messages[0].msg.as_string())
+    Subject: A posted message
+    From: _xtest-owner@example.com
+    To: aperson@yahoo.com
+    MIME-Version: 1.0
+    Content-Type: multipart/mixed; boundary="..."
+    Message-ID: <...>
+    Date: ...
+    Precedence: bulk
+    <BLANKLINE>
+    --...
+    Content-Type: text/plain; charset="us-ascii"
+    MIME-Version: 1.0
+    Content-Transfer-Encoding: 7bit
+    <BLANKLINE>
+    <BLANKLINE>
+    Your message to the _xtest mailing-list was rejected for the following
+    reasons:
+    <BLANKLINE>
+    A silly reason
+    <BLANKLINE>
+    The original message as received by Mailman is attached.
+    <BLANKLINE>
+    --...
+    Content-Type: message/rfc822
+    MIME-Version: 1.0
+    <BLANKLINE>
+    From: aperson@yahoo.com
+    To: _xtest@example.com
+    Subject: A posted message
+    X-Mailman-Rule-Hits: dmarc-moderation
+    <BLANKLINE>
+    <BLANKLINE>
+    --...--
+    <BLANKLINE>
diff --git a/src/mailman/rules/docs/rules.rst b/src/mailman/rules/docs/rules.rst
index 812486b45..e00889061 100644
--- a/src/mailman/rules/docs/rules.rst
+++ b/src/mailman/rules/docs/rules.rst
@@ -22,6 +22,7 @@ names to rule objects.
     any True
     approved True
     banned-address True
+    dmarc-moderation True
     emergency True
     implicit-dest True
     loop True