Debian Codegraph @

lualib/plugins/rbl.lua

raw
1 --[[
2 Copyright (c) 2022, Vsevolod Stakhov <[email protected]>
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15 ]]--
16
17 local T = require "lua_shape.core"
18 local lua_maps = require "lua_maps"
19 local lua_util = require "lua_util"
20 local PluginSchema = require "lua_shape.plugin_schema"
21
22 -- Common RBL plugin definitions
23
24 local check_types = {
25 from = {
26 connfilter = true,
27 },
28 received = {},
29 helo = {
30 connfilter = true,
31 },
32 urls = {},
33 content_urls = {},
34 numeric_urls = {},
35 emails = {},
36 images = {},
37 replyto = {},
38 dkim = {},
39 rdns = {
40 connfilter = true,
41 },
42 selector = {
43 require_argument = true,
44 },
45 }
46
47 local default_options = {
48 ['default_enabled'] = true,
49 ['default_ipv4'] = true,
50 ['default_ipv6'] = true,
51 ['default_unknown'] = false,
52 ['default_dkim_domainonly'] = true,
53 ['default_emails_domainonly'] = false,
54 ['default_exclude_users'] = false,
55 ['default_exclude_local'] = true,
56 ['default_no_ip'] = false,
57 ['default_dkim_match_from'] = false,
58 ['default_selector_flatten'] = true,
59 }
60
61 local return_codes_schema = T.table({}, {
62 open = true,
63 key = T.transform(T.string(), string.upper),
64 extra = T.one_of({
65 T.array(T.string()),
66 -- Transform string to array
67 T.transform(T.string(), function(val)
68 return { val }
69 end)
70 })
71 }):doc({ summary = "Map of symbol names to IP patterns" })
72
73 local return_bits_schema = T.table({}, {
74 open = true,
75 key = T.transform(T.string(), string.upper),
76 extra = T.one_of({
77 T.array(T.one_of({
78 T.number(),
79 T.transform(T.string(), tonumber)
80 })),
81 -- Transform string or number to array
82 T.one_of({
83 T.transform(T.string(), function(val)
84 return { tonumber(val) }
85 end),
86 T.transform(T.number(), function(val)
87 return { val }
88 end)
89 })
90 })
91 }):doc({ summary = "Map of symbol names to bit numbers" })
92
93 local rule_schema_tbl = {
94 content_urls = T.boolean():optional()
95 :doc({ summary = "Check URLs found in message body content" }),
96 disable_monitoring = T.boolean():optional()
97 :doc({ summary = "Disable automatic monitoring/health checks for this RBL" }),
98 disabled = T.boolean():optional()
99 :doc({ summary = "Completely disable this RBL rule" }),
100 dkim = T.boolean():optional()
101 :doc({ summary = "Check DKIM signature domains against this RBL" }),
102 dkim_domainonly = T.boolean():optional()
103 :doc({ summary = "Use only the domain part of DKIM signatures for lookups" }),
104 dkim_match_from = T.boolean():optional()
105 :doc({ summary = "Only check DKIM domains that match the From header domain" }),
106 emails = T.boolean():optional()
107 :doc({ summary = "Check email addresses found in message against this RBL" }),
108 emails_delimiter = T.string():optional()
109 :doc({ summary = "Delimiter to use when constructing email-based RBL queries" }),
110 emails_domainonly = T.boolean():optional()
111 :doc({ summary = "Use only the domain part of email addresses for lookups" }),
112 enabled = T.boolean():optional()
113 :doc({ summary = "Enable this RBL rule" }),
114 exclude_local = T.boolean():optional()
115 :doc({ summary = "Skip RBL checks for locally originated messages" }),
116 exclude_users = T.boolean():optional()
117 :doc({ summary = "Skip RBL checks for authenticated users" }),
118 from = T.boolean():optional()
119 :doc({ summary = "Check the sending IP address (from SMTP envelope) against this RBL" }),
120 hash = T.enum({ "sha1", "sha256", "sha384", "sha512", "md5", "blake2" }):optional()
121 :doc({ summary = "Hash algorithm to use for RBL queries (for hash-based RBLs)" }),
122 hash_format = T.enum({ "hex", "base32", "base64" }):optional()
123 :doc({ summary = "Encoding format for hashed RBL queries" }),
124 hash_len = T.one_of({ T.integer(), T.transform(T.string(), tonumber) }):optional()
125 :doc({ summary = "Truncate hash to this many characters" }),
126 helo = T.boolean():optional()
127 :doc({ summary = "Check the HELO/EHLO hostname against this RBL" }),
128 ignore_default = T.boolean():optional()
129 :doc({ summary = "Ignore default settings for this rule (alias for ignore_defaults)" }),
130 ignore_defaults = T.boolean():optional()
131 :doc({ summary = "Ignore default settings for this rule" }),
132 ignore_url_whitelist = T.boolean():optional()
133 :doc({ summary = "Do not apply URL whitelist to this RBL" }),
134 ignore_whitelist = T.boolean():optional()
135 :doc({ summary = "Do not apply global whitelist to this RBL" }),
136 ignore_whitelists = T.boolean():optional()
137 :doc({ summary = "Do not apply any whitelists to this RBL" }),
138 images = T.boolean():optional()
139 :doc({ summary = "Check URLs of embedded images against this RBL" }),
140 ipv4 = T.boolean():optional()
141 :doc({ summary = "Enable lookups for IPv4 addresses" }),
142 ipv6 = T.boolean():optional()
143 :doc({ summary = "Enable lookups for IPv6 addresses" }),
144 is_whitelist = T.boolean():optional()
145 :doc({ summary = "Treat this RBL as a whitelist (positive result means whitelisted)" }),
146 local_exclude_ip_map = T.string():optional()
147 :doc({ summary = "Path to map file containing IPs to exclude from this RBL check" }),
148 monitored_address = T.string():optional()
149 :doc({ summary = "Specific address to use for RBL health monitoring queries" }),
150 no_ip = T.boolean():optional()
151 :doc({ summary = "Disable IP-based lookups for this RBL" }),
152 process_script = T.string():optional()
153 :doc({ summary = "Lua script to process/transform RBL query results" }),
154 random_monitored = T.boolean():optional()
155 :doc({ summary = "Use random addresses for RBL health monitoring" }),
156 rbl = T.string()
157 :doc({ summary = "The RBL zone/domain to query (required)" }),
158 rdns = T.boolean():optional()
159 :doc({ summary = "Check reverse DNS (PTR) hostname of sender IP against this RBL" }),
160 received = T.boolean():optional()
161 :doc({ summary = "Check IP addresses from Received headers against this RBL" }),
162 received_flags = T.array(T.string()):optional()
163 :doc({ summary = "Only check Received headers with these flags set" }),
164 received_max_pos = T.number():optional()
165 :doc({ summary = "Maximum position in Received header chain to check (1 = first hop)" }),
166 received_min_pos = T.number():optional()
167 :doc({ summary = "Minimum position in Received header chain to check" }),
168 received_nflags = T.array(T.string()):optional()
169 :doc({ summary = "Only check Received headers without these flags set" }),
170 replyto = T.boolean():optional()
171 :doc({ summary = "Check Reply-To header domain against this RBL" }),
172 requests_limit = T.one_of({ T.integer(), T.transform(T.string(), tonumber) }):optional()
173 :doc({ summary = "Maximum number of RBL requests per message for this rule" }),
174 require_symbols = T.one_of({
175 T.array(T.string()),
176 T.transform(T.string(), function(s)
177 return { s }
178 end)
179 }):optional()
180 :doc({ summary = "Only perform RBL check if these symbols are present" }),
181 resolve_ip = T.boolean():optional()
182 :doc({ summary = "Resolve hostnames to IPs before RBL lookup" }),
183 return_bits = return_bits_schema:optional()
184 :doc({ summary = "Map symbol names to bit positions in RBL response" }),
185 return_codes = return_codes_schema:optional()
186 :doc({ summary = "Map symbol names to specific RBL return codes/IPs" }),
187 returnbits = return_bits_schema:optional()
188 :doc({ summary = "Alias for return_bits" }),
189 returncodes = return_codes_schema:optional()
190 :doc({ summary = "Alias for return_codes" }),
191 returncodes_matcher = T.enum({ "equality", "glob", "luapattern", "radix", "regexp" }):optional()
192 :doc({ summary = "Method to match return codes: equality, glob, luapattern, radix, or regexp" }),
193 selector = T.one_of({ { name = "string", schema = T.string() }, { name = "table", schema = T.table({}, { open = true }) } }):optional()
194 :doc({ summary = "Selector expression to extract custom data for RBL lookup" }),
195 selector_flatten = T.boolean():optional()
196 :doc({ summary = "Flatten selector results into individual lookups" }),
197 symbol = T.string():optional()
198 :doc({ summary = "Symbol name to register for this RBL rule" }),
199 symbols_prefixes = T.table({}, { open = true, extra = T.string() }):optional()
200 :doc({ summary = "Prefix mappings for generated symbol names" }),
201 unknown = T.boolean():optional()
202 :doc({ summary = "Check IPs with unknown/missing PTR records" }),
203 url_compose_map = lua_maps.map_schema:optional()
204 :doc({ summary = "Map to compose/rewrite URLs before RBL lookup" }),
205 url_full_hostname = T.boolean():optional()
206 :doc({ summary = "Use full hostname (not just registered domain) for URL lookups" }),
207 url_whitelist = lua_maps.map_schema:optional()
208 :doc({ summary = "Map of URLs to exclude from this RBL check" }),
209 urls = T.boolean():optional()
210 :doc({ summary = "Check URLs found in message against this RBL" }),
211 whitelist = lua_maps.map_schema:optional()
212 :doc({ summary = "Map of IPs/domains to exclude from this RBL check" }),
213 whitelist_exception = T.one_of({
214 T.array(T.string()),
215 T.transform(T.string(), function(s)
216 return { s }
217 end)
218 }):optional()
219 :doc({ summary = "Symbols that bypass the whitelist" }),
220 checks = T.array(T.enum(lua_util.keys(check_types))):optional()
221 :doc({ summary = "List of check types to enable: from, received, helo, urls, emails, dkim, rdns, etc." }),
222 exclude_checks = T.array(T.enum(lua_util.keys(check_types))):optional()
223 :doc({ summary = "List of check types to explicitly disable" }),
224 }
225
226 local function convert_checks(rule, name)
227 local rspamd_logger = require "rspamd_logger"
228 if rule.checks then
229 local all_connfilter = true
230 local exclude_checks = lua_util.list_to_hash(rule.exclude_checks or {})
231 for _, check in ipairs(rule.checks) do
232 if not exclude_checks[check] then
233 local check_type = check_types[check]
234 if check_type.require_argument then
235 if not rule[check] then
236 rspamd_logger.errx(rspamd_config, 'rbl rule %s has check %s which requires an argument',
237 name, check)
238 return nil
239 end
240 end
241
242 if not check_type.connfilter then
243 all_connfilter = false
244 end
245
246 if not check_type then
247 rspamd_logger.errx(rspamd_config, 'rbl rule %s has invalid check type: %s',
248 name, check)
249 return nil
250 end
251
252 rule[check] = true
253 else
254 rspamd_logger.infox(rspamd_config, 'disable check %s in %s: excluded explicitly',
255 check, name)
256 end
257 end
258 rule.connfilter = all_connfilter
259 end
260
261 -- Now check if we have any check enabled at all
262 local check_found = false
263 for k, _ in pairs(check_types) do
264 if type(rule[k]) ~= 'nil' then
265 check_found = true
266 break
267 end
268 end
269
270 if not check_found then
271 -- Enable implicit `from` check to allow upgrade
272 rspamd_logger.warnx(rspamd_config, 'rbl rule %s has no check enabled, enable default `from` check',
273 name)
274 rule.from = true
275 end
276
277 if rule.returncodes and not rule.returncodes_matcher then
278 for _, v in pairs(rule.returncodes) do
279 for _, e in ipairs(v) do
280 if e:find('[%%%[]') then
281 rspamd_logger.warn(rspamd_config, 'implicitly enabling luapattern returncodes_matcher for rule %s', name)
282 rule.returncodes_matcher = 'luapattern'
283 break
284 end
285 end
286 if rule.returncodes_matcher then
287 break
288 end
289 end
290 end
291
292 return rule
293 end
294
295
296 -- Add default boolean flags to the schema
297 for def_k, _ in pairs(default_options) do
298 rule_schema_tbl[def_k:sub(#('default_') + 1)] = T.boolean():optional()
299 end
300
301 local rule_schema = T.table(rule_schema_tbl):doc({ summary = "RBL rule configuration schema" })
302
303 local plugin_schema = T.table({
304 enabled = T.boolean():optional()
305 :doc({ summary = "Enable or disable the RBL module" }),
306 disable_monitoring = T.boolean():optional()
307 :doc({ summary = "Disable health monitoring for all RBLs" }),
308 local_exclude_ip_map = lua_maps.map_schema:optional()
309 :doc({ summary = "Global map of IPs to exclude from all RBL checks" }),
310 default_enabled = T.boolean():optional()
311 :doc({ summary = "Default value for enabled option in rules" }),
312 default_ipv4 = T.boolean():optional()
313 :doc({ summary = "Default value for ipv4 option in rules" }),
314 default_ipv6 = T.boolean():optional()
315 :doc({ summary = "Default value for ipv6 option in rules" }),
316 default_unknown = T.boolean():optional()
317 :doc({ summary = "Default value for unknown option in rules" }),
318 default_dkim_domainonly = T.boolean():optional()
319 :doc({ summary = "Default value for dkim_domainonly option in rules" }),
320 default_emails_domainonly = T.boolean():optional()
321 :doc({ summary = "Default value for emails_domainonly option in rules" }),
322 default_exclude_users = T.boolean():optional()
323 :doc({ summary = "Default value for exclude_users option in rules" }),
324 default_exclude_local = T.boolean():optional()
325 :doc({ summary = "Default value for exclude_local option in rules" }),
326 default_no_ip = T.boolean():optional()
327 :doc({ summary = "Default value for no_ip option in rules" }),
328 default_dkim_match_from = T.boolean():optional()
329 :doc({ summary = "Default value for dkim_match_from option in rules" }),
330 default_selector_flatten = T.boolean():optional()
331 :doc({ summary = "Default value for selector_flatten option in rules" }),
332 default_received_flags = T.array(T.string()):optional()
333 :doc({ summary = "Default received flags for all rules" }),
334 default_received_nflags = T.array(T.string()):optional()
335 :doc({ summary = "Default received negative flags for all rules" }),
336 }, {
337 open = true,
338 extra = rule_schema:optional()
339 :doc({ summary = "RBL rule definition keyed by rule name" }),
340 }):doc({ summary = "RBL module configuration" })
341
342 PluginSchema.register("plugins.rbl.rule", rule_schema)
343 PluginSchema.register("plugins.rbl", plugin_schema)
344
345 return {
346 check_types = check_types,
347 rule_schema = rule_schema,
348 default_options = default_options,
349 convert_checks = convert_checks,
350 }