Debian Codegraph @

lualib/lua_scanners/oletools.lua

raw
1 --[[
2 Copyright (c) 2022, Vsevolod Stakhov <[email protected]>
3 Copyright (c) 2018, Carsten Rosenberg <[email protected]>
4
5 Licensed under the Apache License, Version 2.0 (the "License");
6 you may not use this file except in compliance with the License.
7 You may obtain a copy of the License at
8
9 http://www.apache.org/licenses/LICENSE-2.0
10
11 Unless required by applicable law or agreed to in writing, software
12 distributed under the License is distributed on an "AS IS" BASIS,
13 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 See the License for the specific language governing permissions and
15 limitations under the License.
16 ]]--
17
18 --[[[
19 -- @module oletools
20 -- This module contains oletools access functions.
21 -- Olefy is needed: https://github.com/HeinleinSupport/olefy
22 --]]
23
24 local lua_util = require "lua_util"
25 local tcp = require "rspamd_tcp"
26 local upstream_list = require "rspamd_upstream_list"
27 local rspamd_logger = require "rspamd_logger"
28 local ucl = require "ucl"
29 local common = require "lua_scanners/common"
30
31 local N = 'oletools'
32
33 local function oletools_config(opts)
34
35 local oletools_conf = {
36 name = N,
37 scan_mime_parts = true,
38 scan_text_mime = false,
39 scan_image_mime = false,
40 default_port = 10050,
41 timeout = 15.0,
42 log_clean = false,
43 retransmits = 2,
44 cache_expire = 86400, -- expire redis in 1d
45 min_size = 500,
46 symbol = "OLETOOLS",
47 message = '${SCANNER}: Oletools threat message found: "${VIRUS}"',
48 detection_category = "office macro",
49 default_score = 1,
50 action = false,
51 extended = false,
52 symbol_type = 'postfilter',
53 dynamic_scan = true,
54 }
55
56 oletools_conf = lua_util.override_defaults(oletools_conf, opts)
57
58 if not oletools_conf.prefix then
59 oletools_conf.prefix = 'rs_' .. oletools_conf.name .. '_'
60 end
61
62 if not oletools_conf.log_prefix then
63 if oletools_conf.name:lower() == oletools_conf.type:lower() then
64 oletools_conf.log_prefix = oletools_conf.name
65 else
66 oletools_conf.log_prefix = oletools_conf.name .. ' (' .. oletools_conf.type .. ')'
67 end
68 end
69
70 if not oletools_conf.servers then
71 rspamd_logger.errx(rspamd_config, 'no servers defined')
72
73 return nil
74 end
75
76 oletools_conf.upstreams = upstream_list.create(rspamd_config,
77 oletools_conf.servers,
78 oletools_conf.default_port)
79
80 if oletools_conf.upstreams then
81 lua_util.add_debug_alias('external_services', oletools_conf.name)
82 return oletools_conf
83 end
84
85 rspamd_logger.errx(rspamd_config, 'cannot parse servers %s',
86 oletools_conf.servers)
87 return nil
88 end
89
90 local function oletools_check(task, content, digest, rule, maybe_part)
91 local function oletools_check_uncached ()
92 local upstream = rule.upstreams:get_upstream_round_robin()
93 local addr = upstream:get_addr()
94 local retransmits = rule.retransmits
95 local protocol = 'OLEFY/1.0\nMethod: oletools\nRspamd-ID: ' .. task:get_uid() .. '\n\n'
96 local json_response = ""
97
98 local function oletools_callback(err, data, conn)
99
100 local function oletools_requery(error)
101
102 -- retry with another upstream until retransmits exceeds
103 if retransmits > 0 then
104
105 retransmits = retransmits - 1
106
107 -- Select a different upstream!
108 upstream = rule.upstreams:get_upstream_round_robin()
109 addr = upstream:get_addr()
110
111 lua_util.debugm(rule.name, task, '%s: error: %s; retry IP: %s; retries left: %s',
112 rule.log_prefix, err, addr, retransmits)
113
114 tcp.request({
115 task = task,
116 host = addr:to_string(),
117 port = addr:get_port(),
118 upstream = upstream,
119 timeout = rule.timeout,
120 shutdown = true,
121 data = { protocol, content },
122 callback = oletools_callback,
123 })
124 else
125 rspamd_logger.errx(task, '%s: failed to scan, maximum retransmits ' ..
126 'exceed - err: %s', rule.log_prefix, error)
127 common.yield_result(task, rule,
128 'failed to scan, maximum retransmits exceed - err: ' .. error,
129 0.0, 'fail', maybe_part)
130 end
131 end
132
133 if err then
134
135 oletools_requery(err)
136
137 else
138 json_response = json_response .. tostring(data)
139
140 if not string.find(json_response, '\t\n\n\t') and #data == 8192 then
141 lua_util.debugm(rule.name, task, '%s: no stop word: add_read - #json: %s / current packet: %s',
142 rule.log_prefix, #json_response, #data)
143 conn:add_read(oletools_callback)
144
145 else
146 local ucl_parser = ucl.parser()
147 local ok, ucl_err = ucl_parser:parse_string(tostring(json_response))
148 if not ok then
149 rspamd_logger.errx(task, "%s: error parsing json response, retry: %s",
150 rule.log_prefix, ucl_err)
151 oletools_requery(ucl_err)
152 return
153 end
154
155 local result = ucl_parser:get_object()
156
157 local oletools_rc = {
158 [0] = 'RETURN_OK',
159 [1] = 'RETURN_WARNINGS',
160 [2] = 'RETURN_WRONG_ARGS',
161 [3] = 'RETURN_FILE_NOT_FOUND',
162 [4] = 'RETURN_XGLOB_ERR',
163 [5] = 'RETURN_OPEN_ERROR',
164 [6] = 'RETURN_PARSE_ERROR',
165 [7] = 'RETURN_SEVERAL_ERRS',
166 [8] = 'RETURN_UNEXPECTED',
167 [9] = 'RETURN_ENCRYPTED',
168 }
169
170 -- M=Macros, A=Auto-executable, S=Suspicious keywords, I=IOCs,
171 -- H=Hex strings, B=Base64 strings, D=Dridex strings, V=VBA strings
172 -- Keep sorted to avoid dragons
173 local analysis_cat_table = {
174 autoexec = '-',
175 base64 = '-',
176 dridex = '-',
177 hex = '-',
178 iocs = '-',
179 macro_exist = '-',
180 suspicious = '-',
181 vba = '-'
182 }
183 local analysis_keyword_table = {}
184
185 for _, v in ipairs(result) do
186
187 if v.error ~= nil and v.type ~= 'error' then
188 -- olefy, not oletools error
189 rspamd_logger.errx(task, '%s: ERROR found: %s', rule.log_prefix,
190 v.error)
191 if v.error == 'File too small' then
192 common.save_cache(task, digest, rule, 'OK', 1.0, maybe_part)
193 common.log_clean(task, rule, 'File too small to be scanned for macros')
194 return
195 else
196 oletools_requery(v.error)
197 end
198
199 elseif tostring(v.type) == "MetaInformation" and v.version ~= nil then
200 -- if MetaInformation section - check and print script and version
201
202 lua_util.debugm(N, task, '%s: version: %s %s', rule.log_prefix,
203 tostring(v.script_name), tostring(v.version))
204
205 elseif tostring(v.type) == "MetaInformation" and v.return_code ~= nil then
206 -- if MetaInformation section - check return_code
207
208 local oletools_rc_code = tonumber(v.return_code)
209 if oletools_rc_code == 9 then
210 rspamd_logger.warnx(task, '%s: File is encrypted.', rule.log_prefix)
211 common.yield_result(task, rule,
212 'failed - err: ' .. oletools_rc[oletools_rc_code],
213 0.0, 'encrypted', maybe_part)
214 common.save_cache(task, digest, rule, 'encrypted', 1.0, maybe_part)
215 return
216 elseif oletools_rc_code == 5 then
217 rspamd_logger.warnx(task, '%s: olefy could not open the file - error: %s', rule.log_prefix,
218 result[2]['message'])
219 common.yield_result(task, rule,
220 'failed - err: ' .. oletools_rc[oletools_rc_code],
221 0.0, 'fail', maybe_part)
222 return
223 elseif oletools_rc_code > 6 then
224 rspamd_logger.errx(task, '%s: MetaInfo section error code: %s',
225 rule.log_prefix, oletools_rc[oletools_rc_code])
226 rspamd_logger.errx(task, '%s: MetaInfo section message: %s',
227 rule.log_prefix, result[2]['message'])
228 common.yield_result(task, rule,
229 'failed - err: ' .. oletools_rc[oletools_rc_code],
230 0.0, 'fail', maybe_part)
231 return
232 elseif oletools_rc_code > 1 then
233 rspamd_logger.errx(task, '%s: Error message: %s',
234 rule.log_prefix, result[2]['message'])
235 oletools_requery(oletools_rc[oletools_rc_code])
236 end
237
238 elseif tostring(v.type) == "error" then
239 -- error section found - check message
240 rspamd_logger.errx(task, '%s: Error section error code: %s',
241 rule.log_prefix, v.error)
242 rspamd_logger.errx(task, '%s: Error section message: %s',
243 rule.log_prefix, v.message)
244 --common.yield_result(task, rule, 'failed - err: ' .. v.error, 0.0, 'fail')
245
246 elseif type(v.analysis) == 'table' and type(v.macros) == 'table' then
247 -- analysis + macro found - evaluate response
248
249 if type(v.analysis) == 'table' and #v.analysis == 0 and #v.macros == 0 then
250 rspamd_logger.warnx(task, '%s: maybe unhandled python or oletools error', rule.log_prefix)
251 oletools_requery('oletools unhandled error')
252
253 elseif #v.macros > 0 then
254
255 analysis_cat_table.macro_exist = 'M'
256
257 lua_util.debugm(rule.name, task,
258 '%s: filename: %s', rule.log_prefix, result[2]['file'])
259 lua_util.debugm(rule.name, task,
260 '%s: type: %s', rule.log_prefix, result[2]['type'])
261
262 for _, m in ipairs(v.macros) do
263 lua_util.debugm(rule.name, task, '%s: macros found - code: %s, ole_stream: %s, ' ..
264 'vba_filename: %s', rule.log_prefix, m.code, m.ole_stream, m.vba_filename)
265 end
266
267 for _, a in ipairs(v.analysis) do
268 lua_util.debugm(rule.name, task, '%s: threat found - type: %s, keyword: %s, ' ..
269 'description: %s', rule.log_prefix, a.type, a.keyword, a.description)
270 if a.type == 'AutoExec' then
271 analysis_cat_table.autoexec = 'A'
272 table.insert(analysis_keyword_table, a.keyword)
273 elseif a.type == 'Suspicious' then
274 if rule.extended == true or
275 (a.keyword ~= 'Base64 Strings' and a.keyword ~= 'Hex Strings')
276 then
277 analysis_cat_table.suspicious = 'S'
278 table.insert(analysis_keyword_table, a.keyword)
279 end
280 elseif a.type == 'IOC' then
281 analysis_cat_table.iocs = 'I'
282 elseif a.type == 'Hex strings' then
283 analysis_cat_table.hex = 'H'
284 elseif a.type == 'Base64 strings' then
285 analysis_cat_table.base64 = 'B'
286 elseif a.type == 'Dridex strings' then
287 analysis_cat_table.dridex = 'D'
288 elseif a.type == 'VBA strings' then
289 analysis_cat_table.vba = 'V'
290 end
291 end
292 end
293 end
294 end
295
296 lua_util.debugm(N, task, '%s: analysis_keyword_table: %s', rule.log_prefix, analysis_keyword_table)
297 lua_util.debugm(N, task, '%s: analysis_cat_table: %s', rule.log_prefix, analysis_cat_table)
298
299 if rule.extended == false and analysis_cat_table.autoexec == 'A' and analysis_cat_table.suspicious == 'S' then
300 -- use single string as virus name
301 local threat = 'AutoExec + Suspicious (' .. table.concat(analysis_keyword_table, ',') .. ')'
302 lua_util.debugm(rule.name, task, '%s: threat result: %s', rule.log_prefix, threat)
303 common.yield_result(task, rule, threat, rule.default_score, nil, maybe_part)
304 common.save_cache(task, digest, rule, threat, rule.default_score, maybe_part)
305
306 elseif rule.extended == true and #analysis_keyword_table > 0 then
307 -- report any flags (types) and any most keywords as individual virus name
308 local analysis_cat_table_values_sorted = {}
309
310 -- see https://github.com/rspamd/rspamd/commit/6bd3e2b9f49d1de3ab882aeca9c30bc7d526ac9d#commitcomment-40130493
311 -- for details
312 local analysis_cat_table_keys_sorted = lua_util.keys(analysis_cat_table)
313 table.sort(analysis_cat_table_keys_sorted)
314
315 for _, v in ipairs(analysis_cat_table_keys_sorted) do
316 table.insert(analysis_cat_table_values_sorted, analysis_cat_table[v])
317 end
318
319 table.insert(analysis_keyword_table, 1, table.concat(analysis_cat_table_values_sorted))
320
321 lua_util.debugm(rule.name, task, '%s: extended threat result: %s',
322 rule.log_prefix, table.concat(analysis_keyword_table, ','))
323
324 common.yield_result(task, rule, analysis_keyword_table,
325 rule.default_score, nil, maybe_part)
326 common.save_cache(task, digest, rule, analysis_keyword_table,
327 rule.default_score, maybe_part)
328
329 elseif analysis_cat_table.macro_exist == '-' and #analysis_keyword_table == 0 then
330 common.save_cache(task, digest, rule, 'OK', 1.0, maybe_part)
331 common.log_clean(task, rule, 'No macro found')
332
333 else
334 common.save_cache(task, digest, rule, 'OK', 1.0, maybe_part)
335 common.log_clean(task, rule, 'Scanned Macro is OK')
336 end
337 end
338 end
339 end
340
341 tcp.request({
342 task = task,
343 host = addr:to_string(),
344 port = addr:get_port(),
345 upstream = upstream,
346 timeout = rule.timeout,
347 shutdown = true,
348 data = { protocol, content },
349 callback = oletools_callback,
350 })
351
352 end
353
354 if common.condition_check_and_continue(task, content, rule, digest,
355 oletools_check_uncached, maybe_part) then
356 return
357 else
358 oletools_check_uncached()
359 end
360
361 end
362
363 return {
364 type = { N, 'attachment scanner', 'hash', 'scanner' },
365 description = 'oletools office macro scanner',
366 configure = oletools_config,
367 check = oletools_check,
368 name = N
369 }