--- a/mod_firewall/scripts/spam-blocking.pfw	Fri Feb 24 09:51:43 2017 +0000
+++ b/mod_firewall/scripts/spam-blocking.pfw	Fri Feb 24 12:13:17 2017 +0000
@@ -1,8 +1,33 @@
-#### Anti-spam ruleset
+#### Anti-spam ruleset ###########################################
+# This script provides some foundational anti-spam
+# rules. It does not do any form of content filtering,
+# but this can be implemented by other scripts and
+# modules as desired.
+#
+# The following chains are available as extension
+# points:
+#
+# ::user/spam_check_message_content
+#   Apply additional checks to messages that may be spam
+#
+# ::user/spam_check_subscription_request
+#   Apply additional checks to subscription requests
+#
+# ::user/spam_handle_unknown_custom
+#   Override default handling of stanzas that weren't explicitly
+#   passed or rejected by the anti-spam checks
+#
+# ::user/spam_reject_custom
+#   Override default handling of stanzas that have
+#   been recognised as spam (default is to bounce
+#   a policy-violation error)
+##################################################################
 
-#### General rules for all incoming stanzas ####
+#### General rules for all incoming stanzas ######################
 ::deliver
 
+LOG=Considering $(stanza:top_tag())
+
 # Pass stanzas that a user sends to their own account
 TO SELF?
 PASS.
@@ -17,28 +42,36 @@
 
 # Run extra rules that apply to messages only
 KIND: message
-JUMP_CHAIN=user/check_spam_message
+JUMP CHAIN=user/spam_check_message
 
 # Run extra rules that apply to presence stanzas only
 KIND: presence
-JUMP CHAIN=user/check_spam_presence
+JUMP CHAIN=user/spam_check_presence
+
+JUMP CHAIN=user/spam_handle_unknown
 
-#### Rules for messages ####
-::user/check_spam_message
+# Default is to allow, override this with
+# the 'user/spam_handle_unknown' chain
+PASS.
+
+#### Rules for messages ##########################################
+::user/spam_check_message
 
 # Non-chat message types often generate pop-ups in clients,
 # so we won't accept them from strangers
 NOT TYPE: chat
-JUMP CHAIN=user/reject_spam
+JUMP CHAIN=user/spam_reject
 
 # This chain can be used by other scripts
 # and modules that analyze message content
-JUMP CHAIN=user/check_spam_message_content
+JUMP CHAIN=user/spam_check_message_content
+
+##################################################################
 
-#### Rules for presence stanzas ####
-::user/check_spam_presence
+#### Rules for presence stanzas ##################################
+::user/spam_check_presence
 
-# These may be received if rosters get out of sync, and are harmless
+# These may be received if rosters get out of sync and are harmless
 # because they will not be routed to the client unless necessary
 TYPE: unsubscribe|unsubscribed
 PASS.
@@ -50,10 +83,31 @@
 
 # This chain can be used by other scripts
 # and modules to filter subscription requests
-JUMP CHAIN=user/check_subscription_request
+JUMP CHAIN=user/spam_check_subscription_request
+
+##################################################################
 
-#### Stanzas reaching this chain will be rejected ####
-::user/reject_spam
+#### Stanzas reaching this chain will be rejected ################
+::user/spam_reject
+
+# This chain can be used by other scripts
+# and modules to override the default behaviour
+# when rejecting spam stanzas
+JUMP CHAIN=user/spam_reject_custom
 
 LOG=Rejecting suspected spam: $(stanza:top_tag())
 BOUNCE=policy-violation
+
+##################################################################
+
+#### Stanzas that may be spam, but we're not sure either way######
+::user/spam_handle_unknown
+
+# This chain can be used by other scripts
+# and modules to apply additional checks, or to
+# override the default behaviour
+JUMP CHAIN=user/spam_handle_unknown_custom
+
+#LOG=[debug] Spam check allowing: $(stanza:top_tag())
+
+##################################################################