zeek/doc/devel/spicy/autogen/zeek-functions.spicy

.. _spicy_confirm_protocol:

.. rubric:: ``function zeek::confirm_protocol()``

[Deprecated] Triggers a DPD protocol confirmation for the current connection.

This function has been deprecated and will be removed. Use ``spicy::accept_input``
instead, which will have the same effect with Zeek.

.. _spicy_reject_protocol:

.. rubric:: ``function zeek::reject_protocol(reason: string)``

[Deprecated] Triggers a DPD protocol violation for the current connection.

This function has been deprecated and will be removed. Use ``spicy::decline_input``
instead, which will have the same effect with Zeek.

.. _spicy_weird:

.. rubric:: ``function zeek::weird(id: string, addl: string = "") : &cxxname="zeek::spicy::rt::weird";``

Reports a "weird" to Zeek. This should be used with similar semantics as in
Zeek: something quite unexpected happening at the protocol level, which however
does not prevent us from continuing to process the connection.

id: the name of the weird, which (just like in Zeek) should be a *static*
string identifying the situation reported (e.g., ``unexpected_command``).

addl: additional information to record along with the weird

.. _spicy_is_orig:

.. rubric:: ``function zeek::is_orig() : bool``

Returns true if we're currently parsing the originator side of a connection.

.. _spicy_uid:

.. rubric:: ``function zeek::uid() : string``

Returns the current connection's UID.

.. _spicy_conn_id:

.. rubric:: ``function zeek::conn_id() : tuple<orig_h: addr, orig_p: port, resp_h: addr, resp_p: port>``

Returns the current connection's 4-tuple ID to make IP address and port information available.

.. _spicy_flip_roles:

.. rubric:: ``function zeek::flip_roles()``

Instructs Zeek to flip the directionality of the current connection.

.. _spicy_number_packets:

.. rubric:: ``function zeek::number_packets() : uint64``

Returns the number of packets seen so far on the current side of the current connection.

.. _spicy_has_analyzer:

.. rubric:: ``function zeek::has_analyzer(analyzer: string, if_enabled: bool = True) : bool``

Checks if there is a Zeek analyzer of a given name.

analyzer: the Zeek-side name of the analyzer to check for
if_enabled: if true, only checks for analyzers that are enabled

Returns the type of the analyzer if it exists, or ``Undef`` if it does not.

.. _spicy_analyzer_type:

.. rubric:: ``function zeek::analyzer_type(analyzer: string, if_enabled: bool = True) : AnalyzerType``

Returns the type of a Zeek analyzer of a given name.

analyzer: the Zeek-side name of the analyzer to check
if_enabled: if true, only checks for analyzers that are enabled

Returns the type of the analyzer if it exists, or ``Undef`` if it does not.

.. _spicy_protocol_begin:

.. rubric:: ``function zeek::protocol_begin(analyzer: optional<string>, protocol: spicy::Protocol = spicy::Protocol::TCP)``

Adds a Zeek-side child protocol analyzer to the current connection.

If the same analyzer was added previously with `protocol_handle_get_or_create` or
`protocol_begin` with same argument, and not closed with `protocol_handle_close`
or `protocol_end`, no new analyzer will be added.

See `protocol_handle_get_or_create` for lifetime and error semantics.

