Threat Bus features a plugin-based architecture. The following document describes the existing plugin types in detail and explains their responsibilities.
Threat Bus differentiates two plugin types. Application plugins are required to extend Threat Bus with new functionality. "Apps" in this context are security tools, like Zeek or VAST. Backbone plugins are required for the actual message passing. At least one backbone plugin is required for the bus to be functional. The most basic plugin for that job is the in-memory backbone.
Application plugins implement application specific logic. They have two main responsibilities. Foremost, application plugins have to handle all communication with the apps (e.g., with Zeek instances). Second, application plugins are responsible for message mapping.
Threat Bus dictates an internal message format. Backbones only work with that format (see below). Application plugins, on the other hand, have to map from and to the internal format from and to whatever format the subscribing apps require.
Let's discuss this on the example of the
Zeek plugin. It implements
broker, the Zeek Messaging Library, for Zeek
deployments to connect to. Threat Bus is entirely unaware of the
dependency. The plugin spawns an endpoint, capsules all communication logic and
only forwards (un)subscription requests to the Bus.
When Threat Bus becomes aware of new indicators of compromise (IoCs), it
forwards them to all subscribers of the
threatbus/intel topic. Typically, Zeek
is interested in IoCs for intel matching. It is the job of the Zeek plugin, to
map the Threat Bus internal
intel format to something that Zeek can
understand. In this case, that would be the
Zeek intel format.
Likewise, when new messages arrive from Zeek (i.e., sightings), the Zeek plugin has to map them to the Threat Bus internal format. Once mapped, messages are put to the global queue for incoming messages and will be picked up by the backbones.
Threat Bus itself is at no point involved with the entire Zeek/broker communication and does not know about any other format than its own internal format.
Backbone plugins implement the message provisioning logic. Whenever new
subscriptions come in, backbones get notified by Threat Bus. Every subscription
comes in the form of a
topic and a queue called
outq. The sole job of a
backbone is to read messages from the global queue of incoming messages (
and, based on the topic, sort those messages to the all the known
Apps and Wrappers
Threat Bus is a pub/sub broker, and hence applications have to subscribe themselves to the bus. However, that requires active behavior from applications, and hence could require changes to the source code. Generally speaking, that is undesirable.
Some applications, like Zeek, can be scripted. In that particular case, the logic for connecting to Threat Bus is implemented in a separate script.
Other applications, like VAST, cannot be scripted. Those applications require either a change to the source code or a wrapper script to initiate communication with Threat Bus. Please refer to the VAST wrapper script for an example.