Skip to content
This repository was archived by the owner on Oct 13, 2025. It is now read-only.

Commit c61e7c0

Browse files
zeek-botzeek-bot
committed
Generate docs
1 parent cda316e commit c61e7c0

File tree

17 files changed

+647
-322
lines changed

17 files changed

+647
-322
lines changed

‎script-reference/autogenerated-script-index.rst‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -512,6 +512,9 @@
512512
builtin-plugins/Zeek_JavaScript/__load__.zeek </scripts/builtin-plugins/Zeek_JavaScript/__load__.zeek>
513513
zeekygen/__load__.zeek </scripts/zeekygen/__load__.zeek>
514514
test-all-policy.zeek </scripts/test-all-policy.zeek>
515+
policy/frameworks/analyzer/debug-logging.zeek </scripts/policy/frameworks/analyzer/debug-logging.zeek>
516+
policy/frameworks/analyzer/detect-protocols.zeek </scripts/policy/frameworks/analyzer/detect-protocols.zeek>
517+
policy/frameworks/analyzer/packet-segment-logging.zeek </scripts/policy/frameworks/analyzer/packet-segment-logging.zeek>
515518
policy/frameworks/cluster/backend/zeromq/__load__.zeek </scripts/policy/frameworks/cluster/backend/zeromq/__load__.zeek>
516519
policy/frameworks/cluster/backend/zeromq/main.zeek </scripts/policy/frameworks/cluster/backend/zeromq/main.zeek>
517520
policy/frameworks/cluster/experimental.zeek </scripts/policy/frameworks/cluster/experimental.zeek>
@@ -536,8 +539,6 @@
536539
policy/frameworks/management/supervisor/main.zeek </scripts/policy/frameworks/management/supervisor/main.zeek>
537540
policy/frameworks/management/supervisor/api.zeek </scripts/policy/frameworks/management/supervisor/api.zeek>
538541
policy/frameworks/management/supervisor/config.zeek </scripts/policy/frameworks/management/supervisor/config.zeek>
539-
policy/frameworks/dpd/detect-protocols.zeek </scripts/policy/frameworks/dpd/detect-protocols.zeek>
540-
policy/frameworks/dpd/packet-segment-logging.zeek </scripts/policy/frameworks/dpd/packet-segment-logging.zeek>
541542
policy/frameworks/intel/do_notice.zeek </scripts/policy/frameworks/intel/do_notice.zeek>
542543
policy/frameworks/intel/do_expire.zeek </scripts/policy/frameworks/intel/do_expire.zeek>
543544
policy/frameworks/intel/whitelist.zeek </scripts/policy/frameworks/intel/whitelist.zeek>
@@ -639,10 +640,13 @@
639640
policy/protocols/ssl/weak-keys.zeek </scripts/policy/protocols/ssl/weak-keys.zeek>
640641
policy/tuning/json-logs.zeek </scripts/policy/tuning/json-logs.zeek>
641642
policy/tuning/track-all-assets.zeek </scripts/policy/tuning/track-all-assets.zeek>
643+
policy/frameworks/analyzer/deprecated-dpd-log.zeek </scripts/policy/frameworks/analyzer/deprecated-dpd-log.zeek>
644+
policy/frameworks/dpd/detect-protocols.zeek </scripts/policy/frameworks/dpd/detect-protocols.zeek>
642645
policy/frameworks/cluster/backend/zeromq/connect.zeek </scripts/policy/frameworks/cluster/backend/zeromq/connect.zeek>
643646
policy/frameworks/cluster/nodes-experimental/manager.zeek </scripts/policy/frameworks/cluster/nodes-experimental/manager.zeek>
644647
policy/frameworks/control/controllee.zeek </scripts/policy/frameworks/control/controllee.zeek>
645648
policy/frameworks/control/controller.zeek </scripts/policy/frameworks/control/controller.zeek>
649+
policy/frameworks/dpd/packet-segment-logging.zeek </scripts/policy/frameworks/dpd/packet-segment-logging.zeek>
646650
policy/frameworks/management/agent/main.zeek </scripts/policy/frameworks/management/agent/main.zeek>
647651
policy/frameworks/management/controller/main.zeek </scripts/policy/frameworks/management/controller/main.zeek>
648652
policy/frameworks/management/node/__load__.zeek </scripts/policy/frameworks/management/node/__load__.zeek>

