Usage

This section covers a brief walk-through of how to get started with Threat Bus. First you have to install Threat Bus and all plugins you need. Threat Bus uses a configuration file to specify global and plugin-specific settings.

Configuration

Once installed via pip, each plugin requires its own section in the Threat Bus configuration file. See the example below to understand the structure of the config file.

logging:
console: true
console_verbosity: DEBUG
file: false
file_verbosity: DEBUG
filename: threatbus.log
plugins:
backbones:
inmem:
apps:
zeek:
host: "127.0.0.1"
port: 47761
module_namespace: Tenzir # this setting is required for Zeek's messaging library `broker`
misp:
api:
host: https://localhost
ssl: false
key: <KEY>
zmq:
host: localhost
port: 50000

Logging Configuration

Logging is configured globally. The main application forwards the logging settings to all installed plugins. Logging is supported via colored console logs and via file.

Plugin Configuration

The plugin configuration either goes into the backbones or apps section, depending on the plugin type. The available options are defined by the specific plugin. See the documentation of the individual plugins for more details.

Start Up

Threat Bus requires a configuration file to start. Pass it via -c <file>:

venv/bin/threatbus -c config.yaml

Start Zeek as Threat Bus App

Apps need to register at the bus. Zeek can be scripted, and the relevant functionality is implemented in a Zeek script. To connect Zeek with Threat Bus, download and load the Zeek script as follows.

curl -L -o threatbus.zeek https://raw.githubusercontent.com/tenzir/threatbus/master/apps/zeek/threatbus.zeek
zeek -i <INTERFACE> -C threatbus.zeek

Start Zeek and Request an IOC Snapshot

Threat Bus allows apps to request snapshots of intelligence items from the past. The Zeek script implements the request functionality. Invoke it like this.

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

Use the Docker Container

Threat Bus can be used in a containerized setup. The pre-built docker image comes with all required dependencies and all existing plugins pre-installed.

docker run tenzir/threatbus:latest --help