Debian Codegraph @

lualib/lua_url_filter.lua

raw
1 --[[
2 Copyright (c) 2025, 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 ---@module lua_url_filter
18 -- Fast URL validation during parsing - called from C
19 -- URLs passed as rspamd_text for efficient processing
20
21 local exports = {}
22 local rspamd_util = require "rspamd_util"
23
24 -- Filter result constants
25 exports.ACCEPT = 0
26 exports.SUSPICIOUS = 1
27 exports.REJECT = 2
28
29 -- Custom filters (user can add their own)
30 local custom_filters = {}
31
32 ---
33 -- Register a custom URL filter
34 -- @param filter_func function(url_text, flags) -> result
35 function exports.register_filter(filter_func)
36 table.insert(custom_filters, filter_func)
37 end
38
39 ---
40 -- Clear all custom filters (mainly for testing)
41 function exports.clear_filters()
42 custom_filters = {}
43 end
44
45 ---
46 -- Main entry point called from C during URL parsing
47 -- @param url_text rspamd_text - URL string as text object
48 -- @param flags number - URL parsing flags
49 -- @return number - ACCEPT/SUSPICIOUS/REJECT
50 function exports.filter_url_string(url_text, flags)
51 -- Sanity check: URL length
52 local url_len = url_text:len()
53 if url_len > 2048 then
54 return exports.REJECT -- Overly long URL
55 end
56
57 -- Build control character set: 0x00-0x08, 0x0B-0x1F, 0x7F
58 -- (excluding \t=0x09 and \n=0x0A)
59 local control_chars = "\000\001\002\003\004\005\006\007\008" .. -- 0x00-0x08
60 "\011\012\013\014\015\016\017\018\019\020" .. -- 0x0B-0x14
61 "\021\022\023\024\025\026\027\028\029\030\031" .. -- 0x15-0x1F
62 "\127" -- 0x7F (DEL)
63
64 -- Check for control characters using memcspn
65 local span = url_text:memcspn(control_chars)
66 if span < url_len then
67 return exports.REJECT -- Control character found
68 end
69
70 -- UTF-8 validation (rspamd_util.is_valid_utf8 accepts both text and string)
71 if not rspamd_util.is_valid_utf8(url_text) then
72 return exports.REJECT -- Invalid UTF-8
73 end
74
75 -- Count @ signs and check user field using rspamd_text methods only
76 local at_count = 0
77 local first_at_pos = nil
78 local search_from = 1
79
80 -- Count @ signs using memchr
81 while search_from <= url_len do
82 local substr = url_text:sub(search_from)
83 local found = substr:memchr(string.byte('@'), false)
84
85 if not found or found == -1 then
86 break
87 end
88
89 at_count = at_count + 1
90 -- Adjust found position to be relative to start of url_text
91 local absolute_pos = search_from + found - 1
92 -- Defensive check: ensure position is within bounds (should always be true due to url_len check)
93 if absolute_pos > url_len then
94 return exports.REJECT -- Position overflow, should not happen
95 end
96 if at_count == 1 then
97 first_at_pos = absolute_pos
98 end
99 search_from = absolute_pos + 1 -- Move past the @ we just found
100
101 if at_count > 20 then
102 return exports.REJECT -- Way too many @ signs
103 end
104 end
105
106 -- Check user field length (if @ present)
107 if first_at_pos then
108 -- Find :// to determine start of user field
109 local schema_pos = url_text:find("://")
110 local user_start = schema_pos and (schema_pos + 3) or 1
111 local user_len = first_at_pos - user_start
112
113 if user_len > 512 then
114 return exports.REJECT -- Extremely long user field
115 elseif user_len > 64 then
116 return exports.SUSPICIOUS -- Long user field, mark for inspection
117 end
118
119 -- Multiple @ signs is suspicious
120 if at_count > 1 then
121 return exports.SUSPICIOUS
122 end
123 end
124
125 -- Run custom filters
126 for _, filter in ipairs(custom_filters) do
127 local result = filter(url_text, flags)
128 if result == exports.REJECT then
129 return exports.REJECT -- First filter to reject wins
130 end
131 -- Note: SUSPICIOUS results don't immediately return; we continue checking
132 -- other filters as one might REJECT (upgrade), but we won't downgrade to ACCEPT
133 end
134
135 return exports.ACCEPT
136 end
137
138 ---
139 -- Filter URL object (called from Lua plugin context)
140 -- @param url userdata - URL object
141 -- @return number - ACCEPT/SUSPICIOUS/REJECT
142 function exports.filter_url(url)
143 if not url then
144 return exports.ACCEPT
145 end
146
147 -- Get URL as rspamd_text (pass true to get_text)
148 local url_text = url:get_text(true)
149 if not url_text then
150 return exports.ACCEPT
151 end
152
153 -- Get flags directly from URL object (no table conversion)
154 local flags = url:get_flags_num() or 0
155
156 return exports.filter_url_string(url_text, flags)
157 end
158
159 return exports