Plugin Development

This page provides a simply overview of the steps necessary for plugin development. We recommend to use a virtual environment for all development activities.

Clone the Threat Bus project, setup a virtual env, and install threatbus and some plugins with the in development mode:

git clone https://github.com/tenzir/threatbus.git
cd threatbus
virtualenv venv
source venv/bin/activate
make dev-mode

Configuration & Extension

A plugin must define a setup.py. Whenever a plugin is installed, you have to add a corresponding configuration section to threatbus' config.yaml. That section has to be named after the name in the entry-point declaration of the plugin's setup.py file.

Please adhere to the plugin naming conventions proposed by pluggy and always prefix your plugin name with threatbus-.

Plugins can either be apps or backbones. Application plugins add new functionality to threatbus and allow communication to a threat-intelligence-enabled app (e.g., Zeek or Suricata). Backbone plugins add a new storage and distribution backend to threatbus (e.g., in-memory or Kafka).

Consider the following example setup:

  • Plugin folder structure:
    plugins
    ├── apps
    | └── threatbus-myapp
    │ ├── setup.py
    | └── threatbus_myapp.py
    └── backbones
    └── threatbus-mybackbone
    ├── setup.py
    └── threatbus_mybackbone.py
  • The setup.py file for a new plugin call myapp
    from setuptools import setup
    setup(
    name="threatbus-myapp",
    install_requires="threatbus",
    entry_points={"threatbus.app": ["myapp = threatbus_myapp"]},
    package_dir={"": "plugins/apps"},
    packages=["threatbus_myapp"],,
    )
  • The corresponding config.yaml entry for the new plugin
    ...
    plugins:
    apps:
    myapp:
    some-property: some-value

Implementation Specs

Plugin specifications are defined in the threatbus/appspecs.py and threatbus/backbonespecs.py files, respectively. For any plugin, you should at least implement the run function.