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

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

29
doc/scripts/policy/protocols/ssl/certificate-request-info.zeek.rst Normal file
View file

@ -0,0 +1,29 @@
:tocdepth: 3
policy/protocols/ssl/certificate-request-info.zeek
==================================================
.. zeek:namespace:: SSL
When the server requests a client certificate, it optionally may specify a list of CAs that
it accepts. If the server does this, this script adds this list to ssl.log.
:Namespace: SSL
:Imports: :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
=========================================== ===============================================================================================================================
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
requested_client_certificate_authorities: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&optional` :zeek:attr:`&log`
List of client certificate CAs accepted by the server
=========================================== ===============================================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~

98
doc/scripts/policy/protocols/ssl/decryption.zeek.rst Normal file
View file

@ -0,0 +1,98 @@
:tocdepth: 3
policy/protocols/ssl/decryption.zeek
====================================
.. zeek:namespace:: SSL
This script allows for the decryption of certain TLS 1.2 connections, if the user is in possession
of the private key material for the session. Key material can either be provided via a file (useful
for processing trace files) or via sending events via Broker (for live decoding).
Please note that this feature is experimental and can change without guarantees to our typical
deprecation timeline. Please also note that currently only TLS 1.2 connections that use the
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 cipher suite are supported.
:Namespace: SSL
:Imports: :doc:`base/frameworks/input </scripts/base/frameworks/input/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/conn </scripts/base/protocols/conn/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinable Options
###################
============================================================================ =====================================================================================================
:zeek:id:`SSL::keylog_file`: :zeek:type:`string` :zeek:attr:`&redef` This can be set to a file that contains the session secrets for decryption, when parsing a pcap file.
:zeek:id:`SSL::secret_expiration`: :zeek:type:`interval` :zeek:attr:`&redef` Secrets expire after this time of not being used.
============================================================================ =====================================================================================================
Redefinitions
#############
======================================================================================= ===========================================================
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
client_random: :zeek:type:`string` :zeek:attr:`&optional`
:zeek:id:`SSL::disable_analyzer_after_detection`: :zeek:type:`bool` :zeek:attr:`&redef`
======================================================================================= ===========================================================
Events
######
============================================== ==============================================================================================
:zeek:id:`SSL::add_keys`: :zeek:type:`event` This event can be triggered, e.g., via Broker to add known keys to the TLS key database.
:zeek:id:`SSL::add_secret`: :zeek:type:`event` This event can be triggered, e.g., via Broker to add known secrets to the TLS secret database.
============================================== ==============================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Redefinable Options
###################
.. zeek:id:: SSL::keylog_file
:source-code: policy/protocols/ssl/decryption.zeek 24 24
:Type: :zeek:type:`string`
:Attributes: :zeek:attr:`&redef`
:Default: ``""``
This can be set to a file that contains the session secrets for decryption, when parsing a pcap file.
Please note that, when using this feature, you probably want to pause processing of data till this
file has been read.
.. zeek:id:: SSL::secret_expiration
:source-code: policy/protocols/ssl/decryption.zeek 27 27
:Type: :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default: ``5.0 mins``
Secrets expire after this time of not being used.
Events
######
.. zeek:id:: SSL::add_keys
:source-code: policy/protocols/ssl/decryption.zeek 82 85
:Type: :zeek:type:`event` (client_random: :zeek:type:`string`, keys: :zeek:type:`string`)
This event can be triggered, e.g., via Broker to add known keys to the TLS key database.
:param client_random: client random for which the key is set
:param keys: key material
.. zeek:id:: SSL::add_secret
:source-code: policy/protocols/ssl/decryption.zeek 87 90
:Type: :zeek:type:`event` (client_random: :zeek:type:`string`, secrets: :zeek:type:`string`)
This event can be triggered, e.g., via Broker to add known secrets to the TLS secret database.
:param client_random: client random for which the secret is set
:param secrets: derived TLS secrets material

71
doc/scripts/policy/protocols/ssl/expiring-certs.zeek.rst Normal file
View file

