| 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 |
} |