base/bif/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_info: event

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

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_flipped: event

Generated for a connection when the direction was flipped by Zeek’s heuristics and originator and responder roles were reversed.

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.

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_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.

See also: is_protocol_analyzer, is_packet_analyzer, is_file_analyzer

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.

See also: is_protocol_analyzer, is_packet_analyzer, is_file_analyzer

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.

See also: flow_weird, net_weird, file_weird, expired_conn_weird

Note

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

connection_flipped
Type

event (c: connection)

Generated for a connection when the direction was flipped by Zeek’s heuristics and originator and responder roles were reversed. If state is kept on a connection record for originator and responder, this event can be used to update or reset such state. The orig and resp fields as well as the contents of the id field reflect the post-flip state.

Parameters

c – The connection.

See also: connection_established, new_connection

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.

See also: connection_established, new_connection

connection_reused
Type

event (c: connection)

Generated when a connection 4-tuple is reused. This event is raised when 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.

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

connection_state_remove
Type

event (c: connection)

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

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

connection_status_update
Type

event (c: connection)

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

Parameters

c – The connection.

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

connection_timeout
Type

event (c: connection)

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

Parameters

c – The connection.

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

Note

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

content_gap
Type

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

Generated when 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.

See also: dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_lost_name
Type

event (dm: dns_mapping)

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

See also: dns_mapping_altered, dns_mapping_new_name, dns_mapping_unverified, dns_mapping_valid

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.

See also: dns_mapping_altered, dns_mapping_new_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_new_name
Type

event (dm: dns_mapping)

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

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_unverified, dns_mapping_valid

dns_mapping_unverified
Type

event (dm: dns_mapping)

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

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_valid

dns_mapping_valid
Type

event (dm: dns_mapping)

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

See also: dns_mapping_altered, dns_mapping_lost_name, dns_mapping_new_name, dns_mapping_unverified

esp_packet
Type

event (p: pkt_hdr)

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

Parameters

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

See also: new_packet, tcp_packet, ipv6_ext_headers

event_queue_flush_point
Type

event ()

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

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.

See also: flow_weird, net_weird, file_weird, conn_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.

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.

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

file_new
Type

event (f: fa_file)

Indicates that 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.

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

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.

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

file_reassembly_overflow
Type

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

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

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.

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

file_sniff
Type

event (f: fa_file, meta: fa_metadata)

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

Parameters
  • f – The file.

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

See also: file_over_new_connection, file_timeout, file_gap, file_state_remove

file_state_remove
Type

event (f: fa_file)

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

Parameters

f – The file.

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

file_timeout
Type

event (f: fa_file)

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

Parameters

f – The file.

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

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.

See also: flow_weird, net_weird, conn_weird, expired_conn_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.

See also: conn_weird, net_weird, file_weird, expired_conn_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.

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.

See also: set_file_handle

ipv6_ext_headers
Type

event (c: connection, p: pkt_hdr)

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

Parameters
  • c – The connection the packet is part of.

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

See also: new_packet, tcp_packet, packet_contents, esp_packet

mobile_ipv6_message
Type

event (p: pkt_hdr)

Generated for any packet using a Mobile IPv6 Mobility Header.

Parameters

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

See also: new_packet, tcp_packet, ipv6_ext_headers

net_done
Type

event (t: time)

Generated as one of the first steps of Zeek’s main-loop termination, just before it starts to flush any remaining events/timers/state. The event engine generates this event when Zeek is about to terminate, either due to having exhausted reading its input trace file(s), receiving a termination signal, or because Zeek was run without a network input source and has finished executing any global statements. This event comes before zeek_done.

Parameters

t – The time at with the Zeek-termination process started.

See also: zeek_init, zeek_done

Note

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

net_weird
Type

event (name: string, addl: string, source: string)

Type

event (name: string, addl: string)

Generated for unexpected activity that is not tied to a specific connection or pair of hosts. 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 not tied directly to a specific connection or pair of hosts.

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.

  • 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.

See also: flow_weird, file_weird, conn_weird, expired_conn_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.

network_time_init
Type

event ()

Generated when network time is initialized. The event engine generates this event after the network time has been determined but before processing of packets is started.

See also: zeek_init, network_time

new_connection
Type

event (c: connection)

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

Parameters

c – The connection.

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

Note

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

new_event
Type

event (name: string, params: call_argument_vector)

A meta event generated for events that Zeek 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.

