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
* 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;
## 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;
## Max number of items we buffer at most per peer. What action to take when
## the buffer reaches its maximum size is determined by
## `peer_overflow_policy`.
## :zeek:see:`Broker::peer_overflow_policy`.
const peer_buffer_size = 2048 &redef;
## 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
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;
## 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;
## 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
};
## 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;
## The default reader mode used. Defaults to `MANUAL`.
## The default reader mode used. Defaults to :zeek:see:`Input::MANUAL`.
option default_mode = MANUAL;
## Separator between fields.
@ -60,7 +60,7 @@ export {
# Common definitions for tables and events
## 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;
## Reader to use for this stream.
@ -112,7 +112,7 @@ export {
##
## The event is raised like if it had been declared as follows:
## 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;
## A key/value table that will be passed to the reader.
@ -126,7 +126,7 @@ export {
# Common definitions for tables and events
## 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;
## Reader to use for this stream.
@ -151,8 +151,8 @@ export {
want_record: bool &default=T;
## The event that is raised each time a new line is received from the
## reader. The event will receive an Input::EventDescription record
## as the first argument, an Input::Event enum as the second
## reader. The event will receive an :zeek:see:`Input::EventDescription` record
## as the first argument, an :zeek:see:`Input::Event` enum as the second
## argument, and the fields (as specified in *fields*) as the following
## arguments (this will either be a single record value containing
## 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
## is raised by the input stream. If the level is error, the stream will automatically
## be closed.
## The event receives the Input::EventDescription as the first argument, the
## message as the second argument and the Reporter::Level as the third argument.
## The event receives the :zeek:see:`Input::EventDescription` as the first argument, the
## 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:
## 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;
## A key/value table that will be passed to the reader.
@ -179,7 +179,7 @@ export {
## file analysis framework.
type AnalysisDescription: record {
## 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;
## 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.
##
## description: `TableDescription` record describing the source.
## description: :zeek:see:`Input::TableDescription` record describing the source.
##
## Returns: true on success.
global add_table: function(description: Input::TableDescription) : bool;
## 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.
global add_event: function(description: Input::EventDescription) : bool;
@ -278,4 +278,3 @@ function force_update(id: string) : bool
{
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
## flattened. This will be the string between field name components.
## For example, setting this to "_" will cause the typical field
## "id.orig_h" to turn into "id_orig_h".
## For example, setting this to ``_`` will cause the typical field
## ``id.orig_h`` to turn into ``id_orig_h``.
const default_scope_sep = "." &redef;
## 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.
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`.
##
## 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;
## 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-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.
type ResourceUsage: record {
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;
## 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.
##
## node: the name of a previously created node via
@ -149,7 +149,7 @@ export {
global stdout_hook: hook(node: string, msg: string);
## 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.
##
## 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,
label_values: labels_vector &default=vector()): Counter;
## Increment a :zeek:see:`Telemetry::Counter` by `amount`.
## Using a negative `amount` is an error.
## Increment a :zeek:see:`Telemetry::Counter` by ``amount``.
## Using a negative ``amount`` is an error.
##
## c: The counter instance.
##
@ -52,7 +52,7 @@ export {
## Returns: True if the counter was incremented successfully.
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
## :zeek:see:`Telemetry::sync` hook implementation.
## Setting a value that is less than the current value of the
@ -126,7 +126,7 @@ export {
global gauge_with: function(gf: GaugeFamily,
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.
##
@ -135,7 +135,7 @@ export {
## Returns: True if the gauge was incremented successfully.
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.
##
@ -144,7 +144,7 @@ export {
## Returns: True if the gauge was incremented successfully.
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.
##
@ -153,7 +153,7 @@ export {
## Returns: True if the gauge value was set successfully.
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`.
## This is a short-cut for :zeek:see:`Telemetry::gauge_inc`.
## Using a negative amount is an error.
@ -169,7 +169,7 @@ export {
label_values: labels_vector &default=vector(),
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`.
## This is a short-cut for :zeek:see:`Telemetry::gauge_dec`.
##
@ -184,7 +184,7 @@ export {
label_values: labels_vector &default=vector(),
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`.
## 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.
##! The most convenient way to access this are the Version::number
##! and Version::info constants.
##! Provide information about the currently running Zeek version. The most
##! convenient way to access this are the :zeek:see:`Version::number` and
##! :zeek:see:`Version::info` constants.
module Version;
@ -41,11 +41,11 @@ export {
##
## version_string: Zeek version string.
##
## Returns: `VersionDescription` record.
## Returns: :zeek:see:`Version::VersionDescription` record.
global parse: function(version_string: string): VersionDescription;
## Test if the current running version of Zeek is greater or equal to the given version
## string.
## Test if the current running version of Zeek is greater or equal to
## the given version string.
##
## version_string: Version to check against the current running version.
##
@ -118,13 +118,15 @@ function parse(version_string: string): VersionDescription
}
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());
## version number of the currently running version of Zeek as a numeric representation.
## The format of the number is ABBCC with A being the major version,
## bb being the minor version (2 digits) and CC being the patchlevel (2 digits).
## As an example, Zeek 2.4.1 results in the number 20401
## version number of the currently running version of Zeek as a numeric
## representation. The format of the number is ABBCC with A being the
## major version, bb being the minor version (2 digits) and CC being the
## patchlevel (2 digits). As an example, Zeek 2.4.1 results in the
## number 20401
const number = info$version_number;
}

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

@ -6,7 +6,7 @@ module Exec;
export {
type Command: record {
## The command line to execute. Use care to avoid injection
## The command line to execute. Use care to avoid injection
## attacks (i.e., if the command uses untrusted/variable data,
## sanitize it with :zeek:see:`safe_shell_quote`).
cmd: string;
@ -34,10 +34,10 @@ export {
};
## Function for running command line programs and getting
## output. This is an asynchronous function which is meant
## to be run with the `when` statement.
## output. This is an asynchronous function which is meant
## 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!
##
## Returns: A record representing the full results from the
## external program execution.

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

@ -2,9 +2,9 @@
##
## 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.
function extract_count(s: string, get_first: bool &default=T): count
{

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

@ -8,19 +8,19 @@ export {
const max_bpf_shunts = 100 &redef;
## Call this function to use BPF to shunt a connection (to prevent the
## data packets from reaching Zeek). For TCP connections, control
## data packets from reaching Zeek). For TCP connections, control
## packets are still allowed through so that Zeek can continue logging
## the connection and it can stop shunting once the connection ends.
global shunt_conn: function(id: conn_id): bool;
## 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.
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
## update done by the `PacketFilter` framework.
## update done by the ``PacketFilter`` framework.
global unshunt_host_pair: function(id: conn_id): bool;
## Performs the same function as the :zeek:id:`PacketFilter::unshunt_host_pair`
@ -40,7 +40,7 @@ export {
No_More_Conn_Shunts_Available,
## Limitations in BPF make shunting some connections with BPF
## impossible. This notice encompasses those various cases.
## impossible. This notice encompasses those various cases.
Cannot_BPF_Shunt_Conn,
};
}

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

@ -1,5 +1,5 @@
##! Implementation of a telemetry.log and telemetry_histogram.log file
##! using metrics accessible via the Telemetry module.
##! Implementation of a :file:`telemetry.log` and :file:`telemetry_histogram.log`
##! file using metrics accessible via the Telemetry module.
@load base/frameworks/telemetry
@ -12,8 +12,9 @@ export {
option log_interval = 60sec;
## Only metrics with prefixes in this set will be included in the
## `telemetry.log` and `telemetry_histogram.log` files by default.
## Setting this option to an empty set includes all prefixes.
## :file:`telemetry.log` and :file:`telemetry_histogram.log` files
## by default. Setting this option to an empty set includes all
## prefixes.
##
## For more fine-grained customization, setting this option to an
## 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
## :zeek:see:`Files::add_analyzer`. The amount of data fed into the file
## sniffing can be increased or decreased by changing either
## :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
## :zeek:see:`default_file_bof_buffer_size` or the ``bof_buffer_size`` field
## 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*
## 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();
%}
## 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.
##
## 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();
%}
## 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
%{
if ( v->GetType()->Tag() != zeek::TYPE_TABLE )