:tocdepth: 3 base/bif/event.bif.bro ====================== .. bro:namespace:: 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 Summary ~~~~~~~ Events ###### ======================================================================== ============================================================================= :bro:id:`OS_version_found`: :bro:type:`event` Generated when an operating system has been fingerprinted. :bro:id:`anonymization_mapping`: :bro:type:`event` Deprecated. :bro:id:`bro_done`: :bro:type:`event` Generated at Bro termination time. :bro:id:`bro_init`: :bro:type:`event` Generated at Bro initialization time. :bro:id:`bro_script_loaded`: :bro:type:`event` Raised for each policy script loaded by the script interpreter. :bro:id:`conn_stats`: :bro:type:`event` Generated when a TCP connection terminated, passing on statistics about the two endpoints. :bro:id:`conn_weird`: :bro:type:`event` Generated for unexpected activity related to a specific connection. :bro:id:`connection_external`: :bro:type:`event` Generated for a new connection received from the communication subsystem. :bro:id:`connection_flow_label_changed`: :bro:type:`event` Generated for a connection over IPv6 when one direction has changed the flow label that it's using. :bro:id:`connection_reused`: :bro:type:`event` Generated when a connection 4-tuple is reused. :bro:id:`connection_state_remove`: :bro:type:`event` Generated when a connection's internal state is about to be removed from memory. :bro:id:`connection_status_update`: :bro:type:`event` Generated in regular intervals during the lifetime of a connection. :bro:id:`connection_timeout`: :bro:type:`event` Generated when a TCP connection timed out. :bro:id:`content_gap`: :bro:type:`event` Generated when Bro detects a gap in a reassembled TCP payload stream. :bro:id:`dns_mapping_altered`: :bro:type:`event` Generated when an internal DNS lookup produced a different result than in the past. :bro:id:`dns_mapping_lost_name`: :bro:type:`event` Generated when an internal DNS lookup returned zero answers even though it had succeeded in the past. :bro:id:`dns_mapping_new_name`: :bro:type:`event` Generated when an internal DNS lookup succeeded but an earlier attempt did not. :bro:id:`dns_mapping_unverified`: :bro:type:`event` Generated when an internal DNS lookup got no answer even though it had succeeded in the past. :bro:id:`dns_mapping_valid`: :bro:type:`event` Generated when an internal DNS lookup produces the same result as last time. :bro:id:`esp_packet`: :bro:type:`event` Generated for any packets using the IPv6 Encapsulating Security Payload (ESP) extension header. :bro:id:`event_queue_flush_point`: :bro:type:`event` Marks a point in the event stream at which the event queue started flushing. :bro:id:`file_gap`: :bro:type:`event` Indicates that a chunk of the file is missing. :bro:id:`file_new`: :bro:type:`event` Indicates that an analysis of a new file has begun. :bro:id:`file_opened`: :bro:type:`event` Generated each time Bro's script interpreter opens a file. :bro:id:`file_over_new_connection`: :bro:type:`event` Indicates that a file has been seen being transferred over a connection different from the original. :bro:id:`file_reassembly_overflow`: :bro:type:`event` Indicates that the file had an overflow of the reassembly buffer. :bro:id:`file_sniff`: :bro:type:`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. :bro:id:`file_state_remove`: :bro:type:`event` This event is generated each time file analysis is ending for a given file. :bro:id:`file_timeout`: :bro:type:`event` Indicates that file analysis has timed out because no activity was seen for the file in a while. :bro:id:`finished_send_state`: :bro:type:`event` Generated after a call to :bro:id:`send_state` when all data has been successfully sent to the remote side. :bro:id:`flow_weird`: :bro:type:`event` Generated for unexpected activity related to a pair of hosts, but independent of a specific connection. :bro:id:`gaobot_signature_found`: :bro:type:`event` Deprecated. :bro:id:`get_file_handle`: :bro:type:`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. :bro:id:`ipv6_ext_headers`: :bro:type:`event` Generated for every IPv6 packet that contains extension headers. :bro:id:`kazaa_signature_found`: :bro:type:`event` Deprecated. :bro:id:`load_sample`: :bro:type:`event` Generated regularly for the purpose of profiling Bro's processing. :bro:id:`mobile_ipv6_message`: :bro:type:`event` Generated for any packet using a Mobile IPv6 Mobility Header. :bro:id:`napster_signature_found`: :bro:type:`event` Deprecated. :bro:id:`net_weird`: :bro:type:`event` Generated for unexpected activity that is not tied to a specific connection or pair of hosts. :bro:id:`new_connection`: :bro:type:`event` Generated for every new connection. :bro:id:`new_event`: :bro:type:`event` A meta event generated for events that Bro raises. :bro:id:`new_packet`: :bro:type:`event` Generated for all packets that make it into Bro's connection processing. :bro:id:`packet_contents`: :bro:type:`event` Generated for every packet that has a non-empty transport-layer payload. :bro:id:`print_hook`: :bro:type:`event` Deprecated. :bro:id:`profiling_update`: :bro:type:`event` Generated each time Bro's internal profiling log is updated. :bro:id:`protocol_confirmation`: :bro:type:`event` Generated when a protocol analyzer confirms that a connection is indeed using that protocol. :bro:id:`protocol_violation`: :bro:type:`event` Generated when a protocol analyzer determines that a connection it is parsing is not conforming to the protocol it expects. :bro:id:`raw_packet`: :bro:type:`event` Generated for every packet Bro sees that have a valid link-layer header. :bro:id:`remote_capture_filter`: :bro:type:`event` Generated when a remote peer sent us a capture filter. :bro:id:`remote_connection_closed`: :bro:type:`event` Generated when a connection to a remote Bro has been closed. :bro:id:`remote_connection_error`: :bro:type:`event` Generated when a connection to a remote Bro encountered an error. :bro:id:`remote_connection_established`: :bro:type:`event` Generated when a connection to a remote Bro has been established. :bro:id:`remote_connection_handshake_done`: :bro:type:`event` Generated when a remote connection's initial handshake has been completed. :bro:id:`remote_event_registered`: :bro:type:`event` Generated for each event registered by a remote peer. :bro:id:`remote_log`: :bro:type:`event` Generated for communication log messages. :bro:id:`remote_log_peer`: :bro:type:`event` Generated for communication log messages. :bro:id:`remote_pong`: :bro:type:`event` Generated when a remote peer has answered to our ping. :bro:id:`remote_state_access_performed`: :bro:type:`event` Generated each time a remote state access has been replayed locally. :bro:id:`remote_state_inconsistency`: :bro:type:`event` Generated if state synchronization detects an inconsistency. :bro:id:`reporter_error`: :bro:type:`event` :bro:attr:`&error_handler` Raised for errors reported via Bro's reporter framework. :bro:id:`reporter_info`: :bro:type:`event` :bro:attr:`&error_handler` Raised for informational messages reported via Bro's reporter framework. :bro:id:`reporter_warning`: :bro:type:`event` :bro:attr:`&error_handler` Raised for warnings reported via Bro's reporter framework. :bro:id:`rexmit_inconsistency`: :bro:type:`event` Generated when Bro detects a TCP retransmission inconsistency. :bro:id:`root_backdoor_signature_found`: :bro:type:`event` Deprecated. :bro:id:`rotate_interval`: :bro:type:`event` Deprecated. :bro:id:`rotate_size`: :bro:type:`event` Deprecated. :bro:id:`scheduled_analyzer_applied`: :bro:type:`event` Generated when a connection is seen that is marked as being expected. :bro:id:`signature_match`: :bro:type:`event` Generated when a signature matches. :bro:id:`software_parse_error`: :bro:type:`event` Generated when a protocol analyzer finds an identification of a software used on a system but cannot parse it. :bro:id:`software_unparsed_version_found`: :bro:type:`event` Generated when a protocol analyzer finds an identification of a software used on a system. :bro:id:`software_version_found`: :bro:type:`event` Generated when a protocol analyzer finds an identification of a software used on a system. :bro:id:`tunnel_changed`: :bro:type:`event` Generated for a connection whose tunneling has changed. :bro:id:`udp_session_done`: :bro:type:`event` Generated when a UDP session for a supported protocol has finished. ======================================================================== ============================================================================= Detailed Interface ~~~~~~~~~~~~~~~~~~ Events ###### .. bro:id:: OS_version_found :Type: :bro:type:`event` (c: :bro:type:`connection`, host: :bro:type:`addr`, OS: :bro:type:`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 :bro:id:`passive_fingerprint_file`. :c: The connection. :host: The host running the reported OS. :OS: The OS version string. .. bro:see:: passive_fingerprint_file software_parse_error software_version_found software_unparsed_version_found generate_OS_version_event .. bro:id:: anonymization_mapping :Type: :bro:type:`event` (orig: :bro:type:`addr`, mapped: :bro:type:`addr`) Deprecated. Will be removed. .. bro:id:: bro_done :Type: :bro: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. .. bro:see:: bro_init .. note:: If Bro terminates due to an invocation of :bro:id:`exit`, then this event is not generated. .. bro:id:: bro_init :Type: :bro: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. .. bro:see:: bro_done .. note:: When a ``bro_init`` handler executes, Bro has not yet seen any input packets and therefore :bro:id:`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:id:: bro_script_loaded :Type: :bro:type:`event` (path: :bro:type:`string`, level: :bro:type:`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``. .. bro:id:: conn_stats :Type: :bro:type:`event` (c: :bro:type:`connection`, os: :bro:type:`endpoint_stats`, rs: :bro:type:`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. .. bro:see:: connection_state_remove .. bro:id:: conn_weird :Type: :bro:type:`event` (name: :bro:type:`string`, c: :bro:type:`connection`, addl: :bro:type:`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. .. bro:see:: 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. .. bro:id:: connection_external :Type: :bro:type:`event` (c: :bro:type:`connection`, tag: :bro:type:`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. .. bro:id:: connection_flow_label_changed :Type: :bro:type:`event` (c: :bro:type:`connection`, is_orig: :bro:type:`bool`, old_label: :bro:type:`count`, new_label: :bro:type:`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. .. bro:see:: connection_established new_connection .. bro:id:: connection_reused :Type: :bro:type:`event` (c: :bro:type:`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. .. bro:see:: 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 .. bro:id:: connection_state_remove :Type: :bro:type:`event` (c: :bro:type:`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. .. bro:see:: 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 .. bro:id:: connection_status_update :Type: :bro:type:`event` (c: :bro:type:`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. .. bro:see:: 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 .. bro:id:: connection_timeout :Type: :bro:type:`event` (c: :bro:type:`connection`) Generated when a TCP connection timed out. This event is raised when no activity was seen for an interval of at least :bro:id:`tcp_connection_linger`, and either one endpoint has already closed the connection or one side never became active. :c: The connection. .. bro:see:: 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 :bro:id:`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). .. bro:id:: content_gap :Type: :bro:type:`event` (c: :bro:type:`connection`, is_orig: :bro:type:`bool`, seq: :bro:type:`count`, length: :bro:type:`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. .. bro:id:: dns_mapping_altered :Type: :bro:type:`event` (dm: :bro:type:`dns_mapping`, old_addrs: :bro:type:`addr_set`, new_addrs: :bro:type:`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. .. bro:see:: dns_mapping_lost_name dns_mapping_new_name dns_mapping_unverified dns_mapping_valid .. bro:id:: dns_mapping_lost_name :Type: :bro:type:`event` (dm: :bro:type:`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. .. bro:see:: dns_mapping_altered dns_mapping_new_name dns_mapping_unverified dns_mapping_valid .. bro:id:: dns_mapping_new_name :Type: :bro:type:`event` (dm: :bro:type:`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. .. bro:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_unverified dns_mapping_valid .. bro:id:: dns_mapping_unverified :Type: :bro:type:`event` (dm: :bro:type:`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. .. bro:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_new_name dns_mapping_valid .. bro:id:: dns_mapping_valid :Type: :bro:type:`event` (dm: :bro:type:`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). .. bro:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_new_name dns_mapping_unverified .. bro:id:: esp_packet :Type: :bro:type:`event` (p: :bro:type:`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. .. bro:see:: new_packet tcp_packet ipv6_ext_headers .. bro:id:: event_queue_flush_point :Type: :bro:type:`event` () Marks a point in the event stream at which the event queue started flushing. .. bro:id:: file_gap :Type: :bro:type:`event` (f: :bro:type:`fa_file`, offset: :bro:type:`count`, len: :bro:type:`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. .. bro:see:: file_new file_over_new_connection file_timeout file_sniff file_state_remove file_reassembly_overflow .. bro:id:: file_new :Type: :bro:type:`event` (f: :bro:type:`fa_file`) Indicates that an analysis of a new file has begun. The analysis can be augmented at this time via :bro:see:`Files::add_analyzer`. :f: The file. .. bro:see:: file_over_new_connection file_timeout file_gap file_sniff file_state_remove .. bro:id:: file_opened :Type: :bro:type:`event` (f: :bro:type:`file`) Generated each time Bro's script interpreter opens a file. This event is triggered only for files opened via :bro:id:`open`, and in particular not for normal log files as created by log writers. :f: The opened file. .. bro:id:: file_over_new_connection :Type: :bro:type:`event` (f: :bro:type:`fa_file`, c: :bro:type:`connection`, is_orig: :bro:type:`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. .. bro:see:: file_new file_timeout file_gap file_sniff file_state_remove .. bro:id:: file_reassembly_overflow :Type: :bro:type:`event` (f: :bro:type:`fa_file`, offset: :bro:type:`count`, skipped: :bro:type:`count`) Indicates that the file had an overflow of the reassembly buffer. This is a specialization of the :bro:id:`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. .. bro:see:: 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 .. bro:id:: file_sniff :Type: :bro:type:`event` (f: :bro:type:`fa_file`, meta: :bro:type:`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 :bro:see:`Files::add_analyzer`. The amount of data fed into the file sniffing can be increased or decreased by changing either :bro:see:`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. .. bro:see:: file_over_new_connection file_timeout file_gap file_state_remove .. bro:id:: file_state_remove :Type: :bro:type:`event` (f: :bro:type:`fa_file`) This event is generated each time file analysis is ending for a given file. :f: The file. .. bro:see:: file_new file_over_new_connection file_timeout file_gap file_sniff .. bro:id:: file_timeout :Type: :bro:type:`event` (f: :bro:type:`fa_file`) Indicates that file analysis has timed out because no activity was seen for the file in a while. :f: The file. .. bro:see:: file_new file_over_new_connection file_gap file_sniff file_state_remove default_file_timeout_interval Files::set_timeout_interval .. bro:id:: finished_send_state :Type: :bro:type:`event` (p: :bro:type:`event_peer`) Generated after a call to :bro:id:`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. .. bro:see:: 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 .. bro:id:: flow_weird :Type: :bro:type:`event` (name: :bro:type:`string`, src: :bro:type:`addr`, dst: :bro:type:`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. .. bro:see:: 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. .. bro:id:: gaobot_signature_found :Type: :bro:type:`event` (c: :bro:type:`connection`) Deprecated. Will be removed. .. bro:id:: get_file_handle :Type: :bro:type:`event` (tag: :bro:type:`Analyzer::Tag`, c: :bro:type:`connection`, is_orig: :bro:type:`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 :bro:see:`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. .. bro:see:: set_file_handle .. bro:id:: ipv6_ext_headers :Type: :bro:type:`event` (c: :bro:type:`connection`, p: :bro:type:`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. .. bro:see:: new_packet tcp_packet packet_contents esp_packet .. bro:id:: kazaa_signature_found :Type: :bro:type:`event` (c: :bro:type:`connection`) Deprecated. Will be removed. .. bro:id:: load_sample :Type: :bro:type:`event` (samples: :bro:type:`load_sample_info`, CPU: :bro:type:`interval`, dmem: :bro:type:`int`) Generated regularly for the purpose of profiling Bro's processing. This event is raised for every :bro:id:`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. .. bro:id:: mobile_ipv6_message :Type: :bro:type:`event` (p: :bro:type:`pkt_hdr`) Generated for any packet using a Mobile IPv6 Mobility Header. :p: Information from the header of the packet that triggered the event. .. bro:see:: new_packet tcp_packet ipv6_ext_headers .. bro:id:: napster_signature_found :Type: :bro:type:`event` (c: :bro:type:`connection`) Deprecated. Will be removed. .. bro:id:: net_weird :Type: :bro:type:`event` (name: :bro:type:`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. .. bro:see:: 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. .. bro:id:: new_connection :Type: :bro:type:`event` (c: :bro:type:`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. .. bro:see:: 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. .. bro:id:: new_event :Type: :bro:type:`event` (name: :bro:type:`string`, params: :bro:type:`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. .. bro:id:: new_packet :Type: :bro:type:`event` (c: :bro:type:`connection`, p: :bro:type:`pkt_hdr`) Generated for all packets that make it into Bro's connection processing. In contrast to :bro:id:`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. .. bro:see:: tcp_packet packet_contents raw_packet .. bro:id:: packet_contents :Type: :bro:type:`event` (c: :bro:type:`connection`, contents: :bro:type:`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 :bro:id:`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. .. bro:see:: new_packet tcp_packet .. bro:id:: print_hook :Type: :bro:type:`event` (f: :bro:type:`file`, s: :bro:type:`string`) Deprecated. Will be removed. .. bro:id:: profiling_update :Type: :bro:type:`event` (f: :bro:type:`file`, expensive: :bro:type:`bool`) Generated each time Bro's internal profiling log is updated. The file is defined by :bro:id:`profiling_file`, and its update frequency by :bro:id:`profiling_interval` and :bro:id:`expensive_profiling_multiple`. :f: The profiling file. :expensive: True if this event corresponds to heavier-weight profiling as indicated by the :bro:id:`expensive_profiling_multiple` variable. .. bro:see:: profiling_interval expensive_profiling_multiple .. bro:id:: protocol_confirmation :Type: :bro:type:`event` (c: :bro:type:`connection`, atype: :bro:type:`Analyzer::Tag`, aid: :bro:type:`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 :bro:id:`disable_analyzer`. .. bro:see:: protocol_violation .. note:: Bro's default scripts use this event to determine the ``service`` column of :bro:type:`Conn::Info`: once confirmed, the protocol will be listed there (and thus in ``conn.log``). .. bro:id:: protocol_violation :Type: :bro:type:`event` (c: :bro:type:`connection`, atype: :bro:type:`Analyzer::Tag`, aid: :bro:type:`count`, reason: :bro:type:`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 :bro:id:`disable_analyzer`. :reason: TODO. .. bro:see:: protocol_confirmation .. note:: Bro's default scripts use this event to disable an analyzer via :bro:id:`disable_analyzer` if it's parsing the wrong protocol. That's however a script-level decision and not done automatically by the event engine. .. bro:id:: raw_packet :Type: :bro:type:`event` (p: :bro:type:`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. .. bro:see:: new_packet packet_contents .. bro:id:: remote_capture_filter :Type: :bro:type:`event` (p: :bro:type:`event_peer`, filter: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_connection_closed :Type: :bro:type:`event` (p: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_connection_error :Type: :bro:type:`event` (p: :bro:type:`event_peer`, reason: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_connection_established :Type: :bro:type:`event` (p: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_connection_handshake_done :Type: :bro:type:`event` (p: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_event_registered :Type: :bro:type:`event` (p: :bro:type:`event_peer`, name: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_log :Type: :bro:type:`event` (level: :bro:type:`count`, src: :bro:type:`count`, msg: :bro:type:`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 :bro:id:`REMOTE_LOG_INFO` or :bro:id:`REMOTE_LOG_ERROR`. :src: The component of the communication system that logged the message. Currently, this will be one of :bro:id:`REMOTE_SRC_CHILD` (Bro's child process), :bro:id:`REMOTE_SRC_PARENT` (Bro's main process), or :bro:id:`REMOTE_SRC_SCRIPT` (the script level). :msg: The message logged. .. bro:see:: 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 .. bro:id:: remote_log_peer :Type: :bro:type:`event` (p: :bro:type:`event_peer`, level: :bro:type:`count`, src: :bro:type:`count`, msg: :bro:type:`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 :bro:see:`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 :bro:id:`REMOTE_LOG_INFO` or :bro:id:`REMOTE_LOG_ERROR`. :src: The component of the communication system that logged the message. Currently, this will be one of :bro:id:`REMOTE_SRC_CHILD` (Bro's child process), :bro:id:`REMOTE_SRC_PARENT` (Bro's main process), or :bro:id:`REMOTE_SRC_SCRIPT` (the script level). :msg: The message logged. .. bro:see:: 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 .. bro:id:: remote_pong :Type: :bro:type:`event` (p: :bro:type:`event_peer`, seq: :bro:type:`count`, d1: :bro:type:`interval`, d2: :bro:type:`interval`, d3: :bro:type:`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 :bro:id:`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 :bro:id:`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. .. bro:see:: 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 .. bro:id:: remote_state_access_performed :Type: :bro:type:`event` (id: :bro:type:`string`, v: :bro:type:`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. .. bro:see:: 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 .. bro:id:: remote_state_inconsistency :Type: :bro:type:`event` (operation: :bro:type:`string`, id: :bro:type:`string`, expected_old: :bro:type:`string`, real_old: :bro:type:`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 :bro:id:`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. .. bro:see:: 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 .. bro:id:: reporter_error :Type: :bro:type:`event` (t: :bro:type:`time`, msg: :bro:type:`string`, location: :bro:type:`string`) :Attributes: :bro:attr:`&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 :bro:id:`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. .. bro:see:: 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. .. bro:id:: reporter_info :Type: :bro:type:`event` (t: :bro:type:`time`, msg: :bro:type:`string`, location: :bro:type:`string`) :Attributes: :bro:attr:`&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 :bro:id:`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. .. bro:see:: 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. .. bro:id:: reporter_warning :Type: :bro:type:`event` (t: :bro:type:`time`, msg: :bro:type:`string`, location: :bro:type:`string`) :Attributes: :bro:attr:`&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 :bro:id:`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. .. bro:see:: 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. .. bro:id:: rexmit_inconsistency :Type: :bro:type:`event` (c: :bro:type:`connection`, t1: :bro:type:`string`, t2: :bro:type:`string`, tcp_flags: :bro:type:`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 :bro:id:`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". .. bro:see:: tcp_rexmit tcp_contents .. bro:id:: root_backdoor_signature_found :Type: :bro:type:`event` (c: :bro:type:`connection`) Deprecated. Will be removed. .. bro:id:: rotate_interval :Type: :bro:type:`event` (f: :bro:type:`file`) Deprecated. Will be removed. .. bro:id:: rotate_size :Type: :bro:type:`event` (f: :bro:type:`file`) Deprecated. Will be removed. .. bro:id:: scheduled_analyzer_applied :Type: :bro:type:`event` (c: :bro:type:`connection`, a: :bro:type:`Analyzer::Tag`) Generated when a connection is seen that is marked as being expected. The function :bro:id:`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 :bro:id:`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``. .. bro:see:: 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. .. bro:id:: signature_match :Type: :bro:type:`event` (state: :bro:type:`signature_state`, msg: :bro:type:`string`, data: :bro:type:`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 :doc:`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. .. bro:id:: software_parse_error :Type: :bro:type:`event` (c: :bro:type:`connection`, host: :bro:type:`addr`, descr: :bro:type:`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 :bro:id:`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. .. bro:see:: software_version_found software_unparsed_version_found OS_version_found .. bro:id:: software_unparsed_version_found :Type: :bro:type:`event` (c: :bro:type:`connection`, host: :bro:type:`addr`, str: :bro:type:`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 :bro:id:`software_version_found` and :bro:id:`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. .. bro:see:: software_parse_error software_version_found OS_version_found .. bro:id:: software_version_found :Type: :bro:type:`event` (c: :bro:type:`connection`, host: :bro:type:`addr`, s: :bro:type:`software`, descr: :bro:type:`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, :bro:id:`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. .. bro:see:: software_parse_error software_unparsed_version_found OS_version_found .. bro:id:: tunnel_changed :Type: :bro:type:`event` (c: :bro:type:`connection`, e: :bro:type:`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. .. bro:id:: udp_session_done :Type: :bro:type:`event` (u: :bro:type:`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. .. bro:see:: udp_contents udp_reply udp_request