analyzer: type of analyzer to instantiate, specified through its Zeek-side
name (similar to what Zeek's signature action `enable` takes)

protocol: the transport-layer protocol that the analyzer uses; only TCP is
currently supported here

Note: For backwards compatibility, the analyzer argument can be left unset to add
a DPD analyzer. This use is deprecated, though; use the single-argument version of
`protocol_begin` for that instead.

.. _spicy_protocol_begin_2:

.. rubric:: ``function zeek::protocol_begin(protocol: spicy::Protocol = spicy::Protocol::TCP)``

Adds a Zeek-side DPD child protocol analyzer performing dynamic protocol detection
on subsequently provided data.

If the same DPD analyzer was added previously with `protocol_handle_get_or_create` or
`protocol_begin` with same argument, and not closed with `protocol_handle_close`
or `protocol_end`, no new analyzer will be added.

See `protocol_handle_get_or_create` for lifetime and error semantics.

protocol: the transport-layer protocol on which to perform protocol detection;
only TCP is currently supported here

.. _spicy_protocol_handle_get_or_create:

.. rubric:: ``function zeek::protocol_handle_get_or_create(analyzer: string, protocol: spicy::Protocol = spicy::Protocol::TCP) : ProtocolHandle``

Gets a handle to a Zeek-side child protocol analyzer for the current connection.

If no such child exists yet it will be added; otherwise a handle to the
existing child protocol analyzer will be returned.

This function will return an error if:

- not called from a protocol analyzer, or
- the requested child protocol analyzer is of unknown type or not support by the requested transport protocol, or
- creation of a child analyzer of the requested type was prevented by a
  previous call of `disable_analyzer` with `prevent=T`

By default, any newly created child protocol analyzer will remain alive
until Zeek expires the current connection's state. Alternatively, one
can call `protocol_handle_close` or `protocol_end` to delete the analyzer
earlier.

analyzer: type of analyzer to get or instantiate, specified through its Zeek-side
name (similar to what Zeek's signature action `enable` takes).

protocol: the transport-layer protocol that the analyser uses; only TCP is
currently supported here


.. _spicy_protocol_data_in:

.. rubric:: ``function zeek::protocol_data_in(is_orig: bool, data: bytes, protocol: spicy::Protocol = spicy::Protocol::TCP)``

Forwards protocol data to all previously instantiated Zeek-side child protocol analyzers of a given transport-layer.

is_orig: true to feed the data to the child's originator side, false for the responder

data: chunk of data to forward to child analyzer

protocol: the transport-layer protocol of the children to forward to; only TCP is currently supported here

.. _spicy_protocol_data_in_2:

.. rubric:: ``function zeek::protocol_data_in(is_orig: bool, data: bytes, h: ProtocolHandle)``

Forwards protocol data to a specific previously instantiated Zeek-side child analyzer.

is_orig: true to feed the data to the child's originator side, false for the responder

data: chunk of data to forward to child analyzer

h: handle to the child analyzer to forward data into

.. _spicy_protocol_gap:

.. rubric:: ``function zeek::protocol_gap(is_orig: bool, offset: uint64, len: uint64, h: optional<ProtocolHandle> = Null)``

Signals a gap in input data to all previously instantiated Zeek-side child protocol analyzers.

is_orig: true to signal gap to the child's originator side, false for the responder

offset: start offset of gap in input stream

len: size of gap

h: optional handle to the child analyzer signal a gap to, else signal to all child analyzers

.. _spicy_protocol_end:

.. rubric:: ``function zeek::protocol_end()``

Signals end-of-data to all previously instantiated Zeek-side child protocol
analyzers and removes them.

.. _spicy_protocol_handle_close:

.. rubric:: ``function zeek::protocol_handle_close(handle: ProtocolHandle)``

Signals end-of-data to the given child analyzer and removes it.

The given handle must be live, i.e., it must not have been used in a
previous protocol_handle_close call, and must not have been live when
protocol_end was called. If the handle is not live a runtime error will
be triggered.

handle: handle to the child analyzer to remove

.. _spicy_file_begin:

.. rubric:: ``function zeek::file_begin(mime_type: optional<string> = Null, fuid: optional<string> = Null) : string``

Signals the beginning of a file to Zeek's file analysis, associating it with the current connection.
Optionally, a mime type can be provided. It will be passed on to Zeek's file analysis framework.
Optionally, a file ID can be provided. It will be passed on to Zeek's file analysis framework.
Returns the Zeek-side file ID of the new file.

This function creates a new Zeek file analyzer that will remain alive until
either `file_end` gets called, or Zeek eventually expires the analyzer
through a timeout. (As Zeek does not tie a file analyzer's lifetime to any
connection, it may survive the termination of the current connection.)

.. _spicy_fuid:

.. rubric:: ``function zeek::fuid() : string``

Returns the current file's FUID.

.. _spicy_terminate_session:

.. rubric:: ``function zeek::terminate_session()``

Terminates the currently active Zeek-side session, flushing all state. Any
subsequent activity will start a new session from scratch. This can only be
called from inside a protocol analyzer.

.. _spicy_skip_input:

.. rubric:: ``function zeek::skip_input()``

Tells Zeek to skip sending any further input data to the current analyzer.
This is supported for protocol and file analyzers.

.. _spicy_file_set_size:

.. rubric:: ``function zeek::file_set_size(size: uint64, fid: optional<string> = Null)``

Signals the expected size of a file to Zeek's file analysis.

size: expected size of file
fid: Zeek-side ID of the file to operate on; if not given, the file started by the most recent file_begin() will be used

.. _spicy_file_data_in:

.. rubric:: ``function zeek::file_data_in(data: bytes, fid: optional<string> = Null)``

Passes file content on to Zeek's file analysis.

data: chunk of raw data to pass into analysis
fid: Zeek-side ID of the file to operate on; if not given, the file started by the most recent file_begin() will be used

.. _spicy_file_data_in_at_offset:

.. rubric:: ``function zeek::file_data_in_at_offset(data: bytes, offset: uint64, fid: optional<string> = Null)``

Passes file content at a specific offset on to Zeek's file analysis.

data: chunk of raw data to pass into analysis
offset: position in file where data starts
fid: Zeek-side ID of the file to operate on; if not given, the file started by the most recent file_begin() will be used

.. _spicy_file_gap:

.. rubric:: ``function zeek::file_gap(offset: uint64, len: uint64, fid: optional<string> = Null)``

Signals a gap in a file to Zeek's file analysis.

offset: position in file where gap starts
len: size of gap
fid: Zeek-side ID of the file to operate on; if not given, the file started by the most recent file_begin() will be used

.. _spicy_file_end:

.. rubric:: ``function zeek::file_end(fid: optional<string> = Null)``

Signals the end of a file to Zeek's file analysis.

fid: Zeek-side ID of the file to operate on; if not given, the file started by the most recent file_begin() will be used

.. _spicy_forward_packet:

.. rubric:: ``function zeek::forward_packet(identifier: uint32)``

Inside a packet analyzer, forwards what data remains after parsing the top-level unit
on to another analyzer. The index specifies the target, per the current dispatcher table.

.. _spicy_network_time:

.. rubric:: ``function zeek::network_time() : time``

Gets the network time from Zeek.

.. _spicy_get_address:

.. rubric:: ``function zeek::get_address(id: string) : addr``

Returns the value of a global Zeek script variable of Zeek type ``addr``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_bool:

.. rubric:: ``function zeek::get_bool(id: string) : bool``

Returns the value of a global Zeek script variable of Zeek type ``bool``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_count:

.. rubric:: ``function zeek::get_count(id: string) : uint64``

Returns the value of a global Zeek script variable of Zeek type ``count``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_double:

.. rubric:: ``function zeek::get_double(id: string) : real``

Returns the value of a global Zeek script variable of Zeek type ``double``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_enum:

.. rubric:: ``function zeek::get_enum(id: string) : string``

Returns the value of a global Zeek script variable of Zeek type ``enum``.
The value is returned as a string containing the enum's label name, without
any scope. Throws an exception if there's no such Zeek of that name, or if
it's not of the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_int:

.. rubric:: ``function zeek::get_int(id: string) : int64``

Returns the value of a global Zeek script variable of Zeek type ``int``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_interval:

.. rubric:: ``function zeek::get_interval(id: string) : interval``

Returns the value of a global Zeek script variable of Zeek type
``interval``. Throws an exception if there's no such Zeek of that name, or
if it's not of the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_port:

.. rubric:: ``function zeek::get_port(id: string) : port``

Returns the value of a global Zeek script variable of Zeek type ``port``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_record:

.. rubric:: ``function zeek::get_record(id: string) : ZeekRecord``

Returns the value of a global Zeek script variable of Zeek type ``record``.
The value is returned as an opaque handle to the record, which can be used
with the ``zeek::record_*()`` functions to access the record's fields.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_set:

.. rubric:: ``function zeek::get_set(id: string) : ZeekSet``

Returns the value of a global Zeek script variable of Zeek type ``set``. The
value is returned as an opaque handle to the set, which can be used with the
``zeek::set_*()`` functions to access the set's content. Throws an exception
if there's no such Zeek of that name, or if it's not of the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_string:

.. rubric:: ``function zeek::get_string(id: string) : bytes``

Returns the value of a global Zeek script variable of Zeek type ``string``.
The string's value is returned as a Spicy ``bytes`` value. Throws an
exception if there's no such Zeek of that name, or if it's not of the
expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_subnet:

.. rubric:: ``function zeek::get_subnet(id: string) : network``

Returns the value of a global Zeek script variable of Zeek type ``subnet``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_table:

.. rubric:: ``function zeek::get_table(id: string) : ZeekTable``

Returns the value of a global Zeek script variable of Zeek type ``table``.
The value is returned as an opaque handle to the set, which can be used with
the ``zeek::set_*()`` functions to access the set's content. Throws an
exception if there's no such Zeek of that name, or if it's not of the
expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_time:

.. rubric:: ``function zeek::get_time(id: string) : time``

Returns the value of a global Zeek script variable of Zeek type ``time``.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_vector:

.. rubric:: ``function zeek::get_vector(id: string) : ZeekVector``

Returns the value of a global Zeek script variable of Zeek type ``vector``.
The value is returned as an opaque handle to the vector, which can be used
with the ``zeek::vector_*()`` functions to access the vector's content.
Throws an exception if there's no such Zeek of that name, or if it's not of
the expected type.

id: fully-qualified name of the global Zeek variable to retrieve

.. _spicy_get_value:

.. rubric:: ``function zeek::get_value(id: string) : ZeekVal``

Returns an opaque handle to a global Zeek script variable. The handle can be
used with the ``zeek::as_*()`` functions to access the variable's value.
Throws an exception if there's no Zeek variable of that name.

.. _spicy_as_address:

.. rubric:: ``function zeek::as_address(v: ZeekVal) : addr``

Returns a Zeek ``addr`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_bool:

.. rubric:: ``function zeek::as_bool(v: ZeekVal) : bool``

Returns a Zeek ``bool`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_count:

.. rubric:: ``function zeek::as_count(v: ZeekVal) : uint64``

Returns a Zeek ``count`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_double:

.. rubric:: ``function zeek::as_double(v: ZeekVal) : real``

Returns a Zeek ``double`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_enum:

.. rubric:: ``function zeek::as_enum(v: ZeekVal) : string``

Returns a Zeek ``enum`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_int:

.. rubric:: ``function zeek::as_int(v: ZeekVal) : int64``

Returns a Zeek ``int`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_interval:

.. rubric:: ``function zeek::as_interval(v: ZeekVal) : interval``

Returns a Zeek ``interval`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_port:

.. rubric:: ``function zeek::as_port(v: ZeekVal) : port``

Returns a Zeek ``port`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_record:

.. rubric:: ``function zeek::as_record(v: ZeekVal) : ZeekRecord``

Returns a Zeek ``record`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_set:

.. rubric:: ``function zeek::as_set(v: ZeekVal) : ZeekSet``

Returns a Zeek ``set`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_string:

.. rubric:: ``function zeek::as_string(v: ZeekVal) : bytes``

Returns a Zeek ``string`` value refereced by an opaque handle. The string's
value is returned as a Spicy ``bytes`` value. Throws an exception if the
referenced value is not of the expected type.

.. _spicy_as_subnet:

.. rubric:: ``function zeek::as_subnet(v: ZeekVal) : network``

Returns a Zeek ``subnet`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_table:

.. rubric:: ``function zeek::as_table(v: ZeekVal) : ZeekTable``

Returns a Zeek ``table`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_time:

.. rubric:: ``function zeek::as_time(v: ZeekVal) : time``

Returns a Zeek ``time`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_as_vector:

.. rubric:: ``function zeek::as_vector(v: ZeekVal) : ZeekVector``

Returns a Zeek ``vector`` value refereced by an opaque handle. Throws an
exception if the referenced value is not of the expected type.

.. _spicy_set_contains:

.. rubric:: ``function zeek::set_contains(id: string, v: any) : bool``

Returns true if a Zeek set contains a given value. Throws an exception if
the given ID does not exist, or does not have the expected type.

id: fully-qualified name of the global Zeek set to check
v: value to check for, which must be of the Spicy-side equivalent of the set's key type

.. _spicy_set_contains_2:

.. rubric:: ``function zeek::set_contains(s: ZeekSet, v: any) : bool``

Returns true if a Zeek set contains a given value. Throws an exception if
the set does not have the expected type.

s: opaque handle to the Zeek set, as returned by other functions
v: value to check for, which must be of the Spicy-side equivalent of the set's key type

.. _spicy_table_contains:

.. rubric:: ``function zeek::table_contains(id: string, v: any) : bool``

Returns true if a Zeek table contains a given value. Throws an exception if
the given ID does not exist, or does not have the expected type.

id: fully-qualified name of the global Zeek table to check
v: value to check for, which must be of the Spicy-side equivalent of the table's key type

.. _spicy_table_contains_2:

.. rubric:: ``function zeek::table_contains(t: ZeekTable, v: any) : bool``

Returns true if a Zeek table contains a given value. Throws an exception if
the given ID does not exist, or does not have the expected type.

t: opaque handle to the Zeek table, as returned by other functions
v: value to check for, which must be of the Spicy-side equivalent of the table's key type

.. _spicy_table_lookup:

.. rubric:: ``function zeek::table_lookup(id: string, v: any) : optional<ZeekVal>``

Returns the value associated with a key in a Zeek table. Returns an error
result if the key does not exist in the table. Throws an exception if the
given table ID does not exist, or does not have the expected type.

id: fully-qualified name of the global Zeek table to check
v: value to lookup, which must be of the Spicy-side equivalent of the table's key type

.. _spicy_table_lookup_2:

.. rubric:: ``function zeek::table_lookup(t: ZeekTable, v: any) : optional<ZeekVal>``

Returns the value associated with a key in a Zeek table. Returns an error
result if the key does not exist in the table. Throws an exception if the
given table ID does not exist, or does not have the expected type.

t: opaque handle to the Zeek table, as returned by other functions
v: value to lookup, which must be of the Spicy-side equivalent of the table's key type

.. _spicy_record_has_value:

.. rubric:: ``function zeek::record_has_value(id: string, field: string) : bool``

Returns true if a Zeek record provides a value for a given field. This
includes fields with `&default` values. Throws an exception if the given ID
does not exist, or does not have the expected type.

id: fully-qualified name of the global Zeek record to check field: name of
the field to check

.. _spicy_record_has_value_2:

.. rubric:: ``function zeek::record_has_value(r: ZeekRecord, field: string) : bool``

Returns true if a Zeek record provides a value for a given field.
This includes fields with `&default` values.

r: opaque handle to the Zeek record, as returned by other functions
field: name of the field to check

.. _spicy_record_has_field:

.. rubric:: ``function zeek::record_has_field(id: string, field: string) : bool``

Returns true if the type of a Zeek record has a field of a given name.
Throws an exception if the given ID does not exist, or does not have the
expected type.

id: fully-qualified name of the global Zeek record to check
field: name of the field to check

.. _spicy_record_has_field_2:

.. rubric:: ``function zeek::record_has_field(r: ZeekRecord, field: string) : bool``

Returns true if the type of a Zeek record has a field of a given name.

r: opaque handle to the Zeek record, as returned by other functions
field: name of the field to check

.. _spicy_record_field:

.. rubric:: ``function zeek::record_field(id: string, field: string) : ZeekVal``

Returns a field's value from a Zeek record. Throws an exception if the given
ID does not exist, or does not have the expected type; or if there's no such
field in the record type, or if the field does not have a value.

id: fully-qualified name of the global Zeek record to check
field: name of the field to retrieve

.. _spicy_record_field_2:

.. rubric:: ``function zeek::record_field(r: ZeekRecord, field: string) : ZeekVal``

Returns a field's value from a Zeek record. Throws an exception if the given
record does not have such a field, or if the field does not have a value.

r: opaque handle to the Zeek record, as returned by other functions
field: name of the field to retrieve

.. _spicy_vector_index:

.. rubric:: ``function zeek::vector_index(id: string, index: uint64) : ZeekVal``

Returns the value of an index in a Zeek vector. Throws an exception if the
given ID does not exist, or does not have the expected type; or if the index
is out of bounds.

id: fully-qualified name of the global Zeek vector to check
index: index of the element to retrieve

.. _spicy_vector_index_2:

.. rubric:: ``function zeek::vector_index(v: ZeekVector, index: uint64) : ZeekVal``

Returns the value of an index in a Zeek vector. Throws an exception if the
index is out of bounds.

v: opaque handle to the Zeek vector, as returned by other functions
index: index of the element to retrieve

.. _spicy_vector_size:

.. rubric:: ``function zeek::vector_size(id: string) : uint64``

Returns the size of a Zeek vector. Throws an exception if the given ID does
not exist, or does not have the expected type.

id: fully-qualified name of the global Zeek vector to check

.. _spicy_vector_size_2:

.. rubric:: ``function zeek::vector_size(v: ZeekVector) : uint64``

Returns the size of a Zeek vector.

v: opaque handle to the Zeek vector, as returned by other functions