# Dispatcher¶

## Overview¶

stoQ provides for the ability to dispatch, or route, payloads to other plugins. This is done by leveraging yara to identify payloads that have certain characteristics and then automatically routing to specific plugins based on the results. Currently two plugin categories are supported for use with dispatching, extractor and carver.

## Usage¶

If dispatching is desired, simply start the worker with the -D command line argument. Ensure that your dispatcher.yar file contains the appropriate rules to properly route the payloads.

### Writing a Dispatcher Rule¶

Dispatching relies on yara and a set of rules to appropriately route payloads to their intended plugin. As with any yara rules, the strings and condition parameters are required, but dispatching also requires the meta attribute. Two keys, plugin and save are required within the meta attribute. The plugin key identifies the stoQ plugin category and plugin name (e.g., plugin = "carver:rtf") that should be loaded if the yara rule hits. It can contain multiple comma separated plugins that the payload should be dispatched to (e.g., plugin = "carver:rtf,decoder:b64"). There is no limit on how many plugins may be used for dispatching. The save key identifies whether content that is extracted or carved from the payload should be saved. Additionally, all of the meta values are passed to the specified plugin as **kwargs.

As an example, a stoQ dispatcher plugin that would identify RTF documents and then send the document to the RTF carver plugin would be written as:

rule rtf_file
{
meta:
plugin = "carver:rtf"
save = "True"
strings:
$rtf = "{\\rt" nocase condition:$rtf at 0
}


Results from the specified plugin are returned as a list() of sets(). Each unique object, or payload, that is extracted from the primary payload is assigned an incremental payload and a unique uuid. In version of stoQ prior to 0.9.38, a puuid key is also added to the results in order to identify the parent uuid the stream was extracted from. In stoQ version 0.9.38 and later, uuid is appended to a list for better tracking of parent child relationships. The results from the dispatcher are then appended to the primary results dict() and the key payloads is added with the total count of streams processed, to include the original payload.