event.bif.zeek¶

GLOBAL¶

The protocol-independent events that the C/C++ core of Zeek 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¶

`Pcap::file_done`: `event`	An event that signals a pcap file is done being processed.
`analyzer_confirmation`: `event` `&deprecated` = …	Generated when a protocol analyzer confirms that a connection is indeed using that protocol.
`analyzer_confirmation_info`: `event`	Generated when an analyzer confirms successful parsing of a protocol, file, or packets.
`analyzer_violation`: `event` `&deprecated` = …	Generated when a protocol analyzer determines that a connection it is parsing is not conforming to the protocol it expects.
`analyzer_violation_info`: `event`	Generated for analyzer violations when parsing of a protocol, file, or packet.
`anonymization_mapping`: `event`	Shows an IP address anonymization mapping.
`conn_stats`: `event`	Generated when a TCP connection terminated, passing on statistics about the two endpoints.
`conn_weird`: `event`	Generated for unexpected activity related to a specific connection.
`connection_flow_label_changed`: `event`	Generated for a connection over IPv6 when one direction has changed the flow label that it’s using.
`connection_reused`: `event`	Generated when a connection 4-tuple is reused.
`connection_state_remove`: `event`	Generated when a connection’s internal state is about to be removed from memory.
`connection_status_update`: `event`	Generated in regular intervals during the lifetime of a connection.
`connection_timeout`: `event`	Generated when a TCP connection timed out.
`content_gap`: `event`	Generated when Zeek detects a gap in a reassembled TCP payload stream.
`dns_mapping_altered`: `event`	Generated when an internal DNS lookup produced a different result than in the past.
`dns_mapping_lost_name`: `event`	Generated when an internal DNS lookup returned zero answers even though it had succeeded in the past.
`dns_mapping_name_changed`: `event`	Generated when an internal DNS lookup returns a different host name than in the past.
`dns_mapping_new_name`: `event`	Generated when an internal DNS lookup succeeded but an earlier attempt did not.
`dns_mapping_unverified`: `event`	Generated when an internal DNS lookup got no answer even though it had succeeded in the past.
`dns_mapping_valid`: `event`	Generated when an internal DNS lookup produces the same result as last time.
`esp_packet`: `event`	Generated for any packets using the IPv6 Encapsulating Security Payload (ESP) extension header.
`event_queue_flush_point`: `event`	Marks a point in the event stream at which the event queue started flushing.
`expired_conn_weird`: `event`	Generated for unexpected activity related to a specific connection whose internal state has already been expired.
`file_gap`: `event`	Indicates that a chunk of the file is missing.
`file_new`: `event`	Indicates that analysis of a new file has begun.
`file_opened`: `event`	Generated each time Zeek’s script interpreter opens a file.
`file_over_new_connection`: `event`	Indicates that Zeek has begun to observe a file for the first time on the given connection.
`file_reassembly_overflow`: `event`	Indicates that the file had an overflow of the reassembly buffer.
`file_sniff`: `event`	Provide all metadata that has been inferred about a particular file from inspection of the initial content that been seen at the beginning of the file.
`file_state_remove`: `event`	This event is generated each time file analysis is ending for a given file.
`file_timeout`: `event`	Indicates that file analysis has timed out because no activity was seen for the file in a while.
`file_weird`: `event`	Generated for unexpected activity that is tied to a file.
`flow_weird`: `event`	Generated for unexpected activity related to a pair of hosts, but independent of a specific connection.
`get_file_handle`: `event`	This event is handled to provide feedback to the file analysis framework about how to identify the logical “file” to which some data/input belongs.
`ipv6_ext_headers`: `event`	Generated for every IPv6 packet that contains extension headers.
`load_sample`: `event`	Generated regularly for the purpose of profiling Zeek’s processing.
`mobile_ipv6_message`: `event`	Generated for any packet using a Mobile IPv6 Mobility Header.
`net_done`: `event`	Generated as one of the first steps of Zeek’s main-loop termination, just before it starts to flush any remaining events/timers/state.
`net_weird`: `event`	Generated for unexpected activity that is not tied to a specific connection or pair of hosts.
`network_time_init`: `event`	Generated when network time is initialized.
`new_connection`: `event`	Generated for every new connection.
`new_event`: `event`	A meta event generated for events that Zeek raises.
`new_packet`: `event`	Generated for all packets that make it into Zeek’s connection processing.
`packet_contents`: `event`	Generated for every packet that has a non-empty transport-layer payload.
`packet_not_processed`: `event`	An event for handling packets that reached the end of processing without being marked as processed.
`profiling_update`: `event`	Generated each time Zeek’s internal profiling log is updated.
`protocol_late_match`: `event`	Generated if a DPD signature matched but the DPD buffer is already exhausted and thus the analyzer could not be attached.
`raw_packet`: `event`	Generated for every packet Zeek sees that have a valid link-layer header.
`reporter_error`: `event` `&error_handler`	Raised for errors reported via Zeek’s reporter framework.
`reporter_info`: `event` `&error_handler`	Raised for informational messages reported via Zeek’s reporter framework.
`reporter_warning`: `event` `&error_handler`	Raised for warnings reported via Zeek’s reporter framework.
`rexmit_inconsistency`: `event`	Generated when Zeek detects a TCP retransmission inconsistency.
`scheduled_analyzer_applied`: `event`	Generated when a connection is seen that is marked as being expected.
`signature_match`: `event`	Generated when a signature matches.
`tunnel_changed`: `event`	Generated for a connection whose tunneling has changed.
`udp_session_done`: `event`	Generated when a UDP session for a supported protocol has finished.
`unknown_protocol`: `event`	Generated when a packet analyzer attempts to forward a protocol that it doesn’t know how to handle.
`zeek_done`: `event`	Generated at Zeek termination time.
`zeek_init`: `event`	Generated at Zeek initialization time.
`zeek_script_loaded`: `event`	Raised for each policy script loaded by the script interpreter.

