Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 22:58:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3
zeek/doc/scripts/base/bif/event.bif.zeek.rst
Tim Wojtulewicz ded98cd373 Copy docs into Zeek repo directly 
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.
2025-09-26 02:58:29 +00:00

1332 lines
58 KiB
ReStructuredText
Raw Permalink Blame History

:tocdepth: 3
base/bif/event.bif.zeek
=======================
.. zeek:namespace:: 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
######
=========================================================================== =======================================================================================
:zeek:id:`Pcap::file_done`: :zeek:type:`event` An event that signals a pcap file is done being processed.
:zeek:id:`analyzer_confirmation_info`: :zeek:type:`event` Generated when an analyzer confirms successful parsing of a protocol, file, or packets.
:zeek:id:`analyzer_violation_info`: :zeek:type:`event` Generated for analyzer violations when parsing of a protocol, file, or packet.
:zeek:id:`anonymization_mapping`: :zeek:type:`event` Shows an IP address anonymization mapping.
:zeek:id:`conn_stats`: :zeek:type:`event` Generated when a TCP connection terminated, passing on statistics about the
two endpoints.
:zeek:id:`conn_weird`: :zeek:type:`event` Generated for unexpected activity related to a specific connection.
:zeek:id:`connection_flipped`: :zeek:type:`event` Generated for a connection when the direction was flipped by Zeek's
heuristics and originator and responder roles were reversed.
:zeek:id:`connection_flow_label_changed`: :zeek:type:`event` Generated for a connection over IPv6 when one direction has changed
the flow label that it's using.
:zeek:id:`connection_reused`: :zeek:type:`event` Generated when a connection 4-tuple is reused.
:zeek:id:`connection_state_remove`: :zeek:type:`event` Generated when a connection's internal state is about to be removed from
memory.
:zeek:id:`connection_status_update`: :zeek:type:`event` Generated in regular intervals during the lifetime of a connection.
:zeek:id:`connection_timeout`: :zeek:type:`event` Generated when a TCP connection timed out.
:zeek:id:`content_gap`: :zeek:type:`event` Generated when Zeek detects a gap in a reassembled TCP payload stream.
:zeek:id:`dns_mapping_altered`: :zeek:type:`event` Generated when an internal DNS lookup produced a different result than in
the past.
:zeek:id:`dns_mapping_lost_name`: :zeek:type:`event` Generated when an internal DNS lookup returned zero answers even though it
had succeeded in the past.
:zeek:id:`dns_mapping_name_changed`: :zeek:type:`event` Generated when an internal DNS lookup returns a different host name than
in the past.
:zeek:id:`dns_mapping_new_name`: :zeek:type:`event` Generated when an internal DNS lookup succeeded but an earlier attempt
did not.
:zeek:id:`dns_mapping_unverified`: :zeek:type:`event` Generated when an internal DNS lookup got no answer even though it had
succeeded in the past.
:zeek:id:`dns_mapping_valid`: :zeek:type:`event` Generated when an internal DNS lookup produces the same result as last time.
:zeek:id:`esp_packet`: :zeek:type:`event` Generated for any packets using the IPv6 Encapsulating Security Payload (ESP)
extension header.
:zeek:id:`event_queue_flush_point`: :zeek:type:`event` Marks a point in the event stream at which the event queue started flushing.
:zeek:id:`expired_conn_weird`: :zeek:type:`event` Generated for unexpected activity related to a specific connection whose
internal state has already been expired.
:zeek:id:`file_gap`: :zeek:type:`event` Indicates that a chunk of the file is missing.
:zeek:id:`file_new`: :zeek:type:`event` Indicates that analysis of a new file has begun.
:zeek:id:`file_opened`: :zeek:type:`event` Generated each time Zeek's script interpreter opens a file.
:zeek:id:`file_over_new_connection`: :zeek:type:`event` Indicates that Zeek has begun to observe a file for the first time on the
given connection.
:zeek:id:`file_reassembly_overflow`: :zeek:type:`event` Indicates that the file had an overflow of the reassembly buffer.
:zeek:id:`file_sniff`: :zeek: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.
:zeek:id:`file_state_remove`: :zeek:type:`event` This event is generated each time file analysis is ending for a given file.
:zeek:id:`file_timeout`: :zeek:type:`event` Indicates that file analysis has timed out because no activity was seen
for the file in a while.
:zeek:id:`file_weird`: :zeek:type:`event` Generated for unexpected activity that is tied to a file.
:zeek:id:`flow_weird`: :zeek:type:`event` Generated for unexpected activity related to a pair of hosts, but independent
of a specific connection.
:zeek:id:`get_file_handle`: :zeek: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.
:zeek:id:`ipv6_ext_headers`: :zeek:type:`event` Generated for every IPv6 packet that contains extension headers.
:zeek:id:`mobile_ipv6_message`: :zeek:type:`event` Generated for any packet using a Mobile IPv6 Mobility Header.
:zeek:id:`net_done`: :zeek:type:`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.
:zeek:id:`net_weird`: :zeek:type:`event` Generated for unexpected activity that is not tied to a specific connection
or pair of hosts.
:zeek:id:`network_time_init`: :zeek:type:`event` Generated when network time is initialized.
:zeek:id:`new_connection`: :zeek:type:`event` Generated for every new connection.
:zeek:id:`new_event`: :zeek:type:`event` A meta event generated for events that Zeek raises.
:zeek:id:`new_packet`: :zeek:type:`event` Generated for all packets that make it into Zeek's connection processing.
:zeek:id:`packet_contents`: :zeek:type:`event` Generated for every packet that has a non-empty transport-layer payload.
:zeek:id:`packet_not_processed`: :zeek:type:`event` An event for handling packets that reached the end of processing without
being marked as processed.
:zeek:id:`profiling_update`: :zeek:type:`event` Generated each time Zeek's internal profiling log is updated.
:zeek:id:`protocol_late_match`: :zeek:type:`event` Generated if a DPD signature matched but the DPD buffer is already exhausted
and thus the analyzer could not be attached.
:zeek:id:`raw_packet`: :zeek:type:`event` Generated for every packet Zeek sees that have a valid link-layer header.
:zeek:id:`reporter_error`: :zeek:type:`event` :zeek:attr:`&error_handler` Raised for errors reported via Zeek's reporter framework.
:zeek:id:`reporter_info`: :zeek:type:`event` :zeek:attr:`&error_handler` Raised for informational messages reported via Zeek's reporter framework.
:zeek:id:`reporter_warning`: :zeek:type:`event` :zeek:attr:`&error_handler` Raised for warnings reported via Zeek's reporter framework.
:zeek:id:`rexmit_inconsistency`: :zeek:type:`event` Generated when Zeek detects a TCP retransmission inconsistency.
:zeek:id:`scheduled_analyzer_applied`: :zeek:type:`event` Generated when a connection is seen that is marked as being expected.
:zeek:id:`signature_match`: :zeek:type:`event` Generated when a signature matches.
:zeek:id:`tunnel_changed`: :zeek:type:`event` Generated for a connection whose tunneling has changed.
:zeek:id:`udp_session_done`: :zeek:type:`event` Generated when a UDP session for a supported protocol has finished.
:zeek:id:`unknown_protocol`: :zeek:type:`event` Generated when a packet analyzer attempts to forward a protocol that it doesn't
know how to handle.
:zeek:id:`zeek_done`: :zeek:type:`event` Generated at Zeek termination time.
:zeek:id:`zeek_init`: :zeek:type:`event` Generated at Zeek initialization time.
:zeek:id:`zeek_script_loaded`: :zeek:type:`event` Raised for each policy script loaded by the script interpreter.
=========================================================================== =======================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Events
######
.. zeek:id:: Pcap::file_done
:source-code: base/bif/event.bif.zeek 948 948
:Type: :zeek:type:`event` (path: :zeek:type:`string`)
An event that signals a pcap file is done being processed.
:param path: the filesystem path of the pcap file
.. zeek:id:: analyzer_confirmation_info
:source-code: base/bif/event.bif.zeek 411 411
:Type: :zeek:type:`event` (atype: :zeek:type:`AllAnalyzers::Tag`, info: :zeek:type:`AnalyzerConfirmationInfo`)
Generated when an analyzer confirms successful parsing of a protocol, file, or packets.
:param atype: The type of the analyzer confirming analysis. The value may be associated
with a protocol, file or packet analyzer.
:param info: Details about the confirmation, which may include a :zeek:type:`connection`
object or :zeek:type:`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.
.. zeek:see:: is_protocol_analyzer is_packet_analyzer is_file_analyzer
.. zeek:id:: analyzer_violation_info
:source-code: base/bif/event.bif.zeek 424 424
:Type: :zeek:type:`event` (atype: :zeek:type:`AllAnalyzers::Tag`, info: :zeek:type:`AnalyzerViolationInfo`)
Generated for analyzer violations when parsing of a protocol, file, or packet.
:param atype: The type of the analyzer reporting the violation. The value may be associated
with a protocol, file or packet analyzer.
:param info: Details about the violation. This record may include a :zeek:type:`connection`
object or :zeek:type:`fa_file` and optionally the raw data as :zeek:type:`string`
related to this violation.
.. zeek:see:: is_protocol_analyzer is_packet_analyzer is_file_analyzer
.. zeek:id:: anonymization_mapping
:source-code: base/bif/event.bif.zeek 942 942
:Type: :zeek:type:`event` (orig: :zeek:type:`addr`, mapped: :zeek:type:`addr`)
Shows an IP address anonymization mapping.
.. zeek:id:: conn_stats
:source-code: base/bif/event.bif.zeek 453 453
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, os: :zeek:type:`endpoint_stats`, rs: :zeek:type:`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.
:param c: The connection.
:param os: Statistics for the originator endpoint.
:param rs: Statistics for the responder endpoint.
.. zeek:see:: connection_state_remove
.. zeek:id:: conn_weird
:source-code: base/bif/event.bif.zeek 479 479
:Type: :zeek:type:`event` (name: :zeek:type:`string`, c: :zeek:type:`connection`, addl: :zeek:type:`string`, source: :zeek:type:`string`)
:Type: :zeek:type:`event` (name: :zeek:type:`string`, c: :zeek:type:`connection`, addl: :zeek:type:`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.
:param 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.
:param c: The corresponding connection.
:param addl: Optional additional context further describing the situation.
:param source: Optional source for the weird. When called by analyzers, this should
be filled in with the name of the analyzer.
.. zeek:see:: 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.
.. zeek:id:: connection_flipped
:source-code: base/protocols/conn/main.zeek 319 327
:Type: :zeek:type:`event` (c: :zeek:type:`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.
:param c: The connection.
.. zeek:see:: connection_established new_connection
.. zeek:id:: connection_flow_label_changed
:source-code: base/bif/event.bif.zeek 236 236
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`, old_label: :zeek:type:`count`, new_label: :zeek:type:`count`)
Generated for a connection over IPv6 when one direction has changed
the flow label that it's using.
:param c: The connection.
:param is_orig: True if the event is raised for the originator side.
:param old_label: The old flow label that the endpoint was using.
:param new_label: The new flow label that the endpoint is using.
.. zeek:see:: connection_established new_connection
.. zeek:id:: connection_reused
:source-code: base/protocols/ftp/main.zeek 460 464
:Type: :zeek:type:`event` (c: :zeek:type:`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.
:param c: The connection.
.. zeek:see:: 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
.. zeek:id:: connection_state_remove
:source-code: base/bif/event.bif.zeek 179 179
:Type: :zeek:type:`event` (c: :zeek:type:`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.
:param c: The connection.
.. zeek:see:: 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 unknown_ip_inactivity_timeout
conn_stats
.. zeek:id:: connection_status_update
:source-code: base/bif/event.bif.zeek 209 209
:Type: :zeek:type:`event` (c: :zeek: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.
:param c: The connection.
.. zeek:see:: 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
.. zeek:id:: connection_timeout
:source-code: base/bif/event.bif.zeek 159 159
:Type: :zeek:type:`event` (c: :zeek:type:`connection`)
Generated when a TCP connection timed out. This event is raised when
no activity was seen for an interval of at least
:zeek:id:`tcp_connection_linger`, and either one endpoint has already
closed the connection or one side never became active.
:param c: The connection.
.. zeek:see:: 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
:zeek: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).
.. zeek:id:: content_gap
:source-code: base/bif/event.bif.zeek 392 392
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`, seq: :zeek:type:`count`, length: :zeek:type:`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).
:param c: The connection.
:param is_orig: True if the gap is on the originator's side.
:param seq: The sequence number where the gap starts.
:param 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.
.. zeek:id:: dns_mapping_altered
:source-code: base/bif/event.bif.zeek 926 926
:Type: :zeek:type:`event` (dm: :zeek:type:`dns_mapping`, old_addrs: :zeek:type:`addr_set`, new_addrs: :zeek:type:`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.
:param dm: A record describing the new resolver result.
:param old_addrs: Addresses that used to be part of the returned set for the query
described by *dm*, but are not anymore.
:param new_addrs: Addresses that were not part of the returned set for the query
described by *dm*, but now are.
.. zeek:see:: dns_mapping_lost_name dns_mapping_new_name dns_mapping_unverified
dns_mapping_valid
.. zeek:id:: dns_mapping_lost_name
:source-code: base/bif/event.bif.zeek 893 893
:Type: :zeek:type:`event` (dm: :zeek:type:`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.
:param dm: A record describing the old resolver result.
.. zeek:see:: dns_mapping_altered dns_mapping_new_name dns_mapping_unverified
dns_mapping_valid
.. zeek:id:: dns_mapping_name_changed
:source-code: base/bif/event.bif.zeek 908 908
:Type: :zeek:type:`event` (prev: :zeek:type:`dns_mapping`, latest: :zeek:type:`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.
:param prev: A record describing the old resolver result.
:param latest: A record describing the new resolver result.
.. zeek:see:: dns_mapping_altered dns_mapping_new_name dns_mapping_unverified
dns_mapping_valid
.. zeek:id:: dns_mapping_new_name
:source-code: base/bif/event.bif.zeek 880 880
:Type: :zeek:type:`event` (dm: :zeek:type:`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.
:param dm: A record describing the new resolver result.
.. zeek:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_unverified
dns_mapping_valid
.. zeek:id:: dns_mapping_unverified
:source-code: base/bif/event.bif.zeek 868 868
:Type: :zeek:type:`event` (dm: :zeek:type:`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.
:param dm: A record describing the old resolver result.
.. zeek:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_new_name
dns_mapping_valid
.. zeek:id:: dns_mapping_valid
:source-code: base/bif/event.bif.zeek 855 855
:Type: :zeek:type:`event` (dm: :zeek:type:`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.
:param dm: A record describing the new resolver result (which matches the old one).
.. zeek:see:: dns_mapping_altered dns_mapping_lost_name dns_mapping_new_name
dns_mapping_unverified
.. zeek:id:: esp_packet
:source-code: base/bif/event.bif.zeek 322 322
:Type: :zeek:type:`event` (p: :zeek:type:`pkt_hdr`)
Generated for any packets using the IPv6 Encapsulating Security Payload (ESP)
extension header.
:param p: Information from the header of the packet that triggered the event.
.. zeek:see:: new_packet tcp_packet ipv6_ext_headers
.. zeek:id:: event_queue_flush_point
:source-code: base/bif/event.bif.zeek 719 719
:Type: :zeek:type:`event` ()
Marks a point in the event stream at which the event queue started flushing.
.. zeek:id:: expired_conn_weird
:source-code: base/frameworks/notice/weird.zeek 432 444
:Type: :zeek:type:`event` (name: :zeek:type:`string`, id: :zeek:type:`conn_id`, uid: :zeek:type:`string`, addl: :zeek:type:`string`, source: :zeek:type:`string`)
:Type: :zeek:type:`event` (name: :zeek:type:`string`, id: :zeek:type:`conn_id`, uid: :zeek:type:`string`, addl: :zeek:type:`string`)
Generated for unexpected activity related to a specific connection whose
internal state has already been expired. That is to say,
:zeek:see:`Reporter::conn_weird` may have been called from a script, but
the internal connection object/state was expired and so the full
:zeek:see:`connection` record is no longer available, just the UID
and :zeek:see:`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.
:param 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.
:param id: The tuple associated with a previously-expired connection.
:param uid: The UID string associated with a previously-expired connection.
:param addl: Optional additional context further describing the situation.
:param source: Optional source for the weird. When called by analyzers, this should
be filled in with the name of the analyzer.
.. zeek:see:: 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.
.. zeek:id:: file_gap
:source-code: base/bif/event.bif.zeek 814 814
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`, offset: :zeek:type:`count`, len: :zeek:type:`count`)
Indicates that a chunk of the file is missing.
:param f: The file.
:param offset: The byte offset from the start of the file at which the gap begins.
:param len: The number of missing bytes.
.. zeek:see:: file_new file_over_new_connection file_timeout
file_sniff file_state_remove file_reassembly_overflow
.. zeek:id:: file_new
:source-code: base/bif/event.bif.zeek 752 752
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`)
Indicates that analysis of a new file has begun. The analysis can be
augmented at this time via :zeek:see:`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
:zeek:see:`get_file_handle`/:zeek:see:`set_file_handle` mechanism. That is,
Zeek triggers this event whenever a protocol analyzer thinks it's
encountering a new file.
:param f: The file.
.. zeek:see:: file_over_new_connection file_timeout file_gap
file_sniff file_state_remove
.. zeek:id:: file_opened
:source-code: base/bif/event.bif.zeek 715 715
:Type: :zeek:type:`event` (f: :zeek:type:`file`)
Generated each time Zeek's script interpreter opens a file. This event is
triggered only for files opened via :zeek:id:`open`, and in particular not for
normal log files as created by log writers.
:param f: The opened file.
.. zeek:id:: file_over_new_connection
:source-code: base/bif/event.bif.zeek 771 771
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`, c: :zeek:type:`connection`, is_orig: :zeek:type:`bool`)
Indicates that Zeek has begun to observe a file for the first time on the
given connection. This is similar to :zeek:see:`file_new`, but also triggers
once on each subsequent connection in which the relevant protocol analyzer
encounters any part of the file. As with :zeek:see:`file_new`, the protocol
analyzer defines file identity. When Zeek encounters a file for the first
time, it first triggers :zeek:see:`file_new`, then
:zeek:see:`file_over_new_connection`.
:param f: The file.
:param c: The new connection over which the file is seen being transferred.
:param is_orig: true if the originator of *c* is the one sending the file.
.. zeek:see:: file_new file_timeout file_gap file_sniff
file_state_remove
.. zeek:id:: file_reassembly_overflow
:source-code: base/bif/event.bif.zeek 834 834
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`, offset: :zeek:type:`count`, skipped: :zeek:type:`count`)
Indicates that the file had an overflow of the reassembly buffer.
This is a specialization of the :zeek:id:`file_gap` event.
:param f: The file.
:param 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.
:param 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.
.. zeek: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
.. zeek:id:: file_sniff
:source-code: base/bif/event.bif.zeek 790 790
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`, meta: :zeek: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
:zeek:see:`Files::add_analyzer`. The amount of data fed into the file
sniffing can be increased or decreased by changing either
:zeek:see:`default_file_bof_buffer_size` or the ``bof_buffer_size`` field
in an :zeek:type:`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.
:param f: The file.
:param meta: Metadata that's been discovered about the file.
.. zeek:see:: file_over_new_connection file_timeout file_gap
file_state_remove
.. zeek:id:: file_state_remove
:source-code: base/bif/event.bif.zeek 843 843
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`)
This event is generated each time file analysis is ending for a given file.
:param f: The file.
.. zeek:see:: file_new file_over_new_connection file_timeout file_gap
file_sniff
.. zeek:id:: file_timeout
:source-code: base/frameworks/files/main.zeek 572 576
:Type: :zeek:type:`event` (f: :zeek:type:`fa_file`)
Indicates that file analysis has timed out because no activity was seen
for the file in a while.
:param f: The file.
.. zeek:see:: file_new file_over_new_connection file_gap
file_sniff file_state_remove default_file_timeout_interval
Files::set_timeout_interval
.. zeek:id:: file_weird
:source-code: base/frameworks/notice/weird.zeek 477 488
:Type: :zeek:type:`event` (name: :zeek:type:`string`, f: :zeek:type:`fa_file`, addl: :zeek:type:`string`, source: :zeek:type:`string`)
:Type: :zeek:type:`event` (name: :zeek:type:`string`, f: :zeek:type:`fa_file`, addl: :zeek:type:`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.
:param 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.
:param f: The corresponding file.
:param addl: Additional information related to the weird.
:param source: The name of the file analyzer that generated the weird.
.. zeek:see:: 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.
.. zeek:id:: flow_weird
:source-code: base/frameworks/notice/weird.zeek 446 462
:Type: :zeek:type:`event` (name: :zeek:type:`string`, src: :zeek:type:`addr`, dst: :zeek:type:`addr`, addl: :zeek:type:`string`, source: :zeek:type:`string`)
:Type: :zeek:type:`event` (name: :zeek:type:`string`, src: :zeek:type:`addr`, dst: :zeek:type:`addr`, addl: :zeek:type:`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.
:param 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.
:param src: The source address corresponding to the activity.
:param dst: The destination address corresponding to the activity.
:param addl: Optional additional context further describing the situation.
:param source: Optional source for the weird. When called by analyzers, this should
be filled in with the name of the analyzer.
.. zeek:see:: 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.
.. zeek:id:: get_file_handle
:source-code: base/frameworks/files/main.zeek 516 532
:Type: :zeek:type:`event` (tag: :zeek:type:`Analyzer::Tag`, c: :zeek:type:`connection`, is_orig: :zeek: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 :zeek:see:`set_file_handle` will "win".
:param tag: The analyzer which is carrying the file data.
:param c: The connection which is carrying the file data.
:param is_orig: The direction the file data is flowing over the connection.
.. zeek:see:: set_file_handle
.. zeek:id:: ipv6_ext_headers
:source-code: base/bif/event.bif.zeek 313 313
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, p: :zeek: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.
:param c: The connection the packet is part of.
:param p: Information from the header of the packet that triggered the event.
.. zeek:see:: new_packet tcp_packet packet_contents esp_packet
.. zeek:id:: mobile_ipv6_message
:source-code: base/bif/event.bif.zeek 330 330
:Type: :zeek:type:`event` (p: :zeek:type:`pkt_hdr`)
Generated for any packet using a Mobile IPv6 Mobility Header.
:param p: Information from the header of the packet that triggered the event.
.. zeek:see:: new_packet tcp_packet ipv6_ext_headers
.. zeek:id:: net_done
:source-code: base/init-bare.zeek 6471 6474
:Type: :zeek:type:`event` (t: :zeek:type:`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:see:`zeek_done`.
:param t: The time at with the Zeek-termination process started.
.. zeek:see:: zeek_init zeek_done
.. note::
If Zeek terminates due to an invocation of :zeek:id:`exit`, then this event
is not generated.
.. zeek:id:: net_weird
:source-code: base/bif/event.bif.zeek 571 571
:Type: :zeek:type:`event` (name: :zeek:type:`string`, addl: :zeek:type:`string`, source: :zeek:type:`string`)
:Type: :zeek:type:`event` (name: :zeek:type:`string`, addl: :zeek:type:`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.
:param 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.
:param addl: Optional additional context further describing the situation.
:param source: Optional source for the weird. When called by analyzers, this should
be filled in with the name of the analyzer.
.. zeek:see:: 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.
.. zeek:id:: network_time_init
:source-code: base/bif/event.bif.zeek 95 95
:Type: :zeek: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.
.. zeek:see:: zeek_init network_time
.. zeek:id:: new_connection
:source-code: base/bif/event.bif.zeek 118 118
:Type: :zeek:type:`event` (c: :zeek:type:`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.
:param c: The connection.
.. zeek:see:: 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. Consider to use events like :zeek:id:`connection_established` or
:zeek:id:`conn_generic_packet_threshold_crossed` instead.
.. zeek:id:: new_event
:source-code: policy/misc/dump-events.zeek 27 50
:Type: :zeek:type:`event` (name: :zeek:type:`string`, params: :zeek:type:`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.
:param name: The name of the event.
:param params: The event's parameters.
.. zeek:id:: new_packet
:source-code: base/bif/event.bif.zeek 301 301
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, p: :zeek:type:`pkt_hdr`)
Generated for all packets that make it into Zeek's connection processing. In
contrast to :zeek: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.
:param c: The connection the packet is part of.
:param p: Information from the header of the packet that triggered the event.
.. zeek:see:: tcp_packet packet_contents raw_packet
.. zeek:id:: packet_contents
:source-code: base/bif/event.bif.zeek 345 345
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, contents: :zeek: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
:zeek:id:`new_packet`. That said, if you work from a trace and want to
do some packet-level analysis, it may come in handy.
:param c: The connection the packet is part of.
:param contents: The raw transport-layer payload.
.. zeek:see:: new_packet tcp_packet
.. zeek:id:: packet_not_processed
:source-code: base/bif/event.bif.zeek 974 974
:Type: :zeek:type:`event` (pkt: :zeek:type:`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.
:param pkt: Data for the unprocessed packet
.. zeek:id:: profiling_update
:source-code: base/bif/event.bif.zeek 638 638
:Type: :zeek:type:`event` (f: :zeek:type:`file`, expensive: :zeek:type:`bool`)
Generated each time Zeek's internal profiling log is updated. The file is
defined by :zeek:id:`profiling_file`, and its update frequency by
:zeek:id:`profiling_interval` and :zeek:id:`expensive_profiling_multiple`.
:param f: The profiling file.
:param expensive: True if this event corresponds to heavier-weight profiling as
indicated by the :zeek:id:`expensive_profiling_multiple` variable.
.. zeek:see:: profiling_interval expensive_profiling_multiple
.. zeek:id:: protocol_late_match
:source-code: policy/protocols/conn/speculative-service.zeek 32 37
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, atype: :zeek:type:`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.
:param c: The connection.
:param 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.
.. zeek:see:: dpd_buffer_size dpd_max_packets
.. zeek:id:: raw_packet
:source-code: base/bif/event.bif.zeek 284 284
:Type: :zeek:type:`event` (p: :zeek:type:`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.
:param p: Information from the header of the packet that triggered the event.
.. zeek:see:: new_packet packet_contents
.. zeek:id:: reporter_error
:source-code: base/frameworks/reporter/main.zeek 56 59
:Type: :zeek:type:`event` (t: :zeek:type:`time`, msg: :zeek:type:`string`, location: :zeek:type:`string`)
:Attributes: :zeek:attr:`&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
:zeek:id:`Reporter::error`.
:param t: The time the error was passed to the reporter.
:param msg: The error message.
:param location: A (potentially empty) string describing a location associated with
the error.
.. zeek:see:: 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.
.. zeek:id:: reporter_info
:source-code: base/frameworks/reporter/main.zeek 46 49
:Type: :zeek:type:`event` (t: :zeek:type:`time`, msg: :zeek:type:`string`, location: :zeek:type:`string`)
:Attributes: :zeek:attr:`&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 :zeek:id:`Reporter::info`.
:param t: The time the message was passed to the reporter.
:param msg: The message itself.
:param location: A (potentially empty) string describing a location associated with
the message.
.. zeek:see:: 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.
.. zeek:id:: reporter_warning
:source-code: base/frameworks/reporter/main.zeek 51 54
:Type: :zeek:type:`event` (t: :zeek:type:`time`, msg: :zeek:type:`string`, location: :zeek:type:`string`)
:Attributes: :zeek:attr:`&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
:zeek:id:`Reporter::warning`.
:param t: The time the warning was passed to the reporter.
:param msg: The warning message.
:param location: A (potentially empty) string describing a location associated with
the warning.
.. zeek:see:: 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.
.. zeek:id:: rexmit_inconsistency
:source-code: policy/protocols/conn/weirds.zeek 20 27
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, t1: :zeek:type:`string`, t2: :zeek:type:`string`, tcp_flags: :zeek:type:`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 :zeek:id:`tcp_max_old_segments` is larger than zero,
mismatches with that older still-buffered data will likewise trigger the event.
:param c: The connection showing the inconsistency.
:param t1: The original payload.
:param t2: The new payload.
:param 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".
.. zeek:see:: tcp_rexmit tcp_contents
.. zeek:id:: scheduled_analyzer_applied
:source-code: base/bif/event.bif.zeek 272 272
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, a: :zeek:type:`Analyzer::Tag`)
Generated when a connection is seen that is marked as being expected.
The function :zeek:id:`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.
:param c: The connection.
:param a: The analyzer that was scheduled for the connection with the
:zeek: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``.
.. zeek:see:: 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.
.. zeek:id:: signature_match
:source-code: base/bif/event.bif.zeek 620 620
:Type: :zeek:type:`event` (state: :zeek:type:`signature_state`, msg: :zeek:type:`string`, data: :zeek:type:`string`, end_of_match: :zeek:type:`count`)
:Type: :zeek:type:`event` (state: :zeek:type:`signature_state`, msg: :zeek:type:`string`, data: :zeek:type:`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 :doc:`user manual </frameworks/signatures>` for more information
about Zeek's signature engine.
:param state: Context about the match, including which signatures triggered the
event and the connection for which the match was found.
:param msg: The message passed to the ``event`` signature action.
:param 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.
:param end_of_match: Where within data the pattern match ended. 0 if not applicable or when *data* is empty.
.. zeek:id:: tunnel_changed
:source-code: base/bif/event.bif.zeek 133 133
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, e: :zeek: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 Zeek's
default scripts are doing).
:param c: The connection whose tunnel/encapsulation changed.
:param e: The new encapsulation.
.. zeek:id:: udp_session_done
:source-code: base/bif/event.bif.zeek 247 247
:Type: :zeek:type:`event` (u: :zeek:type:`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.
:param u: The connection record for the corresponding UDP flow.
.. zeek:see:: udp_contents udp_reply udp_request
.. zeek:id:: unknown_protocol
:source-code: policy/misc/unknown-protocols.zeek 42 53
:Type: :zeek:type:`event` (analyzer_name: :zeek:type:`string`, protocol: :zeek:type:`count`, first_bytes: :zeek:type:`string`, analyzer_history: :zeek:type:`string_vec`)
Generated when a packet analyzer attempts to forward a protocol that it doesn't
know how to handle.
:param analyzer_name: The string name of the analyzer attempting to forward the protocol
:param protocol: The identifier of the protocol being forwarded
:param first_bytes: A certain number of bytes at the start of the unknown protocol's header.
:param analyzer_history: The chain of packet analyzers that processed the packet up to this
point. This includes the history of encapsulating packets in case
of tunneling.
.. zeek:see:: UnknownProtocol::first_bytes_count
.. zeek:id:: zeek_done
:source-code: base/bif/event.bif.zeek 67 67
:Type: :zeek: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.
.. zeek:see:: zeek_init
.. note::
If Zeek terminates due to an invocation of :zeek:id:`exit`, then this event
is not generated.
.. zeek:id:: zeek_init
:source-code: base/bif/event.bif.zeek 53 53
:Type: :zeek: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.
.. zeek:see:: zeek_done network_time_init
.. note::
When a ``zeek_init`` handler executes, Zeek has not yet seen any input
packets and therefore :zeek:id:`network_time` is not initialized yet. An
artifact of that is that any timer installed in a ``zeek_init`` handler,
like with :zeek:keyword:`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 :zeek:see:`network_time_init` event.
.. zeek:id:: zeek_script_loaded
:source-code: policy/misc/loaded-scripts.zeek 37 40
:Type: :zeek:type:`event` (path: :zeek:type:`string`, level: :zeek:type:`count`)
Raised for each policy script loaded by the script interpreter.
:param path: The full path to the script loaded.
:param level: The "nesting level": zero for a top-level Zeek script and incremented
recursively for each ``@load``.
Reference in a new issue View git blame Copy permalink