mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
8dd3debeae
So far the Spicy runtime supported forwarding data into other analyzers only for TCP analyzers. This puts branching logic in place that let the relevant runtime functions dispatch differently based on the target transport-layer protocol. We don't implement anything else than TCP yet; that will come next. Along with the internal changes, this also updates the user-visible runtime function to pass protocol information in. For now, this likewise remains limited to TCP. The function signatures are chosen so that they stay backwards-compatible to previous Spicy version. In particular, they default to TCP where not otherwise specified.
200 lines
10 KiB
Text
200 lines
10 KiB
Text
# Copyright (c) 2020-2021 by the Zeek Project. See LICENSE for details.
|
|
|
|
module zeek;
|
|
|
|
import spicy;
|
|
|
|
# Note: Retain the formatting here, doc/scripts/autogen-spicy-lib is picking up on that.
|
|
|
|
%cxx-include = "zeek/spicy/runtime-support.h";
|
|
|
|
## [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.
|
|
public function confirm_protocol() : void &cxxname="zeek::spicy::rt::confirm_protocol";
|
|
|
|
## [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.
|
|
public function reject_protocol(reason: string) : void &cxxname="zeek::spicy::rt::reject_protocol";
|
|
|
|
## 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
|
|
public function weird(id: string, addl: string = "") &cxxname="zeek::spicy::rt::weird";
|
|
|
|
## Returns true if we're currently parsing the originator side of a connection.
|
|
public function is_orig() : bool &cxxname="zeek::spicy::rt::is_orig";
|
|
|
|
## Returns the current connection's UID.
|
|
public function uid() : string &cxxname="zeek::spicy::rt::uid";
|
|
|
|
## Returns the current connection's 4-tuple ID to make IP address and port information available.
|
|
public function conn_id() : tuple<orig_h: addr, orig_p: port, resp_h: addr, resp_p: port> &cxxname="zeek::spicy::rt::conn_id";
|
|
|
|
## Instructs Zeek to flip the directionality of the current connection.
|
|
public function flip_roles() : void &cxxname="zeek::spicy::rt::flip_roles";
|
|
|
|
## Returns the number of packets seen so far on the current side of the current connection.
|
|
public function number_packets() : uint64 &cxxname="zeek::spicy::rt::number_packets";
|
|
|
|
## Opaque handle to a protocol analyzer.
|
|
public type ProtocolHandle = __library_type("zeek::spicy::rt::ProtocolHandle");
|
|
|
|
## 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 the error semantics of this function.
|
|
##
|
|
## 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.
|
|
public function protocol_begin(analyzer: optional<string>, protocol: spicy::Protocol = spicy::Protocol::TCP) : void &cxxname="zeek::spicy::rt::protocol_begin";
|
|
|
|
## 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 the error semantics of this function.
|
|
##
|
|
## protocol: the transport-layer protocol on which to perform protocol detection;
|
|
## only TCP is currently supported here
|
|
public function protocol_begin(protocol: spicy::Protocol = spicy::Protocol::TCP) : void &cxxname="zeek::spicy::rt::protocol_begin";
|
|
|
|
## 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`
|
|
##
|
|
## 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
|
|
##
|
|
public function protocol_handle_get_or_create(analyzer: string, protocol: spicy::Protocol = spicy::Protocol::TCP) : ProtocolHandle &cxxname="zeek::spicy::rt::protocol_handle_get_or_create";
|
|
|
|
## 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
|
|
public function protocol_data_in(is_orig: bool, data: bytes, protocol: spicy::Protocol = spicy::Protocol::TCP) : void &cxxname="zeek::spicy::rt::protocol_data_in";
|
|
|
|
## 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
|
|
public function protocol_data_in(is_orig: bool, data: bytes, h: ProtocolHandle) : void &cxxname="zeek::spicy::rt::protocol_data_in";
|
|
|
|
## 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
|
|
public function protocol_gap(is_orig: bool, offset: uint64, len: uint64, h: optional<ProtocolHandle> = Null) : void &cxxname="zeek::spicy::rt::protocol_gap";
|
|
|
|
## Signals end-of-data to all previously instantiated Zeek-side child protocol
|
|
## analyzers and removes them.
|
|
public function protocol_end() : void &cxxname="zeek::spicy::rt::protocol_end";
|
|
|
|
## 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
|
|
public function protocol_handle_close(handle: ProtocolHandle): void &cxxname="zeek::spicy::rt::protocol_handle_close";
|
|
|
|
## 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.
|
|
public function file_begin(mime_type: optional<string> = Null, fuid: optional<string> = Null) : string &cxxname="zeek::spicy::rt::file_begin";
|
|
|
|
## Returns the current file's FUID.
|
|
public function fuid() : string &cxxname="zeek::spicy::rt::fuid";
|
|
|
|
## 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.
|
|
public function terminate_session() : void &cxxname="zeek::spicy::rt::terminate_session";
|
|
|
|
## Tells Zeek to skip sending any further input data to the current analyzer.
|
|
## This is supported for protocol and file analyzers.
|
|
public function skip_input() : void &cxxname="zeek::spicy::rt::skip_input";
|
|
|
|
## 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
|
|
public function file_set_size(size: uint64, fid: optional<string> = Null) : void &cxxname="zeek::spicy::rt::file_set_size";
|
|
|
|
## 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
|
|
public function file_data_in(data: bytes, fid: optional<string> = Null) : void &cxxname="zeek::spicy::rt::file_data_in";
|
|
|
|
## 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
|
|
public function file_data_in_at_offset(data: bytes, offset: uint64, fid: optional<string> = Null) : void &cxxname="zeek::spicy::rt::file_data_in_at_offset";
|
|
|
|
## 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
|
|
public function file_gap(offset: uint64, len: uint64, fid: optional<string> = Null) : void &cxxname="zeek::spicy::rt::file_gap";
|
|
|
|
## 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
|
|
public function file_end(fid: optional<string> = Null) : void &cxxname="zeek::spicy::rt::file_end";
|
|
|
|
## 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.
|
|
public function forward_packet(identifier: uint32) : void &cxxname="zeek::spicy::rt::forward_packet";
|
|
|
|
## Gets the network time from Zeek.
|
|
public function network_time() : time &cxxname="zeek::spicy::rt::network_time";
|