Package: threatbus-zmq
Threat Bus App Plugin for ZMQ ProtocolA Threat Bus plugin that enables communication with any application that can
communicate via [ZeroMQ].Installationpipinstallthreatbus-zmqConfigurationThe plugin uses ZeroMQ to communicate with applications, likevast-threatbus.
The plugin serves three ZeroMQ endpoints to connect with. One endpoint for
managing subscriptions (and thus snapshot requests). The other two endpoints
exist for pub-sub operations....plugins:zmq:host:"127.0.0.1"manage:13370pub:13371sub:13372...Initially, apps that want to connect with this plugin only need to know themanageendpoint. The plugin and the app negotiate all other internals for
pub-sub message exchange at runtime. See the protocol definition below for
details.Management ProtocolSubscriptions and unsubscriptions are referred to asmanagement. All
management messages are JSON formatted and exchanged via themanageZMQ
endpoint that the plugin exposes.The manage endpoint uses theZeroMQ Request/Replypattern for message exchange. That means, all messages get an immediate response
from the server. With each JSON reply, the zmq Threat Bus plugin sends astatusfield that indicates the success of the requested operation.Subscribe at the PluginTo subscribe to Threat Bus via the zmq plugin, an app needs to send a JSON
struct as follows to themanageendpoint of the plugin:{
  "action": "subscribe",
  "topic": <TOPIC>,       # either 'threatbus/sighting' or 'threatbus/intel'
  "snapshot": <SNAPSHOT>  # number of days for a snapshot, 0 for no snapshot
}In response, the app will either receive asuccessorerrorresponse.Error response:{
  "status": "error"
}Success response:{
  "topic": <P2P_TOPIC>,
  "pub_port": 13371,
  "sub_port": 13372,
  "status": "success",
}Thepub_portandsub_portof the reply provide the port that an app should
connect with to participate in the pub/sub message exchange. A connecting app
can access these ports following theZeroMQ Pub/Subpattern. The plugin will publish messages on thepub_portand accept
messages on thesub_port.Thetopicfield of the response contains a unique topic for the client. That
topicmustbe used to receive messages. The unique topic is a 32 characters
wide random string and guarantees that other subscribers won't accidentally
see traffic that should only be visible to the new client.For more details see below atPub/Sub via ZeroMQ.Unsubscribe from the PluginTo unsubscribe, a connected app has to send a JSON struct to themanageendpoint of the plugin, as follows:{
  "action": "unsubscribe",
  "topic": <P2P_TOPIC>       # the 32-characters random topic that the app got during subscription handshake
}In response, the app will either receive asuccessorerrorresponse.Error response:{
  "status": "error"
}Success response:{
  "status": "success"
}HeartbeatsThe plugin supports synchronous heartbeats from subscribed apps. Both, Threat
Bus and the connected apps benefit from heartbeats, they can mutually ensure
that the connected party is still alive.Subscribed apps can send heartbeat messages with the following JSON format to
themanageendpoint of this plugin:{
  "action": "heartbeat",
  "topic": <P2P_TOPIC>       # the 32-characters random topic that the app got during subscription handshake
}As stated in the beginning of this section, themanageendpoint implements theZeroMQ Request/Replypattern. Threat Bus answers immediately to each heartbeat request with either asuccessorerrorresponse.Error response:{
  "status": "error"
}Success response:{
  "status": "success"
}Anerrorresponse indicates that either Threat Bus has internal errors or that
it lost track of the app's subscription. Note: This only happens when Threat Bus
is restarted. Apps can then use that information to re-subscribe.If Threat Bus does not answer a heartbeat message, it is either down or not
reachable (e.g., due to network issues). Plugins can use that information to try
again later.Pub/Sub via ZeroMQOnce an app has subscribed to a certain Threat Bus topic using themanageendpoint of the zmq plugin, it gets a unique, randomp2p_topic(see
above). Thep2p_topicdiffers from the subscribed Threat Bus topic. The
zmq plugin uses only thep2p_topicto publish messages to subscribers.
Messages are either STIX-2 Indicators and Sightings or are of the types
specified inthreatbus.data,
i.e.,SnapshotRequest, andSnapshotEnvelope.ZeroMQ usesprefix matchingfor pub/sub
connections. The zmq plugin leverages this feature to indicate the type of
each sent message to the subscriber. Hence, an app can simply match the topic
suffix to determine the message type.For example, all STIX-2 Indicators will always be sent on the topicp2p_topic + "indicator", all messages of the typethreatbus.data.SnapshotRequeston the topicp2p_topic + "snapshotrequest"and so forth.SnapshotsThreat Bus'snapshotfeature allows apps to request a snapshot during subscription. Threat Bus always
forwards snapshot requests to all app plugins. Thezmqplugin again
forwards theseSnapshotRequeststo all connected apps. Apps, however, can
decide if they want to implement this feature, i.e., whether they respond toSnapshotRequestmessages or not.SnapshotRequestsare received like any other messages, via thep2p_topic. In
case the app wants to provide this feature, it must handle message of this type
(see above for an explanation of topic suffix matching).Once the snapshot is handled, the app must use theSnapshotEnvelopemessage
type to send back messages to the plugin.LicenseThreat Bus comes with a3-clause BSD license.