# 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 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

  online_lookup(license, endpoint='https://cloud.malcat.fr', ssl_verify=True)

    Performs an online Kesakode lookup query on the current file and get the result back. Consumes one token. Note that you need to specify the license key since Malcat may not know your license key (e.g. if activated using Offline activation). The result is returned and will be available via the `kesakode` attribute.

    Parameters:

      - license (str) – your Malcat license key, or your special keskakode key if you’ve got one with more quota.

      - endpoint (str) – which Kesakode endpoint to use

      - ssl_verify (bool) – enforce SSL certificate validity. Set this to false if your company does HTTPS mitm.

    Returns:

      the Kesakode lookup result: global verdict and function/strings match details

    Return type:

      malcat.KesakodeResult

## 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:

    - `malcat.Detection.Level.CLEAN`

    - `malcat.Detection.Level.LIBRARY`

    - `malcat.Detection.Level.MALWARE`

  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:

    - `malcat.Detection.Level.CLEAN`

    - `malcat.Detection.Level.LIBRARY`

    - `malcat.Detection.Level.SUSPICIOUS`

    - `malcat.Detection.Level.MALWARE`

  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)