Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-02 06:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Merge remote-tracking branch 'origin/topic/timw/rst-linting'

Browse source 
* origin/topic/timw/rst-linting:
  Fix errors from rst linting on the generated docs
This commit is contained in:
Tim Wojtulewicz 2025-01-24 11:42:14 -07:00
commit 8c28e47dc1
17 changed files with 72 additions and 66 deletions
Download patch file Download diff file Expand all files Collapse all files

4
CHANGES
View file

@ -1,3 +1,7 @@
7.2.0-dev.116 | 2025-01-24 11:42:14 -0700
* Fix errors from rst linting on the generated docs (Tim Wojtulewicz, Corelight)
7.2.0-dev.113 | 2025-01-23 11:49:23 -0700 7.2.0-dev.113 | 2025-01-23 11:49:23 -0700
* Fix options parsing segfault (Evan Typanski, Corelight) * Fix options parsing segfault (Evan Typanski, Corelight)

2
VERSION
View file

@ -1 +1 @@
7.2.0-dev.113 7.2.0-dev.116

2
doc

@ -1 +1 @@
Subproject commit 610494461fad4ea630c4d31bb30f8bab141da167 Subproject commit c78d4a247a05b47365f3f2e08cfd62b539f6bcbe

8
scripts/base/frameworks/broker/main.zeek
View file

