mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
0040111955
This reflects the `spicy-plugin` code as of `d8c296b81cc2a11`. In addition to moving the code into Zeek's source tree, this comes with a couple small functional changes: - `spicyz` no longer tries to infer if it's running from the build directory. Instead `ZEEK_SPICY_LIBRARY` can be set to a custom location. `zeek-set-path.sh` does that now. - ZEEK_CONFIG can be set to change what `spicyz -z` print out. This is primarily for backwards compatibility. Some further notes on specifics: - We raise the minimum Spicy version to 1.8 (i.e., current `main` branch). - Renamed the `compiler/` subdirectory to `spicyz` to avoid include-path conflicts with the Spicy headers. - In `cmake/`, the corresponding PR brings a new/extended version of `FindZeek`, which Spicy analyzer packages need. We also now install some of the files that the Spicy plugin used to bring for testing, so that existing packages keep working. - For now, this all remains backwards compatible with the current `zkg` analyzer templates so that they work with both external and integrated Spicy support. Later, once we don't need to support any external Spicy plugin versions anymore, we can clean up the templates as well. - All the plugin's tests have moved into the standard test suite. They are skipped if configure with `--disable-spicy`. This holds off on adapting the new code further to Zeek's coding conventions, so that it remains easier to maintain it in parallel to the (now legacy) external plugin. We'll make a pass over the formatting for (presumable) Zeek 6.1.
157 lines
8.3 KiB
Text
157 lines
8.3 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.
|
|
## Returns the Zeek-side file ID of the new file.
|
|
public function file_begin(mime_type: 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";
|
|
|
|
## 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";
|