Static configuration extractor engine

Module interface

class malduck.extractor.Extractor(parent)

Base class for extractor modules

Following parameters need to be defined:

• family (see extractor.ExtractorBase.family)

• yara_rules

• overrides (optional, see extractor.ExtractorBase.overrides)

Example extractor code for Citadel:

from ripper import Extractor

class Citadel(Extractor):
    family = "citadel"
    yara_rules = ["citadel"]
    overrides = ["zeus"]

    @Extractor.extractor("briankerbs")
    def citadel_found(self, p, addr):
        log.info('[+] `Coded by Brian Krebs` str @ %X' % addr)
        return True

    @Extractor.extractor
    def cit_login(self, p, addr):
        log.info('[+] Found login_key xor @ %X' % addr)
        hit = p.uint32v(addr + 4)
        print(hex(hit))
        if p.is_addr(hit):
            return {'login_key': p.asciiz(hit)}

        hit = p.uint32v(addr + 5)
        print(hex(hit))
        if p.is_addr(hit):
            return {'login_key': p.asciiz(hit)}

@extractor

Decorator for string-based extractor methods. Method is called each time when string with the same identifier as method name has matched

Extractor can be called for many number-suffixed strings e.g. $keyex1 and $keyex2 will call keyex method.

@extractor(string_or_method, final=False)

Specialized @extractor variant

Parameters

• string_or_method (str) – If method name doesn’t match the string identifier pass yara string identifier as decorator argument

• final (bool) – Extractor will be called whenever Yara rule has been matched, but always after string-based extractors

@final

Decorator for final extractors, called after regular extraction methods.

from ripper import Extractor

class Evil(Extractor):
    yara_rules = ["evil"]
    family = "evil"

    ...

    @Extractor.needs_pe
    @Extractor.final
    def get_config(self, p):
        cfg = {"urls": self.get_cncs_from_rsrc(p)}
        if "role" not in self.collected_config:
            cfg["role"] = "loader"
        return cfg

@weak

Use this decorator for extractors when successful extraction is not sufficient to mark family as matched.

All “weak configs” will be flushed when “strong config” appears.

@needs_pe

Use this decorator for extractors that need PE instance. (malduck.procmem.ProcessMemoryPE)

@needs_elf

Use this decorator for extractors that need ELF instance. (malduck.procmem.ProcessMemoryELF)

property collected_config

Shows collected config so far (useful in “final” extractors)

Return type

dict

property globals

Container for global variables associated with analysis

Return type

dict

handle_yara(p, match)

Override this if you don’t want to use decorators and customize ripping process (e.g. yara-independent, brute-force techniques)

Parameters

• p (malduck.procmem.ProcessMemory) – ProcessMemory object

• match (List[malduck.yara.YaraMatch]) – Found yara matches for this family

property log

Logger instance for Extractor methods

Returns

logging.Logger

property matched

Returns True if family has been matched so far

Return type

bool

on_error(exc, method_name)

Handler for all Exception’s throwed by extractor methods.

Parameters

• exc (Exception) – Exception object

• method_name (str) – Name of method which throwed exception

push_config(config)

Push partial config (used by Extractor.handle_yara())

Parameters

config (dict) – Partial config element

push_procmem(procmem, **info)

Push procmem object for further analysis

Parameters

• procmem (malduck.procmem.ProcessMemory) – ProcessMemory object

• info – Additional info about object

yara_rules = ()

Names of Yara rules for which handle_yara is called

class malduck.extractor.ExtractManager(modules)

Multi-dump extraction context. Handles merging configs from different dumps, additional dropped families etc.

Parameters

modules (ExtractorModules) – Object with loaded extractor modules

property config

Extracted configuration (list of configs for each extracted family)

property extractors

Bound extractor modules :rtype: List[Type[malduck.extractor.Extractor]]

on_error(exc, extractor)

Handler for all Exception’s thrown by Extractor.handle_yara().