@ -0,0 +1,71 @@
:tocdepth: 3
policy/protocols/ssl/expiring-certs.zeek
========================================
.. zeek:namespace:: SSL
Generate notices when X.509 certificates over SSL/TLS are expired or
going to expire soon based on the date and time values stored within the
certificate.
:Namespace: SSL
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.zeek </scripts/base/utils/directions-and-hosts.zeek>`
Summary
~~~~~~~
Runtime Options
###############
======================================================================================= ======================================================================
:zeek:id:`SSL::notify_certs_expiration`: :zeek:type:`Host` :zeek:attr:`&redef` The category of hosts you would like to be notified about which have
certificates that are going to be expiring soon.
:zeek:id:`SSL::notify_when_cert_expiring_in`: :zeek:type:`interval` :zeek:attr:`&redef` The time before a certificate is going to expire that you would like
to start receiving :zeek:enum:`SSL::Certificate_Expires_Soon` notices.
======================================================================================= ======================================================================
Redefinitions
#############
============================================ ==============================================================
:zeek:type:`Notice::Type`: :zeek:type:`enum`
* :zeek:enum:`SSL::Certificate_Expired`:
Indicates that a certificate's NotValidAfter date has lapsed
and the certificate is now invalid.
* :zeek:enum:`SSL::Certificate_Expires_Soon`:
Indicates that a certificate is going to expire within
:zeek:id:`SSL::notify_when_cert_expiring_in`.
* :zeek:enum:`SSL::Certificate_Not_Valid_Yet`:
Indicates that a certificate's NotValidBefore date is future
dated.
============================================ ==============================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: SSL::notify_certs_expiration
:source-code: policy/protocols/ssl/expiring-certs.zeek 30 30
:Type: :zeek:type:`Host`
:Attributes: :zeek:attr:`&redef`
:Default: ``LOCAL_HOSTS``
The category of hosts you would like to be notified about which have
certificates that are going to be expiring soon. By default, these
notices will be suppressed by the notice framework for 1 day after
a particular certificate has had a notice generated.
Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS
.. zeek:id:: SSL::notify_when_cert_expiring_in
:source-code: policy/protocols/ssl/expiring-certs.zeek 34 34
:Type: :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default: ``30.0 days``
The time before a certificate is going to expire that you would like
to start receiving :zeek:enum:`SSL::Certificate_Expires_Soon` notices.

53
doc/scripts/policy/protocols/ssl/heartbleed.zeek.rst Normal file
View file

@ -0,0 +1,53 @@
:tocdepth: 3
policy/protocols/ssl/heartbleed.zeek
====================================
.. zeek:namespace:: Heartbleed
Detect the TLS heartbleed attack. See http://heartbleed.com for more.
:Namespace: Heartbleed
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
======================================================================================= ================================================================================================
:zeek:type:`Notice::Type`: :zeek:type:`enum`
* :zeek:enum:`Heartbleed::SSL_Heartbeat_Attack`:
Indicates that a host performed a heartbleed attack or scan.
* :zeek:enum:`Heartbleed::SSL_Heartbeat_Attack_Success`:
Indicates that a host performing a heartbleed attack was probably successful.
* :zeek:enum:`Heartbleed::SSL_Heartbeat_Many_Requests`:
Indicates we saw many heartbeat requests without a reply.
* :zeek:enum:`Heartbleed::SSL_Heartbeat_Odd_Length`:
Indicates we saw heartbeat requests with odd length.
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
last_originator_heartbeat_request_size: :zeek:type:`count` :zeek:attr:`&optional`
last_responder_heartbeat_request_size: :zeek:type:`count` :zeek:attr:`&optional`
originator_heartbeats: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
responder_heartbeats: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
heartbleed_detected: :zeek:type:`bool` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional`
enc_appdata_packages: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
enc_appdata_bytes: :zeek:type:`count` :zeek:attr:`&default` = ``0`` :zeek:attr:`&optional`
:zeek:id:`SSL::disable_analyzer_after_detection`: :zeek:type:`bool` :zeek:attr:`&redef`
======================================================================================= ================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~