@ -83,12 +83,12 @@ export {
const log_batch_interval = 1sec &redef; const log_batch_interval = 1sec &redef;
## Max number of threads to use for Broker/CAF functionality. The ## Max number of threads to use for Broker/CAF functionality. The
## ZEEK_BROKER_MAX_THREADS environment variable overrides this setting. ## ``ZEEK_BROKER_MAX_THREADS`` environment variable overrides this setting.
const max_threads = 1 &redef; const max_threads = 1 &redef;
## Max number of items we buffer at most per peer. What action to take when ## Max number of items we buffer at most per peer. What action to take when
## the buffer reaches its maximum size is determined by ## the buffer reaches its maximum size is determined by
## `peer_overflow_policy`. ## :zeek:see:`Broker::peer_overflow_policy`.
const peer_buffer_size = 2048 &redef; const peer_buffer_size = 2048 &redef;
## Configures how Broker responds to peers that cannot keep up with the ## Configures how Broker responds to peers that cannot keep up with the
@ -98,10 +98,10 @@ export {
## - drop_oldest: removed the olsted message from the buffer, then append ## - drop_oldest: removed the olsted message from the buffer, then append
const peer_overflow_policy = "disconnect" &redef; const peer_overflow_policy = "disconnect" &redef;
## Same as `peer_buffer_size` but for WebSocket clients. ## Same as :zeek:see:`Broker::peer_buffer_size` but for WebSocket clients.
const web_socket_buffer_size = 512 &redef; const web_socket_buffer_size = 512 &redef;
## Same as `peer_overflow_policy` but for WebSocket clients. ## Same as :zeek:see:`Broker::peer_overflow_policy` but for WebSocket clients.
const web_socket_overflow_policy = "disconnect" &redef; const web_socket_overflow_policy = "disconnect" &redef;
## The CAF scheduling policy to use. Available options are "sharing" and ## The CAF scheduling policy to use. Available options are "sharing" and

27
scripts/base/frameworks/input/main.zeek
View file

@ -24,10 +24,10 @@ export {
STREAM = 2 STREAM = 2
}; };
## The default input reader used. Defaults to `READER_ASCII`. ## The default input reader used. Defaults to :zeek:see:`Input::READER_ASCII`.
option default_reader = READER_ASCII; option default_reader = READER_ASCII;
## The default reader mode used. Defaults to `MANUAL`. ## The default reader mode used. Defaults to :zeek:see:`Input::MANUAL`.
option default_mode = MANUAL; option default_mode = MANUAL;
## Separator between fields. ## Separator between fields.
@ -60,7 +60,7 @@ export {
# Common definitions for tables and events # Common definitions for tables and events
## String that allows the reader to find the source of the data. ## String that allows the reader to find the source of the data.
## For `READER_ASCII`, this is the filename. ## For :zeek:see:`Input::READER_ASCII`, this is the filename.
source: string; source: string;
## Reader to use for this stream. ## Reader to use for this stream.
@ -112,7 +112,7 @@ export {
## ##
## The event is raised like if it had been declared as follows: ## The event is raised like if it had been declared as follows:
## error_ev: function(desc: TableDescription, message: string, level: Reporter::Level) &optional; ## error_ev: function(desc: TableDescription, message: string, level: Reporter::Level) &optional;
## The actual declaration uses the ``any`` type because of deficiencies of the Zeek type system. ## The actual declaration uses the :zeek:type:`any` type because of deficiencies of the Zeek type system.
error_ev: any &optional; error_ev: any &optional;
## A key/value table that will be passed to the reader. ## A key/value table that will be passed to the reader.
@ -126,7 +126,7 @@ export {
# Common definitions for tables and events # Common definitions for tables and events
## String that allows the reader to find the source. ## String that allows the reader to find the source.
## For `READER_ASCII`, this is the filename. ## For :zeek:see:`Input::READER_ASCII`, this is the filename.
source: string; source: string;
## Reader to use for this stream. ## Reader to use for this stream.
@ -151,8 +151,8 @@ export {
want_record: bool &default=T; want_record: bool &default=T;
## The event that is raised each time a new line is received from the ## The event that is raised each time a new line is received from the
## reader. The event will receive an Input::EventDescription record ## reader. The event will receive an :zeek:see:`Input::EventDescription` record
## as the first argument, an Input::Event enum as the second ## as the first argument, an :zeek:see:`Input::Event` enum as the second
## argument, and the fields (as specified in *fields*) as the following ## argument, and the fields (as specified in *fields*) as the following
## arguments (this will either be a single record value containing ## arguments (this will either be a single record value containing
## all fields, or each field value as a separate argument). ## all fields, or each field value as a separate argument).
@ -161,12 +161,12 @@ export {
## Error event that is raised when an information, warning or error ## Error event that is raised when an information, warning or error
## is raised by the input stream. If the level is error, the stream will automatically ## is raised by the input stream. If the level is error, the stream will automatically
## be closed. ## be closed.
## The event receives the Input::EventDescription as the first argument, the ## The event receives the :zeek:see:`Input::EventDescription` as the first argument, the
## message as the second argument and the Reporter::Level as the third argument. ## message as the second argument and the :zeek:see:`Reporter::Level` as the third argument.
## ##
## The event is raised like it had been declared as follows: ## The event is raised like it had been declared as follows:
## error_ev: function(desc: EventDescription, message: string, level: Reporter::Level) &optional; ## error_ev: function(desc: EventDescription, message: string, level: Reporter::Level) &optional;
## The actual declaration uses the ``any`` type because of deficiencies of the Zeek type system. ## The actual declaration uses the :zeek:type:`any` type because of deficiencies of the Zeek type system.
error_ev: any &optional; error_ev: any &optional;
## A key/value table that will be passed to the reader. ## A key/value table that will be passed to the reader.
@ -179,7 +179,7 @@ export {
## file analysis framework. ## file analysis framework.
type AnalysisDescription: record { type AnalysisDescription: record {
## String that allows the reader to find the source. ## String that allows the reader to find the source.
## For `READER_ASCII`, this is the filename. ## For :zeek:see:`Input::READER_ASCII`, this is the filename.
source: string; source: string;
## Reader to use for this stream. Compatible readers must be ## Reader to use for this stream. Compatible readers must be
@ -205,14 +205,14 @@ export {
## Create a new table input stream from a given source. ## Create a new table input stream from a given source.
## ##
## description: `TableDescription` record describing the source. ## description: :zeek:see:`Input::TableDescription` record describing the source.
## ##
## Returns: true on success. ## Returns: true on success.
global add_table: function(description: Input::TableDescription) : bool; global add_table: function(description: Input::TableDescription) : bool;
## Create a new event input stream from a given source. ## Create a new event input stream from a given source.
## ##
## description: `EventDescription` record describing the source. ## description: :zeek:see:`Input::EventDescription` record describing the source.
## ##
## Returns: true on success. ## Returns: true on success.
global add_event: function(description: Input::EventDescription) : bool; global add_event: function(description: Input::EventDescription) : bool;
@ -278,4 +278,3 @@ function force_update(id: string) : bool
{ {
return __force_update(id); return __force_update(id);
} }

6
scripts/base/frameworks/logging/main.zeek
View file

@ -198,12 +198,12 @@ export {
## Default separator for log field scopes when logs are unrolled and ## Default separator for log field scopes when logs are unrolled and
## flattened. This will be the string between field name components. ## flattened. This will be the string between field name components.
## For example, setting this to "_" will cause the typical field ## For example, setting this to ``_`` will cause the typical field
## "id.orig_h" to turn into "id_orig_h". ## ``id.orig_h`` to turn into ``id_orig_h``.
const default_scope_sep = "." &redef; const default_scope_sep = "." &redef;
## A prefix for extension fields which can be optionally prefixed ## A prefix for extension fields which can be optionally prefixed
## on all log lines by setting the `ext_func` field in the ## on all log lines by setting the ``ext_func`` field in the
## log filter. ## log filter.
const Log::default_ext_prefix: string = "_" &redef; const Log::default_ext_prefix: string = "_" &redef;

2
scripts/base/frameworks/notice/main.zeek
View file

@ -203,7 +203,7 @@ export {
## on rotation with :zeek:enum:`Notice::ACTION_ALARM`. ## on rotation with :zeek:enum:`Notice::ACTION_ALARM`.
## ##
## Note that this is overridden by the ZeekControl MailTo option or by ## Note that this is overridden by the ZeekControl MailTo option or by
## the `email_dest` field in the :zeek:see:`Notice::Info` record. ## the ``email_dest`` field in the :zeek:see:`Notice::Info` record.
const mail_dest = "" &redef; const mail_dest = "" &redef;
## Address that emails will be from. ## Address that emails will be from.

2
scripts/base/frameworks/spicy/init-bare.zeek
View file

@ -23,7 +23,7 @@ export {
# doc-options-end # doc-options-end
# doc-types-start # doc-types-start
## Result type for `Spicy::resource_usage()`. The values reflect resource ## Result type for :zeek:see:`Spicy::resource_usage`. The values reflect resource
## usage as reported by the Spicy runtime system. ## usage as reported by the Spicy runtime system.
type ResourceUsage: record { type ResourceUsage: record {
user_time : interval; ##< user CPU time of the Zeek process user_time : interval; ##< user CPU time of the Zeek process

4
scripts/base/frameworks/supervisor/api.zeek
View file

@ -135,7 +135,7 @@ export {
global node: function(): NodeConfig; global node: function(): NodeConfig;
## Hooks into the stdout stream for all supervisor's child processes. ## Hooks into the stdout stream for all supervisor's child processes.
## If a hook terminates with `break`, that will suppress output to the ## If a hook terminates with ``break``, that will suppress output to the
## associated stream. ## associated stream.
## ##
## node: the name of a previously created node via ## node: the name of a previously created node via
@ -149,7 +149,7 @@ export {
global stdout_hook: hook(node: string, msg: string); global stdout_hook: hook(node: string, msg: string);
## Hooks into the stderr stream for all supervisor's child processes. ## Hooks into the stderr stream for all supervisor's child processes.
## If a hook terminates with `break`, that will suppress output to the ## If a hook terminates with ``break``, that will suppress output to the
## associated stream. ## associated stream.
## ##
## node: the name of a previously created node via ## node: the name of a previously created node via

18
scripts/base/frameworks/telemetry/main.zeek
View file

@ -42,8 +42,8 @@ export {
global counter_with: function(cf: CounterFamily, global counter_with: function(cf: CounterFamily,
label_values: labels_vector &default=vector()): Counter; label_values: labels_vector &default=vector()): Counter;
## Increment a :zeek:see:`Telemetry::Counter` by `amount`. ## Increment a :zeek:see:`Telemetry::Counter` by ``amount``.
## Using a negative `amount` is an error. ## Using a negative ``amount`` is an error.
## ##
## c: The counter instance. ## c: The counter instance.
## ##
@ -52,7 +52,7 @@ export {
## Returns: True if the counter was incremented successfully. ## Returns: True if the counter was incremented successfully.
global counter_inc: function(c: Counter, amount: double &default=1.0): bool; global counter_inc: function(c: Counter, amount: double &default=1.0): bool;
## Helper to set a :zeek:see:`Telemetry::Counter` to the given `value`. ## Helper to set a :zeek:see:`Telemetry::Counter` to the given ``value``.
## This can be useful for mirroring counter metrics in an ## This can be useful for mirroring counter metrics in an
## :zeek:see:`Telemetry::sync` hook implementation. ## :zeek:see:`Telemetry::sync` hook implementation.
## Setting a value that is less than the current value of the ## Setting a value that is less than the current value of the
@ -126,7 +126,7 @@ export {
global gauge_with: function(gf: GaugeFamily, global gauge_with: function(gf: GaugeFamily,
label_values: labels_vector &default=vector()): Gauge; label_values: labels_vector &default=vector()): Gauge;
## Increment a :zeek:see:`Telemetry::Gauge` by `amount`. ## Increment a :zeek:see:`Telemetry::Gauge` by ``amount``.
## ##
## g: The gauge instance. ## g: The gauge instance.
## ##
@ -135,7 +135,7 @@ export {
## Returns: True if the gauge was incremented successfully. ## Returns: True if the gauge was incremented successfully.
global gauge_inc: function(g: Gauge, amount: double &default=1.0): bool; global gauge_inc: function(g: Gauge, amount: double &default=1.0): bool;
## Decrement a :zeek:see:`Telemetry::Gauge` by `amount`. ## Decrement a :zeek:see:`Telemetry::Gauge` by ``amount``.
## ##
## g: The gauge instance. ## g: The gauge instance.
## ##
@ -144,7 +144,7 @@ export {
## Returns: True if the gauge was incremented successfully. ## Returns: True if the gauge was incremented successfully.
global gauge_dec: function(g: Gauge, amount: double &default=1.0): bool; global gauge_dec: function(g: Gauge, amount: double &default=1.0): bool;
## Helper to set a :zeek:see:`Telemetry::Gauge` to the given `value`. ## Helper to set a :zeek:see:`Telemetry::Gauge` to the given ``value``.
## ##
## g: The gauge instance. ## g: The gauge instance.
## ##
@ -153,7 +153,7 @@ export {
## Returns: True if the gauge value was set successfully. ## Returns: True if the gauge value was set successfully.
global gauge_set: function(g: Gauge, value: double): bool; global gauge_set: function(g: Gauge, value: double): bool;
## Increment a :zeek:see:`Telemetry::Gauge` by the given `amount` through ## Increment a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through
## the :zeek:see:`Telemetry::GaugeFamily`. ## the :zeek:see:`Telemetry::GaugeFamily`.
## This is a short-cut for :zeek:see:`Telemetry::gauge_inc`. ## This is a short-cut for :zeek:see:`Telemetry::gauge_inc`.
## Using a negative amount is an error. ## Using a negative amount is an error.
@ -169,7 +169,7 @@ export {
label_values: labels_vector &default=vector(), label_values: labels_vector &default=vector(),
amount: double &default=1.0): bool; amount: double &default=1.0): bool;
## Decrement a :zeek:see:`Telemetry::Gauge` by the given `amount` through ## Decrement a :zeek:see:`Telemetry::Gauge` by the given ``amount`` through
## the :zeek:see:`Telemetry::GaugeFamily`. ## the :zeek:see:`Telemetry::GaugeFamily`.
## This is a short-cut for :zeek:see:`Telemetry::gauge_dec`. ## This is a short-cut for :zeek:see:`Telemetry::gauge_dec`.
## ##
@ -184,7 +184,7 @@ export {
label_values: labels_vector &default=vector(), label_values: labels_vector &default=vector(),
amount: double &default=1.0): bool; amount: double &default=1.0): bool;
## Set a :zeek:see:`Telemetry::Gauge` to the given `value` through ## Set a :zeek:see:`Telemetry::Gauge` to the given ``value`` through
## the :zeek:see:`Telemetry::GaugeFamily`. ## the :zeek:see:`Telemetry::GaugeFamily`.
## This is a short-cut for :zeek:see:`Telemetry::gauge_set`. ## This is a short-cut for :zeek:see:`Telemetry::gauge_set`.
## ##

24
scripts/base/misc/version.zeek
View file

@ -1,6 +1,6 @@
##! Provide information about the currently running Zeek version. ##! Provide information about the currently running Zeek version. The most
##! The most convenient way to access this are the Version::number ##! convenient way to access this are the :zeek:see:`Version::number` and
##! and Version::info constants. ##! :zeek:see:`Version::info` constants.
module Version; module Version;
@ -41,11 +41,11 @@ export {
## ##
## version_string: Zeek version string. ## version_string: Zeek version string.
## ##
## Returns: `VersionDescription` record. ## Returns: :zeek:see:`Version::VersionDescription` record.
global parse: function(version_string: string): VersionDescription; global parse: function(version_string: string): VersionDescription;
## Test if the current running version of Zeek is greater or equal to the given version ## Test if the current running version of Zeek is greater or equal to
## string. ## the given version string.
## ##
## version_string: Version to check against the current running version. ## version_string: Version to check against the current running version.
## ##
@ -118,13 +118,15 @@ function parse(version_string: string): VersionDescription
} }
export { export {
## `VersionDescription` record pertaining to the currently running version of Zeek. ## :zeek:see:`Version::VersionDescription` record pertaining to the currently
## running version of Zeek.
const info = Version::parse(zeek_version()); const info = Version::parse(zeek_version());
## version number of the currently running version of Zeek as a numeric representation. ## version number of the currently running version of Zeek as a numeric
## The format of the number is ABBCC with A being the major version, ## representation. The format of the number is ABBCC with A being the
## bb being the minor version (2 digits) and CC being the patchlevel (2 digits). ## major version, bb being the minor version (2 digits) and CC being the
## As an example, Zeek 2.4.1 results in the number 20401 ## patchlevel (2 digits). As an example, Zeek 2.4.1 results in the
## number 20401
const number = info$version_number; const number = info$version_number;
} }

2
scripts/base/utils/exec.zeek
View file

@ -35,7 +35,7 @@ export {
## Function for running command line programs and getting ## Function for running command line programs and getting
## output. This is an asynchronous function which is meant ## output. This is an asynchronous function which is meant
## to be run with the `when` statement. ## to be run with the ``when`` statement.
## ##
## cmd: The command to run. Use care to avoid injection attacks! ## cmd: The command to run. Use care to avoid injection attacks!
## ##

4
scripts/base/utils/numbers.zeek
View file

@ -2,9 +2,9 @@
## ##
## s: The string to search for a number. ## s: The string to search for a number.
## ##
## get_first: Provide `F` if you would like the last number found. ## get_first: Provide ``F`` if you would like the last number found.
## ##
## Returns: The request integer from the given string or 0 if ## Returns: The request integer from the given string or ``0`` if
## no integer was found. ## no integer was found.
function extract_count(s: string, get_first: bool &default=T): count function extract_count(s: string, get_first: bool &default=T): count
{ {

6
scripts/policy/frameworks/packet-filter/shunt.zeek
View file

@ -14,13 +14,13 @@ export {
global shunt_conn: function(id: conn_id): bool; global shunt_conn: function(id: conn_id): bool;
## This function will use a BPF expression to shunt traffic between ## This function will use a BPF expression to shunt traffic between
## the two hosts given in the `conn_id` so that the traffic is never ## the two hosts given in the ``conn_id`` so that the traffic is never
## exposed to Zeek's traffic processing. ## exposed to Zeek's traffic processing.
global shunt_host_pair: function(id: conn_id): bool; global shunt_host_pair: function(id: conn_id): bool;
## Remove shunting for a host pair given as a `conn_id`. The filter ## Remove shunting for a host pair given as a ``conn_id``. The filter
## is not immediately removed. It waits for the occasional filter ## is not immediately removed. It waits for the occasional filter
## update done by the `PacketFilter` framework. ## update done by the ``PacketFilter`` framework.
global unshunt_host_pair: function(id: conn_id): bool; global unshunt_host_pair: function(id: conn_id): bool;
## Performs the same function as the :zeek:id:`PacketFilter::unshunt_host_pair` ## Performs the same function as the :zeek:id:`PacketFilter::unshunt_host_pair`

9
scripts/policy/frameworks/telemetry/log.zeek
View file

@ -1,5 +1,5 @@
##! Implementation of a telemetry.log and telemetry_histogram.log file ##! Implementation of a :file:`telemetry.log` and :file:`telemetry_histogram.log`
##! using metrics accessible via the Telemetry module. ##! file using metrics accessible via the Telemetry module.
@load base/frameworks/telemetry @load base/frameworks/telemetry
@ -12,8 +12,9 @@ export {
option log_interval = 60sec; option log_interval = 60sec;
## Only metrics with prefixes in this set will be included in the ## Only metrics with prefixes in this set will be included in the
## `telemetry.log` and `telemetry_histogram.log` files by default. ## :file:`telemetry.log` and :file:`telemetry_histogram.log` files
## Setting this option to an empty set includes all prefixes. ## by default. Setting this option to an empty set includes all
## prefixes.
## ##
## For more fine-grained customization, setting this option to an ## For more fine-grained customization, setting this option to an
## empty set and implementing the :zeek:see:`Telemetry::log_policy` ## empty set and implementing the :zeek:see:`Telemetry::log_policy`

4
src/event.bif
View file

@ -724,8 +724,8 @@ event file_over_new_connection%(f: fa_file, c: connection, is_orig: bool%);
## of the file. The analysis can be augmented at this time via ## 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 ## :zeek:see:`Files::add_analyzer`. The amount of data fed into the file
## sniffing can be increased or decreased by changing either ## sniffing can be increased or decreased by changing either
## :zeek:see:`default_file_bof_buffer_size` or the `bof_buffer_size` field ## :zeek:see:`default_file_bof_buffer_size` or the ``bof_buffer_size`` field
## in an `fa_file` record. The event will be raised even if content inspection ## 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* ## has been unable to infer any metadata, in which case the fields in *meta*
## will be left all unset. ## will be left all unset.
## ##

4
src/packet_analysis/packet_analysis.bif
View file

@ -28,7 +28,7 @@ function register_packet_analyzer%(parent: PacketAnalyzer::Tag, identifier: coun
return zeek::val_mgr->True(); return zeek::val_mgr->True();
%} %}
## Attempts to add an entry to `parent`'s dispatcher that maps a protocol/index to a next-stage `child` ## Attempts to add an entry to ``parent``'s dispatcher that maps a protocol/index to a next-stage ``child``
## analyzer. This may fail if either of the two names does not respond to a known analyzer. ## analyzer. This may fail if either of the two names does not respond to a known analyzer.
## ##
## parent: The parent analyzer being modified ## parent: The parent analyzer being modified
@ -49,7 +49,7 @@ function try_register_packet_analyzer_by_name%(parent: string, identifier: count
return zeek::val_mgr->True(); return zeek::val_mgr->True();
%} %}
## Internal function that is used to update the core-mirror of the script-level `ignore_checksums_nets` variable. ## Internal function that is used to update the core-mirror of the script-level ``ignore_checksums_nets`` variable.
function PacketAnalyzer::__set_ignore_checksums_nets%(v: subnet_set%) : bool function PacketAnalyzer::__set_ignore_checksums_nets%(v: subnet_set%) : bool
%{ %{
if ( v->GetType()->Tag() != zeek::TYPE_TABLE ) if ( v->GetType()->Tag() != zeek::TYPE_TABLE )