Deprecated since version 2.1.0: Look at ExtractManager.on_extractor_error() instead.

Parameters

• exc (Exception) – Exception object

• extractor (malduck.extractor.Extractor) – Extractor object which throwed exception

on_extractor_error(exc, extractor, method_name)

Handler for all Exception’s thrown by extractor methods (including Extractor.handle_yara()).

Override this method if you want to set your own error handler.

Parameters

• exc (Exception) – Exception object

• extractor (extractor.Extractor) – Extractor instance

• method_name (str) – Name of method which throwed exception

push_file(filepath, base=0)

Pushes file for extraction. Config extractor entrypoint.

Parameters

• filepath (str) – Path to extracted file

• base (int) – Memory dump base address

Returns

Family name if ripped successfully and provided better configuration than previous files. Returns None otherwise.

push_procmem(p, rip_binaries=False)

Pushes ProcessMemory object for extraction

Parameters

• p (malduck.procmem.ProcessMemory) – ProcessMemory object

• rip_binaries – Look for binaries (PE, ELF) in provided ProcessMemory and try to perform extraction using

specialized variants (ProcessMemoryPE, ProcessMemoryELF) :type rip_binaries: bool (default: False) :return: Family name if ripped successfully and provided better configuration than previous procmems.

Returns None otherwise.

property rules

Bound Yara rules :rtype: malduck.yara.Yara

class malduck.extractor.ExtractorModules(modules_path=None)

Configuration object with loaded Extractor modules for ExtractManager

Parameters

modules_path (str) – Path with module files (Extractor classes and Yara files, default ‘~/.malduck’)

on_error(exc, module_name)

Handler for all Exception’s throwed during module load

Override this method if you want to set your own error handler.

Parameters

• exc (Exception) – Exception object

• module_name (str) – Name of module which throwed exception

Internally used classes and routines

class malduck.extractor.extract_manager.ProcmemExtractManager(parent)

Single-dump extraction context (single family)

collected_config = None

Collected configuration so far (especially useful for “final” extractors)

property config

Returns collected config, but if family is not matched - returns empty dict. Family is not included in config itself, look at ProcmemExtractManager.family.

family = None

Matched family

on_extractor_error(exc, extractor, method_name)

Handler for all Exception’s throwed by extractor methods.

Parameters

• exc (Exception) – Exception object

• extractor (extractor.Extractor) – Extractor instance

• method_name (str) – Name of method which throwed exception

parent = None

Bound ExtractManager instance

push_config(config, extractor)

Pushes new partial config

If strong config provides different family than stored so far and that family overrides stored family - set stored family Example: citadel overrides zeus

Parameters

• config (dict) – Partial config object

• extractor (malduck.extractor.Extractor) – Extractor object reference

push_procmem(p, _matches=None)

Pushes ProcessMemory object for extraction

Parameters

• p (malduck.procmem.ProcessMemory) – ProcessMemory object

• _matches (malduck.yara.YaraMatches) – YaraMatches object (used internally)

class malduck.extractor.extractor.ExtractorBase(parent)

property collected_config

Shows collected config so far (useful in “final” extractors)

Return type

dict

family = None

Extracted malware family, automatically added to “family” key for strong extraction methods

property globals

Container for global variables associated with analysis

Return type

dict

property log

Logger instance for Extractor methods

Returns

logging.Logger

property matched

Returns True if family has been matched so far

Return type

bool

overrides = []

Family match overrides another match e.g. citadel overrides zeus

parent = None

ProcmemExtractManager instance

push_config(config)

Push partial config (used by Extractor.handle_yara())

Parameters

config (dict) – Partial config element

push_procmem(procmem, **info)

Push procmem object for further analysis

Parameters

• procmem (malduck.procmem.ProcessMemory) – ProcessMemory object

• info – Additional info about object

class malduck.extractor.extractor.MetaExtractor

Metaclass for Extractor. Handles proper registration of decorated extraction methods