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

Copy docs into Zeek repo directly

Browse source 
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the
zeek-docs repo.
This commit is contained in:
Tim Wojtulewicz 2025-09-15 15:52:18 -07:00
parent 83f1e74643
commit ded98cd373
1074 changed files with 169319 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

14
doc/scripts/base/protocols/conn/__load__.zeek.rst Normal file
View file

@ -0,0 +1,14 @@
:tocdepth: 3
base/protocols/conn/__load__.zeek
=================================
:Imports: :doc:`base/protocols/conn/contents.zeek </scripts/base/protocols/conn/contents.zeek>`, :doc:`base/protocols/conn/inactivity.zeek </scripts/base/protocols/conn/inactivity.zeek>`, :doc:`base/protocols/conn/main.zeek </scripts/base/protocols/conn/main.zeek>`, :doc:`base/protocols/conn/polling.zeek </scripts/base/protocols/conn/polling.zeek>`, :doc:`base/protocols/conn/removal-hooks.zeek </scripts/base/protocols/conn/removal-hooks.zeek>`, :doc:`base/protocols/conn/thresholds.zeek </scripts/base/protocols/conn/thresholds.zeek>`
Summary
~~~~~~~
Detailed Interface
~~~~~~~~~~~~~~~~~~

71
doc/scripts/base/protocols/conn/contents.zeek.rst Normal file
View file

@ -0,0 +1,71 @@
:tocdepth: 3
base/protocols/conn/contents.zeek
=================================
.. zeek:namespace:: Conn
This script can be used to extract either the originator's data or the
responders data or both. By default nothing is extracted, and in order
to actually extract data the ``c$extract_orig`` and/or the
``c$extract_resp`` variable must be set to ``T``. One way to achieve this
would be to handle the :zeek:id:`connection_established` event elsewhere
and set the ``extract_orig`` and ``extract_resp`` options there.
However, there may be trouble with the timing due to event queue delay.
.. note::
This script does not work well in a cluster context unless it has a
remotely mounted disk to write the content files to.
:Namespace: Conn
:Imports: :doc:`base/utils/files.zeek </scripts/base/utils/files.zeek>`
Summary
~~~~~~~
Runtime Options
###############
=========================================================================== ==================================================================
:zeek:id:`Conn::default_extract`: :zeek:type:`bool` :zeek:attr:`&redef` If this variable is set to ``T``, then all contents of all
connections will be extracted.
:zeek:id:`Conn::extraction_prefix`: :zeek:type:`string` :zeek:attr:`&redef` The prefix given to files containing extracted connections as they
are opened on disk.
=========================================================================== ==================================================================
Redefinitions
#############
============================================ ==================================================================================================================
:zeek:type:`connection`: :zeek:type:`record`
:New Fields: :zeek:type:`connection`
extract_orig: :zeek:type:`bool` :zeek:attr:`&default` = :zeek:see:`Conn::default_extract` :zeek:attr:`&optional`
extract_resp: :zeek:type:`bool` :zeek:attr:`&default` = :zeek:see:`Conn::default_extract` :zeek:attr:`&optional`
============================================ ==================================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: Conn::default_extract
:source-code: base/protocols/conn/contents.zeek 25 25
:Type: :zeek:type:`bool`
:Attributes: :zeek:attr:`&redef`
:Default: ``F``
If this variable is set to ``T``, then all contents of all
connections will be extracted.
.. zeek:id:: Conn::extraction_prefix
:source-code: base/protocols/conn/contents.zeek 21 21
:Type: :zeek:type:`string`
:Attributes: :zeek:attr:`&redef`
:Default: ``"contents"``
The prefix given to files containing extracted connections as they
are opened on disk.

64
doc/scripts/base/protocols/conn/inactivity.zeek.rst Normal file
View file

