Package: threatbus
Threat BusA threat intelligence dissemination layer for open-source security tools.Getting Started—Contributing Guidelines—Writing Plugins—License—DocumentationKey FeaturesConnect Open-Source Security Tools: Threat Bus is a pub-sub broker for
threat intelligence data. WithThreat Busyou can seamlessly integrate
threat intel platforms likeOpenCTIorMISPwith detection
tools and databases likeZeekorVAST.Native STIX-2: Threat Bus transports indicators and sightings encoded as
per theSTIX-2open format specification.Plugin-based Architecture: The project is plugin-based and can be extended
easily. Read about the differentplugin typesandhow to write your own.
We welcome contributions to adopt new open source tools!Official Plugins: We maintain many plugins right in the official Threat
Bus repository. Check out our integrations forMISP,Zeek,CIFv3, and generally apps that connect viaZeroMQ, likevast-threatbusand ourOpenCTI connector.Snapshotting: The snapshot feature allows subscribers to directly request
threat intelligence data for a certain time range from other applications.
Threat Bus handles the point-to-point communication of all involved apps.Getting StartedTheconfig.yaml.examplefile provides a working configuration for Threat Bus
with all existing application plugins enabled together with the RabbitMQ
backbone.The following example shows how to connectZeekvia Threat Bus. There
are more integrations available, so make sure to check out allThreat Bus projects on PyPI.The example assumes thatthreatbusis available in your PATH. See the
section onInstallationbelow for more information on how to
get there.Start Threat BusthreatbusStart with a specially named config fileTheconfig.yaml.examplefile in this directory gives an overview of
the available config keys and their default values.threatbus-c/path/to/your/special-config.yamlEnvironment variables take precedence over config file values. Prefix
everything withTHREATBUS_exportTHREATBUS_LOGGING__CONSOLE=truethreatbus-c/path/to/your/special-config.yamlNote that you must use a double underscores__in your env to refer to nested
config variables.Start Zeek as Threat Bus appzeek-i<INTERFACE>-C./apps/zeek/threatbus.zeekStart Zeek and request a snapshotzeek-i<INTERFACE>-C./apps/zeek/threatbus.zeek"Tenzir::snapshot_intel=30 days"Threat Bus also ships as pre-built Docker image and is available onDocker Hub.Use the Threat Bus Docker containerdockerruntenzir/threatbus:latest--helpStart Threat Bus container with a custom config filedockerrun-p47661:47661-v$PWD/my-custom-config.yaml:/opt/tenzir/threatbus/my-custom-config.yamltenzir/threatbus:latest-cmy-custom-config.yamlTip: Threat Bus checks for config files with default names. If you mount your
config file to/opt/tenzir/threatbus/config.yaml, you can start the
application without specifying the config file location with the-cparameter.InstallationInstallthreatbusand all plugins that you require. Optionally, use a virtual
environment.Note that Threat Bus requires at least Python 3.7+, earlier versions are not supported.virtualenv venv                       # optional
source venv/bin/activate              # optional
pip install threatbus
pip install threatbus-inmem           # inmemory backbone plugin
pip install threatbus-rabbitmq        # RabbitMQ backbone plugin
pip install threatbus-misp[zmq]       # MISP application plugin
pip install threatbus-zeek            # Zeek application plugin
pip install threatbus-zmq             # ZeroMQ application plugin
pip install threatbus-<plugin_name>TestingUse theMakefileto run unit and integration tests.make unit-tests
make integration-testsThe integration tests require a localZeekandDockerinstallation.DevelopmentSetup a virtual environment and installthreatbusand some plugins with the
in development mode:virtualenv venv
source venv/bin/activate
make dev-modeConfiguration & ExtensionA plugin must define asetup.py. Whenever a plugin is installed, you have to
add a corresponding configuration section tothreatbus'config.yaml. That
section has to be named after thenamein the entrypoint declaration of the
plugin'ssetup.pyfile.Please adhere to theplugin naming conventionsand always prefix your plugin name withthreatbus-.Plugins can either beappsorbackbones. Application plugins (apps) add new
functionality to Threat Bus and allow communication to a specific app and/or
via a specific protocol (e.g., ZeroMQ or Zeek/broker). Backbone plugins add a
new storage and distribution backend to Threat Bus (e.g., in-memory or
RabbitMQ).Example:plugin folder structure:plugins
├──apps|└──threatbus-myapp
│├──setup.py|└──threatbus_myapp.py
└──backbones└──threatbus-inmem├──setup.py└──threatbus_inmem.pysetup.pyfromsetuptoolsimportsetupsetup(name="threatbus-myapp",install_requires="threatbus",entry_points={"threatbus.app":["myapp = threatbus_myapp"]},py_modules=["threatbus_myapp"],)config.yamlentry forthreatbus...plugins:apps:myapp:...Threat Bus APIPlugins specifications are available inthreatbus/appspecs.pyandthreatbus/backbonespecs.py, respectively. For any plugin, you should at least
implement therunfunction.App plugins are provided two callback functions to use for subscription
management. Internally, Threat Bus will propagate subscription requests to all
installed backbone plugins.The subscription callback allows applications to request an optional snapshot
time delta. Threat Bus will forward snapshot requests to all those apps that
have implemented the snapshot feature (seethreatbus/appspecs.py).ImplementationPlease use theStoppableWorkerbase class to model your plugin's busy work. Plugins should never block the main
thread of the application. Implementing that class also facilitates a graceful
shutdown.All officially maintained Threat Bus plugins implementStoppableWorker. Refer
to any of the existing plugins for an example.LicenseThreat Bus comes with a3-clause BSD license.