base/bif/event.bif.bro

GLOBAL

The protocol-independent events that the C/C++ core of Bro can generate.

This is mostly events not related to a specific transport- or application-layer protocol, but also includes a few that may be generated by more than one protocols analyzer (like events generated by both UDP and TCP analysis.)

Namespace:GLOBAL Source File:/scripts/base/bif/event.bif.bro

Summary

Events

OS_version_found: event	Generated when an operating system has been fingerprinted.
anonymization_mapping: event	Deprecated.
bro_done: event	Generated at Bro termination time.
bro_init: event	Generated at Bro initialization time.
bro_script_loaded: event	Raised for each policy script loaded by the script interpreter.
conn_stats: event	Generated when a TCP connection terminated, passing on statistics about the two endpoints.
conn_weird: event	Generated for unexpected activity related to a specific connection.
connection_external: event	Generated for a new connection received from the communication subsystem.
connection_flow_label_changed: event	Generated for a connection over IPv6 when one direction has changed the flow label that it’s using.
connection_reused: event	Generated when a connection 4-tuple is reused.
connection_state_remove: event	Generated when a connection’s internal state is about to be removed from memory.
connection_status_update: event	Generated in regular intervals during the lifetime of a connection.
connection_timeout: event	Generated when a TCP connection timed out.
content_gap: event	Generated when Bro detects a gap in a reassembled TCP payload stream.
dns_mapping_altered: event	Generated when an internal DNS lookup produced a different result than in the past.
dns_mapping_lost_name: event	Generated when an internal DNS lookup returned zero answers even though it had succeeded in the past.
dns_mapping_new_name: event	Generated when an internal DNS lookup succeeded but an earlier attempt did not.
dns_mapping_unverified: event	Generated when an internal DNS lookup got no answer even though it had succeeded in the past.
dns_mapping_valid: event	Generated when an internal DNS lookup produces the same result as last time.
esp_packet: event	Generated for any packets using the IPv6 Encapsulating Security Payload (ESP) extension header.
event_queue_flush_point: event	Marks a point in the event stream at which the event queue started flushing.
file_gap: event	Indicates that a chunk of the file is missing.
file_new: event	Indicates that an analysis of a new file has begun.
file_opened: event	Generated each time Bro’s script interpreter opens a file.
file_over_new_connection: event	Indicates that a file has been seen being transferred over a connection different from the original.
file_reassembly_overflow: event	Indicates that the file had an overflow of the reassembly buffer.
file_sniff: event	Provide all metadata that has been inferred about a particular file from inspection of the initial content that been seen at the beginning of the file.
file_state_remove: event	This event is generated each time file analysis is ending for a given file.
file_timeout: event	Indicates that file analysis has timed out because no activity was seen for the file in a while.
finished_send_state: event	Generated after a call to send_state when all data has been successfully sent to the remote side.
flow_weird: event	Generated for unexpected activity related to a pair of hosts, but independent of a specific connection.
gaobot_signature_found: event	Deprecated.
get_file_handle: event	This event is handled to provide feedback to the file analysis framework about how to identify the logical “file” to which some data/input belongs.
ipv6_ext_headers: event	Generated for every IPv6 packet that contains extension headers.
kazaa_signature_found: event	Deprecated.
load_sample: event	Generated regularly for the purpose of profiling Bro’s processing.
mobile_ipv6_message: event	Generated for any packet using a Mobile IPv6 Mobility Header.
napster_signature_found: event	Deprecated.
net_weird: event	Generated for unexpected activity that is not tied to a specific connection or pair of hosts.
new_connection: event	Generated for every new connection.
new_event: event	A meta event generated for events that Bro raises.
new_packet: event	Generated for all packets that make it into Bro’s connection processing.
packet_contents: event	Generated for every packet that has a non-empty transport-layer payload.
print_hook: event	Deprecated.
profiling_update: event	Generated each time Bro’s internal profiling log is updated.
protocol_confirmation: event	Generated when a protocol analyzer confirms that a connection is indeed using that protocol.
protocol_violation: event	Generated when a protocol analyzer determines that a connection it is parsing is not conforming to the protocol it expects.
raw_packet: event	Generated for every packet Bro sees that have a valid link-layer header.
remote_capture_filter: event	Generated when a remote peer sent us a capture filter.
remote_connection_closed: event	Generated when a connection to a remote Bro has been closed.
remote_connection_error: event	Generated when a connection to a remote Bro encountered an error.
remote_connection_established: event	Generated when a connection to a remote Bro has been established.
remote_connection_handshake_done: event	Generated when a remote connection’s initial handshake has been completed.
remote_event_registered: event	Generated for each event registered by a remote peer.
remote_log: event	Generated for communication log messages.
remote_log_peer: event	Generated for communication log messages.
remote_pong: event	Generated when a remote peer has answered to our ping.
remote_state_access_performed: event	Generated each time a remote state access has been replayed locally.
remote_state_inconsistency: event	Generated if state synchronization detects an inconsistency.
reporter_error: event &error_handler	Raised for errors reported via Bro’s reporter framework.
reporter_info: event &error_handler	Raised for informational messages reported via Bro’s reporter framework.
reporter_warning: event &error_handler	Raised for warnings reported via Bro’s reporter framework.
rexmit_inconsistency: event	Generated when Bro detects a TCP retransmission inconsistency.
root_backdoor_signature_found: event	Deprecated.
rotate_interval: event	Deprecated.
rotate_size: event	Deprecated.
scheduled_analyzer_applied: event	Generated when a connection is seen that is marked as being expected.
signature_match: event	Generated when a signature matches.
software_parse_error: event	Generated when a protocol analyzer finds an identification of a software used on a system but cannot parse it.
software_unparsed_version_found: event	Generated when a protocol analyzer finds an identification of a software used on a system.
software_version_found: event	Generated when a protocol analyzer finds an identification of a software used on a system.
tunnel_changed: event	Generated for a connection whose tunneling has changed.
udp_session_done: event	Generated when a UDP session for a supported protocol has finished.

