mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
ae0b328826
Allow spicy parsers to generate their own file IDs and provide them to Zeek. This duplicates functionality that is currently possible (and used) by some binpac-based analyzers. One example for an analyzer creating its own file IDs is the SSL analyzer.
162 lines
8.6 KiB
Text
162 lines
8.6 KiB
Text
# Copyright (c) 2020-2021 by the Zeek Project. See LICENSE for details.
|
|
|
|
module zeek;
|
|
|
|
# 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.
|
|
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); if not
|
|
## specified, Zeek will perform its usual dynamic protocol detection to figure
|
|
## out how to parse the data (the latter will work only for TCP protocols, though.)
|
|
public function protocol_begin(analyzer: optional<string> = Null) : 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 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 unknown, 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 instantiate, specified through its Zeek-side
|
|
## name (similar to what Zeek's signature action `enable` takes).
|
|
public function protocol_handle_get_or_create(analyzer: string) : ProtocolHandle &cxxname="zeek::spicy::rt::protocol_handle_get_or_create";
|
|
|
|
## Forwards protocol data to all previously instantiated Zeek-side child protocol analyzers.
|
|
##
|
|
## 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: optional handle to the child analyzer to forward data into, else forward to all child analyzers
|
|
public function protocol_data_in(is_orig: bool, data: bytes, h: optional<ProtocolHandle> = Null) : 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";
|