lib/PublicInbox/SaPlugin/ListMirror.pod

   1 =head1 NAME
   2
   3 PublicInbox::SaPlugin::ListMirror - SpamAssassin plugin for mailing list mirrors
   4
   5 =head1 SYNOPSIS
   6
   7   loadplugin PublicInbox::SaPlugin::ListMirror
   8
   9 Declare some mailing lists based on the expected List-Id value,
  10 expected servers, and mailing list address:
  11
  12   list_mirror List-Id <foo.example.com> *.example.com foo@example.com
  13   list_mirror List-Id <bar.example.com> *.example.com bar@example.com
  14
  15 Bump the score for messages which come from unexpected servers:
  16
  17   header LIST_MIRROR_RECEIVED eval:check_list_mirror_received()
  18   describe LIST_MIRROR_RECEIVED Received does not match expected
  19   score LIST_MIRROR_RECEIVED 10
  20
  21 Bump the score for messages which Bcc the list:
  22
  23   header LIST_MIRROR_BCC eval:check_list_mirror_bcc()
  24   describe LIST_MIRROR_BCC Mailing list was Bcc-ed
  25   score LIST_MIRROR_BCC 5
  26
  27 =head1 DESCRIPTION
  28
  29 This plugin contains common functions to provide accurate, ongoing
  30 mirrors of existing mailing lists.  It may be used independently of the
  31 rest of public-inbox, it does not depend on any public-inbox code, only
  32 SpamAssassin.
  33
  34 =head1 ADMINISTRATOR SETTINGS
  35
  36 This plugin has no administrator settings, aside from the need
  37 to load it via C<loadplugin> and enabling user rules
  38 C<allow_user_rules 1>
  39
  40 =head1 USER SETTINGS
  41
  42 =over 4
  43
  44 =item list_mirror HEADER HEADER_VALUE HOSTNAME_GLOB [LIST_ADDRESS]
  45
  46 Declare a list based on an expected C<HEADER> matching C<HEADER_NAME>
  47 exactly coming from C<HOSTNAME_GLOB>.  C<LIST_ADDRESS> is optional,
  48 but may specify the address of the mailing list being mirrored.
  49
  50 C<List-Id> or C<X-Mailing-List> are common values of C<HEADER>
  51
  52 An example of C<HEADER_VALUE> is C<E<lt>foo.example.orgE<gt>>
  53 if C<HEADER> is C<List-Id>.
  54
  55 C<HOSTNAME_GLOB> may be a wildcard match for machines where mail can
  56 come from or an exact match.
  57
  58 C<LIST_ADDRESS> is only required if using the L</check_list_mirror_bcc>
  59 eval rule
  60
  61 C<list_mirror> may be specified multiple times.
  62
  63 =back
  64
  65 =head1 EVAL FUNCTIONS
  66
  67 =over 4
  68
  69 =item header LIST_MIRROR_RECEIVED eval:check_list_mirror_received()
  70
  71 The C<check_list_mirror_received> function implements C<Received:>
  72 header checking based on L</list_mirror> configuration values.
  73
  74 This rule can be used to score and prevent messages from being injected
  75 directly into your mirror without going through the expected mailing
  76 list servers:
  77
  78   ifplugin PublicInbox::SaPlugin::ListMirror
  79     header LIST_MIRROR_RECEIVED eval:check_list_mirror_received()
  80     describe LIST_MIRROR_RECEIVED Received does not match expected
  81   endif
  82
  83 =item header LIST_MIRROR_BCC eval:check_list_mirror_bcc()
  84
  85 The C<check_list_mirror_bcc> function checks for Bcc to mailing lists
  86 declared with a C<LIST_ADDRESS> via L</list_mirror>
  87
  88 Spammers will often Bcc mailing lists; while it's uncommon and
  89 strange for valid messages to be Bcc-ed to any public mailing list.
  90 This rule allows users to assign a score to Bcc-ed messages
  91
  92   ifplugin PublicInbox::SaPlugin::ListMirror
  93     header LIST_MIRROR_BCC eval:check_list_mirror_bcc()
  94     describe LIST_MIRROR_BCC Mailing list was Bcc-ed
  95   endif
  96
  97 =back
  98
  99 =head1 CONTACT
 100
 101 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 102
 103 The mail archives are hosted at L<https://public-inbox.org/meta/>
 104 and L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 105
 106 =head1 COPYRIGHT
 107
 108 Copyright (C) 2016-2021 all contributors L<mailto:meta@public-inbox.org>
 109
 110 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 111
 112 =head1 SEE ALSO
 113
 114 L<Mail::SpamAssassin::Conf>