Detailed Interface¶

Events¶

Pcap::file_done¶

Type: event (path: string)

An event that signals a pcap file is done being processed.

Parameters: path – the filesystem path of the pcap file

analyzer_confirmation¶

Type: event (c: connection, atype: AllAnalyzers::Tag, aid: count)
Attributes: &deprecated = “Remove in 6.1. Use the generic analyzer_confirmation_info event instead.”

Generated when a protocol analyzer confirms that a connection is indeed using that protocol. Zeek’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.

Parameters

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

Note

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

analyzer_confirmation_info¶

Type: event (atype: AllAnalyzers::Tag, info: AnalyzerConfirmationInfo)

Generated when an analyzer confirms successful parsing of a protocol, file, or packets.

Parameters

atype – The type of the analyzer confirming analysis. The value may be associated with a protocol, file or packet analyzer.
info – Details about the confirmation, which may include a connection object or fa_file object related to the confirmation.

Note

For packet analyzers, a confirmation is only raised if there’s a session (connection) associated with a given packet. Confirmations are raised only once per session. Tunnel protocols like VXLAN or Geneve are examples for this behavior.

analyzer_violation¶

Type: event (c: connection, atype: AllAnalyzers::Tag, aid: count, reason: string)
Attributes: &deprecated = “Remove in 6.1. Use the generic analyzer_violation_info event instead.”

Generated when a protocol analyzer determines that a connection it is parsing is not conforming to the protocol it expects. Zeek’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.

Parameters

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

Note

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

analyzer_violation_info¶

Type: event (atype: AllAnalyzers::Tag, info: AnalyzerViolationInfo)

Generated for analyzer violations when parsing of a protocol, file, or packet.

Parameters

atype – The type of the analyzer reporting the violation. The value may be associated with a protocol, file or packet analyzer.
info – Details about the violation. This record may include a connection object or fa_file and optionally the raw data as string related to this violation.

anonymization_mapping¶

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

Shows an IP address anonymization mapping.

conn_stats¶

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

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

Parameters

c – The connection.
os – Statistics for the originator endpoint.
rs – Statistics for the responder endpoint.

See also: connection_state_remove

conn_weird¶

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

Generated for unexpected activity related to a specific connection. When Zeek’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.

Parameters

name – A unique name for the specific type of “weird” situation. Zeek’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.
source – Optional source for the weird. When called by analyzers, this should be filled in with the name of the analyzer.

Note

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

connection_flow_label_changed¶

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

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

Parameters

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.

connection_reused ¶

Type: event (c: connection)

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

Parameters: c – The connection.

connection_state_remove¶

Type: event (c: connection)

Generated when a connection’s internal state is about to be removed from memory. Zeek 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.

Parameters: c – The connection.

connection_status_update¶

Type: event (c: connection)

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

Parameters: c – The connection.

connection_timeout¶

Type: event (c: connection)

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

Parameters: c – The connection.

Note

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

content_gap¶

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

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

Parameters

c – The connection.
is_orig – True if the gap is on the originator’s side.
seq – The sequence number where the gap starts.
length – The number of bytes missing.

Note

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

dns_mapping_altered¶

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

Generated when an internal DNS lookup produced a different result than in the past. Zeek 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.

Parameters

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.

