Skip to content

ScanTlsh

Compare file against a list of TLSH values. Output from this scanner implies matched file has TLSH value lower than defined threshold indicating a possible similar file to a known file. (e.g., Malware family)

Attributes:

Name Type Description
tlsh_rules

Dictionary of TLSH hashes and their associated families
Options

location: Location of the TLSH rules file. Defaults to '/etc/tlsh'. score: TLSH diff score. Defaults to 30.

Source code in strelka/src/python/strelka/scanners/scan_tlsh.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
class ScanTlsh(strelka.Scanner):
    """Compare file against a list of TLSH values.
    Output from this scanner implies matched file
    has TLSH value lower than defined threshold
    indicating a possible similar file to a known
    file. (e.g., Malware family)

    Attributes:
        tlsh_rules: Dictionary of TLSH hashes and their associated families

    Options:
        location: Location of the TLSH rules file.
            Defaults to '/etc/tlsh'.
        score: TLSH diff score.
            Defaults to 30.
    """

    def init(self):
        self.tlsh_rules = None

    def scan(self, data, file, options, expire_at):
        # Get the location of the TLSH rule files and the score threshold
        location = options.get("location", "/etc/strelka/tlsh/")
        score_threshold = options.get("score", 30)

        # Hash the data
        tlsh_file = tlsh.hash(data)

        # If the hash is "TNULL", add a flag and return
        if tlsh_file == "TNULL":
            return

        try:
            # If the TLSH rules have not been loaded yet, load them from the specified location
            if self.tlsh_rules is None:
                if os.path.isdir(location):
                    self.tlsh_rules = {}
                    # Load all YAML files in the directory recursively
                    for filepath in glob.iglob(f"{location}/**/*.yaml", recursive=True):
                        with open(filepath, "r") as tlsh_rules:
                            try:
                                self.tlsh_rules.update(
                                    yaml.safe_load(tlsh_rules.read())
                                )
                            except yaml.YAMLError:
                                self.flags.append(f"yaml_error: {filepath}")
                                return
                elif os.path.isfile(location):
                    with open(location, "r") as tlsh_rules:
                        self.tlsh_rules = yaml.safe_load(tlsh_rules.read())
                else:
                    self.flags.append("tlsh_location_not_found")
        except FileNotFoundError:
            self.flags.append("tlsh_files_not_found")

        # Initialize variables to store the family, score, and matched TLSH hash
        this_family = None
        this_score = score_threshold
        matched_tlsh_hash = None

        # Iterate over the TLSH rule hashes
        for family, tlsh_hashes in self.tlsh_rules.items():
            for tlsh_hash in tlsh_hashes:
                try:
                    # Calculate the difference score between the file hash and the rule hash
                    score = tlsh.diff(tlsh_file, tlsh_hash)
                except ValueError:
                    self.flags.append(f"bad_tlsh: {tlsh_hash}")
                    continue
                if score < score_threshold:
                    # If the score is less than the threshold, update matches
                    if score <= this_score:
                        this_family = family
                        this_score = score
                        matched_tlsh_hash = tlsh_hash

        if this_family:
            self.event["match"] = {
                "family": this_family,
                "score": this_score,
                "tlsh": matched_tlsh_hash,
            }

Features

The features of this scanner are detailed below. These features represent the capabilities and the type of analysis the scanner can perform. This may include support for Indicators of Compromise (IOC), the ability to emit files for further analysis, and the presence of extended documentation for complex analysis techniques.

Feature
Support
IOC Support
Emit Files
Extended Docs
Malware Scanner
Image Thumbnails

Tastes

Strelka's file distribution system assigns scanners to files based on 'flavors' and 'tastes'. Flavors describe the type of file, typically determined by MIME types from libmagic, matches from YARA rules, or characteristics of parent files. Tastes are the criteria used within Strelka to determine which scanners are applied to which files, with positive and negative tastes defining files to be included or excluded respectively.

Source Filetype
Include / Exclude
*

Scanner Fields

This section provides a list of fields that are extracted from the files processed by this scanner. These fields include the data elements that the scanner extracts from each file, representing the analytical results produced by the scanner. If the test file is missing or cannot be parsed, this section will not contain any data.

Field Name
Field Type
elapsed
str
flags
list
match
dict
match.family
str
match.score
int
match.tlsh
str

Sample Event

Below is a sample event generated by this scanner, demonstrating the kind of output that can be expected when it processes a file. This sample is derived from a mock scan event configured in the scanner's test file. If no test file is available, this section will not display a sample event.

    test_scan_event = {
        "elapsed": 0.001,
        "match": {
            "family": "TestMatchA",
            "score": 0,
            "tlsh": "T120957D477C8041A6C0AA9336896652D17B30BC991F2127D32F60F7F92F367E85E7931A",
        },
        "flags": [],
    }