244
doc/scripts/policy/protocols/ssl/known-certs.zeek.rst Normal file
View file

@ -0,0 +1,244 @@
:tocdepth: 3
policy/protocols/ssl/known-certs.zeek
=====================================
.. zeek:namespace:: Known
Log information about certificates while attempting to avoid duplicate
logging.
:Namespace: Known
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.zeek </scripts/base/utils/directions-and-hosts.zeek>`
Summary
~~~~~~~
Runtime Options
###############
=============================================================================== ====================================================================
:zeek:id:`Known::cert_store_expiry`: :zeek:type:`interval` :zeek:attr:`&redef` The expiry interval of new entries in :zeek:see:`Known::cert_store`.
:zeek:id:`Known::cert_store_timeout`: :zeek:type:`interval` :zeek:attr:`&redef` The timeout interval to use for operations against
:zeek:see:`Known::cert_store`.
:zeek:id:`Known::cert_tracking`: :zeek:type:`Host` :zeek:attr:`&redef` The certificates whose existence should be logged and tracked.
=============================================================================== ====================================================================
Redefinable Options
###################
========================================================================== ===============================================================
:zeek:id:`Known::cert_store_name`: :zeek:type:`string` :zeek:attr:`&redef` The Broker topic name to use for :zeek:see:`Known::cert_store`.
:zeek:id:`Known::use_cert_store`: :zeek:type:`bool` :zeek:attr:`&redef` Toggles between different implementations of this script.
========================================================================== ===============================================================
State Variables
###############
======================================================================================================= ===================================================================
:zeek:id:`Known::cert_store`: :zeek:type:`Cluster::StoreInfo` Holds the set of all known certificates.
:zeek:id:`Known::certs`: :zeek:type:`set` :zeek:attr:`&create_expire` = ``1.0 day`` :zeek:attr:`&redef` The set of all known certificates to store for preventing duplicate
logging.
======================================================================================================= ===================================================================
Types
#####
========================================================= =
:zeek:type:`Known::AddrCertHashPair`: :zeek:type:`record`
:zeek:type:`Known::CertsInfo`: :zeek:type:`record`
========================================================= =
Redefinitions
#############
======================================= ===============================
:zeek:type:`Log::ID`: :zeek:type:`enum`
* :zeek:enum:`Known::CERTS_LOG`
======================================= ===============================
Events
######
===================================================== =====================================================================
:zeek:id:`Known::log_known_certs`: :zeek:type:`event` Event that can be handled to access the loggable record as it is sent
on to the logging framework.
===================================================== =====================================================================
Hooks
#####
================================================================ =
:zeek:id:`Known::log_policy_certs`: :zeek:type:`Log::PolicyHook`
================================================================ =
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: Known::cert_store_expiry
:source-code: policy/protocols/ssl/known-certs.zeek 57 57
:Type: :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default: ``1.0 day``
The expiry interval of new entries in :zeek:see:`Known::cert_store`.
This also changes the interval at which certs get logged.
.. zeek:id:: Known::cert_store_timeout
:source-code: policy/protocols/ssl/known-certs.zeek 61 61
:Type: :zeek:type:`interval`
:Attributes: :zeek:attr:`&redef`
:Default: ``15.0 secs``
The timeout interval to use for operations against
:zeek:see:`Known::cert_store`.
.. zeek:id:: Known::cert_tracking
:source-code: policy/protocols/ssl/known-certs.zeek 34 34
:Type: :zeek:type:`Host`
:Attributes: :zeek:attr:`&redef`
:Default: ``LOCAL_HOSTS``
:Redefinition: from :doc:`/scripts/policy/tuning/track-all-assets.zeek`
``=``::
ALL_HOSTS
The certificates whose existence should be logged and tracked.
Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS.
Redefinable Options
###################
.. zeek:id:: Known::cert_store_name
:source-code: policy/protocols/ssl/known-certs.zeek 53 53
:Type: :zeek:type:`string`
:Attributes: :zeek:attr:`&redef`
:Default: ``"zeek/known/certs"``
The Broker topic name to use for :zeek:see:`Known::cert_store`.
.. zeek:id:: Known::use_cert_store
:source-code: policy/protocols/ssl/known-certs.zeek 40 40
:Type: :zeek:type:`bool`
:Attributes: :zeek:attr:`&redef`
:Default: ``F``
Toggles between different implementations of this script.
When true, use a Broker data store, else use a regular Zeek set
with keys uniformly distributed over proxy nodes in cluster
operation.
State Variables
###############
.. zeek:id:: Known::cert_store
:source-code: policy/protocols/ssl/known-certs.zeek 50 50
:Type: :zeek:type:`Cluster::StoreInfo`
:Default:
::
{
name=<uninitialized>
store=<uninitialized>
master_node=""
master=F
backend=Broker::MEMORY
options=[sqlite=[path="", synchronous=<uninitialized>, journal_mode=<uninitialized>, failure_mode=Broker::SQLITE_FAILURE_MODE_FAIL, integrity_check=F]]
clone_resync_interval=10.0 secs
clone_stale_interval=5.0 mins
clone_mutation_buffer_interval=2.0 mins
}
Holds the set of all known certificates. Keys in the store are of
type :zeek:type:`Known::AddrCertHashPair` and their associated value is
always the boolean value of "true".
.. zeek:id:: Known::certs
:source-code: policy/protocols/ssl/known-certs.zeek 70 70
:Type: :zeek:type:`set` [:zeek:type:`addr`, :zeek:type:`string`]
:Attributes: :zeek:attr:`&create_expire` = ``1.0 day`` :zeek:attr:`&redef`
:Default: ``{}``
The set of all known certificates to store for preventing duplicate
logging. It can also be used from other scripts to
inspect if a certificate has been seen in use. The string value
in the set is for storing the DER formatted certificate' SHA1 hash.
In cluster operation, this set is uniformly distributed across
proxy nodes.
Types
#####
.. zeek:type:: Known::AddrCertHashPair
:source-code: policy/protocols/ssl/known-certs.zeek 42 45
:Type: :zeek:type:`record`
.. zeek:field:: host :zeek:type:`addr`
.. zeek:field:: hash :zeek:type:`string`
.. zeek:type:: Known::CertsInfo
:source-code: policy/protocols/ssl/known-certs.zeek 16 30
:Type: :zeek:type:`record`
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
The timestamp when the certificate was detected.
.. zeek:field:: host :zeek:type:`addr` :zeek:attr:`&log`
The address that offered the certificate.
.. zeek:field:: port_num :zeek:type:`port` :zeek:attr:`&log` :zeek:attr:`&optional`
If the certificate was handed out by a server, this is the
port that the server was listening on.
.. zeek:field:: subject :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Certificate subject.
.. zeek:field:: issuer_subject :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Certificate issuer subject.
.. zeek:field:: serial :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Serial number for the certificate.
Events
######
.. zeek:id:: Known::log_known_certs
:source-code: policy/protocols/ssl/known-certs.zeek 74 74
:Type: :zeek:type:`event` (rec: :zeek:type:`Known::CertsInfo`)
Event that can be handled to access the loggable record as it is sent
on to the logging framework.
Hooks
#####
.. zeek:id:: Known::log_policy_certs
:source-code: policy/protocols/ssl/known-certs.zeek 14 14
:Type: :zeek:type:`Log::PolicyHook`

29
doc/scripts/policy/protocols/ssl/log-certs-base64.zeek.rst Normal file
View file

@ -0,0 +1,29 @@
:tocdepth: 3
policy/protocols/ssl/log-certs-base64.zeek
==========================================
This script is used to extract certificates seen on the wire to Zeek log files.
The certificates are base64-encoded and written to ssl.log, to the newly added cert
field.
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
======================================================================================= ==========================================================================
:zeek:type:`X509::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`X509::Info`
cert: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Base64 encoded X.509 certificate.
:zeek:id:`X509::default_max_field_string_bytes`: :zeek:type:`count` :zeek:attr:`&redef` Certificates can be large and we don't want to risk truncating the output.
======================================================================================= ==========================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~

