Kesakode

Kesakode is a hash lookup service exclusive to Malcat users and tightly integrated inside Malcat’s UI (cf. Kesakode lookup). It can be used to match known functions, strings and constant sets against a database of known clean, malware and library files.

You can programmatically perform a kesakode lookup on the current analysed file by either:

  • accessing the Analysis.kesakode attribute (of type KesakodeResult), which will contain the most recent Kesakode lookup result. Initially, it will contain the Offline Kesakode results (albait not in headless mode, only when scripting from the UI), but will be overriden by any further online lookup

  • using the function Analysis.kesakode_lookup(). This is an on-demand analysis that will consume one token of your quota and return an instance of KesakodeResult, described below:

Global result

class malcat.KesakodeResult

This class contains the result of a Kesakode query for the current file.

Attributes

verdict: Dict[str, float]

The global verdict, a dictionnary that associate malware family names with their detection prbability. Example:

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
print(kesakode_result.verdict)

>> { 'Amadey': 100.0, 'ArtraDownloader': 0.23188406229019165, 'CryptoFortress': 0.05797101557254791, 'DarkStRAT': 0.05797101557254791 }
quota_left: int

How many kesakode calls you have left for this month

quota_total: int

How many kesakode calls you can make in a month

Methods

__iter__()

Iterate over all Kesakode function/string matches across the file. Note that the matches contains malware, lib and clean matches.

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
for m in kesakode_result:
    print(f"{m.type.name} match at {analysis.ppa(m.address)}: {m.hits}")

>> FUNCTION match at 0x00401cfc (sub_401cfc): [Level.MALWARE::Amadey (100.00%)]
>> STRING match at 0x004097b0 (.bss:17b0): [Level.MALWARE::Amadey (33.33%), Level.MALWARE::UFRStealer (16.67%), Level.MALWARE::Emotet (16.67%), Level.MALWARE::RokRAT (16.67%), Level.MALWARE::APT3Keylogger (16.67%)]
>> ...
Return type:

iterator over KesakodeMatch

__getitem__(interval)

Iterate over all Kesakode function/string matches contained in the interval (effective address). Note that the matches contains malware, lib and clean matches.

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
matches = list(kesakode_result[analysis.p2a(0) : analysis.p2a(0x5000)])
print("there are {} matches in range[#0-#5000[".format(len(matches)))
Parameters:

interval (slice) – effective address interval

Return type:

iterator over the list of matches (KesakodeMatch)

__getitem__(ea)

Returns the KesakodeMatch matching over the effective address ea.

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
ep_rva = analysis.struct['OptionalHeader']['AddressOfEntryPoint']
try:
    match = kesakode_result[ep_rva]
    print(f"Entry point has a {match.type.name} match: {match.hits}")
except KeyError:
    print("No match at entrypoint")
Parameters:

ea (int) – effective address

Return type:

KesakodeMatch

Raises:

KeyError if nothing matches over ea

__contains__(ea)

return True iff there exists a KesakodeMatch which contains the effective address ea

Parameters:

ea (int) – address to query

Return type:

bool

__len__()

return the number of KesakodeMatch instances

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
if len(kesakode_result) == 0:
    raise ValueError("No match!")
find(ea)

return the KesakodeMatch matching which starts at or contains the effective address ea, or None if no one can be found.

Parameters:

ea (int) – effective address for the query

Return type:

KesakodeMatch or None

find_forward(ea)

return the KesakodeMatch which starts at or contains the effective address ea or starts directly after ea, or None if no KesakodeMatch has matched beyond ea.

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
first_match = kesakode_result.find_forward(0)
if first_match is None:
    raise ValueError("No match in program!")
Parameters:

ea (int) – effective address for the query

Return type:

KesakodeMatch or None

find_backward(ea)

return the KesakodeMatch which starts at or contains the effective address ea or the first one that start before ea, or None if no KesakodeMatch has matched before ea.

kesakode_result = analysis.kesakode_lookup("AAAA-BBBB-CCCC-DDDD")
last_match = kesakode_result.find_backward(analysis.map.end)
if last_match is None:
    raise ValueError("No match in program!")
Parameters:

ea (int) – effective address for the query

Return type:

KesakodeMatch or None

Match & hits

A KesakodeMatch is a collection of one or more malcat.KesakodeMatch.Hit instances for a given function or string.

class malcat.KesakodeMatch

This class represents the collection of one or more KesakodeHit instances for a given function or string.

address: int (effective address)

the effective address of the function or string where the match did happen

size: int

the length of the function or string that did match

type: malcat.KesakodeMatch.Type

The type of object that did match at this address: malcat.KesakodeMatch.Type.FUNCTION or malcat.KesakodeMatch.Type.STRING

level: malcat.Detection.Level

In which Kesakode’s collection did the hit with the biggest score/probability happen, one of:

hits: List[malcat.KesakodeMatch.Hit]

The list of all malware/lib/clean hits for the given string/function

class malcat.KesakodeMatch.Hit

This class represents a single clean, lib or malware hit in Kesakode’s database for a KesakodeMatch instance.

level: malcat.Detection.Level

In which Kesakode’s collection did the hit happen, one of:

name: str

For malware hits, the name of the malware family, for lib hits, the name of the library. The empty string for clean hits.

score: float

The probability that this hit is the right one. The sum of all hits in a KesakodeMatch should sum up to 100%

symbol: str

For function, the (optional) name of the function as found in our database. This is usually only set for library functions, where the symbols are available.

class malcat.KesakodeMatch.Type
FUNCTION

A function was matched in Kesakode’s DB

STRING

A string was matched in Kesakode’s DB

class malcat.Detection.Level
CLEAN

This is a clean hit, i.e. it was found in Kesakode’s goodware collection (and not in the library collection)

LIBRARY

This is a library hit, i.e. it was found in Kesakode’s library collection

SUSPICIOUS

This is a near-malware hit, could be malware but not sure

MALWARE

This is a malware hit, i.e. it was found in Kesakode’s malware collection (and only in this one)