Detailed Interface

Events

OS_version_found

Type:event (c: connection, host: addr, OS: OS_version)

Generated when an operating system has been fingerprinted. Bro uses p0f to fingerprint endpoints passively, and it raises this event for each system identified. The p0f fingerprints are defined by passive_fingerprint_file.

C:The connection. Host:The host running the reported OS. OS:The OS version string.

See also: passive_fingerprint_file, software_parse_error, software_version_found, software_unparsed_version_found, generate_OS_version_event

anonymization_mapping

Type:event (orig: addr, mapped: addr)

Deprecated. Will be removed.

bro_done

Type:event ()

Generated at Bro termination time. The event engine generates this event when Bro is about to terminate, either due to having exhausted reading its input trace file(s), receiving a termination signal, or because Bro was run without a network input source and has finished executing any global statements.

See also: bro_init

Note

If Bro terminates due to an invocation of exit, then this event is not generated.

bro_init

Type:event ()

Generated at Bro initialization time. The event engine generates this event just before normal input processing begins. It can be used to execute one-time initialization code at startup. At the time a handler runs, Bro will have executed any global initializations and statements.

See also: bro_done

Note

When a bro_init handler executes, Bro has not yet seen any input packets and therefore network_time is not initialized yet. An artifact of that is that any timer installed in a bro_init handler will fire immediately with the first packet. The standard way to work around that is to ignore the first time the timer fires and immediately reschedule.

bro_script_loaded

Type:event (path: string, level: count)

Raised for each policy script loaded by the script interpreter.

Path:The full path to the script loaded. Level:The “nesting level”: zero for a top-level Bro script and incremented recursively for each @load.

conn_stats

Type:event (c: connection, os: endpoint_stats, rs: endpoint_stats)

Generated when a TCP connection terminated, passing on statistics about the two endpoints. This event is always generated when Bro flushes the internal connection state, independent of how a connection terminates.

C:The connection. Os:Statistics for the originator endpoint. Rs:Statistics for the responder endpoint.

See also: connection_state_remove

conn_weird

Type:event (name: string, c: connection, addl: string)

Generated for unexpected activity related to a specific connection. When Bro’s packet analysis encounters activity that does not conform to a protocol’s specification, it raises one of the *_weird events to report that. This event is raised if the activity is tied directly to a specific connection.

Name:A unique name for the specific type of “weird” situation. Bro’s default scripts use this name in filtering policies that specify which “weirds” are worth reporting. C:The corresponding connection. Addl:Optional additional context further describing the situation.

See also: flow_weird, net_weird

Note

“Weird” activity is much more common in real-world network traffic than one would intuitively expect. While in principle, any protocol violation could be an attack attempt, it’s much more likely that an endpoint’s implementation interprets an RFC quite liberally.

connection_external

Type:event (c: connection, tag: string)

Generated for a new connection received from the communication subsystem. Remote peers can inject packets into Bro’s packet loop, for example via Broccoli. The communication system raises this event with the first packet of a connection coming in this way.

C:The connection. Tag:TODO.

connection_flow_label_changed

Type:event (c: connection, is_orig: bool, old_label: count, new_label: count)

Generated for a connection over IPv6 when one direction has changed the flow label that it’s using.