‎scripts/base/frameworks/analyzer/dpd.zeek.rst‎

Lines changed: 13 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -4,59 +4,47 @@ base/frameworks/analyzer/dpd.zeek
44
=================================
55
.. zeek:namespace:: DPD
66
7-
Activates port-independent protocol detection and selectively disables
8-
analyzers if protocol violations occur.
7+
Disables analyzers if protocol violations occur, and add service information
8+
to connection log.
99

1010
:Namespace: DPD
11+
:Imports: :doc:`base/frameworks/analyzer/main.zeek </scripts/base/frameworks/analyzer/main.zeek>`
1112

1213
Summary
1314
~~~~~~~
1415
Runtime Options
1516
###############
1617
============================================================================================================================================================ =========================================================================
17-
:zeek:id:`DPD::ignore_violations`: :zeek:type:`set` :zeek:attr:`&redef` Analyzers which you don't want to throw
18+
:zeek:id:`DPD::ignore_violations`: :zeek:type:`set` :zeek:attr:`&redef` Analyzers which you don't want to remove on violations.
1819
:zeek:id:`DPD::ignore_violations_after`: :zeek:type:`count` :zeek:attr:`&redef` Ignore violations which go this many bytes into the connection.
1920
:zeek:id:`DPD::max_violations`: :zeek:type:`table` :zeek:attr:`&deprecated` = *...* :zeek:attr:`&default` = ``5`` :zeek:attr:`&optional` :zeek:attr:`&redef` Deprecated, please see https://github.com/zeek/zeek/pull/4200 for details
2021
:zeek:id:`DPD::track_removed_services_in_connection`: :zeek:type:`bool` :zeek:attr:`&redef` Change behavior of service field in conn.log:
2122
Failed services are no longer removed.
2223
============================================================================================================================================================ =========================================================================
2324

24-
Types
25-
#####
26-
=========================================== ======================================================================
27-
:zeek:type:`DPD::Info`: :zeek:type:`record` The record type defining the columns to log in the DPD logging stream.
28-
=========================================== ======================================================================
29-
3025
Redefinitions
3126
#############
3227
============================================ ===================================================================================================================
33-
:zeek:type:`Log::ID`: :zeek:type:`enum` Add the DPD logging stream identifier.
34-
35-
* :zeek:enum:`DPD::LOG`
3628
:zeek:type:`connection`: :zeek:type:`record`
3729

3830
:New Fields: :zeek:type:`connection`
3931

40-
dpd: :zeek:type:`DPD::Info` :zeek:attr:`&optional`
41-
4232
service_violation: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
4333
The set of services (analyzers) for which Zeek has observed a
4434
violation after the same service had previously been confirmed.
35+
36+
failed_analyzers: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
37+
The set of prototol analyzers that were removed due to a protocol
38+
violation after the same analyzer had previously been confirmed.
4539
============================================ ===================================================================================================================
4640

47-
Hooks
48-
#####
49-
======================================================== =============================================
50-
:zeek:id:`DPD::log_policy`: :zeek:type:`Log::PolicyHook` A default logging policy hook for the stream.
51-
======================================================== =============================================
52-
5341

5442
Detailed Interface
5543
~~~~~~~~~~~~~~~~~~
5644
Runtime Options
5745
###############
5846
.. zeek:id:: DPD::ignore_violations
59-
:source-code: base/frameworks/analyzer/dpd.zeek 33 33
47+
:source-code: base/frameworks/analyzer/dpd.zeek 13 13
6048

6149
:Type: :zeek:type:`set` [:zeek:type:`Analyzer::Tag`]
6250
:Attributes: :zeek:attr:`&redef`
@@ -74,10 +62,10 @@ Runtime Options
7462
Analyzer::ANALYZER_NTLM
7563

