base/frameworks/broker/main.bro

Broker
Log

Various data structure definitions for use with Bro’s communication system.

Namespaces:Broker, Log
Imports:base/bif/comm.bif.bro, base/bif/messaging.bif.bro
Source File:/scripts/base/frameworks/broker/main.bro

Summary

Options

Broker::endpoint_name: string &redef A name used to identify this endpoint to peers.

Types

Broker::Data: record Opaque communication data.
Broker::DataVector: vector Opaque communication data.
Broker::EndpointFlags: record Change communication behavior.
Broker::EventArgs: record Opaque event communication data.
Broker::SendFlags: record Fine-grained tuning of communication behavior for a particular message.
Broker::TableItem: record Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.
Log::ID: enum Type that defines an ID unique to each log stream.

Functions

Broker::auto_event: function Automatically send an event to any interested peers whenever it is locally dispatched (e.g.
Broker::auto_event_stop: function Stop automatically sending an event to peers upon local dispatch.
Broker::connect: function Initiate a remote connection.
Broker::disable_remote_logs: function Disable remote logs for a given log stream.
Broker::disconnect: function Remove a remote connection.
Broker::enable: function Enable use of communication.
Broker::enable_remote_logs: function Enable remote logs for a given log stream.
Broker::listen: function Listen for remote connections.
Broker::publish_topic: function Allow sending messages to peers if associated with the given topic.
Broker::remote_logs_enabled: function Check if remote logs are enabled for a given log stream.
Broker::send_event: function Send an event to any interested peers.
Broker::send_print: function Print a simple message to any interested peers.
Broker::set_endpoint_flags: function Changes endpoint flags originally supplied to Broker::enable.
Broker::subscribe_to_events: function Register interest in all peer event messages that use a certain topic prefix.
Broker::subscribe_to_logs: function Register interest in all peer log messages that use a certain topic prefix.
Broker::subscribe_to_prints: function Register interest in all peer print messages that use a certain topic prefix.
Broker::unpublish_topic: function Disallow sending messages to peers if associated with the given topic.
Broker::unsubscribe_to_events: function Unregister interest in all peer event messages that use a topic prefix.
Broker::unsubscribe_to_logs: function Unregister interest in all peer log messages that use a topic prefix.
Broker::unsubscribe_to_prints: function Unregister interest in all peer print messages that use a topic prefix.

Detailed Interface

Options

Broker::endpoint_name
Type:string
Attributes:&redef
Default:""

A name used to identify this endpoint to peers.

See also: Broker::connect, Broker::listen

Types

Broker::Data
Type:

record

d: opaque of Broker::Data &optional

Opaque communication data.

Broker::DataVector
Type:vector of Broker::Data

Opaque communication data.

Broker::EndpointFlags
Type:

record

auto_publish: bool &default = T &optional

Whether to restrict message topics that can be published to peers.

auto_advertise: bool &default = T &optional

Whether to restrict what message topics or data store identifiers the local endpoint advertises to peers (e.g. subscribing to events or making a master data store available).

Change communication behavior.

Broker::EventArgs
Type:

record

name: string &optional

The name of the event. Not set if invalid event or arguments.

args: Broker::DataVector

The arguments to the event.

Opaque event communication data.

Broker::SendFlags
Type:

record

self: bool &default = F &optional

Send the message to the local endpoint.

peers: bool &default = T &optional

Send the message to peer endpoints that advertise interest in the topic associated with the message.

unsolicited: bool &default = F &optional

Send the message to peer endpoints even if they don’t advertise interest in the topic associated with the message.

Fine-grained tuning of communication behavior for a particular message.

Broker::TableItem
Type:

record

key: Broker::Data

val: Broker::Data

Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.

Log::ID
Type:

enum

Log::UNKNOWN

Dummy place-holder.

Files::LOG

(present if base/frameworks/files/main.bro is loaded)

Logging stream for file analysis.

Reporter::LOG

(present if base/frameworks/reporter/main.bro is loaded)

Notice::LOG

(present if base/frameworks/notice/main.bro is loaded)

This is the primary logging stream for notices.

Notice::ALARM_LOG

(present if base/frameworks/notice/main.bro is loaded)

This is the alarm stream.

Weird::LOG

(present if base/frameworks/notice/weird.bro is loaded)

NetControl::LOG

(present if base/frameworks/netcontrol/main.bro is loaded)

OpenFlow::LOG

(present if base/frameworks/openflow/plugins/log.bro is loaded)

Cluster::LOG

(present if base/frameworks/cluster/main.bro is loaded)

NetControl::DROP

(present if base/frameworks/netcontrol/types.bro is loaded)

Stop forwarding all packets matching the entity.

No additional arguments.

NetControl::SHUNT

(present if base/frameworks/netcontrol/shunt.bro is loaded)

NetControl::CATCH_RELEASE

(present if base/frameworks/netcontrol/catch-and-release.bro is loaded)

DPD::LOG

(present if base/frameworks/dpd/main.bro is loaded)

Signatures::LOG

(present if base/frameworks/signatures/main.bro is loaded)

PacketFilter::LOG

(present if base/frameworks/packet-filter/main.bro is loaded)

Software::LOG

(present if base/frameworks/software/main.bro is loaded)

Communication::LOG

(present if base/frameworks/communication/main.bro is loaded)

Intel::LOG

(present if base/frameworks/intel/main.bro is loaded)

Tunnel::LOG

(present if base/frameworks/tunnels/main.bro is loaded)

Conn::LOG

(present if base/protocols/conn/main.bro is loaded)

DCE_RPC::LOG

(present if base/protocols/dce-rpc/main.bro is loaded)

DHCP::LOG

(present if base/protocols/dhcp/main.bro is loaded)

DNP3::LOG

(present if base/protocols/dnp3/main.bro is loaded)

DNS::LOG

(present if base/protocols/dns/main.bro is loaded)

FTP::LOG

(present if base/protocols/ftp/main.bro is loaded)

SSL::LOG

(present if base/protocols/ssl/main.bro is loaded)

X509::LOG

(present if base/files/x509/main.bro is loaded)

HTTP::LOG

(present if base/protocols/http/main.bro is loaded)

IRC::LOG

(present if base/protocols/irc/main.bro is loaded)

KRB::LOG

(present if base/protocols/krb/main.bro is loaded)

Modbus::LOG

(present if base/protocols/modbus/main.bro is loaded)

mysql::LOG

(present if base/protocols/mysql/main.bro is loaded)

NTLM::LOG

(present if base/protocols/ntlm/main.bro is loaded)

RADIUS::LOG

(present if base/protocols/radius/main.bro is loaded)

RDP::LOG

(present if base/protocols/rdp/main.bro is loaded)

RFB::LOG

(present if base/protocols/rfb/main.bro is loaded)

SIP::LOG

(present if base/protocols/sip/main.bro is loaded)

SNMP::LOG

(present if base/protocols/snmp/main.bro is loaded)

SMTP::LOG

(present if base/protocols/smtp/main.bro is loaded)

SOCKS::LOG

(present if base/protocols/socks/main.bro is loaded)

SSH::LOG

(present if base/protocols/ssh/main.bro is loaded)

Syslog::LOG

(present if base/protocols/syslog/main.bro is loaded)

PE::LOG

(present if base/files/pe/main.bro is loaded)

Unified2::LOG

(present if base/files/unified2/main.bro is loaded)

Barnyard2::LOG

(present if policy/integration/barnyard2/main.bro is loaded)

CaptureLoss::LOG

(present if policy/misc/capture-loss.bro is loaded)

Traceroute::LOG

(present if policy/misc/detect-traceroute/main.bro is loaded)

Known::DEVICES_LOG

(present if policy/misc/known-devices.bro is loaded)

LoadedScripts::LOG

(present if policy/misc/loaded-scripts.bro is loaded)

Stats::LOG

(present if policy/misc/stats.bro is loaded)

Known::HOSTS_LOG

(present if policy/protocols/conn/known-hosts.bro is loaded)

Known::SERVICES_LOG

(present if policy/protocols/conn/known-services.bro is loaded)

Known::MODBUS_LOG

(present if policy/protocols/modbus/known-masters-slaves.bro is loaded)

Modbus::REGISTER_CHANGE_LOG

(present if policy/protocols/modbus/track-memmap.bro is loaded)

SMB::CMD_LOG

(present if policy/protocols/smb/main.bro is loaded)

SMB::AUTH_LOG

(present if policy/protocols/smb/main.bro is loaded)

SMB::MAPPING_LOG

(present if policy/protocols/smb/main.bro is loaded)

SMB::FILES_LOG

(present if policy/protocols/smb/main.bro is loaded)

Known::CERTS_LOG

(present if policy/protocols/ssl/known-certs.bro is loaded)

BroxygenExample::LOG

(present if broxygen/example.bro is loaded)

Type that defines an ID unique to each log stream. Scripts creating new log streams need to redef this enum to add their own specific log ID. The log ID implicitly determines the default name of the generated log file.

Functions

Broker::auto_event
Type:function (topic: string, ev: any, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool

Automatically send an event to any interested peers whenever it is locally dispatched (e.g. using “event my_event(...);” in a script).

Topic:a topic string associated with the event message. Peers advertise interest by registering a subscription to some prefix of this topic name.
Ev:a Bro event value.
Flags:tune the behavior of how the message is sent.
Returns:true if automatic event sending is now enabled.
Broker::auto_event_stop
Type:function (topic: string, ev: any) : bool

Stop automatically sending an event to peers upon local dispatch.

Topic:a topic originally given to Broker::auto_event.
Ev:an event originally given to Broker::auto_event.
Returns:true if automatic events will not occur for the topic/event pair.
Broker::connect
Type:function (a: string, p: port, retry: interval) : bool

Initiate a remote connection.

A:an address to connect to, e.g. “localhost” or “127.0.0.1”.
P:the TCP port on which the remote side is listening.
Retry:an interval at which to retry establishing the connection with the remote peer if it cannot be made initially, or if it ever becomes disconnected.
Returns:true if it’s possible to try connecting with the peer and it’s a new peer. The actual connection may not be established until a later point in time.

See also: Broker::outgoing_connection_established

Broker::disable_remote_logs
Type:function (id: Log::ID) : bool

Disable remote logs for a given log stream.

Id:the log stream to disable remote logs for.
Returns:true if remote logs are disabled for the stream.
Broker::disconnect
Type:function (a: string, p: port) : bool

Remove a remote connection.

A:the address used in previous successful call to Broker::connect.
P:the port used in previous successful call to Broker::connect.
Returns:true if the arguments match a previously successful call to Broker::connect.
Broker::enable
Type:function (flags: Broker::EndpointFlags &default = [auto_publish=T, auto_advertise=T] &optional) : bool

Enable use of communication.

Flags:used to tune the local Broker endpoint behavior.
Returns:true if communication is successfully initialized.
Broker::enable_remote_logs
Type:function (id: Log::ID, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool

Enable remote logs for a given log stream.

Id:the log stream to enable remote logs for.
Flags:tune the behavior of how log entry messages are sent.
Returns:true if remote logs are enabled for the stream.
Broker::listen
Type:function (p: port, a: string &default = "" &optional, reuse: bool &default = T &optional) : bool

Listen for remote connections.

P:the TCP port to listen on.
A:an address string on which to accept connections, e.g. “127.0.0.1”. An empty string refers to @p INADDR_ANY.
Reuse:equivalent to behavior of SO_REUSEADDR.
Returns:true if the local endpoint is now listening for connections.

See also: Broker::incoming_connection_established

Broker::publish_topic
Type:function (topic: string) : bool

Allow sending messages to peers if associated with the given topic. This has no effect if auto publication behavior is enabled via the flags supplied to Broker::enable or Broker::set_endpoint_flags.

Topic:a topic to allow messages to be published under.
Returns:true if successful.
Broker::remote_logs_enabled
Type:function (id: Log::ID) : bool

Check if remote logs are enabled for a given log stream.

Id:the log stream to check.
Returns:true if remote logs are enabled for the given stream.
Broker::send_event
Type:function (topic: string, args: Broker::EventArgs, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool

Send an event to any interested peers.

Topic:a topic associated with the event message.
Args:event arguments as made by Broker::event_args.
Flags:tune the behavior of how the message is sent.
Returns:true if the message is sent.
Broker::send_print
Type:function (topic: string, msg: string, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool

Print a simple message to any interested peers. The receiver can use Broker::print_handler to handle messages.

Topic:a topic associated with the printed message.
Msg:the print message to send to peers.
Flags:tune the behavior of how the message is sent.
Returns:true if the message is sent.
Broker::set_endpoint_flags
Type:function (flags: Broker::EndpointFlags &default = [auto_publish=T, auto_advertise=T] &optional) : bool

Changes endpoint flags originally supplied to Broker::enable.

Flags:the new endpoint behavior flags to use.
Returns:true if flags were changed.
Broker::subscribe_to_events
Type:function (topic_prefix: string) : bool

Register interest in all peer event messages that use a certain topic prefix.

Topic_prefix:a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”.
Returns:true if it’s a new event subscription and it is now registered.
Broker::subscribe_to_logs
Type:function (topic_prefix: string) : bool

Register interest in all peer log messages that use a certain topic prefix. Logs are implicitly sent with topic “bro/log/<stream-name>” and the receiving side processes them through the logging framework as usual.

Topic_prefix:a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”.
Returns:true if it’s a new log subscription and it is now registered.
Broker::subscribe_to_prints
Type:function (topic_prefix: string) : bool

Register interest in all peer print messages that use a certain topic prefix. Use Broker::print_handler to handle received messages.

Topic_prefix:a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”.
Returns:true if it’s a new print subscription and it is now registered.
Broker::unpublish_topic
Type:function (topic: string) : bool

Disallow sending messages to peers if associated with the given topic. This has no effect if auto publication behavior is enabled via the flags supplied to Broker::enable or Broker::set_endpoint_flags.

Topic:a topic to disallow messages to be published under.
Returns:true if successful.
Broker::unsubscribe_to_events
Type:function (topic_prefix: string) : bool

Unregister interest in all peer event messages that use a topic prefix.

Topic_prefix:a prefix previously supplied to a successful call to Broker::subscribe_to_events.
Returns:true if interest in the topic prefix is no longer advertised.
Broker::unsubscribe_to_logs
Type:function (topic_prefix: string) : bool

Unregister interest in all peer log messages that use a topic prefix. Logs are implicitly sent with topic “bro/log/<stream-name>” and the receiving side processes them through the logging framework as usual.

Topic_prefix:a prefix previously supplied to a successful call to Broker::subscribe_to_logs.
Returns:true if interest in the topic prefix is no longer advertised.
Broker::unsubscribe_to_prints
Type:function (topic_prefix: string) : bool

Unregister interest in all peer print messages that use a topic prefix.

Topic_prefix:a prefix previously supplied to a successful call to Broker::subscribe_to_prints.
Returns:true if interest in the topic prefix is no longer advertised.

Copyright 2016, The Bro Project. Last updated on July 21, 2017. Created using Sphinx 1.4.8.