DEV IN PROGRESS

Module pychrysalide.plugins

Class PluginModule

Module pychrysalide.plugins

Documentation

This module provides features to deal with plugins: the definitions required to build new Python plugins as well as the functions suitable to interact with existing plugins.

The module is also the place for all plugins without another home.

Sub modules

Classes

Methods

get_all_plugins()

Provide the list of all loaded plugins.

The returned value is a tuple of PluginModule instances.

get_all_plugins_for_action(action)

Provide the list of all loaded plugins suitable for a given action.

The action has to be one of the PluginAction values.

The returned value is a tuple of matching PluginModule instances.

get_plugin_by_name(name)

Find a given plugin from the list of loaded plugins.

The name string define the target to find.

The returned value is a tuple of the found PluginModule instance and its value, or None in case of search failure.

Class PluginModule

PythonModule is the class allowing the creation of Chrysalide plugins for Python.

Calls to the __init__ constructor of this abstract object expect no particular argument.

Several items have to be defined as class attributes in the final class:

  • _name: a string providing a small name for the plugin;
  • _desc: a string for a human readable description of the plugin;
  • _version: a string providing the version of the plugin;
  • _url: a string for the homepage describing the plugin;
  • _actions: a tuple of PluginAction defining the features the plugin is bringing; this list can be empty.

Depending on the implemented actions, some of the following methods have to be defined for new classes:

Hierarchy

builtins.object
 ╰── gi._gi.GObject
      ╰── pychrysalide.plugins.PluginModule

Methods

_attach_debug_format(self, action, format)

Abstract method called when a debugger is attached to a binary format.

The expected action is a PluginAction value and the provided format is a ExeFormat instance.

This method has to be defined in order to handle action such as FORMAT_ATTACH_DEBUG.

_detect_external_tools(self, action, content, version)

Abstract method called when a detection of tools used the build the analyzed content is required.

The expected action is a PluginAction value and the content is a LoadedContent instance. The version parameter is a boolean value indicating if some extra details about the tools version are wished.

The expected result is a list of strings.

This method has to be defined in order to handle action such as DETECTION_OBFUSCATORS.

_get_modname(self)

(Abstract) method providing the raw module name of the plugin.

loaded.

The result should be a short string value.

A default implementation builds the module name from the Python script filename.

_handle_binary_content(self, action, content, wid, status)

Abstract method used to explore a binary content (and possibly to add new contents to explore) or to load a recognized binary content into a LoadedContent instance.

The expected action is a PluginAction value and the initial binary content is a BinContent instance. A tracking identifier is provided and is aimed to be used with methods from ContentExplorer and ContentResolver. A reference to the main status bar may also be provided, as a StatusStack instance if running in graphical mode or None otherwise.

This method has to be defined in order to handle actions such as CONTENT_EXPLORER or CONTENT_RESOLVER.

_handle_binary_format_analysis(self, action, format, gid, status)

Abstract method run at several different steps of a binary format analysis:

  • at the beginning and at the end of the main analysis pass;
  • at the beginning and at the end of the extra final pass.

The expected action is a PluginAction value and the provided format is a KnownFormat instance. The identifier refers to the working queue used to process the analysis. A reference to the main status bar may also be provided, as a StatusStack instance if running in graphical mode or None otherwise.

This method has to be defined in order to handle actions such as FORMAT_ANALYSIS_STARTED, FORMAT_ANALYSIS_ENDED, FORMAT_POST_ANALYSIS_STARTED or FORMAT_POST_ANALYSIS_ENDED.

_handle_loaded_content(self, action, content, gid, status)

Abstract method run once a loaded binary has been analyzed with success.

The expected action is a PluginAction value and the analyzed content is a LoadedContent instance. The identifier refers to the working queue used to process the analysis. A reference to the main status bar may also be provided, as a StatusStack instance if running in graphical mode or None otherwise.

This method has to be defined in order to handle action such as CONTENT_ANALYZED.

_manage(self, action)

Abstract method called to react to several steps of the plugin life.

The expected action is a PluginAction value.

This method has to be defined in order to handle actions such as PLUGIN_LOADED.

_notify_plugins_loaded(self, action)

Abstract method called once all the (native?) plugins are loaded.

The expected action is a PluginAction value.

This method has to be defined in order to handle actions such as NATIVE_PLUGINS_LOADED or PLUGINS_LOADED.

_preload_binary_format(self, action, format, info, status)

Abstract method which is an opportunity to setup instructions or comments ahead of the disassembling process.

Format fields do not need to get disassembled and may be annotated for instance.

The expected action is a PluginAction value and the provided format is a BinFormat instance. The information holder to fill is a PreloadInfo instance. A reference to the main status bar may also be provided, as a StatusStack instance if running in graphical mode or None otherwise.

This method has to be defined in order to handle action such as FORMAT_PRELOAD.

_process_disassembly_event(self, action, format)

Abstract method run at several different steps of a binary analysis.

The expected action is a PluginAction value and the provided format is a ExeFormat instance.

This method has to be defined in order to handle actions such as DISASSEMBLY_STARTED, DISASSEMBLY_RAW, DISASSEMBLY_HOOKED_LINK, DISASSEMBLY_HOOKED_POST, DISASSEMBLY_LIMITED, DISASSEMBLY_LOOPS, DISASSEMBLY_LINKED, DISASSEMBLY_GROUPED, DISASSEMBLY_RANKED, DISASSEMBLY_ENDED.

build_config_filename(final, create=False)

Build a filename suitable for the plugin configuration, ending with the final suffix.

If the create parameter is set, the path to this filename is created.

The result is a string or None on failure.

log_message(type, msg)

Display a message in the log window, in graphical mode, or in the console output if none.

The type of the message has to be a LogMessageType value.

The only difference with the main log_message() function is that messages are automatically prefixed with the plugin name here.

Attributes

config

Dedicated configuration for the plugin.

The value is a GenConfig instance or None if the configuration is not yet created.

As configuration storage path depends on the plugin name, all plugin properties have to get fully loaded by the core before the configuration can be setup.automatically

filename

Filename of the plugin.

interface

Interface exported by the plugin..

This property is a StructObject instance.

The provided information is composed of the following properties :

  • gtp_name;
  • name;
  • desc;
  • version;
  • url;
  • container;
  • required;
  • actions.

The gtp_name value may be None for non-native plugin. All other fields carry a string value except:

  • container: a boolean status indicating if the plugin can embed other plugins;
  • required: a tuple of depedencies names;
  • actions: a tuple of available features from the plugin coded as PluginAction values.

modname

Raw module name of the plugin.

Constants

PluginAction

Features with which plugins can extend the core of Chrysalide.

0= 0x0
65536= 0x10000
65537= 0x10001
65538= 0x10002
131072= 0x20000
131073= 0x20001
131074= 0x20002
16777216= 0x1000000
16842752= 0x1010000
16842753= 0x1010001
33554432= 0x2000000
33554433= 0x2000001
33554434= 0x2000002
33619968= 0x2010000
33619969= 0x2010001
33619970= 0x2010002
33619971= 0x2010003
33619972= 0x2010004
33619973= 0x2010005
33685504= 0x2020000
33685505= 0x2020001
33685506= 0x2020002
33685507= 0x2020003
33685508= 0x2020004
33685509= 0x2020005
33685510= 0x2020006
33685511= 0x2020007
33685512= 0x2020008
33685513= 0x2020009
33751040= 0x2030000