Debian Codegraph @

lualib/lua_scanners/metadefender.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 --[[[
18 -- @module metadefender
19 -- This module contains MetaDefender Cloud integration support for hash lookups
20 -- https://metadefender.opswat.com/
21 --]]
22
23 local lua_util = require "lua_util"
24 local http = require "rspamd_http"
25 local rspamd_cryptobox_hash = require "rspamd_cryptobox_hash"
26 local rspamd_logger = require "rspamd_logger"
27 local common = require "lua_scanners/common"
28
29 local N = 'metadefender'
30
31 local function metadefender_config(opts)
32 local default_conf = {
33 name = N,
34 url = 'https://api.metadefender.com/v4/hash',
35 timeout = 5.0,
36 log_clean = false,
37 retransmits = 1,
38 cache_expire = 7200, -- expire redis in 2h
39 message = '${SCANNER}: spam message found: "${VIRUS}"',
40 detection_category = "virus",
41 default_score = 1,
42 action = false,
43 scan_mime_parts = true,
44 scan_text_mime = false,
45 scan_image_mime = false,
46 apikey = nil, -- Required to set by user
47 -- Specific for metadefender
48 minimum_engines = 3, -- Minimum required to get scored
49 -- Threshold-based categorization
50 low_category = 5, -- Low threat: minimum_engines to low_category-1
51 medium_category = 10, -- Medium threat: low_category to medium_category-1
52 -- High threat: medium_category and above
53 -- Symbol categories
54 symbols = {
55 clean = {
56 symbol = 'METADEFENDER_CLEAN',
57 score = -0.5,
58 description = 'MetaDefender decided attachment to be clean'
59 },
60 low = {
61 symbol = 'METADEFENDER_LOW',
62 score = 2.0,
63 description = 'MetaDefender found low number of threats'
64 },
65 medium = {
66 symbol = 'METADEFENDER_MEDIUM',
67 score = 5.0,
68 description = 'MetaDefender found medium number of threats'
69 },
70 high = {
71 symbol = 'METADEFENDER_HIGH',
72 score = 8.0,
73 description = 'MetaDefender found high number of threats'
74 },
75 },
76 }
77
78 default_conf = lua_util.override_defaults(default_conf, opts)
79
80 if not default_conf.prefix then
81 default_conf.prefix = 'rs_' .. default_conf.name .. '_'
82 end
83
84 if not default_conf.log_prefix then
85 if default_conf.name:lower() == default_conf.type:lower() then
86 default_conf.log_prefix = default_conf.name
87 else
88 default_conf.log_prefix = default_conf.name .. ' (' .. default_conf.type .. ')'
89 end
90 end
91
92 if not default_conf.apikey then
93 rspamd_logger.errx(rspamd_config, 'no apikey defined for metadefender, disable checks')
94
95 return nil
96 end
97
98 lua_util.add_debug_alias('external_services', default_conf.name)
99 return default_conf
100 end
101
102 local function metadefender_check(task, content, digest, rule, maybe_part)
103 local function metadefender_check_uncached()
104 local function make_url(hash)
105 return string.format('%s/%s', rule.url, hash)
106 end
107
108 -- MetaDefender uses SHA256 hash
109 local hash = rspamd_cryptobox_hash.create_specific('sha256')
110 hash:update(content)
111 hash = hash:hex()
112
113 local url = make_url(hash)
114 lua_util.debugm(N, task, "send request %s", url)
115 local request_data = {
116 task = task,
117 url = url,
118 timeout = rule.timeout,
119 headers = {
120 ['apikey'] = rule.apikey,
121 }
122 }
123
124 local function md_http_callback(http_err, code, body, headers)
125 if http_err then
126 rspamd_logger.errx(task, 'HTTP error: %s, body: %s, headers: %s', http_err, body, headers)
127 task:insert_result(rule.symbol_fail, 1.0, 'HTTP error: ' .. http_err)
128 else
129 local cached
130 -- Parse the response
131 if code ~= 200 then
132 if code == 404 then
133 cached = 'OK'
134 if rule['log_clean'] then
135 rspamd_logger.infox(task, '%s: hash %s clean (not found)',
136 rule.log_prefix, hash)
137 else
138 lua_util.debugm(rule.name, task, '%s: hash %s clean (not found)',
139 rule.log_prefix, hash)
140 end
141 elseif code == 429 then
142 -- Request rate limit exceeded
143 rspamd_logger.infox(task, 'metadefender request rate limit exceeded')
144 task:insert_result(rule.symbol_fail, 1.0, 'rate limit exceeded')
145 return
146 else
147 rspamd_logger.errx(task, 'invalid HTTP code: %s, body: %s, headers: %s', code, body, headers)
148 task:insert_result(rule.symbol_fail, 1.0, 'Bad HTTP code: ' .. code)
149 return
150 end
151 else
152 local ucl = require "ucl"
153 local parser = ucl.parser()
154 local res, json_err = parser:parse_string(body)
155
156 lua_util.debugm(rule.name, task, '%s: got reply data: "%s"',
157 rule.log_prefix, body)
158
159 if res then
160 local obj = parser:get_object()
161
162 -- MetaDefender API response structure:
163 -- scan_results.scan_all_result_a: 'Clean', 'Infected', 'Suspicious'
164 -- scan_results.scan_all_result_i: numeric result (0=clean)
165 -- scan_results.total_detected_avs: number of engines detecting malware
166 -- scan_results.total_avs: total number of engines
167
168 if not obj.scan_results then
169 rspamd_logger.errx(task, 'invalid JSON reply: no scan_results field, body: %s', body)
170 task:insert_result(rule.symbol_fail, 1.0, 'Bad JSON reply: no scan_results')
171 return
172 end
173
174 local scan_results = obj.scan_results
175 local detected = scan_results.total_detected_avs or 0
176 local total = scan_results.total_avs or 0
177
178 if detected == 0 then
179 if rule['log_clean'] then
180 rspamd_logger.infox(task, '%s: hash %s clean',
181 rule.log_prefix, hash)
182 else
183 lua_util.debugm(rule.name, task, '%s: hash %s clean',
184 rule.log_prefix, hash)
185 end
186 -- Insert CLEAN symbol
187 if rule.symbols and rule.symbols.clean then
188 local clean_sym = rule.symbols.clean.symbol or 'METADEFENDER_CLEAN'
189 local sopt = string.format("%s:0/%s", hash, total)
190 task:insert_result(clean_sym, 1.0, sopt)
191 -- Save with symbol name for proper cache retrieval
192 cached = string.format("%s\v%s", clean_sym, sopt)
193 else
194 cached = 'OK'
195 end
196 else
197 if detected < rule.minimum_engines then
198 lua_util.debugm(rule.name, task, '%s: hash %s has not enough hits: %s where %s is min',
199 rule.log_prefix, hash, detected, rule.minimum_engines)
200 cached = 'OK'
201 else
202 -- Determine category based on detection count
203 local category
204 local category_sym
205 local sopt = string.format("%s:%s/%s", hash, detected, total)
206
207 if detected >= rule.medium_category then
208 category = 'high'
209 category_sym = rule.symbols.high.symbol or 'METADEFENDER_HIGH'
210 elseif detected >= rule.low_category then
211 category = 'medium'
212 category_sym = rule.symbols.medium.symbol or 'METADEFENDER_MEDIUM'
213 else
214 category = 'low'
215 category_sym = rule.symbols.low.symbol or 'METADEFENDER_LOW'
216 end
217
218 rspamd_logger.infox(task, '%s: result - %s: "%s" - category: %s',
219 rule.log_prefix, rule.detection_category .. 'found', sopt, category)
220
221 task:insert_result(category_sym, 1.0, sopt)
222 -- Save with symbol name for proper cache retrieval
223 cached = string.format("%s\v%s", category_sym, sopt)
224 end
225 end
226 else
227 -- not res
228 rspamd_logger.errx(task, 'invalid JSON reply: %s, body: %s, headers: %s',
229 json_err, body, headers)
230 task:insert_result(rule.symbol_fail, 1.0, 'Bad JSON reply: ' .. json_err)
231 return
232 end
233 end
234
235 if cached then
236 common.save_cache(task, digest, rule, cached, 1.0, maybe_part)
237 end
238 end
239 end
240
241 request_data.callback = md_http_callback
242 http.request(request_data)
243 end
244
245 if common.condition_check_and_continue(task, content, rule, digest,
246 metadefender_check_uncached) then
247 return
248 else
249 metadefender_check_uncached()
250 end
251 end
252
253 return {
254 type = 'antivirus',
255 description = 'MetaDefender Cloud integration',
256 configure = metadefender_config,
257 check = metadefender_check,
258 name = N
259 }