@ -0,0 +1,64 @@
:tocdepth: 3
base/protocols/conn/inactivity.zeek
===================================
.. zeek:namespace:: Conn
Adjust the inactivity timeouts for interactive services which could
very possibly have long delays between packets.
:Namespace: Conn
Summary
~~~~~~~
Runtime Options
###############
===================================================================================== ==================================================================
:zeek:id:`Conn::analyzer_inactivity_timeouts`: :zeek:type:`table` :zeek:attr:`&redef` Define inactivity timeouts by the service detected being used over
the connection.
:zeek:id:`Conn::port_inactivity_timeouts`: :zeek:type:`table` :zeek:attr:`&redef` Define inactivity timeouts based on common protocol ports.
===================================================================================== ==================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: Conn::analyzer_inactivity_timeouts
:source-code: base/protocols/conn/inactivity.zeek 9 9
:Type: :zeek:type:`table` [:zeek:type:`AllAnalyzers::Tag`] of :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default:
::
{
[AllAnalyzers::ANALYZER_ANALYZER_FTP] = 1.0 hr,
[AllAnalyzers::ANALYZER_ANALYZER_SSH] = 1.0 hr
}
Define inactivity timeouts by the service detected being used over
the connection.
.. zeek:id:: Conn::port_inactivity_timeouts
:source-code: base/protocols/conn/inactivity.zeek 15 15
:Type: :zeek:type:`table` [:zeek:type:`port`] of :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default:
::
{
[513/tcp] = 1.0 hr,
[21/tcp] = 1.0 hr,
[23/tcp] = 1.0 hr,
[22/tcp] = 1.0 hr
}
Define inactivity timeouts based on common protocol ports.

62
doc/scripts/base/protocols/conn/index.rst Normal file
View file

@ -0,0 +1,62 @@
:orphan:
Package: base/protocols/conn
============================
Support for connection (TCP, UDP, or ICMP) analysis.
:doc:`/scripts/base/protocols/conn/removal-hooks.zeek`
Adds a framework for registering "connection removal hooks".
All registered hooks for a given connection get run within the
:zeek:see:`connection_state_remove` event for that connection.
This functionality is useful from a performance/scaling concern:
if every new protocol-analysis script uses
:zeek:see:`connection_state_remove` to implement its finalization/cleanup
logic, then all connections take the performance hit of dispatching that
event, even if they aren't related to that specific protocol.
:doc:`/scripts/base/protocols/conn/__load__.zeek`
:doc:`/scripts/base/protocols/conn/main.zeek`
This script manages the tracking/logging of general information regarding
TCP, UDP, and ICMP traffic. For UDP and ICMP, "connections" are to
be interpreted using flow semantics (sequence of packets from a source
host/port to a destination host/port). Further, ICMP "ports" are to
be interpreted as the source port meaning the ICMP message type and
the destination port being the ICMP message code.
:doc:`/scripts/base/protocols/conn/contents.zeek`
This script can be used to extract either the originator's data or the
responders data or both. By default nothing is extracted, and in order
to actually extract data the ``c$extract_orig`` and/or the
``c$extract_resp`` variable must be set to ``T``. One way to achieve this
would be to handle the :zeek:id:`connection_established` event elsewhere
and set the ``extract_orig`` and ``extract_resp`` options there.
However, there may be trouble with the timing due to event queue delay.
.. note::
This script does not work well in a cluster context unless it has a
remotely mounted disk to write the content files to.
:doc:`/scripts/base/protocols/conn/inactivity.zeek`
Adjust the inactivity timeouts for interactive services which could
very possibly have long delays between packets.
:doc:`/scripts/base/protocols/conn/polling.zeek`
Implements a generic way to poll connections looking for certain features
(e.g. monitor bytes transferred). The specific feature of a connection
to look for, the polling interval, and the code to execute if the feature
is found are all controlled by user-defined callback functions.
:doc:`/scripts/base/protocols/conn/thresholds.zeek`
Implements a generic API to throw events when a connection crosses a
fixed threshold of bytes or packets.

346
doc/scripts/base/protocols/conn/main.zeek.rst Normal file
View file

