Decorator Plugins

Overview

Decorator plugins are the last plugins run just before saving results. This plugin class allows for the analysis of all results from each plugin, the original payload, and any extracted payloads. Multiple decorator plugins can be loaded, but each plugin is only passed the results once. Decorator plugins are extremely useful when post-processing is required of the collective results from the entire stoQ workflow.

Decorator plugins can be defined multiple ways. In these examples, we will use the test_decorator decorator plugin.

From stoq.cfg:

[core]
decorators = test_decorator

Note

Multiple plugins can be defined separated by a comma.

From the command line:

$ stoq run -D yara [...]

Note

Multiple plugins can be defined by simply adding the plugin name

Or, when instantiating the Stoq() class:

>>> import stoq
>>> decorators = ['test_decorator']
>>> s = Stoq(decorators=decorators, [...])

Writing a plugin

A decorator plugin must be a subclass of the DecoratorPlugin class. Results from a decorator are appended to the final StoqResponse object.

As with any plugin, a configuration file must also exist and be properly configured.

Example

from typing import Dict, Optional
from configparser import ConfigParser

from stoq.data_classes import StoqResponse, DecoratorResponse
from stoq.plugins import DecoratorPlugin


class ExampleDecorator(DecoratorPlugin):
    def __init__(self, config: ConfigParser, plugin_opts: Optional[Dict]) -> None:
        super().__init__(config, plugin_opts)
        self.msg = config.get('options', 'msg', fallback='do_more msg')

    def decorate(self, response: StoqResponse) -> Optional[DecoratorResponse]:
        do_more = False
        if 'yara' in response.results[0].plugins_run:
            do_more = True
        dr = DecoratorResponse({'do_more': do_more, 'msg': self.msg})
        return dr

API

class stoq.plugins.decorator.DecoratorPlugin(config, plugin_opts)

decorate(response)

Return type:Optional[DecoratorResponse]

Response

class stoq.data_classes.DecoratorResponse(results=None, errors=None)

Object containing response from decorator plugins

Parameters:

• results (Optional[Dict[~KT, ~VT]]) – Results from decorator plugin
• errors (Optional[List[str]]) – Errors that occurred

>>> results = {'decorator_key': 'decorator_value'}
>>> errors = ['This plugin failed for a reason']
>>> response = DecoratorResponse(results=results, errors=errors)