Mercurial > prosody-modules

comparison mod_firewall/README.markdown @ 2540:d637bc0ac604

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
mod_firewall: Update README for latest changes
author Matthew Wild <mwild1@gmail.com>
date Tue, 21 Feb 2017 10:39:00 +0000
parents 898e70e85185
children 9b46d24edf0d
comparison
equal deleted inserted replaced
2539:1510b66a43fc 2540:d637bc0ac604
78 For example: 78 For example:
79 79
80 NOT FROM: user@example.com 80 NOT FROM: user@example.com
81 KIND NOT: message 81 KIND NOT: message
82 82
83 Some conditions do not take parameters, and these should end with just a
84 question mark, like:
85
86 IN ROSTER?
87
83 ### Zones 88 ### Zones
84 89
85 A 'zone' is one or more hosts or JIDs. It is possible to match when a 90 A 'zone' is one or more hosts or JIDs. It is possible to match when a
86 stanza is entering or leaving a zone, while at the same time not 91 stanza is entering or leaving a zone, while at the same time not
87 matching traffic passing between JIDs in the same zone. 92 matching traffic passing between JIDs in the same zone.
102 107
103 Condition Matches 108 Condition Matches
104 ------------ ------------------------------------------ 109 ------------ ------------------------------------------
105 `ENTERING` When a stanza is entering the named zone 110 `ENTERING` When a stanza is entering the named zone
106 `LEAVING` When a stanza is leaving the named zone 111 `LEAVING` When a stanza is leaving the named zone
112
113 ### Lists
114
115 It is possible to create or load lists of strings for use in scripts. For example, you might load a JID blacklist,
116 a list of malware URLs or simple words that you want to filter messages on.
117
118 List type Example
119 ----------- -----------------------
120 memory %LIST spammers: memory
121 file %LIST spammers: file:/etc/spammers.txt
122 http %LIST spammers: http://example.com/spammers.txt
123
124 #### CHECK LIST
125
126 Checks whether a simple expression is found in a given list.
127
128 Example:
129
130 %LIST blacklist: file:/etc/prosody/blacklist.txt
131
132 # Rule to block presence subscription requests from blacklisted JIDs
133 KIND: presence
134 TYPE: subscribe
135 CHECK LIST: blacklist contains $<@from>
136 BOUNCE=policy-violation (Your JID is blacklisted)
137
138 #### SCAN
139
140 SCAN allows you to search inside a stanza for a given pattern, and check each result against a list. For example,
141 you could scan a message body for words and check if any of the words are found in a given list.
142
143 Before using SCAN, you need to define a search location and a pattern. The search location uses the same 'path'
144 format as documented under the 'INSPECT' condition. Patterns can be any valid Lua pattern.
145
146 To use the above example:
147
148 # Define a search location called 'body' which fetches the text of the 'body' element
149 %SEARCH body: body#
150 # Define a pattern called 'word' which matches any sequence of letters
151 %PATTERN word: [A-Za-z]+
152 # Finally, we also need our list of "bad" words:
153 %LIST badwords: file:/etc/prosody/bad_words.txt
154
155 # Now we can use these to SCAN incoming stanzas
156 # If it finds a match, bounce the stanza
157 SCAN: body for word in badwords
158 BOUNCE=policy-violation (This word is not allowed!)
107 159
108 ### Stanza matching 160 ### Stanza matching
109 161
110 Condition Matches 162 Condition Matches
111 ----------- ------------------------------------------------------------------------------------------------------------------------------------------------------------ 163 ----------- ------------------------------------------------------------------------------------------------------------------------------------------------------------
124 176
125 **Note:** The type 'available' for presence does not actually appear in 177 **Note:** The type 'available' for presence does not actually appear in
126 the protocol. Available presence is signalled by the omission of a type. 178 the protocol. Available presence is signalled by the omission of a type.
127 Similarly, a message stanza with no type is equivalent to one of type 179 Similarly, a message stanza with no type is equivalent to one of type
128 'normal'. mod\_firewall handles these cases for you automatically. 180 'normal'. mod\_firewall handles these cases for you automatically.
181
182 ### Sender/recipient matching
183
184 Condition Matches
185 ----------- -------------------------------------------------------
186 `FROM` The JID in the 'from' attribute matches the given JID
187 `TO` The JID in the 'to' attribute matches the given JID
188
189 These conditions both accept wildcards in the JID when the wildcard
190 expression is enclosed in angle brackets ('\<...\>'). For example:
191
192 # All users at example.com
193 FROM: <*>@example.com
194
195 # The user 'admin' on any subdomain of example.com
196 FROM: admin@<*.example.com>
197
198 You can also use [Lua's pattern
199 matching](http://www.lua.org/manual/5.1/manual.html#5.4.1) for more
200 powerful matching abilities. Patterns are a lightweight
201 regular-expression alternative. Simply contain the pattern in double
202 angle brackets. The pattern is automatically anchored at the start and
203 end (so it must match the entire portion of the JID).
204
205 # Match admin@example.com, and admin1@example.com, etc.
206 FROM: <<admin%d*>>@example.com
207
208 **Note:** It is important to know that 'example.com' is a valid JID on
209 its own, and does **not** match 'user@example.com'. To perform domain
210 whitelists or blacklists, use Zones.
211
212 Condition Matches
213 ---------------- ---------------------------------------------------------------
214 `FROM_EXACTLY` The JID in the 'from' attribute exactly matches the given JID
215 `TO_EXACTLY` The JID in the 'to' attribute exactly matches the given JID
216
217 These additional conditions do not support pattern matching, but are
218 useful to match the exact to/from address on a stanza. For example, if
219 no resource is specified then only bare JIDs will be matched. TO and FROM
220 match all resources if no resource is specified to match.
221
222 **Note:** Some chains execute before Prosody has performed any
223 normalisation or validity checks on the to/from JIDs on an incoming
224 stanza. It is not advisable to perform access control or similar rules
225 on JIDs in these chains (see the chain documentation for more info).
129 226
130 #### INSPECT 227 #### INSPECT
131 228
132 INSPECT takes a 'path' through the stanza to get a string (an attribute 229 INSPECT takes a 'path' through the stanza to get a string (an attribute
133 value or text content). An example is the best way to explain. Let's 230 value or text content). An example is the best way to explain. Let's
166 INSPECT is somewhat slower than the other stanza matching conditions. To 263 INSPECT is somewhat slower than the other stanza matching conditions. To
167 minimise performance impact, always place it below other faster 264 minimise performance impact, always place it below other faster
168 condition checks where possible (e.g. above we first checked KIND, TYPE 265 condition checks where possible (e.g. above we first checked KIND, TYPE
169 and PAYLOAD matched before INSPECT). 266 and PAYLOAD matched before INSPECT).
170 267
171 ### Sender/recipient matching
172
173 Condition Matches
174 ----------- -------------------------------------------------------
175 `FROM` The JID in the 'from' attribute matches the given JID
176 `TO` The JID in the 'to' attribute matches the given JID
177
178 These conditions both accept wildcards in the JID when the wildcard
179 expression is enclosed in angle brackets ('\<...\>'). For example:
180
181 # All users at example.com
182 FROM: <*>@example.com
183
184 # The user 'admin' on any subdomain of example.com
185 FROM: admin@<*.example.com>
186
187 You can also use [Lua's pattern
188 matching](http://www.lua.org/manual/5.1/manual.html#5.4.1) for more
189 powerful matching abilities. Patterns are a lightweight
190 regular-expression alternative. Simply contain the pattern in double
191 angle brackets. The pattern is automatically anchored at the start and
192 end (so it must match the entire portion of the JID).
193
194 # Match admin@example.com, and admin1@example.com, etc.
195 FROM: <<admin%d*>>@example.com
196
197 **Note:** It is important to know that 'example.com' is a valid JID on
198 its own, and does **not** match 'user@example.com'. To perform domain
199 whitelists or blacklists, use Zones.
200
201 Condition Matches
202 ---------------- ---------------------------------------------------------------
203 `FROM_EXACTLY` The JID in the 'from' attribute exactly matches the given JID
204 `TO_EXACTLY` The JID in the 'to' attribute exactly matches the given JID
205
206 These additional conditions do not support pattern matching, but are
207 useful to match the exact to/from address on a stanza. For example, if
208 no resource is specified then only bare JIDs will be matched. TO and FROM
209 match all resources if no resource is specified to match.
210
211 **Note:** Some chains execute before Prosody has performed any
212 normalisation or validity checks on the to/from JIDs on an incoming
213 stanza. It is not advisable to perform access control or similar rules
214 on JIDs in these chains (see the chain documentation for more info).
215
216 ### Roster 268 ### Roster
217 269
218 These functions access the roster of the recipient (only). Therefore they cannot (currently) 270 These functions access the roster of the recipient (only). Therefore they cannot (currently)
219 be used in some chains, such as for outgoing messages (the recipient may be on another server). 271 be used in some chains, such as for outgoing messages (the recipient may be on another server).
220 272
221 Performance note: this check can potentially cause storage access (especially if the recipient 273 Performance note: this check can potentially cause storage access (especially if the recipient
222 is currently offline), so you may want to limit its use in high-traffic situations, and place 274 is currently offline), so you may want to limit its use in high-traffic situations, and place
223 it below other checks (such as a rate limiter). 275 it below other checks (such as a rate limiter).
224 276
225 #### IN_ROSTER 277 #### IN ROSTER
226 278
227 Tests whether the sender is in the recipient's roster. 279 Tests whether the sender is in the recipient's roster.
228 280
229 IN_ROSTER: yes 281 IN ROSTER?
230 282
231 #### IN_ROSTER_GROUP 283 #### IN ROSTER GROUP
232 284
233 Tests whether the sender is in the recipient's roster, and in the named group. 285 Tests whether the sender is in the recipient's roster, and in the named group.
234 286
235 IN_ROSTER_GROUP: Friends 287 IN ROSTER GROUP: Friends
236 288
237 #### SUBSCRIBED 289 #### SUBSCRIBED
238 290
239 Tests whether the recipient is subscribed to the sender, ie will receive 291 Tests whether the recipient is subscribed to the sender, ie will receive
240 presence updates from them. 292 presence updates from them.
248 Using Prosody's mod\_groups it is possible to define groups of users on the server. You can 300 Using Prosody's mod\_groups it is possible to define groups of users on the server. You can
249 match based on these groups in firewall rules. 301 match based on these groups in firewall rules.
250 302
251 Condition Matches 303 Condition Matches
252 ------------- ---------------------------- 304 ------------- ----------------------------
253 `FROM_GROUP` When the stanza is being sent from a member of the named group 305 `FROM GROUP` When the stanza is being sent from a member of the named group
254 `TO_GROUP` When the stanza is being sent to a member of the named group 306 `TO GROUP` When the stanza is being sent to a member of the named group
307
308 #### SENT DIRECTED PRESENCE TO SENDER
309
310 This condition matches if the recipient of a stanza has previously sent directed presence to the sender of the stanza. This
311 is often done in XMPP to exchange presence information with JIDs that are not on your roster, such as MUC rooms.
312
313 This condition does not take a parameter - end the condition name with a question mark:
314
315 # Rule to bounce messages from senders not in the roster who haven't been sent directed presence
316 NOT IN ROSTER?
317 NOT SENT DIRECTED PRESENCE TO SENDER?
318 BOUNCE=service-unavailable
255 319
256 ### Admins 320 ### Admins
257 321
258 Prosody allows certain JIDs to be declared as administrators of a host, component or the whole server. 322 Prosody allows certain JIDs to be declared as administrators of a host, component or the whole server.
259 323
260 Condition Matches 324 Condition Matches
261 -------------- ---------------------------------- 325 -------------- ----------------------------------
262 FROM_ADMIN_OF When the sender of the stanza is an admin of the named host on the current server 326 FROM ADMIN OF When the sender of the stanza is an admin of the named host on the current server
263 TO_ADMIN_OF When the recipient of the stanza is an admin of the named host on the current server 327 TO ADMIN OF When the recipient of the stanza is an admin of the named host on the current server
264 328
265 ### Time and date 329 ### Time and date
266 330
267 #### TIME 331 #### TIME
268 332
356 It is possible to 'mark' sessions (see the MARK_ORIGIN action below). To match stanzas from marked sessions, use the 420 It is possible to 'mark' sessions (see the MARK_ORIGIN action below). To match stanzas from marked sessions, use the
357 `ORIGIN_MARKED` condition. 421 `ORIGIN_MARKED` condition.
358 422
359 Condition Description 423 Condition Description
360 ------------------------------- --------------------------------------------------------------- 424 ------------------------------- ---------------------------------------------------------------
361 ORIGIN_MARKED: markname Matches if the origin has been marked with 'markname'. 425 ORIGIN MARKED: markname Matches if the origin has been marked with 'markname'.
362 ORIGIN_MARKED: markname (Xs) Matches if the origin has been marked with 'markname' within the past X seconds. 426 ORIGIN MARKED: markname (Xs) Matches if the origin has been marked with 'markname' within the past X seconds.
363 427
364 Example usage: 428 Example usage:
365 429
366 # This rule drops messages from sessions that have been marked as spammers in the past hour 430 # This rule drops messages from sessions that have been marked as spammers in the past hour
367 ORIGIN_MARKED: spammer (3600s) 431 ORIGIN MARKED: spammer (3600s)
368 DROP. 432 DROP.
369 433
370 # This rule marks the origin session as a spammer if they send a message to a honeypot JID 434 # This rule marks the origin session as a spammer if they send a message to a honeypot JID
371 KIND: message 435 KIND: message
372 TO: honeypot@example.com 436 TO: honeypot@example.com
373 MARK_ORIGIN=spammer 437 MARK ORIGIN=spammer
374 438
375 Actions 439 Actions
376 ------- 440 -------
377 441
378 Actions come after all conditions in a rule block. There must be at 442 Actions come after all conditions in a rule block. There must be at
421 485
422 It is possible to mark sessions, and then use these marks to match rules later on. 486 It is possible to mark sessions, and then use these marks to match rules later on.
423 487
424 Action Description 488 Action Description
425 ------------------------ -------------------------------------------------------------------------- 489 ------------------------ --------------------------------------------------------------------------
426 `MARK_ORIGIN=mark` Marks the originating session with the given flag. 490 `MARK ORIGIN=mark` Marks the originating session with the given flag.
427 `UNMARK_ORIGIN=mark` Removes the given mark from the origin session (if it is set). 491 `UNMARK ORIGIN=mark` Removes the given mark from the origin session (if it is set).
428 492
429 **Note:** Marks apply to sessions, not JIDs. E.g. if marking in a rule that matches a stanza received 493 **Note:** Marks apply to sessions, not JIDs. E.g. if marking in a rule that matches a stanza received
430 over s2s, it is the s2s session that is marked. 494 over s2s, it is the s2s session that is marked.
431 495
432 It is possible to have multiple marks on an origin at any given time. 496 It is possible to have multiple marks on an origin at any given time.
491 TO: alice@remote.example.com 555 TO: alice@remote.example.com
492 DROP. 556 DROP.
493 557
494 Action Description 558 Action Description
495 ------------------------ ------------------------------------------------------------------------ 559 ------------------------ ------------------------------------------------------------------------
496 `JUMP_CHAIN=name` Switches chains, and passes the stanza through the rules in chain 'name'. If the new chain causes the stanza to be dropped/redirected, the current chain halts further processing. 560 `JUMP CHAIN=name` Switches chains, and passes the stanza through the rules in chain 'name'. If the new chain causes the stanza to be dropped/redirected, the current chain halts further processing.
497 561
498 It is possible to jump to chains defined by other scripts and modules. 562 It is possible to jump to chains defined by other scripts and modules.
499 563
500 Expressions 564 Expressions
501 ----------- 565 -----------
504 are static once the firewall script is loaded and compiled internally, however parameters that allow expressions can be dynamically calculated when a 568 are static once the firewall script is loaded and compiled internally, however parameters that allow expressions can be dynamically calculated when a
505 rule is being run. 569 rule is being run.
506 570
507 There are two kinds of expression that you can use: stanza expressions, and code expressions. 571 There are two kinds of expression that you can use: stanza expressions, and code expressions.
508 572
573 ### Stanza expressions
574
509 Stanza expressions are of the form `$<...>`, where `...` is a stanza path. For syntax of stanza paths, see the documentation for the 'INSPECT' condition 575 Stanza expressions are of the form `$<...>`, where `...` is a stanza path. For syntax of stanza paths, see the documentation for the 'INSPECT' condition
510 above. 576 above.
511 577
512 Example: 578 Example:
513 579
514 LOG=Matched a stanza from $<@from> to $<@to> 580 LOG=Matched a stanza from $<@from> to $<@to>
515 581
516 If the path does not match (e.g. the element isn't found, or the attribute doesn't exist) it will return the text `<undefined>`. You can override this 582 There are built in functions which can be applied to the output of a stanza expression, by appending the pipe ('|') operator, followed by the function
517 by specifying an alternative default value, using the syntax `$<path||default>`. 583 name. These functions are:
584
585 Function Description
586 ------------ ---------------------------------------
587 bare Given a JID, strip any resource
588 node Return the node ('user part') of a JID
589 host Return the host ('domain') part of a JID
590 resource Return the resource part of a JID
591
592 For example, to apply a rate limit to stanzas per sender domain:
593
594 LIMIT normal on $<@from|domain>
595
596 If the path does not match (e.g. the element isn't found, or the attribute doesn't exist) or any of the functions fail to produce an output (e.g. an invalid
597 JID was passed to a function that only handles valid JIDs) the expression will return the text `<undefined>`. You can override this by ending the expression
598 with a double pipe ('||') followed by a quoted string to use as a default instead. E.g. to default to the string "normal" when there is no 'type' attribute:
599
600 LOG=Stanza type is $<@type||"normal">
601
602 ### Code expressions
518 603
519 Code expressions use `$(...)` syntax. Code expressions are powerful, and allow unconstrained access to Prosody's internal environment. Therefore 604 Code expressions use `$(...)` syntax. Code expressions are powerful, and allow unconstrained access to Prosody's internal environment. Therefore
520 code expressions are typically for advanced use-cases only. You may want to refer to Prosody's [developer documentation](https://prosody.im/doc/developers) 605 code expressions are typically for advanced use-cases only. You may want to refer to Prosody's [developer documentation](https://prosody.im/doc/developers)
521 for more information. In particular, within code expressions you may access the 'session' object, which is the session object of the origin of the stanza, 606 for more information. In particular, within code expressions you may access the 'session' object, which is the session object of the origin of the stanza,
522 and the 'stanza' object, which is the stanza being considered within the current rule. Whatever value the expression returns will be converted to a string. 607 and the 'stanza' object, which is the stanza being considered within the current rule. Whatever value the expression returns will be converted to a string.