@ -0,0 +1,346 @@
:tocdepth: 3
base/protocols/conn/main.zeek
=============================
.. zeek:namespace:: Conn
This script manages the tracking/logging of general information regarding
TCP, UDP, and ICMP traffic. For UDP and ICMP, "connections" are to
be interpreted using flow semantics (sequence of packets from a source
host/port to a destination host/port). Further, ICMP "ports" are to
be interpreted as the source port meaning the ICMP message type and
the destination port being the ICMP message code.
:Namespace: Conn
:Imports: :doc:`base/utils/site.zeek </scripts/base/utils/site.zeek>`, :doc:`base/utils/strings.zeek </scripts/base/utils/strings.zeek>`
Summary
~~~~~~~
Types
#####
============================================ ===================================================================
:zeek:type:`Conn::Info`: :zeek:type:`record` The record type which contains column fields of the connection log.
============================================ ===================================================================
Redefinitions
#############
============================================ ======================================================
:zeek:type:`Log::ID`: :zeek:type:`enum` The connection logging stream identifier.
* :zeek:enum:`Conn::LOG`
:zeek:type:`connection`: :zeek:type:`record`
:New Fields: :zeek:type:`connection`
conn: :zeek:type:`Conn::Info` :zeek:attr:`&optional`
============================================ ======================================================
Events
######
============================================= ===============================================================
:zeek:id:`Conn::log_conn`: :zeek:type:`event` Event that can be handled to access the :zeek:type:`Conn::Info`
record as it is sent on to the logging framework.
============================================= ===============================================================
Hooks
#####
========================================================= =============================================
:zeek:id:`Conn::log_policy`: :zeek:type:`Log::PolicyHook` A default logging policy hook for the stream.
========================================================= =============================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. zeek:type:: Conn::Info
:source-code: base/protocols/conn/main.zeek 21 168
:Type: :zeek:type:`record`
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
This is the time of the first packet.
.. zeek:field:: uid :zeek:type:`string` :zeek:attr:`&log`
A unique identifier of the connection.
.. zeek:field:: id :zeek:type:`conn_id` :zeek:attr:`&log`
The connection's 4-tuple of endpoint addresses/ports.
.. zeek:field:: proto :zeek:type:`transport_proto` :zeek:attr:`&log`
The transport layer protocol of the connection.
.. zeek:field:: service :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
A comma-separated list of confirmed protocol(s).
With :zeek:see:DPD::track_removed_services_in_connection, the list
includes the same protocols prefixed with "-" to record that Zeek
dropped them due to parsing violations."
.. zeek:field:: duration :zeek:type:`interval` :zeek:attr:`&log` :zeek:attr:`&optional`
How long the connection lasted.
.. note:: The duration doesn't cover trailing "non-productive"
TCP packets (i.e., ones not contributing new stream payload)
once a direction is closed. For example, for regular
3-way/4-way connection tear-downs it doesn't include the
final ACK. The reason is largely historic: this approach
allows more accurate computation of connection data rates.
Zeek does however reflect such trailing packets in the
connection history.
.. zeek:field:: orig_bytes :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
The number of payload bytes the originator sent. For TCP
this is taken from sequence numbers and might be inaccurate
(e.g., due to large connections).
.. zeek:field:: resp_bytes :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
The number of payload bytes the responder sent. See
*orig_bytes*.
.. zeek:field:: conn_state :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Possible *conn_state* values:
* S0: Connection attempt seen, no reply.
* S1: Connection established, not terminated.
* SF: Normal establishment and termination.
Note that this is the same symbol as for state S1.
You can tell the two apart because for S1 there will not be any
byte counts in the summary, while for SF there will be.
* REJ: Connection attempt rejected.
* S2: Connection established and close attempt by originator seen
(but no reply from responder).
* S3: Connection established and close attempt by responder seen
(but no reply from originator).
* RSTO: Connection established, originator aborted (sent a RST).
* RSTR: Responder sent a RST.
* RSTOS0: Originator sent a SYN followed by a RST, we never saw a
SYN-ACK from the responder.
* RSTRH: Responder sent a SYN ACK followed by a RST, we never saw a
SYN from the (purported) originator.
* SH: Originator sent a SYN followed by a FIN, we never saw a
SYN ACK from the responder (hence the connection was "half" open).
* SHR: Responder sent a SYN ACK followed by a FIN, we never saw a
SYN from the originator.
* OTH: No SYN seen, just midstream traffic (one example of this
is a "partial connection" that was not later closed).
.. zeek:field:: local_orig :zeek:type:`bool` :zeek:attr:`&log` :zeek:attr:`&optional`
If the connection is originated locally, this value will be T.
If it was originated remotely it will be F. In the case that
the :zeek:id:`Site::local_nets` variable is undefined, this
field will be left empty at all times.
.. zeek:field:: local_resp :zeek:type:`bool` :zeek:attr:`&log` :zeek:attr:`&optional`
If the connection is responded to locally, this value will be T.
If it was responded to remotely it will be F. In the case that
the :zeek:id:`Site::local_nets` variable is undefined, this
field will be left empty at all times.
.. zeek:field:: missed_bytes :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
Indicates the number of bytes missed in content gaps, which
is representative of packet loss. A value other than zero
will normally cause protocol analysis to fail but some
analysis may have been completed prior to the packet loss.
.. zeek:field:: history :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Records the state history of connections as a string of
letters. The meaning of those letters is:
====== ====================================================
Letter Meaning
====== ====================================================
s a SYN w/o the ACK bit set
h a SYN+ACK ("handshake")
a a pure ACK
d packet with payload ("data")
f packet with FIN bit set
r packet with RST bit set
c packet with a bad checksum (applies to UDP too)
g a content gap
t packet with retransmitted payload
w packet with a zero window advertisement
i inconsistent packet (e.g. FIN+RST bits set)
q multi-flag packet (SYN+FIN or SYN+RST bits set)
^ connection direction was flipped by Zeek's heuristic
x connection analysis partial (e.g. limits exceeded)
====== ====================================================
If the event comes from the originator, the letter is in
upper-case; if it comes from the responder, it's in
lower-case. The 'a', 'd', 'i' and 'q' flags are
recorded a maximum of one time in either direction regardless
of how many are actually seen. 'f', 'h', 'r' and
's' can be recorded multiple times for either direction
if the associated sequence number differs from the
last-seen packet of the same flag type.
'c', 'g', 't' and 'w' are recorded in a logarithmic fashion:
the second instance represents that the event was seen
(at least) 10 times; the third instance, 100 times; etc.
.. zeek:field:: orig_pkts :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of packets that the originator sent.
Only set if :zeek:id:`use_conn_size_analyzer` = T.
.. zeek:field:: orig_ip_bytes :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of IP level bytes that the originator sent (as seen on
the wire, taken from the IP total_length header field).
Only set if :zeek:id:`use_conn_size_analyzer` = T.
.. zeek:field:: resp_pkts :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of packets that the responder sent.
Only set if :zeek:id:`use_conn_size_analyzer` = T.
.. zeek:field:: resp_ip_bytes :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of IP level bytes that the responder sent (as seen on
the wire, taken from the IP total_length header field).
Only set if :zeek:id:`use_conn_size_analyzer` = T.
.. zeek:field:: tunnel_parents :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&log` :zeek:attr:`&optional`
If this connection was over a tunnel, indicate the
*uid* values for any encapsulating parent connections
used over the lifetime of this inner connection.
.. zeek:field:: ip_proto :zeek:type:`count` :zeek:attr:`&optional`
For IP-based connections, this contains the protocol
identifier passed in the IP header. This is different
from the *proto* field in that this value comes
directly from the header.
.. zeek:field:: community_id :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log`
(present if :doc:`/scripts/policy/protocols/conn/community-id-logging.zeek` is loaded)
.. zeek:field:: failed_service :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&log` :zeek:attr:`&optional` :zeek:attr:`&ordered`
(present if :doc:`/scripts/policy/protocols/conn/failed-service-logging.zeek` is loaded)
List of analyzers in a connection that raised violations
causing their removal.
Analyzers are listed in order that they were removed.
.. zeek:field:: ip_proto_name :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/ip-proto-name-logging.zeek` is loaded)
A string version of the ip_proto field
.. zeek:field:: orig_l2_addr :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/mac-logging.zeek` is loaded)
Link-layer address of the originator, if available.
.. zeek:field:: resp_l2_addr :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/mac-logging.zeek` is loaded)
Link-layer address of the responder, if available.
.. zeek:field:: vlan :zeek:type:`int` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/vlan-logging.zeek` is loaded)
The outer VLAN for this connection, if applicable.
.. zeek:field:: inner_vlan :zeek:type:`int` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/vlan-logging.zeek` is loaded)
The inner VLAN for this connection, if applicable.
.. zeek:field:: pppoe_session_id :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/pppoe-session-id-logging.zeek` is loaded)
The PPPoE session id, if applicable for this connection.
.. zeek:field:: speculative_service :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
(present if :doc:`/scripts/policy/protocols/conn/speculative-service.zeek` is loaded)
Protocol that was determined by a matching signature after the beginning
of a connection. In this situation no analyzer can be attached and hence
the data cannot be analyzed nor the protocol can be confirmed.
The record type which contains column fields of the connection log.
Events
######
.. zeek:id:: Conn::log_conn
:source-code: base/protocols/conn/main.zeek 172 172
:Type: :zeek:type:`event` (rec: :zeek:type:`Conn::Info`)
Event that can be handled to access the :zeek:type:`Conn::Info`
record as it is sent on to the logging framework.
Hooks
#####
.. zeek:id:: Conn::log_policy
:source-code: base/protocols/conn/main.zeek 18 18
:Type: :zeek:type:`Log::PolicyHook`
A default logging policy hook for the stream.

52
doc/scripts/base/protocols/conn/polling.zeek.rst Normal file
View file

@ -0,0 +1,52 @@
:tocdepth: 3
base/protocols/conn/polling.zeek
================================
.. zeek:namespace:: ConnPolling
Implements a generic way to poll connections looking for certain features
(e.g. monitor bytes transferred). The specific feature of a connection
to look for, the polling interval, and the code to execute if the feature
is found are all controlled by user-defined callback functions.
:Namespace: ConnPolling
Summary
~~~~~~~
Functions
#########
==================================================== =====================================
:zeek:id:`ConnPolling::watch`: :zeek:type:`function` Starts monitoring a given connection.
==================================================== =====================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Functions
#########
.. zeek:id:: ConnPolling::watch
:source-code: base/protocols/conn/polling.zeek 47 51
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, callback: :zeek:type:`function` (c: :zeek:type:`connection`, cnt: :zeek:type:`count`) : :zeek:type:`interval`, cnt: :zeek:type:`count`, i: :zeek:type:`interval`) : :zeek:type:`void`
Starts monitoring a given connection.
:param c: The connection to watch.
:param callback: A callback function that takes as arguments the monitored
*connection*, and counter *cnt* that increments each time
the callback is called. It returns an interval indicating
how long in the future to schedule an event which will call
the callback. A negative return interval causes polling
to stop.
:param cnt: The initial value of a counter which gets passed to *callback*.
:param i: The initial interval at which to schedule the next callback.
May be ``0secs`` to poll right away.

101
doc/scripts/base/protocols/conn/removal-hooks.zeek.rst Normal file
View file

@ -0,0 +1,101 @@
:tocdepth: 3
base/protocols/conn/removal-hooks.zeek
======================================
.. zeek:namespace:: Conn
Adds a framework for registering "connection removal hooks".
All registered hooks for a given connection get run within the
:zeek:see:`connection_state_remove` event for that connection.
This functionality is useful from a performance/scaling concern:
if every new protocol-analysis script uses
:zeek:see:`connection_state_remove` to implement its finalization/cleanup
logic, then all connections take the performance hit of dispatching that
event, even if they aren't related to that specific protocol.
:Namespace: Conn
Summary
~~~~~~~
Types
#####
================================================= ===========================================================================
:zeek:type:`Conn::RemovalHook`: :zeek:type:`hook` A hook function for use with either :zeek:see:`Conn::register_removal_hook`
or :zeek:see:`Conn::unregister_removal_hook`.
================================================= ===========================================================================
Redefinitions
#############
============================================ =========================================================================================
:zeek:type:`connection`: :zeek:type:`record`
:New Fields: :zeek:type:`connection`
removal_hooks: :zeek:type:`set` [:zeek:type:`Conn::RemovalHook`] :zeek:attr:`&optional`
============================================ =========================================================================================
Functions
#########
=============================================================== =====================================================================
:zeek:id:`Conn::register_removal_hook`: :zeek:type:`function` Register a hook that will later be called during a connection's
:zeek:see:`connection_state_remove` event.
:zeek:id:`Conn::unregister_removal_hook`: :zeek:type:`function` Unregister a hook that would have been called during a connection's
:zeek:see:`connection_state_remove` event such that it will no longer
be called.
=============================================================== =====================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. zeek:type:: Conn::RemovalHook
:source-code: base/protocols/conn/removal-hooks.zeek 17 17
:Type: :zeek:type:`hook` (c: :zeek:type:`connection`) : :zeek:type:`bool`
A hook function for use with either :zeek:see:`Conn::register_removal_hook`
or :zeek:see:`Conn::unregister_removal_hook`. The :zeek:see:`connection`
argument refers to the connection currently being removed within a
:zeek:see:`connection_state_remove` event.
Functions
#########
.. zeek:id:: Conn::register_removal_hook
:source-code: base/protocols/conn/removal-hooks.zeek 47 60
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, hk: :zeek:type:`Conn::RemovalHook`) : :zeek:type:`bool`
Register a hook that will later be called during a connection's
:zeek:see:`connection_state_remove` event.
:param c: The associated connection whose :zeek:see:`connection_state_remove`
event should trigger a callback to *hk*.
:param hk: The hook function to use as a callback.
:returns: false if the provided hook was previously registered, else true.
.. zeek:id:: Conn::unregister_removal_hook
:source-code: base/protocols/conn/removal-hooks.zeek 62 72
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, hk: :zeek:type:`Conn::RemovalHook`) : :zeek:type:`bool`
Unregister a hook that would have been called during a connection's
:zeek:see:`connection_state_remove` event such that it will no longer
be called.
:param c: The associated connection whose :zeek:see:`connection_state_remove`
event could have triggered a callback to *hk*.
:param hk: The hook function that would have been used as a callback.
:returns: true if the provided hook was previously registered, else false.

252
doc/scripts/base/protocols/conn/thresholds.zeek.rst Normal file
View file

@ -0,0 +1,252 @@
:tocdepth: 3
base/protocols/conn/thresholds.zeek
===================================
.. zeek:namespace:: ConnThreshold
Implements a generic API to throw events when a connection crosses a
fixed threshold of bytes or packets.
:Namespace: ConnThreshold
Summary
~~~~~~~
Types
#####
=========================================================== =
:zeek:type:`ConnThreshold::Thresholds`: :zeek:type:`record`
=========================================================== =
Redefinitions
#############
============================================ ===========================================================================
:zeek:type:`connection`: :zeek:type:`record`
:New Fields: :zeek:type:`connection`
thresholds: :zeek:type:`ConnThreshold::Thresholds` :zeek:attr:`&optional`
============================================ ===========================================================================
Events
######
======================================================================== =================================================================
:zeek:id:`ConnThreshold::bytes_threshold_crossed`: :zeek:type:`event` Generated for a connection that crossed a set byte threshold
:zeek:id:`ConnThreshold::duration_threshold_crossed`: :zeek:type:`event` Generated for a connection that crossed a set duration threshold.
:zeek:id:`ConnThreshold::packets_threshold_crossed`: :zeek:type:`event` Generated for a connection that crossed a set byte threshold
======================================================================== =================================================================
Functions
#########
========================================================================== ===================================================================================================
:zeek:id:`ConnThreshold::delete_bytes_threshold`: :zeek:type:`function` Deletes a byte threshold for connection sizes.
:zeek:id:`ConnThreshold::delete_duration_threshold`: :zeek:type:`function` Deletes a duration threshold for a connection.
:zeek:id:`ConnThreshold::delete_packets_threshold`: :zeek:type:`function` Deletes a packet threshold for connection sizes.
:zeek:id:`ConnThreshold::set_bytes_threshold`: :zeek:type:`function` Sets a byte threshold for connection sizes, adding it to potentially already existing thresholds.
:zeek:id:`ConnThreshold::set_duration_threshold`: :zeek:type:`function` Sets a duration threshold for a connection, adding it to potentially already existing thresholds.
:zeek:id:`ConnThreshold::set_packets_threshold`: :zeek:type:`function` Sets a packet threshold for connection sizes, adding it to potentially already existing thresholds.
========================================================================== ===================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. zeek:type:: ConnThreshold::Thresholds
:source-code: base/protocols/conn/thresholds.zeek 8 14
:Type: :zeek:type:`record`
.. zeek:field:: orig_byte :zeek:type:`set` [:zeek:type:`count`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
current originator byte thresholds we watch for
.. zeek:field:: resp_byte :zeek:type:`set` [:zeek:type:`count`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
current responder byte thresholds we watch for
.. zeek:field:: orig_packet :zeek:type:`set` [:zeek:type:`count`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
current originator packet thresholds we watch for
.. zeek:field:: resp_packet :zeek:type:`set` [:zeek:type:`count`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
current responder packet thresholds we watch for
.. zeek:field:: duration :zeek:type:`set` [:zeek:type:`interval`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
current duration thresholds we watch for
Events
######
.. zeek:id:: ConnThreshold::bytes_threshold_crossed
:source-code: base/protocols/ftp/gridftp.zeek 73 86
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`)
Generated for a connection that crossed a set byte threshold
:param c: the connection
:param threshold: the threshold that was set
:param is_orig: True if the threshold was crossed by the originator of the connection
.. zeek:id:: ConnThreshold::duration_threshold_crossed
:source-code: base/protocols/conn/thresholds.zeek 109 109
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, threshold: :zeek:type:`interval`, is_orig: :zeek:type:`bool`)
Generated for a connection that crossed a set duration threshold. Note that this event is
not raised at the exact moment that a duration threshold is crossed; instead it is raised
when the next packet is seen after the threshold has been crossed. On a connection that is
idle, this can be raised significantly later.
:param c: the connection
:param threshold: the threshold that was set
:param is_orig: True if the threshold was crossed by the originator of the connection
.. zeek:id:: ConnThreshold::packets_threshold_crossed
:source-code: base/protocols/conn/thresholds.zeek 97 97
:Type: :zeek:type:`event` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`)
Generated for a connection that crossed a set byte threshold
:param c: the connection
:param threshold: the threshold that was set
:param is_orig: True if the threshold was crossed by the originator of the connection
Functions
#########
.. zeek:id:: ConnThreshold::delete_bytes_threshold
:source-code: base/protocols/conn/thresholds.zeek 266 284
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`) : :zeek:type:`bool`
Deletes a byte threshold for connection sizes.
:param cid: The connection id.
:param threshold: Threshold in bytes to remove.
:param is_orig: If true, threshold is removed for packets from originator, otherwise for packets from responder.
:returns: T on success, F on failure.
.. zeek:id:: ConnThreshold::delete_duration_threshold
:source-code: base/protocols/conn/thresholds.zeek 306 318
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`interval`) : :zeek:type:`bool`
Deletes a duration threshold for a connection.
:param cid: The connection id.
:param threshold: Threshold in packets.
:returns: T on success, F on failure.
.. zeek:id:: ConnThreshold::delete_packets_threshold
:source-code: base/protocols/conn/thresholds.zeek 286 304
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`) : :zeek:type:`bool`
Deletes a packet threshold for connection sizes.
:param cid: The connection id.
:param threshold: Threshold in packets.
:param is_orig: If true, threshold is removed for packets from originator, otherwise for packets from responder.
:returns: T on success, F on failure.
.. zeek:id:: ConnThreshold::set_bytes_threshold
:source-code: base/protocols/conn/thresholds.zeek 224 237
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`) : :zeek:type:`bool`
Sets a byte threshold for connection sizes, adding it to potentially already existing thresholds.
conn_bytes_threshold_crossed will be raised for each set threshold.
:param cid: The connection id.
:param threshold: Threshold in bytes.
:param is_orig: If true, threshold is set for bytes from originator, otherwise for bytes from responder.
:returns: T on success, F on failure.
.. zeek:id:: ConnThreshold::set_duration_threshold
:source-code: base/protocols/conn/thresholds.zeek 254 264
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`interval`) : :zeek:type:`bool`
Sets a duration threshold for a connection, adding it to potentially already existing thresholds.
conn_duration_threshold_crossed will be raised for each set threshold.
:param cid: The connection id.
:param threshold: Threshold in seconds.
:returns: T on success, F on failure.
.. zeek:id:: ConnThreshold::set_packets_threshold
:source-code: base/protocols/conn/thresholds.zeek 239 252
:Type: :zeek:type:`function` (c: :zeek:type:`connection`, threshold: :zeek:type:`count`, is_orig: :zeek:type:`bool`) : :zeek:type:`bool`
Sets a packet threshold for connection sizes, adding it to potentially already existing thresholds.
conn_packets_threshold_crossed will be raised for each set threshold.
:param cid: The connection id.
:param threshold: Threshold in packets.
:param is_orig: If true, threshold is set for packets from originator, otherwise for packets from responder.
:returns: T on success, F on failure.