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 instatiated 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()

Wrapper for yapsy.PluginManager.collectPlugins()

deactivate_plugin(name, category)

Deactivate a plugin within a specific category

Parameters:
  • name (str) – Name of plugin to deactivate
  • category (str) – Category of the named plugin
get_all_plugin_names()

List all plugin names

Returns:All plugin names
Return type:list
get_all_plugins()

Wrapper for yapsy.PluginManager.getAllPlugins()

get_categories()

Wrapper for yapsy.PluginManager.getCategories()

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_plugin_names_of_category(category)

Lists plugin name of a specific category

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

Wrapper for yapsy.PluginManager.getPluginsOfCategory()

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

class stoq.plugins.StoqWorkerPlugin

stoQ Worker Plugin Class

activate(options=None)

Activate the plugin within the framework

Parameters:options (dict) – argparse options
Returns:The worker plugin object
Return type:object
load_carver(carver)

Load an carver plugin

Parameters:carver (str) – The name of carver plugin to be loaded
Returns:True
load_connector(connector)

Load a connector plugin

Parameters:connector (str) – The name of connector plugin to be loaded
Returns:True
load_decoder(decoder)

Load an decoder plugin

Parameters:decoder (str) – The name of decoder plugin to be loaded
Returns:True
load_extractor(extractor)

Load an extractor plugin

Parameters:extractor (str) – The name of extractor plugin to be loaded
Returns:True
load_reader(reader)

Load a reader plugin

Parameters:reader (str) – The name of reader plugin to be loaded
Returns:True
load_source(source)

Load a source plugin

Parameters:source (str) – The name of source plugin to be loaded
Returns:True
load_worker(worker)

Load a worker plugin from another worker plugin

Parameters:worker (str) – The name of worker plugin to be loaded
Returns:True
run()

Run the plugin with a source plugin, or standalone

save_payload(payload, connector)

Save a payload using the designated connector

Parameters:
  • payload (bytes) – Payload to pass to the connector for saving
  • connector (str) – Connector plugin to save the payload with
start(payload=None, **kwargs)

Process the payload with the worker plugin

Parameters:
  • payload (bytes) – (optional) Payload to be processed
  • archive (str) – Connector plugin to use as a source for the payload
  • uuid (str/list) – UUID for this result, and any parent results
  • filename (str) – File name, if available, for the payload
  • path (str) – Path the file is being ingested from
Returns:

Tuple of JSON results and template rendered results

Return type:

dict and str or lists

yara_dispatcher(payload, **kwargs)

Determine if a payload needs additional processing to extract or carve content from a payload

Parameters:payload (bytes) – Payload to be processed
Returns:Set of metadata and content from plugin
Return type:Generator