Debian Codegraph @

lualib/lua_fuzzy_html.lua

raw
1 --[[
2 HTML Fuzzy Hashing Helper Module
3
4 This module provides helper functions for HTML fuzzy hash matching
5 and phishing detection based on HTML structure vs. content mismatches.
6
7 Use case: Detect phishing where HTML structure matches legitimate emails
8 but CTA (Call-To-Action) domains are different.
9 ]]
10
11 local exports = {}
12 local lua_util = require "lua_util"
13
14 --[[
15 Analyze fuzzy results to detect potential phishing based on:
16 - Text content fuzzy match (high score)
17 - HTML structure fuzzy match (high score)
18 - But HTML CTA domains differ from known legitimate
19
20 Returns: phishing_score, explanation
21 ]]
22 exports.check_html_text_mismatch = function(task, fuzzy_results)
23 local html_matches = {}
24 local text_matches = {}
25
26 -- Separate HTML and text fuzzy matches
27 for _, res in ipairs(fuzzy_results or {}) do
28 if res.type == 'html' then
29 table.insert(html_matches, res)
30 elseif res.type == 'txt' then
31 table.insert(text_matches, res)
32 end
33 end
34
35 -- Phishing scenario: high text match but low/no HTML match
36 if #text_matches > 0 and #html_matches == 0 then
37 local max_text_score = 0
38 for _, res in ipairs(text_matches) do
39 if res.score > max_text_score then
40 max_text_score = res.score
41 end
42 end
43
44 -- High text match but no HTML match = suspicious
45 if max_text_score > 0.7 then
46 return max_text_score * 0.5, string.format(
47 "Text fuzzy match (%.2f) without HTML match - possible CTA substitution",
48 max_text_score)
49 end
50 end
51
52 -- Inverse scenario: HTML match but no text match
53 -- (Could be template with varying content - less suspicious)
54 if #html_matches > 0 and #text_matches == 0 then
55 local max_html_score = 0
56 for _, res in ipairs(html_matches) do
57 if res.score > max_html_score then
58 max_html_score = res.score
59 end
60 end
61
62 -- This is expected for newsletters/notifications
63 lua_util.debugm('fuzzy_html', task,
64 'HTML match (%.2f) without text match - likely template variation',
65 max_html_score)
66 end
67
68 return 0, nil
69 end
70
71 --[[
72 Check if message has suspicious HTML fuzzy pattern:
73 - Known legitimate HTML structure
74 - But text content is different or manipulated
75 - Useful for brand protection
76
77 Example: Amazon email template with phishing text
78 ]]
79 exports.check_brand_hijack = function(task, html_fuzzy_result, text_fuzzy_result)
80 if not html_fuzzy_result then
81 return 0, nil
82 end
83
84 -- High HTML match = known template
85 if html_fuzzy_result.score > 0.8 then
86 -- Check if text is suspicious
87 if not text_fuzzy_result or text_fuzzy_result.score < 0.3 then
88 return html_fuzzy_result.score * 0.6,
89 string.format("Known HTML template (%.2f) with unfamiliar text - possible brand hijacking",
90 html_fuzzy_result.score)
91 end
92 end
93
94 return 0, nil
95 end
96
97 return exports