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_VALUE>
  47 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> is the recommended value of C<HEADER> as most
  51 mailing lists support it.
  52
  53 An example of C<HEADER_VALUE> is C<E<lt>foo.example.orgE<gt>>
  54 if C<HEADER> is C<List-ID>.
  55
  56 As of public-inbox 2.0, using C<List-ID> as the C<HEADER> and a
  57 C<HEADER_VALUE> contained by angle brackets (E<lt>list-idE<gt>),
  58 matching is done in accordance with
  59 L<RFC 2919|https://tools.ietf.org/html/rfc2919>.  That is,
  60 C<HEADER_VALUE> will be a case-insensitive substring match
  61 and ignore the optional description C<phrase> as documented
  62 in RFC 2919.
  63
  64 All other C<HEADER> values use exact matches for backwards-compatibility.
  65
  66 C<HOSTNAME_GLOB> may be a wildcard match for machines where mail can
  67 come from or an exact match.
  68
  69 C<LIST_ADDRESS> is only required if using the L</check_list_mirror_bcc>
  70 eval rule
  71
  72 C<list_mirror> may be specified multiple times.
  73
  74 =back
  75
  76 =head1 EVAL FUNCTIONS
  77
  78 =over 4
  79
  80 =item header LIST_MIRROR_RECEIVED eval:check_list_mirror_received()
  81
  82 The C<check_list_mirror_received> function implements C<Received:>
  83 header checking based on L</list_mirror> configuration values.
  84
  85 This rule can be used to score and prevent messages from being injected
  86 directly into your mirror without going through the expected mailing
  87 list servers:
  88
  89   ifplugin PublicInbox::SaPlugin::ListMirror
  90     header LIST_MIRROR_RECEIVED eval:check_list_mirror_received()
  91     describe LIST_MIRROR_RECEIVED Received does not match expected
  92   endif
  93
  94 =item header LIST_MIRROR_BCC eval:check_list_mirror_bcc()
  95
  96 The C<check_list_mirror_bcc> function checks for Bcc to mailing lists
  97 declared with a C<LIST_ADDRESS> via L</list_mirror>
  98
  99 Spammers will often Bcc mailing lists; while it's uncommon and
 100 strange for valid messages to be Bcc-ed to any public mailing list.
 101 This rule allows users to assign a score to Bcc-ed messages
 102
 103   ifplugin PublicInbox::SaPlugin::ListMirror
 104     header LIST_MIRROR_BCC eval:check_list_mirror_bcc()
 105     describe LIST_MIRROR_BCC Mailing list was Bcc-ed
 106   endif
 107
 108 =back
 109
 110 =head1 CONTACT
 111
 112 Feedback welcome via plain-text mail to L<mailto:meta@public-inbox.org>
 113
 114 The mail archives are hosted at L<https://public-inbox.org/meta/>
 115 and L<http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>
 116
 117 =head1 COPYRIGHT
 118
 119 Copyright (C) all contributors L<mailto:meta@public-inbox.org>
 120
 121 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 122
 123 =head1 SEE ALSO
 124
 125 L<Mail::SpamAssassin::Conf>