Packaging Plugins¶
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
plugins.
setup.py¶
The setup.py file is a standard setuptools
script. 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="2.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,
)
MANIFEST.in¶
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.
include example_plugin/*.stoq
requirements.txt¶
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.
plugin subdirectory¶
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.
Examples¶
There are plenty of examples for packaging plugin in stoQ’s public plugin repository.