C:The connection. Is_orig:True if the event is raised for the originator side. Old_label:The old flow label that the endpoint was using. New_label:The new flow label that the endpoint is using.

See also: connection_established, new_connection

connection_reused

Type:event (c: connection)

Generated when a connection 4-tuple is reused. This event is raised when Bro sees a new TCP session or UDP flow using a 4-tuple matching that of an earlier connection it still considers active.

C:The connection.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_state_remove, connection_status_update, connection_timeout, scheduled_analyzer_applied, new_connection, new_connection_contents, partial_connection

connection_state_remove

Type:event (c: connection)

Generated when a connection’s internal state is about to be removed from memory. Bro generates this event reliably once for every connection when it is about to delete the internal state. As such, the event is well-suited for script-level cleanup that needs to be performed for every connection. This event is generated not only for TCP sessions but also for UDP and ICMP flows.

C:The connection.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_reused, connection_status_update, connection_timeout, scheduled_analyzer_applied, new_connection, new_connection_contents, partial_connection, udp_inactivity_timeout, tcp_inactivity_timeout, icmp_inactivity_timeout, conn_stats

connection_status_update

Type:event (c: connection)

Generated in regular intervals during the lifetime of a connection. The event is raised each connection_status_update_interval seconds and can be used to check conditions on a regular basis.

C:The connection.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_reused, connection_state_remove, connection_timeout, scheduled_analyzer_applied, new_connection, new_connection_contents, partial_connection

connection_timeout

Type:event (c: connection)

Generated when a TCP connection timed out. This event is raised when no activity was seen for an interval of at least tcp_connection_linger, and either one endpoint has already closed the connection or one side never became active.

C:The connection.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_reused, connection_state_remove, connection_status_update, scheduled_analyzer_applied, new_connection, new_connection_contents, partial_connection

Note

The precise semantics of this event can be unintuitive as it only covers a subset of cases where a connection times out. Often, handling connection_state_remove is the better option. That one will be generated reliably when an interval of tcp_inactivity_timeout has passed without any activity seen (but also for all other ways a connection may terminate).

content_gap

Type:event (c: connection, is_orig: bool, seq: count, length: count)

Generated when Bro detects a gap in a reassembled TCP payload stream. This event is raised when Bro, while reassembling a payload stream, determines that a chunk of payload is missing (e.g., because the responder has already acknowledged it, even though Bro didn’t see it).

C:The connection. Is_orig:True if the gap is on the originator’s side. Seq:The sequence number where the gap starts. Length:The number of bytes missing.

Note

Content gaps tend to occur occasionally for various reasons, including broken TCP stacks. If, however, one finds lots of them, that typically means that there is a problem with the monitoring infrastructure such as a tap dropping packets, split routing on the path, or reordering at the tap.

dns_mapping_altered

Type:event (dm: dns_mapping, old_addrs: addr_set, new_addrs: addr_set)

Generated when an internal DNS lookup produced a different result than in the past. Bro keeps an internal DNS cache for host names and IP addresses it has already resolved. This event is generated when a subsequent lookup returns a different answer than we have stored in the cache.

Dm:A record describing the new resolver result. Old_addrs:Addresses that used to be part of the returned set for the query described by dm, but are not anymore. New_addrs:Addresses that were not part of the returned set for the query described by dm, but now are.

See also: dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_lost_name

Type:event (dm: dns_mapping)

Generated when an internal DNS lookup returned zero answers even though it had succeeded in the past. Bro keeps an internal DNS cache for host names and IP addresses it has already resolved. This event is generated when on a subsequent lookup we receive an answer that is empty even though we have already stored a result in the cache.

Dm:A record describing the old resolver result.

See also: dns_mapping_altered, dns_mapping_new_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_new_name

Type:event (dm: dns_mapping)

Generated when an internal DNS lookup succeeded but an earlier attempt did not. Bro keeps an internal DNS cache for host names and IP addresses it has already resolved. This event is generated when a subsequent lookup produces an answer for a query that was marked as failed in the cache.

Dm:A record describing the new resolver result.

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_unverified

Type:event (dm: dns_mapping)

Generated when an internal DNS lookup got no answer even though it had succeeded in the past. Bro keeps an internal DNS cache for host names and IP addresses it has already resolved. This event is generated when a subsequent lookup does not produce an answer even though we have already stored a result in the cache.

Dm:A record describing the old resolver result.

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_valid

dns_mapping_valid

Type:event (dm: dns_mapping)

Generated when an internal DNS lookup produces the same result as last time. Bro keeps an internal DNS cache for host names and IP addresses it has already resolved. This event is generated when a subsequent lookup returns the same result as stored in the cache.