7664

77-
Analyzers which you don't want to throw
65+
Analyzers which you don't want to remove on violations.
7866

7967
.. zeek:id:: DPD::ignore_violations_after
80-
:source-code: base/frameworks/analyzer/dpd.zeek 37 37
68+
:source-code: base/frameworks/analyzer/dpd.zeek 17 17
8169

8270
:Type: :zeek:type:`count`
8371
:Attributes: :zeek:attr:`&redef`
@@ -87,7 +75,7 @@ Runtime Options
8775
Set to 0 to never ignore protocol violations.
8876

8977
.. zeek:id:: DPD::max_violations
90-
:source-code: base/frameworks/analyzer/dpd.zeek 30 30
78+
:source-code: base/frameworks/analyzer/dpd.zeek 10 10
9179

9280
:Type: :zeek:type:`table` [:zeek:type:`Analyzer::Tag`] of :zeek:type:`count`
9381
:Attributes: :zeek:attr:`&deprecated` = *"Remove in v8.1: This has become non-functional in Zeek 7.2, see PR #4200"* :zeek:attr:`&default` = ``5`` :zeek:attr:`&optional` :zeek:attr:`&redef`
@@ -96,7 +84,7 @@ Runtime Options
9684
Deprecated, please see https://github.com/zeek/zeek/pull/4200 for details
9785

9886
.. zeek:id:: DPD::track_removed_services_in_connection
99-
:source-code: base/frameworks/analyzer/dpd.zeek 44 44
87+
:source-code: base/frameworks/analyzer/dpd.zeek 24 24
10088

10189
:Type: :zeek:type:`bool`
10290
:Attributes: :zeek:attr:`&redef`
@@ -108,61 +96,4 @@ Runtime Options
10896
E.g. a http connection with a violation would be logged as
10997
"http,-http".
11098

