StoqPluginManager

Overview

StoqPluginManager() is the primary class that controls all aspects of plugin management to include initialization, loading, listing, and unloading. This class is instantiated within the Stoq() class. This should not be instantiated outside of stoQ as it relies on objects within Stoq() to function properly.

Note

Full plugin development documentation can be found at Plugin Development.

Examples

Instantiate Stoq:

from stoq.core import Stoq
stoq = Stoq()

Listing all available plugins:

stoq.list_plugins()

Once Stoq() is initialized, we can load a worker. The worker should always be instantiated first, then any additional plugins may be loaded through the worker plugin itself. The plugins will be instantiated within a dict in the worker plugin class. For example, a stoQ connector plugin may be accessed from it’s plural name (connectors) within the worker object by calling worker.connectors or a reader plugin may be called with worker.readers:

worker = stoq.load_plugin("yara", "worker")
worker.load_connector("file")
payload = worker.connectors['file'].get_file(path="/tmp/bad.exe")
results = worker.scan(payload)

We may also retrieve a payload from a connector, such as MongoDB:

worker.load_connector("mongodb")
file_hash = "da39a3ee5e6b4b0d3255bfef95601890afd80709"
payload = worker.connectors['mongodb'].get_file(sha1=file_hash)
results = worker.scan(payload)

Note

Only certain connector plugins support .get_file(**kwargs). Refer to the plugin to determine if it is supported or not.

Now that we have results, we can load our connector to save the results:

worker.connectors['mongodb'].save(results)

We may also save a file via the connector. In this example, we will save a payload to with some additional attributes to GridFS:

payload_attributes = {}
payload_attributes['md5'] = "d41d8cd98f00b204e9800998ecf8427e"
payload_attributes['sha1'] = "da39a3ee5e6b4b0d3255bfef95601890afd80709"
payload_attributes['sha256'] = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
worker.connectors['mongodb'].save(payload, archive=True, payload_attributes)

Note

save() accepts **kwargs, so one may pass any attribute that is needed to it. GridFS will automatically calculate the payload size and datetime uploaded.

API

class stoq.plugins.StoqPluginManager

stoQ Plugin Manager Class

collect_plugins()

Find all stoQ plugins and their configuration file

get_all_plugin_names

List all plugin names

Returns:All plugin names Return type:list

get_all_plugins

List all valid plugins and configurations

Returns:All valid plugins Return type:dict

get_categories

Create list of plugin categories available

get_plugin(name, category)

Initializes a plugin within a specific category

Parameters:

• name (str) – Name of plugin to get
• category (str) – Category of the named plugin

Returns:

plugin object

Return type:

object

get_plugins_of_category(category)

Lists plugin name of a specific category

Parameters:category (str) – Category to discover plugins in Returns:A tuple of discovered plugins Return type:tuple

list_plugins()

List all available plugins and their category

load_plugin(name, category)

Load the desired plugin

Parameters:

• name (str) – Plugin name to be loaded
• category (str) – The category of plugin to be loaded

Returns:

The loaded plugin object

Return type:

object