Dm:A record describing the new resolver result (which matches the old one).

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_unverified

esp_packet

Type:event (p: pkt_hdr)

Generated for any packets using the IPv6 Encapsulating Security Payload (ESP) extension header.

P:Information from the header of the packet that triggered the event.

See also: new_packet, tcp_packet, ipv6_ext_headers

event_queue_flush_point

Type:event ()

Marks a point in the event stream at which the event queue started flushing.

file_gap

Type:event (f: fa_file, offset: count, len: count)

Indicates that a chunk of the file is missing.

F:The file. Offset:The byte offset from the start of the file at which the gap begins. Len:The number of missing bytes.

See also: file_new, file_over_new_connection, file_timeout, file_sniff, file_state_remove, file_reassembly_overflow

file_new

Type:event (f: fa_file)

Indicates that an analysis of a new file has begun. The analysis can be augmented at this time via Files::add_analyzer.

F:The file.

See also: file_over_new_connection, file_timeout, file_gap, file_sniff, file_state_remove

file_opened

Type:event (f: file)

Generated each time Bro’s script interpreter opens a file. This event is triggered only for files opened via open, and in particular not for normal log files as created by log writers.

F:The opened file.

file_over_new_connection

Type:event (f: fa_file, c: connection, is_orig: bool)

Indicates that a file has been seen being transferred over a connection different from the original.

F:The file. C:The new connection over which the file is seen being transferred. Is_orig:true if the originator of c is the one sending the file.

See also: file_new, file_timeout, file_gap, file_sniff, file_state_remove

file_reassembly_overflow

Type:event (f: fa_file, offset: count, skipped: count)

Indicates that the file had an overflow of the reassembly buffer. This is a specialization of the file_gap event.

F:The file. Offset:The byte offset from the start of the file at which the reassembly couldn’t continue due to running out of reassembly buffer space. Skipped:The number of bytes of the file skipped over to flush some file data and get back under the reassembly buffer size limit. This value will also be represented as a gap.

See also: file_new, file_over_new_connection, file_timeout, file_sniff, file_state_remove, file_gap, Files::enable_reassembler, Files::reassembly_buffer_size, Files::enable_reassembly, Files::disable_reassembly, Files::set_reassembly_buffer_size

file_sniff

Type:event (f: fa_file, meta: fa_metadata)

Provide all metadata that has been inferred about a particular file from inspection of the initial content that been seen at the beginning of the file. The analysis can be augmented at this time via Files::add_analyzer. The amount of data fed into the file sniffing can be increased or decreased by changing either default_file_bof_buffer_size or the bof_buffer_size field in an fa_file record. The event will be raised even if content inspection has been unable to infer any metadata, in which case the fields in meta will be left all unset.

F:The file. Meta:Metadata that’s been discovered about the file.

See also: file_over_new_connection, file_timeout, file_gap, file_state_remove

file_state_remove

Type:event (f: fa_file)

This event is generated each time file analysis is ending for a given file.

F:The file.

See also: file_new, file_over_new_connection, file_timeout, file_gap, file_sniff

file_timeout

Type:event (f: fa_file)

Indicates that file analysis has timed out because no activity was seen for the file in a while.

F:The file.

See also: file_new, file_over_new_connection, file_gap, file_sniff, file_state_remove, default_file_timeout_interval, Files::set_timeout_interval

finished_send_state

Type:event (p: event_peer)

Generated after a call to send_state when all data has been successfully sent to the remote side. While this event is intended primarily for use by Bro’s communication framework, it can also trigger additional code if helpful.

P:A record describing the remote peer.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

flow_weird

Type:event (name: string, src: addr, dst: addr)

Generated for unexpected activity related to a pair of hosts, but independent of a specific connection. When Bro’s packet analysis encounters activity that does not conform to a protocol’s specification, it raises one of the *_weird events to report that. This event is raised if the activity is related to a pair of hosts, yet not to a specific connection between them.

Name:A unique name for the specific type of “weird” situation. Bro’s default scripts use this name in filtering policies that specify which “weirds” are worth reporting. Src:The source address corresponding to the activity. Dst:The destination address corresponding to the activity.

See also: conn_weird, net_weird

Note

“Weird” activity is much more common in real-world network traffic than one would intuitively expect. While in principle, any protocol violation could be an attack attempt, it’s much more likely that an endpoint’s implementation interprets an RFC quite liberally.

gaobot_signature_found

Type:event (c: connection)

Deprecated. Will be removed.

get_file_handle

Type:event (tag: Analyzer::Tag, c: connection, is_orig: bool)

