Zeek Plugin

The Threat Bus Zeek plugin enables communication with the Zeek network monitor. The plugin handles all communication with Zeek via the "Zeek Messaging Library" Broker.

The Zeek plugin converts IoCs from the STIX-2 Indicator format to Broker events and forwards them to subscribed Zeek instances. The conversion happens on a best-effort basis. When Zeek instances encounter an indicator match, they send a Broker message to the Threat Bus Zeek plugin that converts it to a valid STIX-2 Sighting.

Lossy Conversion

The Zeek Intel Framework only supports point-indicators, i.e., IoCs with only a single value like an IP address or domain name. The STIX-2 standard can express more complex, compound IoCs—these cannot be expressed with Zeek intelligence items.

The plugin makes the following deployment assumptions:

  1. Zeek instances that subscribe via the plugin's Broker endpoint must use the threatbus.zeek script.
  2. Subscribing Zeek instances have the Intelligence Framework loaded and enabled so they can match IoCs.

Installation

The plugin uses the Broker python bindings for native interaction with Zeek. Broker and the Python bindings need to be installed on the Threat Bus host system to use this plugin. Please consult the official Broker documentation for installation instructions.

Zeek/Broker Compatibility

If you install Zeek and Broker manually, you must ensure that the installed versions are compatible with each other. Version incompatibilities can lead to silent errors.

Check the Broker releases page on GitHub for compatibility with Zeek.

Once the prerequisites are met, install the Zeek plugin via pip.

pip install threatbus-zeek

Configuration

The plugin starts a listening Broker endpoint. The endpoint characteristics for listening can be configure as follows.

...
plugins:
apps:
zeek:
host: "127.0.0.1"
port: 47761
module_namespace: Tenzir
...

The last parameter module_namespace: Tenzir is required for Zeek's messaging library Broker. This namespace is set in the threatbus.zeek script.

Threat Bus Zeek Script

Threat Bus is a pub/sub broker for security content. Applications like Zeek have to register themselves at the bus. Zeek cannot communicate with Threat Bus out of the box, so we provide a Zeek script threatbus.zeek in the Threat Bus GitHub repository.

The script equips Zeek with the capability to communicate with Threat Bus, including the un/subscription management and the conversion logic between Broker events and indicators & sightings. The script installs an event hook in Zeek that triggers on intelligence matches. Should these matches be related to IoCs that originate from Threat Bus, a proper sighting is generated and sent back.

Users can configure the script via CLI options. See the following list of all available options:

Option NameDefault ValueExplanation
broker_host"127.0.0.1"IP address of the Threat Bus host running the Zeek plugin. For the plugin's configuration see the Threat Bus config.yaml file.
broker_port47761/tcpPort of the Zeek plugin's Broker endpoint. For the plugin's configuration see the Threat Bus config.yaml file.
report_sightingsTToggle to report back sightings to Threat Bus.
noisy_intel_threshold100The number of matches per second an intel item must exceed before we report it as "noisy".
log_operationsTToggle to enable/disable logging.
intel_topic"stix2/indicator"The Threat Bus topic to subscribe for IoC updates.
sighting_topic"stix2/sighting"The Threat Bus topic to report sightings to.
management_topic"threatbus/manage"A Broker topic, used for internal negotiations between Zeek instances and the Threat Bus Zeek plugin.
snapshot_intel0 secUser-defined interval to request a snapshot of historic indicators.

To set options of the Zeek script via CLI invoke it as follows:

zeek -i <INTERFACE> -C ./apps/zeek/threatbus.zeek "Tenzir::snapshot_intel=30 days"