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.