This event is handled to provide feedback to the file analysis framework about how to identify the logical “file” to which some data/input belongs. All incoming data to the framework is buffered, and depends on a handler for this event to return a string value that uniquely identifies a file. Among all handlers of this event, the last one to call set_file_handle will “win”.

Tag:The analyzer which is carrying the file data. C:The connection which is carrying the file data. Is_orig:The direction the file data is flowing over the connection.

See also: set_file_handle

ipv6_ext_headers

Type:event (c: connection, p: pkt_hdr)

Generated for every IPv6 packet that contains extension headers. This is potentially an expensive event to handle if analysing IPv6 traffic that happens to utilize extension headers frequently.

C:The connection the packet is part of. P:Information from the header of the packet that triggered the event.

See also: new_packet, tcp_packet, packet_contents, esp_packet

kazaa_signature_found

Type:event (c: connection)

Deprecated. Will be removed.

load_sample

Type:event (samples: load_sample_info, CPU: interval, dmem: int)

Generated regularly for the purpose of profiling Bro’s processing. This event is raised for every load_sample_freq packet. For these packets, Bro records script-level functions executed during their processing as well as further internal locations. By sampling the processing in this form, one can understand where Bro spends its time.

Samples:A set with functions and locations seen during the processing of the sampled packet. CPU:The CPU time spent on processing the sampled packet. Dmem:The difference in memory usage caused by processing the sampled packet.

mobile_ipv6_message

Type:event (p: pkt_hdr)

Generated for any packet using a Mobile IPv6 Mobility Header.

P:Information from the header of the packet that triggered the event.

See also: new_packet, tcp_packet, ipv6_ext_headers

napster_signature_found

Type:event (c: connection)

Deprecated. Will be removed.

net_weird

Type:event (name: string)

Generated for unexpected activity that is not tied to a specific connection or pair of hosts. When Bro’s packet analysis encounters activity that does not conform to a protocol’s specification, it raises one of the *_weird events to report that. This event is raised if the activity is not tied directly to a specific connection or pair of hosts.

Name:A unique name for the specific type of “weird” situation. Bro’s default scripts use this name in filtering policies that specify which “weirds” are worth reporting.

See also: flow_weird

Note

“Weird” activity is much more common in real-world network traffic than one would intuitively expect. While in principle, any protocol violation could be an attack attempt, it’s much more likely that an endpoint’s implementation interprets an RFC quite liberally.

new_connection

Type:event (c: connection)

Generated for every new connection. This event is raised with the first packet of a previously unknown connection. Bro uses a flow-based definition of “connection” here that includes not only TCP sessions but also UDP and ICMP flows.

C:The connection.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_reused, connection_state_remove, connection_status_update, connection_timeout, scheduled_analyzer_applied, new_connection_contents, partial_connection

Note

Handling this event is potentially expensive. For example, during a SYN flooding attack, every spoofed SYN packet will lead to a new event.

new_event

Type:event (name: string, params: call_argument_vector)

A meta event generated for events that Bro raises. This will report all events for which at least one handler is defined.

Note that handling this meta event is expensive and should be limited to debugging purposes.

Name:The name of the event. Params:The event’s parameters.

new_packet

Type:event (c: connection, p: pkt_hdr)

Generated for all packets that make it into Bro’s connection processing. In contrast to raw_packet this filters out some more packets that don’t pass certain sanity checks.

This is a very low-level and expensive event that should be avoided when at all possible. It’s usually infeasible to handle when processing even medium volumes of traffic in real-time. That said, if you work from a trace and want to do some packet-level analysis, it may come in handy.

C:The connection the packet is part of. P:Information from the header of the packet that triggered the event.

See also: tcp_packet, packet_contents, raw_packet

packet_contents

Type:event (c: connection, contents: string)

Generated for every packet that has a non-empty transport-layer payload. This is a very low-level and expensive event that should be avoided when at all possible. It’s usually infeasible to handle when processing even medium volumes of traffic in real-time. It’s even worse than new_packet. That said, if you work from a trace and want to do some packet-level analysis, it may come in handy.

C:The connection the packet is part of. Contents:The raw transport-layer payload.

See also: new_packet, tcp_packet

print_hook

Type:event (f: file, s: string)

Deprecated. Will be removed.

profiling_update

Type:event (f: file, expensive: bool)

Generated each time Bro’s internal profiling log is updated. The file is defined by profiling_file, and its update frequency by profiling_interval and expensive_profiling_multiple.

F:The profiling file. Expensive:True if this event corresponds to heavier-weight profiling as indicated by the expensive_profiling_multiple variable.

See also: profiling_interval, expensive_profiling_multiple

protocol_confirmation

Type:event (c: connection, atype: Analyzer::Tag, aid: count)

