stoQ has a built-in plugin installation and upgrade capability. stoQ plugins may be packaged to allow for a simple and consistent installation process. Though packaging plugins isn’t a necessity, it is highly recommended to do so for simplicity and reproducibility.
Let’s take a look at a basic directory structure for a stoQ plugin:
|-- example_plugin/ | `-- setup.py | `-- MANIFEST.in | `-- requirements.txt | `-- example_plugin/ | `-- __init__.py | `-- example_plugin.py | `-- example_plugin.stoq
stoQ plugin packages leverage python’s packaging library, setuptools. When a plugin is installed,
pip is used for package management and installation. As such, all rules for both apply for stoQ
The setup.py file is a standard
include_package_data should always be set to
True to ensure the plugin configuration file and any additional files are properly installed.
from setuptools import setup, find_packages setup( name="example_plugin", version="3.0.0", author="Marcus LaFerrera (@mlaferrera)", url="https://github.com/PUNCH-Cyber/stoq-plugins-public", license="Apache License 2.0", description="Example stoQ plugin", packages=find_packages(), include_package_data=True, )
The manifest file ensure that the plugins
.stoq configuration file, and any other required
files, are installed alongside the plugin. More information on the
.stoq configuration file
can be found here.
If a requirements file exists, stoQ will install dependencies appropriately. They will not be installed along side the plugin, but rather in python’s system path. This file is not required if no additional dependencies need to be installed.
The subdirectory above,
example_plugin, is the primary plugin directory. This is the core location
for the stoQ plugin that will be installed into the stoQ plugin directory. The plugin module, along with
files identified in MANIFEST.in will be copied.
More information on writing a plugin can be found here.