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)

WeirdStats::LOG

(present if policy/misc/weird-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.