mirror of
https://github.com/zeek/zeek.git
synced 2025-10-03 15:18:20 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
375 lines
15 KiB
ReStructuredText
375 lines
15 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
base/files/x509/main.zeek
|
|
=========================
|
|
.. zeek:namespace:: X509
|
|
|
|
|
|
:Namespace: X509
|
|
:Imports: :doc:`base/files/hash </scripts/base/files/hash/index>`, :doc:`base/frameworks/cluster </scripts/base/frameworks/cluster/index>`, :doc:`base/frameworks/files </scripts/base/frameworks/files/index>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Runtime Options
|
|
###############
|
|
========================================================================================== ===================================================================
|
|
:zeek:id:`X509::known_log_certs_maximum_size`: :zeek:type:`count` :zeek:attr:`&redef` Maximum size of the known_log_certs table
|
|
:zeek:id:`X509::log_x509_in_files_log`: :zeek:type:`bool` :zeek:attr:`&redef` This option specifies if X.509 certificates are logged in file.log.
|
|
:zeek:id:`X509::relog_known_certificates_after`: :zeek:type:`interval` :zeek:attr:`&redef` By default, x509 certificates are deduplicated.
|
|
========================================================================================== ===================================================================
|
|
|
|
Redefinable Options
|
|
###################
|
|
============================================================================================= ========================================================================
|
|
:zeek:id:`X509::default_max_field_container_elements`: :zeek:type:`count` :zeek:attr:`&redef` The maximum number of elements a single container field can contain when
|
|
logging.
|
|
:zeek:id:`X509::default_max_field_string_bytes`: :zeek:type:`count` :zeek:attr:`&redef` The maximum number of bytes that a single string field can contain when
|
|
logging.
|
|
:zeek:id:`X509::default_max_total_container_elements`: :zeek:type:`count` :zeek:attr:`&redef` The maximum total number of container elements a record may log.
|
|
============================================================================================= ========================================================================
|
|
|
|
State Variables
|
|
###############
|
|
================================================================================================================================= ===========================================================================================
|
|
:zeek:id:`X509::known_log_certs`: :zeek:type:`set` :zeek:attr:`&create_expire` = :zeek:see:`X509::relog_known_certificates_after` The set that stores information about certificates that already have been logged and should
|
|
not be logged again.
|
|
:zeek:id:`X509::known_log_certs_use_broker`: :zeek:type:`bool` Use broker stores to deduplicate certificates across the whole cluster.
|
|
================================================================================================================================= ===========================================================================================
|
|
|
|
Types
|
|
#####
|
|
=================================================== ===================================================================================
|
|
:zeek:type:`X509::Info`: :zeek:type:`record` The record type which contains the fields of the X.509 log.
|
|
:zeek:type:`X509::LogCertHash`: :zeek:type:`record` Type that is used to decide which certificates are duplicates for logging purposes.
|
|
:zeek:type:`X509::SctInfo`: :zeek:type:`record` This record is used to store information about the SCTs that are
|
|
encountered in Certificates.
|
|
=================================================== ===================================================================================
|
|
|
|
Redefinitions
|
|
#############
|
|
================================================================= ======================================================
|
|
:zeek:type:`Files::Info`: :zeek:type:`record` :zeek:attr:`&redef`
|
|
|
|
:New Fields: :zeek:type:`Files::Info`
|
|
|
|
x509: :zeek:type:`X509::Info` :zeek:attr:`&optional`
|
|
Information about X509 certificates.
|
|
:zeek:type:`Log::ID`: :zeek:type:`enum`
|
|
|
|
* :zeek:enum:`X509::LOG`
|
|
================================================================= ======================================================
|
|
|
|
Events
|
|
######
|
|
============================================= ===================================
|
|
:zeek:id:`X509::log_x509`: :zeek:type:`event` Event for accessing logged records.
|
|
============================================= ===================================
|
|
|
|
Hooks
|
|
#####
|
|
============================================================== =======================================================================
|
|
:zeek:id:`X509::create_deduplication_index`: :zeek:type:`hook` Hook that is used to create the index value used for log deduplication.
|
|
:zeek:id:`X509::log_policy`: :zeek:type:`Log::PolicyHook`
|
|
============================================================== =======================================================================
|
|
|
|
Functions
|
|
#########
|
|
========================================================================= ==============================================
|
|
:zeek:id:`X509::hash_function`: :zeek:type:`function` :zeek:attr:`&redef` The hash function used for certificate hashes.
|
|
========================================================================= ==============================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
Runtime Options
|
|
###############
|
|
.. zeek:id:: X509::known_log_certs_maximum_size
|
|
:source-code: base/files/x509/main.zeek 98 98
|
|
|
|
:Type: :zeek:type:`count`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``1000000``
|
|
|
|
Maximum size of the known_log_certs table
|
|
|
|
.. zeek:id:: X509::log_x509_in_files_log
|
|
:source-code: base/files/x509/main.zeek 20 20
|
|
|
|
:Type: :zeek:type:`bool`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``F``
|
|
|
|
This option specifies if X.509 certificates are logged in file.log. Typically, there
|
|
is not much value to having the entry in files.log - especially since, by default, the
|
|
file ID is not present in the X509 log.
|
|
|
|
.. zeek:id:: X509::relog_known_certificates_after
|
|
:source-code: base/files/x509/main.zeek 91 91
|
|
|
|
:Type: :zeek:type:`interval`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``1.0 day``
|
|
|
|
By default, x509 certificates are deduplicated. This configuration option configures
|
|
the maximum time after which certificates are re-logged. Note - depending on other configuration
|
|
options, this setting might only apply on a per-worker basis and you still might see certificates
|
|
logged several times.
|
|
|
|
To disable deduplication completely, set this to 0secs.
|
|
|
|
Redefinable Options
|
|
###################
|
|
.. zeek:id:: X509::default_max_field_container_elements
|
|
:source-code: base/files/x509/main.zeek 121 121
|
|
|
|
:Type: :zeek:type:`count`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``500``
|
|
|
|
The maximum number of elements a single container field can contain when
|
|
logging. If a container reaches this limit, the log output for the field will
|
|
be truncated. Setting this to zero disables the limiting.
|
|
|
|
.. zeek:see:: Log::default_max_field_container_elements
|
|
|
|
.. zeek:id:: X509::default_max_field_string_bytes
|
|
:source-code: base/files/x509/main.zeek 114 114
|
|
|
|
:Type: :zeek:type:`count`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``4096``
|
|
:Redefinition: from :doc:`/scripts/policy/protocols/ssl/log-certs-base64.zeek`
|
|
|
|
``=``::
|
|
|
|
0
|
|
|
|
|
|
The maximum number of bytes that a single string field can contain when
|
|
logging. If a string reaches this limit, the log output for the field will be
|
|
truncated. Setting this to zero disables the limiting.
|
|
|
|
.. zeek:see:: Log::default_max_field_string_bytes
|
|
|
|
.. zeek:id:: X509::default_max_total_container_elements
|
|
:source-code: base/files/x509/main.zeek 130 130
|
|
|
|
:Type: :zeek:type:`count`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
:Default: ``1500``
|
|
|
|
The maximum total number of container elements a record may log. This is the
|
|
sum of all container elements logged for the record. If this limit is reached,
|
|
all further containers will be logged as empty containers. If the limit is
|
|
reached while processing a container, the container will be truncated in the
|
|
output. Setting this to zero disables the limiting.
|
|
|
|
.. zeek:see:: Log::default_max_total_container_elements
|
|
|
|
State Variables
|
|
###############
|
|
.. zeek:id:: X509::known_log_certs
|
|
:source-code: base/files/x509/main.zeek 95 95
|
|
|
|
:Type: :zeek:type:`set` [:zeek:type:`X509::LogCertHash`]
|
|
:Attributes: :zeek:attr:`&create_expire` = :zeek:see:`X509::relog_known_certificates_after`
|
|
:Default: ``{}``
|
|
|
|
The set that stores information about certificates that already have been logged and should
|
|
not be logged again.
|
|
|
|
.. zeek:id:: X509::known_log_certs_use_broker
|
|
:source-code: base/files/x509/main.zeek 104 104
|
|
|
|
:Type: :zeek:type:`bool`
|
|
:Default: ``T``
|
|
|
|
Use broker stores to deduplicate certificates across the whole cluster. This will cause log-deduplication
|
|
to work cluster wide, but come at a slightly higher cost of memory and inter-node-communication.
|
|
|
|
This setting is ignored if Zeek is run in standalone mode.
|
|
|
|
Types
|
|
#####
|
|
.. zeek:type:: X509::Info
|
|
:source-code: base/files/x509/main.zeek 34 60
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: ts :zeek:type:`time` :zeek:attr:`&log`
|
|
|
|
Current timestamp.
|
|
|
|
|
|
.. zeek:field:: fingerprint :zeek:type:`string` :zeek:attr:`&log`
|
|
|
|
Fingerprint of the certificate - uses chosen algorithm.
|
|
|
|
|
|
.. zeek:field:: certificate :zeek:type:`X509::Certificate` :zeek:attr:`&log`
|
|
|
|
Basic information about the certificate.
|
|
|
|
|
|
.. zeek:field:: handle :zeek:type:`opaque` of x509
|
|
|
|
The opaque wrapping the certificate. Mainly used
|
|
for the verify operations.
|
|
|
|
|
|
.. zeek:field:: extensions :zeek:type:`vector` of :zeek:type:`X509::Extension` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
|
|
|
|
All extensions that were encountered in the certificate.
|
|
|
|
|
|
.. zeek:field:: san :zeek:type:`X509::SubjectAlternativeName` :zeek:attr:`&optional` :zeek:attr:`&log`
|
|
|
|
Subject alternative name extension of the certificate.
|
|
|
|
|
|
.. zeek:field:: basic_constraints :zeek:type:`X509::BasicConstraints` :zeek:attr:`&optional` :zeek:attr:`&log`
|
|
|
|
Basic constraints extension of the certificate.
|
|
|
|
|
|
.. zeek:field:: extensions_cache :zeek:type:`vector` of :zeek:type:`any` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
|
|
|
|
All extensions in the order they were raised.
|
|
This is used for caching certificates that are commonly
|
|
encountered and should not be relied on in user scripts.
|
|
|
|
|
|
.. zeek:field:: host_cert :zeek:type:`bool` :zeek:attr:`&log` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional`
|
|
|
|
Indicates if this certificate was a end-host certificate, or sent as part of a chain
|
|
|
|
|
|
.. zeek:field:: client_cert :zeek:type:`bool` :zeek:attr:`&log` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional`
|
|
|
|
Indicates if this certificate was sent from the client
|
|
|
|
|
|
.. zeek:field:: deduplication_index :zeek:type:`X509::LogCertHash` :zeek:attr:`&optional`
|
|
|
|
Record that is used to deduplicate log entries.
|
|
|
|
|
|
.. zeek:field:: always_raise_x509_events :zeek:type:`bool` :zeek:attr:`&default` = ``F`` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/policy/files/x509/disable-certificate-events-known-certs.zeek` is loaded)
|
|
|
|
Set to true to force certificate events to always be raised for this certificate.
|
|
|
|
|
|
.. zeek:field:: cert :zeek:type:`string` :zeek:attr:`&log` :zeek:attr:`&optional`
|
|
|
|
(present if :doc:`/scripts/policy/protocols/ssl/log-certs-base64.zeek` is loaded)
|
|
|
|
Base64 encoded X.509 certificate.
|
|
|
|
|
|
The record type which contains the fields of the X.509 log.
|
|
|
|
.. zeek:type:: X509::LogCertHash
|
|
:source-code: base/files/x509/main.zeek 24 31
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: fingerprint :zeek:type:`string`
|
|
|
|
Certificate fingerprint
|
|
|
|
|
|
.. zeek:field:: host_cert :zeek:type:`bool`
|
|
|
|
Indicates if this certificate was a end-host certificate, or sent as part of a chain
|
|
|
|
|
|
.. zeek:field:: client_cert :zeek:type:`bool`
|
|
|
|
Indicates if this certificate was sent from the client
|
|
|
|
|
|
Type that is used to decide which certificates are duplicates for logging purposes.
|
|
When adding entries to this, also change the create_deduplication_index to update them.
|
|
|
|
.. zeek:type:: X509::SctInfo
|
|
:source-code: base/files/x509/main.zeek 67 83
|
|
|
|
: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:: hash_alg :zeek:type:`count`
|
|
|
|
The hash algorithm used for this sct.
|
|
|
|
|
|
.. zeek:field:: sig_alg :zeek:type:`count`
|
|
|
|
The signature algorithm used for this sct.
|
|
|
|
|
|
.. zeek:field:: signature :zeek:type:`string`
|
|
|
|
The signature of this SCT.
|
|
|
|
|
|
This record is used to store information about the SCTs that are
|
|
encountered in Certificates.
|
|
|
|
Events
|
|
######
|
|
.. zeek:id:: X509::log_x509
|
|
:source-code: base/files/x509/main.zeek 107 107
|
|
|
|
:Type: :zeek:type:`event` (rec: :zeek:type:`X509::Info`)
|
|
|
|
Event for accessing logged records.
|
|
|
|
Hooks
|
|
#####
|
|
.. zeek:id:: X509::create_deduplication_index
|
|
:source-code: base/files/x509/main.zeek 186 192
|
|
|
|
:Type: :zeek:type:`hook` (c: :zeek:type:`X509::Info`) : :zeek:type:`bool`
|
|
|
|
Hook that is used to create the index value used for log deduplication.
|
|
|
|
.. zeek:id:: X509::log_policy
|
|
:source-code: policy/protocols/ssl/log-hostcerts-only.zeek 9 13
|
|
|
|
:Type: :zeek:type:`Log::PolicyHook`
|
|
|
|
|
|
Functions
|
|
#########
|
|
.. zeek:id:: X509::hash_function
|
|
:source-code: base/files/x509/main.zeek 15 15
|
|
|
|
:Type: :zeek:type:`function` (cert: :zeek:type:`string`) : :zeek:type:`string`
|
|
:Attributes: :zeek:attr:`&redef`
|
|
|
|
The hash function used for certificate hashes. By default this is sha256; you can use
|
|
any other hash function and the hashes will change in ssl.log and in x509.log.
|
|
|
|
|