mirror of
https://github.com/zeek/zeek.git
synced 2025-10-07 17:18:20 +00:00
7e9d48f532
The broxygen-generated files now live in the git repo, have tests that check that they are up-to-date, and a script to re-generate them on-demand.
1507 lines
61 KiB
ReStructuredText
1507 lines
61 KiB
ReStructuredText
: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
|
|
<http://lcamtuf.coredump.cx/p0f.shtml>`__ 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 </frameworks/signatures>` 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
|
|
|
|
|