111-
Types
112-
#####
113-
.. zeek:type:: DPD::Info
114-
:source-code: base/frameworks/analyzer/dpd.zeek 14 27
115-
116-
:Type: :zeek:type:`record`
117-
118-
119-
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
120-
121-
Timestamp for when protocol analysis failed.
122-
123-
124-
.. zeek:field:: uid :zeek:type:`string` :zeek:attr:`&log`
125-
126-
Connection unique ID.
127-
128-
129-
.. zeek:field:: id :zeek:type:`conn_id` :zeek:attr:`&log`
130-
131-
Connection ID containing the 4-tuple which identifies endpoints.
132-
133-
134-
.. zeek:field:: proto :zeek:type:`transport_proto` :zeek:attr:`&log`
135-
136-
Transport protocol for the violation.
137-
138-
139-
.. zeek:field:: analyzer :zeek:type:`string` :zeek:attr:`&log`
140-
141-
The analyzer that generated the violation.
142-
143-
144-
.. zeek:field:: failure_reason :zeek:type:`string` :zeek:attr:`&log`
145-
146-
The textual reason for the analysis failure.
147-
148-
149-
.. zeek:field:: packet_segment :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log`
150-
151-
(present if :doc:`/scripts/policy/frameworks/dpd/packet-segment-logging.zeek` is loaded)
152-
153-
A chunk of the payload that most likely resulted in the
154-
analyzer violation.
155-
156-
157-
The record type defining the columns to log in the DPD logging stream.
158-
159-
Hooks
160-
#####
161-
.. zeek:id:: DPD::log_policy
162-
:source-code: base/frameworks/analyzer/dpd.zeek 11 11
163-
164-
:Type: :zeek:type:`Log::PolicyHook`
165-
166-
A default logging policy hook for the stream.
167-
16899

‎scripts/base/frameworks/analyzer/index.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,10 @@ automatically activate a particular analyzer for new connections.
3333

3434
:doc:`/scripts/base/frameworks/analyzer/dpd.zeek`
3535

36-
Activates port-independent protocol detection and selectively disables
37-
analyzers if protocol violations occur.
36+
Disables analyzers if protocol violations occur, and add service information
37+
to connection log.
3838

3939
:doc:`/scripts/base/frameworks/analyzer/logging.zeek`
4040

41-
Logging analyzer confirmations and violations into analyzer.log
41+
Logging analyzer violations into analyzer.log
4242

‎scripts/base/frameworks/analyzer/logging.zeek.rst‎

Lines changed: 34 additions & 64 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,19 @@ base/frameworks/analyzer/logging.zeek
44
=====================================
55
.. zeek:namespace:: Analyzer::Logging
66
7-
Logging analyzer confirmations and violations into analyzer.log
7+
Logging analyzer violations into analyzer.log
88

99
:Namespace: Analyzer::Logging
10-
:Imports: :doc:`base/frameworks/analyzer/main.zeek </scripts/base/frameworks/analyzer/main.zeek>`, :doc:`base/frameworks/config </scripts/base/frameworks/config/index>`, :doc:`base/frameworks/logging </scripts/base/frameworks/logging/index>`
10+
:Imports: :doc:`base/frameworks/analyzer/main.zeek </scripts/base/frameworks/analyzer/main.zeek>`, :doc:`base/frameworks/logging </scripts/base/frameworks/logging/index>`
1111

1212
Summary
1313
~~~~~~~
1414
Runtime Options
1515
###############
16-
=========================================================================================== ==================================================================
17-
:zeek:id:`Analyzer::Logging::enable`: :zeek:type:`bool` :zeek:attr:`&redef` Enable logging of analyzer violations and optionally confirmations
18-
when :zeek:see:`Analyzer::Logging::include_confirmations` is set.
16+
=========================================================================================== ==============================================================
1917
:zeek:id:`Analyzer::Logging::failure_data_max_size`: :zeek:type:`count` :zeek:attr:`&redef` If a violation contains information about the data causing it,
2018
include at most this many bytes of it in the log.
21-
:zeek:id:`Analyzer::Logging::ignore_analyzers`: :zeek:type:`set` :zeek:attr:`&redef` Set of analyzers for which to not log confirmations or violations.
22-
:zeek:id:`Analyzer::Logging::include_confirmations`: :zeek:type:`bool` :zeek:attr:`&redef` Enable analyzer_confirmation.
23-
:zeek:id:`Analyzer::Logging::include_disabling`: :zeek:type:`bool` :zeek:attr:`&redef` Enable tracking of analyzers getting disabled.
24-
=========================================================================================== ==================================================================
19+
=========================================================================================== ==============================================================
2520

2621
Types
2722
#####
@@ -37,6 +32,13 @@ Redefinitions
3732
* :zeek:enum:`Analyzer::Logging::LOG`
3833
======================================= ===========================================
3934

35+
Events
36+
######
37+
============================================================== ===============================================================================
38+
:zeek:id:`Analyzer::Logging::log_analyzer`: :zeek:type:`event` An event that can be handled to access the :zeek:type:`Analyzer::Logging::Info`
39+
record as it is sent on to the logging framework.
40+
============================================================== ===============================================================================
41+
4042
Hooks
4143
#####
4244
====================================================================== =============================================
@@ -48,18 +50,8 @@ Detailed Interface
4850
~~~~~~~~~~~~~~~~~~
4951
Runtime Options
5052
###############
51-
.. zeek:id:: Analyzer::Logging::enable
52-
:source-code: base/frameworks/analyzer/logging.zeek 47 47
53-
54-
:Type: :zeek:type:`bool`
55-
:Attributes: :zeek:attr:`&redef`
56-
:Default: ``T``
57-
58-
Enable logging of analyzer violations and optionally confirmations
59-
when :zeek:see:`Analyzer::Logging::include_confirmations` is set.
60-
6153
.. zeek:id:: Analyzer::Logging::failure_data_max_size
62-
:source-code: base/frameworks/analyzer/logging.zeek 64 64
54+
:source-code: base/frameworks/analyzer/logging.zeek 37 37
6355

6456
:Type: :zeek:type:`count`
6557
:Attributes: :zeek:attr:`&redef`
@@ -68,57 +60,17 @@ Runtime Options
6860
If a violation contains information about the data causing it,
6961
include at most this many bytes of it in the log.
7062

71-
.. zeek:id:: Analyzer::Logging::ignore_analyzers
72-
:source-code: base/frameworks/analyzer/logging.zeek 67 67
73-
74-
:Type: :zeek:type:`set` [:zeek:type:`AllAnalyzers::Tag`]
75-
:Attributes: :zeek:attr:`&redef`
76-
:Default: ``{}``
77-
78-
Set of analyzers for which to not log confirmations or violations.
79-
80-
.. zeek:id:: Analyzer::Logging::include_confirmations
81-
:source-code: base/frameworks/analyzer/logging.zeek 54 54
82-
83-
:Type: :zeek:type:`bool`
84-
:Attributes: :zeek:attr:`&redef`
85-
:Default: ``F``
86-
87-
Enable analyzer_confirmation. They are usually less interesting
88-
outside of development of analyzers or troubleshooting scenarios.
89-
Setting this option may also generated multiple log entries per
90-
connection, minimally one for each conn.log entry with a populated
91-
service field.
92-
93-
.. zeek:id:: Analyzer::Logging::include_disabling
94-
:source-code: base/frameworks/analyzer/logging.zeek 60 60
95-
96-
:Type: :zeek:type:`bool`
97-
:Attributes: :zeek:attr:`&redef`
98-
:Default: ``F``
99-
100-
Enable tracking of analyzers getting disabled. This is mostly
101-
interesting for troubleshooting of analyzers in DPD scenarios.
102-
Setting this option may also generated multiple log entries per
103-
connection.
104-
10563
Types
10664
#####
10765
.. zeek:type:: Analyzer::Logging::Info
108-
:source-code: base/frameworks/analyzer/logging.zeek 18 43
66+
:source-code: base/frameworks/analyzer/logging.zeek 13 33
10967

11068
:Type: :zeek:type:`record`
11169

11270

11371
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
11472
115-
Timestamp of confirmation or violation.
116-
117-
118-
.. zeek:field:: cause :zeek:type:`string` :zeek:attr:`&log`
119-
120-
What caused this log entry to be produced. This can
121-
currently be "violation" or "confirmation".
73+
Timestamp of the violation.
12274

12375

12476
.. zeek:field:: analyzer_kind :zeek:type:`string` :zeek:attr:`&log`
@@ -148,7 +100,7 @@ Types
148100
Connection identifier if available
149101

150102

151-
.. zeek:field:: failure_reason :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
103+
.. zeek:field:: failure_reason :zeek:type:`string` :zeek:attr:`&log`
152104
153105
Failure or violation reason, if available.
154106

@@ -159,12 +111,30 @@ Types
159111
to :zeek:see:`Analyzer::Logging::failure_data_max_size`.
160112

161113

114+
.. zeek:field:: packet_segment :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log`
115+
116+
(present if :doc:`/scripts/policy/frameworks/analyzer/packet-segment-logging.zeek` is loaded)
117+
118+
A chunk of the payload that most likely resulted in the
119+
analyzer violation.
120+
121+
162122
The record type defining the columns to log in the analyzer logging stream.
163123

124+
Events
125+
######
126+
.. zeek:id:: Analyzer::Logging::log_analyzer
127+
:source-code: base/frameworks/analyzer/logging.zeek 41 41
128+
129+
:Type: :zeek:type:`event` (rec: :zeek:type:`Analyzer::Logging::Info`)
130+
131+
An event that can be handled to access the :zeek:type:`Analyzer::Logging::Info`
132+
record as it is sent on to the logging framework.
133+
164134
Hooks
165135
#####
166136
.. zeek:id:: Analyzer::Logging::log_policy
167-
:source-code: base/frameworks/analyzer/logging.zeek 15 15
137+
:source-code: policy/frameworks/analyzer/packet-segment-logging.zeek 38 50
168138

169139
:Type: :zeek:type:`Log::PolicyHook`
170140

0 commit comments

Comments
 (0)