prosody-modules
d611ed13df7e
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

Annotate

mod_anti_spam/README.markdown @ 6209:d611ed13df7e draft

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