Kesakode

Kesakode is a remote 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 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%

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

MALWARE

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