prosody-modules
f6bbf42c341c
mod_anti_spam/README.markdown

Find changesets by keywords by author, files, the commit message, revision number or hash, or revset expression.

Software / code / prosody-modules

Comparison

mod_anti_spam/README.markdown @ 6123:f6bbf42c341c

mod_anti_spam: Add README
author Matthew Wild <mwild1@gmail.com>
date Mon, 30 Dec 2024 13:51:35 +0000
child 6151:0afd83bbdf09
comparison
equal deleted inserted replaced
6122:15f6f1566bdb 6123:f6bbf42c341c
1 ---
2 labels:
3 - 'Stage-Alpha'
4 summary: 'Spam filtering'
5 rockspec:
6 build:
7 modules:
8 mod_anti_spam.rtbl: rtbl.lib.lua
9 mod_anti_spam.trie: trie.lib.lua
10 ---
11
12 This module aims to provide an all-in-one spam filter for any kind of Prosody
13 deployment.
14
15 ## What is spam?
16
17 You're lucky if you have to ask! But it's worth explaining, so we can be clear
18 about what the module does (and does not).
19
20 Similar to every other popular communication network, there are people who try
21 to exploit XMPP for sending unsolicited messages - usually advertisements
22 for products and services. These people have gathered large lists of user
23 addresses, e.g. by searching and "scraping" websites for contact info.
24
25 If your address has not been discovered by the spammers, you won't receive any
26 spam. Prosody does not reveal user addresses (except, obviously, to people who
27 you communicate with). So to avoid it being picked up by spammers, be careful
28 about posting it unprotected on websites, etc.
29
30 However, if get unlucky and your address is discovered by spammers, you may
31 receive dozens of spam messages per day. mod_anti_spam is designed to filter
32 these annoying messages to prevent them from reaching you.
33
34 ## How does it work?
35
36 mod_anti_spam uses a variety of techniques to identify likely spam. Just as
37 the behaviour of spammers changes, The exact methods used to detect spam may
38 evolve over time in future updates.
39
40 If the sender is in the recipient's contact list already, no filtering will be
41 performed.
42
43 Otherwise, if the sender is a "stranger" to the recipient, the module will
44 perform some checks, and decide whether to let the message or contact request
45 through.
46
47 ### Shared block lists
48
49 mod_anti_spam can subscribe to Real-Time Block Lists (RTBLs) such as those
50 published by [xmppbl.org](https://xmppbl.org). This is a highly effective
51 measure to reduce spam from the network.
52
53 To enable this feature, you need to specify one or more compatible spam
54 services in the config file:
55
56 ```lua
57 anti_spam_services = { "xmppbl.org" }
58 ```
59
60 ### Content filters
61
62 mod_anti_spam also supports optionally filtering messages with specific
63 content or matching certain patterns.
64
65 A list of strings to block can be specified in the config file like so:
66
67 ```lua
68 anti_spam_block_strings = {
69 -- Block messages containing the text "exploit"
70 "exploit";
71 }
72 ```
73
74 Alternatively, you can specify a list of [Lua patterns](https://lua.org/manual/5.4/manual.html#6.4.1).
75 These are similar to regular expressions you may be familiar with from tools
76 like grep, but differ in a number of ways. Lua patterns are faster, but have
77 fewer features. The syntax is not fully compatible with other more widely-used
78 regular expression syntaxes. Read the Lua manual for full details.
79
80 ```lua
81 anti_spam_block_patterns = {
82 -- Block OTR handshake greetings (modern XMPP clients do not use OTR)
83 "^%?OTRv2?3?%?";
84 }
85 ```
86
87 There are no string or pattern filters in the module by default.
88
89 ## Handling reports
90
91 We recommend setting up Prosody to allow spam reporting, in case any spam
92 still gets through. Documentation can be found on [xmppbl.org's site](https://xmppbl.org/reports#server-operators).
93
94 ## Compatibility
95
96 Compatible with Prosody 0.12 and later.