18
doc/scripts/policy/protocols/ssl/log-hostcerts-only.zeek.rst Normal file
View file

@ -0,0 +1,18 @@
:tocdepth: 3
policy/protocols/ssl/log-hostcerts-only.zeek
============================================
.. zeek:namespace:: X509
When this script is loaded, only the host certificates (client and server)
will be logged to x509.log. Logging of all other certificates will be suppressed.
:Namespace: X509
:Imports: :doc:`base/files/x509 </scripts/base/files/x509/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Detailed Interface
~~~~~~~~~~~~~~~~~~

85
doc/scripts/policy/protocols/ssl/ssl-log-ext.zeek.rst Normal file
View file

@ -0,0 +1,85 @@
:tocdepth: 3
policy/protocols/ssl/ssl-log-ext.zeek
=====================================
.. zeek:namespace:: SSL
This file adds a lot of additional information to the SSL log
It is not loaded by default since the information significantly expands
the log and is probably not interesting for a majority of people.
:Namespace: SSL
:Imports: :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
=========================================== ===============================================================================================================
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
server_version: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Numeric version of the server in the server hello
client_version: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Numeric version of the client in the client hello
client_ciphers: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Ciphers that were offered by the client for the connection
ssl_client_exts: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
SSL Client extensions
ssl_server_exts: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
SSL server extensions
ticket_lifetime_hint: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Suggested ticket lifetime sent in the session ticket handshake
by the server.
dh_param_size: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
The diffie helman parameter size, when using DH.
point_formats: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
supported elliptic curve point formats
client_curves: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
The curves supported by the client.
orig_alpn: :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Application layer protocol negotiation extension sent by the client.
client_supported_versions: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
TLS 1.3 supported versions
server_supported_version: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
TLS 1.3 supported versions
psk_key_exchange_modes: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
TLS 1.3 Pre-shared key exchange modes
client_key_share_groups: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Key share groups from client hello
server_key_share_group: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Selected key share group from server hello
client_comp_methods: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Client supported compression methods
comp_method: :zeek:type:`count` :zeek:attr:`&optional`
Server chosen compression method
sigalgs: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Client supported signature algorithms
hashalgs: :zeek:type:`vector` of :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Client supported hash algorithms
=========================================== ===============================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~

127
doc/scripts/policy/protocols/ssl/validate-certs.zeek.rst Normal file
View file

@ -0,0 +1,127 @@
:tocdepth: 3
policy/protocols/ssl/validate-certs.zeek
========================================
.. zeek:namespace:: SSL
Perform full certificate chain validation for SSL certificates.
:Namespace: SSL
:Imports: :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
State Variables
###############
========================================================================================================================= ==================================================================
:zeek:id:`SSL::recently_validated_certs`: :zeek:type:`table` :zeek:attr:`&read_expire` = ``5.0 mins`` :zeek:attr:`&redef` Result values for recently validated chains along with the
validation status are kept in this table to avoid constant
validation every time the same certificate chain is seen.
:zeek:id:`SSL::ssl_cache_intermediate_ca`: :zeek:type:`bool` :zeek:attr:`&redef` Use intermediate CA certificate caching when trying to validate
certificates.
:zeek:id:`SSL::ssl_store_valid_chain`: :zeek:type:`bool` :zeek:attr:`&redef` Store the valid chain in c$ssl$valid_chain if validation succeeds.
========================================================================================================================= ==================================================================
Redefinitions
#############
============================================ ========================================================================================
:zeek:type:`Notice::Type`: :zeek:type:`enum`
* :zeek:enum:`SSL::Invalid_Server_Cert`:
This notice indicates that the result of validating the
certificate along with its full certificate chain was
invalid.
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
validation_status: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Result of certificate validation for this connection.
validation_code: :zeek:type:`int` :zeek:attr:`&optional`
Result of certificate validation for this connection, given
as OpenSSL validation code.
valid_chain: :zeek:type:`vector` of :zeek:type:`opaque` of x509 :zeek:attr:`&optional`
Ordered chain of validated certificate, if validation succeeded.
============================================ ========================================================================================
Events
######
==================================================== ===============================================================
:zeek:id:`SSL::intermediate_add`: :zeek:type:`event` Event from a manager to workers when encountering a new, valid
intermediate.
:zeek:id:`SSL::new_intermediate`: :zeek:type:`event` Event from workers to the manager when a new intermediate chain
is to be added.
==================================================== ===============================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
State Variables
###############
.. zeek:id:: SSL::recently_validated_certs
:source-code: policy/protocols/ssl/validate-certs.zeek 33 33
:Type: :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`X509::Result`
:Attributes: :zeek:attr:`&read_expire` = ``5.0 mins`` :zeek:attr:`&redef`
:Default: ``{}``
Result values for recently validated chains along with the
validation status are kept in this table to avoid constant
validation every time the same certificate chain is seen.
.. zeek:id:: SSL::ssl_cache_intermediate_ca
:source-code: policy/protocols/ssl/validate-certs.zeek 46 46
:Type: :zeek:type:`bool`
:Attributes: :zeek:attr:`&redef`
:Default: ``T``
Use intermediate CA certificate caching when trying to validate
certificates. When this is enabled, Zeek keeps track of all valid
intermediate CA certificates that it has seen in the past. When
encountering a host certificate that cannot be validated because
of missing intermediate CA certificate, the cached list is used
to try to validate the cert. This is similar to how Firefox is
doing certificate validation.
Disabling this will usually greatly increase the number of validation warnings
that you encounter. Only disable if you want to find misconfigured servers.
.. zeek:id:: SSL::ssl_store_valid_chain
:source-code: policy/protocols/ssl/validate-certs.zeek 51 51
:Type: :zeek:type:`bool`
:Attributes: :zeek:attr:`&redef`
:Default: ``F``
:Redefinition: from :doc:`/scripts/policy/protocols/ssl/validate-sct.zeek`
``=``::
T
Store the valid chain in c$ssl$valid_chain if validation succeeds.
This has a potentially high memory impact, depending on the local environment
and is thus disabled by default.
Events
######
.. zeek:id:: SSL::intermediate_add
:source-code: policy/protocols/ssl/validate-certs.zeek 72 75
:Type: :zeek:type:`event` (key: :zeek:type:`string`, value: :zeek:type:`vector` of :zeek:type:`opaque` of x509)
Event from a manager to workers when encountering a new, valid
intermediate.
.. zeek:id:: SSL::new_intermediate
:source-code: policy/protocols/ssl/validate-certs.zeek 77 84
:Type: :zeek:type:`event` (key: :zeek:type:`string`, value: :zeek:type:`vector` of :zeek:type:`opaque` of x509)
Event from workers to the manager when a new intermediate chain
is to be added.

36
doc/scripts/policy/protocols/ssl/validate-ocsp.zeek.rst Normal file
View file

@ -0,0 +1,36 @@
:tocdepth: 3
policy/protocols/ssl/validate-ocsp.zeek
=======================================
.. zeek:namespace:: SSL
Perform validation of stapled OCSP responses.
:Namespace: SSL
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`
Summary
~~~~~~~
Redefinitions
#############
============================================ ===========================================================================
:zeek:type:`Notice::Type`: :zeek:type:`enum`
* :zeek:enum:`SSL::Invalid_Ocsp_Response`:
This indicates that the OCSP response was not deemed
to be valid.
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
ocsp_status: :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
Result of ocsp validation for this connection.
ocsp_response: :zeek:type:`string` :zeek:attr:`&optional`
ocsp response as string.
============================================ ===========================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~

