Threat Bus features a plugin-based architecture. The following document describes the existing plugin types in detail and explains their responsibilities.

Plugin Types

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

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 broker 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

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 (inq) and, based on the topic, sort those messages to the all the known outqs.

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.