Generated when a protocol analyzer confirms that a connection is indeed using that protocol. Bro’s dynamic protocol detection heuristically activates analyzers as soon as it believes a connection could be using a particular protocol. It is then left to the corresponding analyzer to verify whether that is indeed the case; if so, this event will be generated.

C:The connection. Atype:The type of the analyzer confirming that its protocol is in use. The value is one of the Analyzer::ANALYZER_* constants. For example, Analyzer::ANALYZER_HTTP means the HTTP analyzer determined that it’s indeed parsing an HTTP connection. Aid:A unique integer ID identifying the specific instance of the analyzer atype that is analyzing the connection c. The ID can be used to reference the analyzer when using builtin functions like disable_analyzer.

See also: protocol_violation

Note

Bro’s default scripts use this event to determine the service column of Conn::Info: once confirmed, the protocol will be listed there (and thus in conn.log).

protocol_violation

Type:event (c: connection, atype: Analyzer::Tag, aid: count, reason: string)

Generated when a protocol analyzer determines that a connection it is parsing is not conforming to the protocol it expects. Bro’s dynamic protocol detection heuristically activates analyzers as soon as it believes a connection could be using a particular protocol. It is then left to the corresponding analyzer to verify whether that is indeed the case; if not, the analyzer will trigger this event.

C:The connection. Atype:The type of the analyzer confirming that its protocol is in use. The value is one of the Analyzer::ANALYZER_* constants. For example, Analyzer::ANALYZER_HTTP means the HTTP analyzer determined that it’s indeed parsing an HTTP connection. Aid:A unique integer ID identifying the specific instance of the analyzer atype that is analyzing the connection c. The ID can be used to reference the analyzer when using builtin functions like disable_analyzer. Reason:TODO.

See also: protocol_confirmation

Note

Bro’s default scripts use this event to disable an analyzer via disable_analyzer if it’s parsing the wrong protocol. That’s however a script-level decision and not done automatically by the event engine.

raw_packet

Type:event (p: raw_pkt_hdr)

Generated for every packet Bro sees that have a valid link-layer header. This is a very very low-level and expensive event that should be avoided when at all possible. It’s usually infeasible to handle when processing even medium volumes of traffic in real-time. That said, if you work from a trace and want to do some packet-level analysis, it may come in handy.

P:Information from the header of the packet that triggered the event.

See also: new_packet, packet_contents

remote_capture_filter

Type:event (p: event_peer, filter: string)

Generated when a remote peer sent us a capture filter. While this event is intended primarily for use by Bro’s communication framework, it can also trigger additional code if helpful.

P:A record describing the peer. Filter:The filter string sent by the peer.

See also: remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_connection_closed

Type:event (p: event_peer)

Generated when a connection to a remote Bro has been closed. This event is intended primarily for use by Bro’s communication framework, but it can also trigger additional code if helpful.

P:A record describing the peer.

See also: remote_capture_filter, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_connection_error

Type:event (p: event_peer, reason: string)

Generated when a connection to a remote Bro encountered an error. This event is intended primarily for use by Bro’s communication framework, but it can also trigger additional code if helpful.

P:A record describing the peer. Reason:A textual description of the error.

See also: remote_capture_filter, remote_connection_closed, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_connection_established

Type:event (p: event_peer)

Generated when a connection to a remote Bro has been established. This event is intended primarily for use by Bro’s communication framework, but it can also trigger additional code if helpful.

P:A record describing the peer.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_connection_handshake_done

Type:event (p: event_peer)

Generated when a remote connection’s initial handshake has been completed. This event is intended primarily for use by Bro’s communication framework, but it can also trigger additional code if helpful.

P:A record describing the peer.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_event_registered

Type:event (p: event_peer, name: string)

Generated for each event registered by a remote peer. This event is intended primarily for use by Bro’s communication framework, but it can also trigger additional code if helpful.

P:A record describing the peer. Name:TODO.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_log, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_log

Type:event (level: count, src: count, msg: string)

Generated for communication log messages. While this event is intended primarily for use by Bro’s communication framework, it can also trigger additional code if helpful.

Level:The log level, which is either REMOTE_LOG_INFO or REMOTE_LOG_ERROR. Src:The component of the communication system that logged the message. Currently, this will be one of REMOTE_SRC_CHILD (Bro’s child process), REMOTE_SRC_PARENT (Bro’s main process), or REMOTE_SRC_SCRIPT (the script level). Msg:The message logged.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook, remote_log_peer

remote_log_peer

Type:event (p: event_peer, level: count, src: count, msg: string)