dns_mapping_lost_name¶

Type: event (dm: dns_mapping)

Generated when an internal DNS lookup returned zero answers even though it had succeeded in the past. Zeek 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.

Parameters: dm – A record describing the old resolver result.

dns_mapping_name_changed¶

Type: event (prev: dns_mapping, latest: dns_mapping)

Generated when an internal DNS lookup returns a different host name than in the past. Zeek 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 has a different host string than we already have in the cache.

Parameters

prev – A record describing the old resolver result.
latest – A record describing the new resolver result.

dns_mapping_new_name¶

Type: event (dm: dns_mapping)

Generated when an internal DNS lookup succeeded but an earlier attempt did not. Zeek 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.

Parameters: dm – A record describing the new resolver result.

dns_mapping_unverified¶

Type: event (dm: dns_mapping)

Generated when an internal DNS lookup got no answer even though it had succeeded in the past. Zeek 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.

Parameters: dm – A record describing the old resolver result.

dns_mapping_valid¶

Type: event (dm: dns_mapping)

Generated when an internal DNS lookup produces the same result as last time. Zeek 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.

Parameters: dm – A record describing the new resolver result (which matches the old one).

esp_packet¶

Type: event (p: pkt_hdr)

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

Parameters: p – Information from the header of the packet that triggered the event.

event_queue_flush_point¶

Type: event ()

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

expired_conn_weird ¶

Type: event (name: string, id: conn_id, uid: string, addl: string, source: string)
Type: event (name: string, id: conn_id, uid: string, addl: string)

Generated for unexpected activity related to a specific connection whose internal state has already been expired. That is to say, Reporter::conn_weird may have been called from a script, but the internal connection object/state was expired and so the full connection record is no longer available, just the UID and conn_id. When Zeek’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.

Parameters

name – A unique name for the specific type of “weird” situation. Zeek’s default scripts use this name in filtering policies that specify which “weirds” are worth reporting.
id – The tuple associated with a previously-expired connection.
uid – The UID string associated with a previously-expired connection.
addl – Optional additional context further describing the situation.
source – Optional source for the weird. When called by analyzers, this should be filled in with the name of the analyzer.

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.

file_gap¶

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

Indicates that a chunk of the file is missing.

Parameters

f – The file.
offset – The byte offset from the start of the file at which the gap begins.
len – The number of missing bytes.

file_new¶

Type: event (f: fa_file)

Indicates that analysis of a new file has begun. The analysis can be augmented at this time via Files::add_analyzer. This event triggers once when Zeek first establishes state for the file. Zeek does not base identity on content (it cannot, since analysis has only just begun), but on the relevant protocol analyzer’s notion of file identity as per the get_file_handle/set_file_handle mechanism. That is, Zeek triggers this event whenever a protocol analyzer thinks it’s encountering a new file.

Parameters: f – The file.

file_opened¶

Type: event (f: file)

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

Parameters: f – The opened file.

file_over_new_connection¶

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

Indicates that Zeek has begun to observe a file for the first time on the given connection. This is similar to file_new, but also triggers once on each subsequent connection in which the relevant protocol analyzer encounters any part of the file. As with file_new, the protocol analyzer defines file identity. When Zeek encounters a file for the first time, it first triggers file_new, then file_over_new_connection.

Parameters

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.

file_reassembly_overflow¶

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

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

Parameters

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.

file_sniff¶

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

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

Parameters

f – The file.
meta – Metadata that’s been discovered about the file.

file_state_remove¶

Type: event (f: fa_file)

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

Parameters: f – The file.

file_timeout ¶

Type: event (f: fa_file)

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

Parameters: f – The file.

file_weird ¶

Type: event (name: string, f: fa_file, addl: string, source: string)
Type: event (name: string, f: fa_file, addl: string)

Generated for unexpected activity that is tied to a file. When Zeek’s packet analysis encounters activity that does not conform to a protocol’s specification, it raises one of the *_weird events to report that.

Parameters

name – A unique name for the specific type of “weird” situation. Zeek’s default scripts use this name in filtering policies that specify which “weirds” are worth reporting.
f – The corresponding file.
addl – Additional information related to the weird.
source – The name of the file analyzer that generated the 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.

flow_weird ¶

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

Generated for unexpected activity related to a pair of hosts, but independent of a specific connection. When Zeek’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.

Parameters

name – A unique name for the specific type of “weird” situation. Zeek’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.
addl – Optional additional context further describing the situation.
source – Optional source for the weird. When called by analyzers, this should be filled in with the name of the analyzer.

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.

get_file_handle ¶

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

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

Parameters

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.