Parameters
  • name – The name of the event.

  • params – The event’s parameters.

new_packet
Type

event (c: connection, p: pkt_hdr)

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

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

Parameters
  • c – The connection the packet is part of.

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

See also: tcp_packet, packet_contents, raw_packet

packet_contents
Type

event (c: connection, contents: string)

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

Parameters
  • c – The connection the packet is part of.

  • contents – The raw transport-layer payload.

See also: new_packet, tcp_packet

packet_not_processed
Type

event (pkt: pcap_packet)

An event for handling packets that reached the end of processing without being marked as processed. Note that this event may lead to unpredictable performance spikes, particularly if a network suddenly receives a burst of packets that are unprocessed.

Parameters

pkt – Data for the unprocessed packet

profiling_update
Type

event (f: file, expensive: bool)

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

Parameters
  • f – The profiling file.

  • expensive – True if this event corresponds to heavier-weight profiling as indicated by the expensive_profiling_multiple variable.

See also: profiling_interval, expensive_profiling_multiple

protocol_late_match
Type

event (c: connection, atype: Analyzer::Tag)

Generated if a DPD signature matched but the DPD buffer is already exhausted and thus the analyzer could not be attached. While this does not confirm that a protocol is actually used, it allows to retain that information.

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.

See also: dpd_buffer_size, dpd_max_packets

raw_packet
Type

event (p: raw_pkt_hdr)

Generated for every packet Zeek 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.

Parameters

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

See also: new_packet, packet_contents

reporter_error
Type

event (t: time, msg: string, location: string)

Attributes

&error_handler

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

Parameters
  • t – The time the error was passed to the reporter.

  • msg – The error message.

  • location – A (potentially empty) string describing a location associated with the error.

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

Note

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

reporter_info
Type

event (t: time, msg: string, location: string)

Attributes

&error_handler

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

Parameters
  • t – The time the message was passed to the reporter.

  • msg – The message itself.

  • location – A (potentially empty) string describing a location associated with the message.

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

Note

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

reporter_warning
Type

event (t: time, msg: string, location: string)

Attributes

&error_handler

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

Parameters
  • t – The time the warning was passed to the reporter.

  • msg – The warning message.

  • location – A (potentially empty) string describing a location associated with the warning.

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

Note

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

rexmit_inconsistency
Type

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

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

Parameters
  • 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; U -> URGENT. This string will not always be set, only if the information is available; it’s “best effort”.

See also: tcp_rexmit, tcp_contents

scheduled_analyzer_applied
Type

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

Generated when a connection is seen that is marked as being expected. The function Analyzer::schedule_analyzer tells Zeek 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.

Parameters
  • c – The connection.

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

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

Todo

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

signature_match
Type

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

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

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

Parameters
  • 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 Zeek 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.

tunnel_changed
Type

event (c: connection, e: EncapsulatingConnVector)

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

Parameters
  • c – The connection whose tunnel/encapsulation changed.

  • e – The new encapsulation.

udp_session_done
Type

event (u: connection)

Generated when a UDP session for a supported protocol has finished. Some of Zeek’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.

Parameters

u – The connection record for the corresponding UDP flow.

See also: udp_contents, udp_reply, udp_request

unknown_protocol
Type

event (analyzer_name: string, protocol: count, first_bytes: string)

Generated when a packet analyzer attempts to forward a protocol that it doesn’t know how to handle.

Parameters
  • analyzer_name – The string name of the analyzer attempting to forward the protocol

  • protocol – The identifier of the protocol being forwarded

  • first_bytes – A certain number of bytes at the start of the unknown protocol’s header.

See also: UnknownProtocol::first_bytes_count

zeek_done
Type

event ()

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

See also: zeek_init

Note

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

zeek_init
Type

event ()

Generated at Zeek 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, Zeek will have executed any global initializations and statements.

See also: zeek_done, network_time_init

Note

When a zeek_init handler executes, Zeek has not yet seen any input packets and therefore network_time is not initialized yet. An artifact of that is that any timer installed in a zeek_init handler, like with schedule, 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 or to instead schedule the first event from with the network_time_init event.

zeek_script_loaded
Type

event (path: string, level: count)

Raised for each policy script loaded by the script interpreter.

Parameters
  • path – The full path to the script loaded.

  • level – The “nesting level”: zero for a top-level Zeek script and incremented recursively for each @load.