Generated for communication log messages. While this event is intended primarily for use by Bro’s communication framework, it can also trigger additional code if helpful. This event is equivalent to remote_log except the message is with respect to a certain peer.

P:A record describing the remote peer. Level:The log level, which is either REMOTE_LOG_INFO or REMOTE_LOG_ERROR. Src:The component of the communication system that logged the message. Currently, this will be one of REMOTE_SRC_CHILD (Bro’s child process), REMOTE_SRC_PARENT (Bro’s main process), or REMOTE_SRC_SCRIPT (the script level). Msg:The message logged.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_pong, remote_state_access_performed, remote_state_inconsistency, print_hook, remote_log

remote_pong

Type:event (p: event_peer, seq: count, d1: interval, d2: interval, d3: interval)

Generated when a remote peer has answered to our ping. This event is part of Bro’s infrastructure for measuring communication latency. One can send a ping by calling send_ping and when a corresponding reply is received, this event will be raised.

P:The peer sending us the pong. Seq:The sequence number passed to the original send_ping call. The number is sent back by the peer in its response. D1:The time interval between sending the ping and receiving the pong. This is the latency of the complete path. D2:The time interval between sending out the ping to the network and its reception at the peer. This is the network latency. D3:The time interval between when the peer’s child process received the ping and when its parent process sent the pong. This is the processing latency at the peer.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_state_access_performed, remote_state_inconsistency, print_hook

remote_state_access_performed

Type:event (id: string, v: any)

Generated each time a remote state access has been replayed locally. This event is primarily intended for debugging.

Id:The name of the Bro script variable that’s being operated on. V:The new value of the variable.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_inconsistency, print_hook

remote_state_inconsistency

Type:event (operation: string, id: string, expected_old: string, real_old: string)

Generated if state synchronization detects an inconsistency. While this event is intended primarily for use by Bro’s communication framework, it can also trigger additional code if helpful. This event is only raised if remote_check_sync_consistency is false.

Operation:The textual description of the state operation performed. Id:The name of the Bro script identifier that was operated on. Expected_old:A textual representation of the value of id that was expected to be found before the operation was carried out. Real_old:A textual representation of the value of id that was actually found before the operation was carried out. The difference between real_old and expected_old is the inconsistency being reported.

See also: remote_capture_filter, remote_connection_closed, remote_connection_error, remote_connection_established, remote_connection_handshake_done, remote_event_registered, remote_log, remote_pong, remote_state_access_performed, print_hook, remote_check_sync_consistency

reporter_error

Type:event (t: time, msg: string, location: string) Attributes:&error_handler

Raised for errors reported via Bro’s reporter framework. Such messages may be generated internally by the event engine and also by other scripts calling Reporter::error.

T:The time the error was passed to the reporter. Msg:The error message. Location:A (potentially empty) string describing a location associated with the error.

See also: reporter_info, reporter_warning, Reporter::info, Reporter::warning, Reporter::error

Note

Bro will not call reporter events recursively. If the handler of any reporter event triggers a new reporter message itself, the output will go to stderr instead.

reporter_info

Type:event (t: time, msg: string, location: string) Attributes:&error_handler

Raised for informational messages reported via Bro’s reporter framework. Such messages may be generated internally by the event engine and also by other scripts calling Reporter::info.

T:The time the message was passed to the reporter. Msg:The message itself. Location:A (potentially empty) string describing a location associated with the message.

See also: reporter_warning, reporter_error, Reporter::info, Reporter::warning, Reporter::error

Note

Bro will not call reporter events recursively. If the handler of any reporter event triggers a new reporter message itself, the output will go to stderr instead.

reporter_warning

Type:event (t: time, msg: string, location: string) Attributes:&error_handler

Raised for warnings reported via Bro’s reporter framework. Such messages may be generated internally by the event engine and also by other scripts calling Reporter::warning.

T:The time the warning was passed to the reporter. Msg:The warning message. Location:A (potentially empty) string describing a location associated with the warning.

See also: reporter_info, reporter_error, Reporter::info, Reporter::warning, Reporter::error

Note

Bro will not call reporter events recursively. If the handler of any reporter event triggers a new reporter message itself, the output will go to stderr instead.

rexmit_inconsistency

Type:event (c: connection, t1: string, t2: string, tcp_flags: string)

Generated when Bro detects a TCP retransmission inconsistency. When reassembling a TCP stream, Bro buffers all payload until it sees the responder acking it. If during that time, the sender resends a chunk of payload but with different content than originally, this event will be raised. In addition, if tcp_max_old_segments is larger than zero, mismatches with that older still-buffered data will likewise trigger the event.