129
doc/scripts/policy/protocols/ssl/validate-sct.zeek.rst Normal file
View file

@ -0,0 +1,129 @@
:tocdepth: 3
policy/protocols/ssl/validate-sct.zeek
======================================
.. zeek:namespace:: SSL
Perform validation of Signed Certificate Timestamps, as used
for Certificate Transparency. See RFC6962 for more details.
:Namespace: SSL
:Imports: :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`policy/protocols/ssl/validate-certs.zeek </scripts/policy/protocols/ssl/validate-certs.zeek>`
Summary
~~~~~~~
Types
#####
============================================== ================================================================
:zeek:type:`SSL::SctInfo`: :zeek:type:`record` This record is used to store information about the SCTs that are
encountered in a SSL connection.
:zeek:type:`SSL::SctSource`: :zeek:type:`enum` List of the different sources for Signed Certificate Timestamp
============================================== ================================================================
Redefinitions
#############
============================================================================ ===================================================================================================================
:zeek:type:`SSL::Info`: :zeek:type:`record`
:New Fields: :zeek:type:`SSL::Info`
valid_scts: :zeek:type:`count` :zeek:attr:`&optional`
Number of valid SCTs that were encountered in the connection.
invalid_scts: :zeek:type:`count` :zeek:attr:`&optional`
Number of SCTs that could not be validated that were encountered in the connection.
valid_ct_logs: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of different Logs for which valid SCTs were encountered in the connection.
valid_ct_operators: :zeek:type:`count` :zeek:attr:`&log` :zeek:attr:`&optional`
Number of different Log operators of which valid SCTs were encountered in the connection.
valid_ct_operators_list: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&optional`
List of operators for which valid SCTs were encountered in the connection.
ct_proofs: :zeek:type:`vector` of :zeek:type:`SSL::SctInfo` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
Information about all SCTs that were encountered in the connection.
:zeek:id:`SSL::ssl_store_valid_chain`: :zeek:type:`bool` :zeek:attr:`&redef`
============================================================================ ===================================================================================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Types
#####
.. zeek:type:: SSL::SctInfo
:source-code: policy/protocols/ssl/validate-sct.zeek 30 50
:Type: :zeek:type:`record`
.. zeek:field:: version :zeek:type:`count`
The version of the encountered SCT (should always be 0 for v1).
.. zeek:field:: logid :zeek:type:`string`
The ID of the log issuing this SCT.
.. zeek:field:: timestamp :zeek:type:`count`
The timestamp at which this SCT was issued measured since the
epoch (January 1, 1970, 00:00), ignoring leap seconds, in
milliseconds. Not converted to a Zeek timestamp because we need
the exact value for validation.
.. zeek:field:: sig_alg :zeek:type:`count`
The signature algorithm used for this sct.
.. zeek:field:: hash_alg :zeek:type:`count`
The hash algorithm used for this sct.
.. zeek:field:: signature :zeek:type:`string`
The signature of this SCT.
.. zeek:field:: source :zeek:type:`SSL::SctSource`
Source of this SCT.
.. zeek:field:: valid :zeek:type:`bool` :zeek:attr:`&optional`
Validation result of this SCT.
This record is used to store information about the SCTs that are
encountered in a SSL connection.
.. zeek:type:: SSL::SctSource
:source-code: policy/protocols/ssl/validate-sct.zeek 16 27
:Type: :zeek:type:`enum`
.. zeek:enum:: SSL::SCT_X509_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in the extension of
an X.509 certificate.
.. zeek:enum:: SSL::SCT_TLS_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in an TLS session
extension.
.. zeek:enum:: SSL::SCT_OCSP_EXT SSL::SctSource
Signed Certificate Timestamp was encountered in the extension of
an stapled OCSP reply.
List of the different sources for Signed Certificate Timestamp

109
doc/scripts/policy/protocols/ssl/weak-keys.zeek.rst Normal file
View file

@ -0,0 +1,109 @@
:tocdepth: 3
policy/protocols/ssl/weak-keys.zeek
===================================
.. zeek:namespace:: SSL
Generate notices when SSL/TLS connections use certificates, DH parameters,
or cipher suites that are deemed to be insecure.
:Namespace: SSL
:Imports: :doc:`base/frameworks/notice </scripts/base/frameworks/notice/index>`, :doc:`base/protocols/ssl </scripts/base/protocols/ssl/index>`, :doc:`base/utils/directions-and-hosts.zeek </scripts/base/utils/directions-and-hosts.zeek>`
Summary
~~~~~~~
Runtime Options
###############
=========================================================================================== ==============================================================================
:zeek:id:`SSL::notify_dh_length_shorter_cert_length`: :zeek:type:`bool` :zeek:attr:`&redef` Warn if the DH key length is smaller than the certificate key length.
:zeek:id:`SSL::notify_minimal_key_length`: :zeek:type:`count` :zeek:attr:`&redef` The minimal key length in bits that is considered to be safe.
:zeek:id:`SSL::notify_weak_keys`: :zeek:type:`Host` :zeek:attr:`&redef` The category of hosts you would like to be notified about which are using weak
keys/ciphers/protocol_versions.
:zeek:id:`SSL::tls_minimum_version`: :zeek:type:`count` :zeek:attr:`&redef` Warn if a server negotiates a SSL session with a protocol version smaller than
the specified version.
:zeek:id:`SSL::unsafe_ciphers_regex`: :zeek:type:`pattern` :zeek:attr:`&redef` Warn if a server negotiates an unsafe cipher suite.
=========================================================================================== ==============================================================================
Redefinitions
#############
============================================ ===============================================================
:zeek:type:`Notice::Type`: :zeek:type:`enum`
* :zeek:enum:`SSL::Old_Version`:
Indicates that a server is using a potentially unsafe version
* :zeek:enum:`SSL::Weak_Cipher`:
Indicates that a server is using a potentially unsafe cipher
* :zeek:enum:`SSL::Weak_Key`:
Indicates that a server is using a potentially unsafe key.
============================================ ===============================================================
Detailed Interface
~~~~~~~~~~~~~~~~~~
Runtime Options
###############
.. zeek:id:: SSL::notify_dh_length_shorter_cert_length
:source-code: policy/protocols/ssl/weak-keys.zeek 34 34
:Type: :zeek:type:`bool`
:Attributes: :zeek:attr:`&redef`
:Default: ``T``
Warn if the DH key length is smaller than the certificate key length. This is
potentially unsafe because it gives a wrong impression of safety due to the
certificate key length. However, it is very common and cannot be avoided in some
settings (e.g. with old java clients).
.. zeek:id:: SSL::notify_minimal_key_length
:source-code: policy/protocols/ssl/weak-keys.zeek 28 28
:Type: :zeek:type:`count`
:Attributes: :zeek:attr:`&redef`
:Default: ``2048``
The minimal key length in bits that is considered to be safe. Any shorter
(non-EC) key lengths will trigger a notice.
.. zeek:id:: SSL::notify_weak_keys
:source-code: policy/protocols/ssl/weak-keys.zeek 24 24
:Type: :zeek:type:`Host`
:Attributes: :zeek:attr:`&redef`
:Default: ``LOCAL_HOSTS``
The category of hosts you would like to be notified about which are using weak
keys/ciphers/protocol_versions. By default, these notices will be suppressed
by the notice framework for 1 day after a particular host has had a notice
generated. Choices are: LOCAL_HOSTS, REMOTE_HOSTS, ALL_HOSTS, NO_HOSTS
.. zeek:id:: SSL::tls_minimum_version
:source-code: policy/protocols/ssl/weak-keys.zeek 41 41
:Type: :zeek:type:`count`
:Attributes: :zeek:attr:`&redef`
:Default: ``769``
Warn if a server negotiates a SSL session with a protocol version smaller than
the specified version. By default, the minimal version is TLSv10 because SSLv2
and v3 have serious security issued.
See https://tools.ietf.org/html/draft-thomson-sslv3-diediedie-00
To disable, set to SSLv20
.. zeek:id:: SSL::unsafe_ciphers_regex
:source-code: policy/protocols/ssl/weak-keys.zeek 45 45
:Type: :zeek:type:`pattern`
:Attributes: :zeek:attr:`&redef`
:Default:
::
/^?((_EXPORT_)|(_RC4_))$?/
Warn if a server negotiates an unsafe cipher suite. By default, we only warn when
encountering old export cipher suites, or RC4 (see RFC7465).