C:The connection showing the inconsistency. T1:The original payload. T2:The new payload. Tcp_flags:A string with the TCP flags of the packet triggering the inconsistency. In the string, each character corresponds to one set flag, as follows: S -> SYN; F -> FIN; R -> RST; A -> ACK; P -> PUSH. This string will not always be set, only if the information is available; it’s “best effort”.

See also: tcp_rexmit, tcp_contents

root_backdoor_signature_found

Type:event (c: connection)

Deprecated. Will be removed.

rotate_interval

Type:event (f: file)

Deprecated. Will be removed.

rotate_size

Type:event (f: file)

Deprecated. Will be removed.

scheduled_analyzer_applied

Type:event (c: connection, a: Analyzer::Tag)

Generated when a connection is seen that is marked as being expected. The function Analyzer::schedule_analyzer tells Bro to expect a particular connection to come up, and which analyzer to associate with it. Once the first packet of such a connection is indeed seen, this event is raised.

C:The connection. A:The analyzer that was scheduled for the connection with the Analyzer::schedule_analyzer call. When the event is raised, that analyzer will already have been activated to process the connection. The count is one of the ANALYZER_* constants, e.g., ANALYZER_HTTP.

See also: connection_EOF, connection_SYN_packet, connection_attempt, connection_established, connection_external, connection_finished, connection_first_ACK, connection_half_finished, connection_partial_close, connection_pending, connection_rejected, connection_reset, connection_reused, connection_state_remove, connection_status_update, connection_timeout, new_connection, new_connection_contents, partial_connection

Todo

We don’t have a good way to document the automatically generated ANALYZER_* constants right now.

signature_match

Type:event (state: signature_state, msg: string, data: string)

Generated when a signature matches. Bro’s signature engine provides high-performance pattern matching separately from the normal script processing. If a signature with an event action matches, this event is raised.

See the user manual for more information about Bro’s signature engine.

State:Context about the match, including which signatures triggered the event and the connection for which the match was found. Msg:The message passed to the event signature action. Data:The last chunk of input that triggered the match. Note that the specifics here are not well-defined as Bro does not buffer any input. If a match is split across packet boundaries, only the last chunk triggering the match will be passed on to the event.

software_parse_error

Type:event (c: connection, host: addr, descr: string)

Generated when a protocol analyzer finds an identification of a software used on a system but cannot parse it. This is a protocol-independent event that is fed by different analyzers. For example, the HTTP analyzer reports user-agent and server software by raising this event if it cannot parse them directly (if it can software_version_found will be generated instead).

C:The connection. Host:The host running the reported software. Descr:The raw (unparsed) software identification string as extracted from the protocol.

See also: software_version_found, software_unparsed_version_found, OS_version_found

software_unparsed_version_found

Type:event (c: connection, host: addr, str: string)

Generated when a protocol analyzer finds an identification of a software used on a system. This is a protocol-independent event that is fed by different analyzers. For example, the HTTP analyzer reports user-agent and server software by raising this event. Different from software_version_found and software_parse_error, this event is always raised, independent of whether Bro can parse the version string.

C:The connection. Host:The host running the reported software. Str:The software identification string as extracted from the protocol.

See also: software_parse_error, software_version_found, OS_version_found

software_version_found

Type:event (c: connection, host: addr, s: software, descr: string)

Generated when a protocol analyzer finds an identification of a software used on a system. This is a protocol-independent event that is fed by different analyzers. For example, the HTTP analyzer reports user-agent and server software by raising this event, assuming it can parse it (if not, software_parse_error will be generated instead).

C:The connection. Host:The host running the reported software. S:A description of the software found. Descr:The raw (unparsed) software identification string as extracted from the protocol.

See also: software_parse_error, software_unparsed_version_found, OS_version_found

tunnel_changed

Type:event (c: connection, e: EncapsulatingConnVector)

Generated for a connection whose tunneling has changed. This could be from a previously seen connection now being encapsulated in a tunnel, or from the outer encapsulation changing. Note that connection c’s tunnel field is NOT automatically/internally assigned to the new encapsulation value of e after this event is raised. If the desired behavior is to track the latest tunnel encapsulation per-connection, then a handler of this event should assign e to c$tunnel (which Bro’s default scripts are doing).

C:The connection whose tunnel/encapsulation changed. E:The new encapsulation.

udp_session_done

Type:event (u: connection)

Generated when a UDP session for a supported protocol has finished. Some of Bro’s application-layer UDP analyzers flag the end of a session by raising this event. Currently, the analyzers for DNS, NTP, Netbios, Syslog, AYIYA, Teredo, and GTPv1 support this.

U:The connection record for the corresponding UDP flow.

See also: udp_contents, udp_reply, udp_request