base/protocols/ssl/main.zeek
- SSL
Base SSL analysis script. This script logs information about the SSL/TLS handshaking and encryption establishment process.
- Namespace:
SSL
- Imports:
base/frameworks/notice/weird.zeek, base/protocols/conn/removal-hooks.zeek, base/protocols/ssl/consts.zeek
Summary
Runtime Options
The Certificate Transparency log bundle. |
|
If true, detach the SSL analyzer from the connection to prevent continuing to process encrypted traffic. |
|
Maximum length of the ssl_history field to prevent unbounded growth when the parser is running into unexpected situations. |
Redefinable Options
The default root CA bundle. |
Types
The record type which contains the field for the Certificate Transparency log bundle. |
|
The record type which contains the fields of the SSL log. |
Redefinitions
|
|
Events
Event that can be handled to access the SSL record as it is sent on to the logging framework. |
Hooks
SSL finalization hook. |
|
Hook that can be used to perform actions right before the log record is written. |
Functions
Delays an SSL record for a specific token: the record will not be logged as long as the token exists or until 15 seconds elapses. |
|
Undelays an SSL record for a previously inserted token, allowing the record to be logged. |
Detailed Interface
Runtime Options
- SSL::ct_logs
- Type:
table
[string
] ofSSL::CTInfo
- Attributes:
- Default:
{}
- Redefinition:
from base/protocols/ssl/ct-list.zeek
<< Value omitted due to
@docs_omit_value
annotation >>
The Certificate Transparency log bundle. By default, the ct-list.zeek script sets this to the current list of known logs. Entries are indexed by (binary) log-id.
- SSL::disable_analyzer_after_detection
- Type:
- Attributes:
- Default:
T
- Redefinition:
from policy/protocols/ssl/decryption.zeek
=
:F
- Redefinition:
from policy/protocols/ssl/heartbleed.zeek
=
:F
If true, detach the SSL analyzer from the connection to prevent continuing to process encrypted traffic. Helps with performance (especially with large file transfers).
- SSL::max_ssl_history_length
-
Maximum length of the ssl_history field to prevent unbounded growth when the parser is running into unexpected situations.
Redefinable Options
- SSL::root_certs
- Type:
- Attributes:
- Default:
{}
- Redefinition:
from base/protocols/ssl/mozilla-ca-list.zeek
<< Value omitted due to
@docs_omit_value
annotation >>
The default root CA bundle. By default, the mozilla-ca-list.zeek script sets this to Mozilla’s root CA list.
Types
- SSL::CTInfo
- Type:
The record type which contains the field for the Certificate Transparency log bundle.
- SSL::Info
- Type:
-
- ts:
time
&log
Time when the SSL connection was first detected.
- uid:
string
&log
Unique ID for the connection.
- id:
conn_id
&log
The connection’s 4-tuple of endpoint addresses/ports.
- version_num:
count
&optional
Numeric SSL/TLS version that the server chose.
- version:
string
&log
&optional
SSL/TLS version that the server chose.
- cipher:
string
&log
&optional
SSL/TLS cipher suite that the server chose.
- curve:
string
&log
&optional
Elliptic curve the server chose when using ECDH/ECDHE.
- server_name:
string
&log
&optional
Value of the Server Name Indicator SSL/TLS extension. It indicates the server name that the client was requesting.
- session_id:
string
&optional
Session ID offered by the client for session resumption. Not used for logging.
- resumed:
bool
&log
&default
=F
&optional
Flag to indicate if the session was resumed reusing the key material exchanged in an earlier connection.
- client_ticket_empty_session_seen:
bool
&default
=F
&optional
Flag to indicate if we saw a non-empty session ticket being sent by the client using an empty session ID. This value is used to determine if a session is being resumed. It’s not logged.
- client_key_exchange_seen:
bool
&default
=F
&optional
Flag to indicate if we saw a client key exchange message sent by the client. This value is used to determine if a session is being resumed. It’s not logged.
- client_psk_seen:
bool
&default
=F
&optional
Track if the client sent a pre-shared-key extension. Used to determine if a TLS 1.3 session is being resumed. Not logged.
- last_alert:
string
&log
&optional
Last alert that was seen during the connection.
- next_protocol:
string
&log
&optional
Next protocol the server chose using the application layer next protocol extension, if present.
- analyzer_id:
count
&optional
The analyzer ID used for the analyzer instance attached to each connection. It is not used for logging since it’s a meaningless arbitrary number.
- established:
bool
&log
&default
=F
&optional
Flag to indicate if this ssl session has been established successfully, or if it was aborted during the handshake.
- logged:
bool
&default
=F
&optional
Flag to indicate if this record already has been logged, to prevent duplicates.
- hrr_seen:
bool
&default
=F
&optional
Flag to indicate that we have seen a Hello Retry request message. Used internally for ssl_history logging
- ssl_history:
string
&log
&default
=""
&optional
SSL history showing which types of packets we received in which order. Letters have the following meaning with client-sent letters being capitalized:
A direction flip occurs when the client hello packet is not sent from the originator of a connection. This can, e.g., occur when DTLS is used in a connection that was set up using STUN.
Letter
Meaning
^
direction flipped
H
hello_request
C
client_hello
S
server_hello
V
hello_verify_request
T
NewSessionTicket
X
certificate
K
server_key_exchange
R
certificate_request
N
server_hello_done
Y
certificate_verify
G
client_key_exchange
F
finished
W
certificate_url
U
certificate_status
A
supplemental_data
Z
unassigned_handshake_type
I
change_cipher_spec
B
heartbeat
D
application_data
E
end_of_early_data
O
encrypted_extensions
P
key_update
M
message_hash
J
hello_retry_request
L
alert
Q
unknown_content_type
delay_tokens:
set
[string
]&optional
- cert_chain:
vector
ofFiles::Info
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Chain of certificates offered by the server to validate its complete signing chain.
- cert_chain_fps:
vector
ofstring
&optional
&log
(present if base/protocols/ssl/files.zeek is loaded)
An ordered vector of all certificate fingerprints for the certificates offered by the server.
- client_cert_chain:
vector
ofFiles::Info
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Chain of certificates offered by the client to validate its complete signing chain.
- client_cert_chain_fps:
vector
ofstring
&optional
&log
(present if base/protocols/ssl/files.zeek is loaded)
An ordered vector of all certificate fingerprints for the certificates offered by the client.
- subject:
string
&log
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Subject of the X.509 certificate offered by the server.
- issuer:
string
&log
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Issuer of the signer of the X.509 certificate offered by the server.
- client_subject:
string
&log
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Subject of the X.509 certificate offered by the client.
- client_issuer:
string
&log
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Subject of the signer of the X.509 certificate offered by the client.
- sni_matches_cert:
bool
&log
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Set to true if the hostname sent in the SNI matches the certificate. Set to false if they do not match. Unset if the client did not send an SNI.
- server_depth:
count
&default
=0
&optional
(present if base/protocols/ssl/files.zeek is loaded)
Current number of certificates seen from either side. Used to create file handles.
- client_depth:
count
&default
=0
&optional
(present if base/protocols/ssl/files.zeek is loaded)
- always_raise_x509_events:
bool
&default
=F
&optional
(present if policy/files/x509/disable-certificate-events-known-certs.zeek is loaded)
Set to true to force certificate events to always be raised for this connection.
- requested_client_certificate_authorities:
vector
ofstring
&optional
&log
(present if policy/protocols/ssl/certificate-request-info.zeek is loaded)
List of client certificate CAs accepted by the server
- client_random:
string
&optional
(present if policy/protocols/ssl/decryption.zeek is loaded)
- last_originator_heartbeat_request_size:
count
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- last_responder_heartbeat_request_size:
count
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- originator_heartbeats:
count
&default
=0
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- responder_heartbeats:
count
&default
=0
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- heartbleed_detected:
bool
&default
=F
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- enc_appdata_packages:
count
&default
=0
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- enc_appdata_bytes:
count
&default
=0
&optional
(present if policy/protocols/ssl/heartbleed.zeek is loaded)
- server_version:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Numeric version of the server in the server hello
- client_version:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Numeric version of the client in the client hello
- client_ciphers:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Ciphers that were offered by the client for the connection
- ssl_client_exts:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
SSL Client extensions
- ssl_server_exts:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
SSL server extensions
- ticket_lifetime_hint:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Suggested ticket lifetime sent in the session ticket handshake by the server.
- dh_param_size:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
The diffie helman parameter size, when using DH.
- point_formats:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
supported elliptic curve point formats
- client_curves:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
The curves supported by the client.
- orig_alpn:
vector
ofstring
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Application layer protocol negotiation extension sent by the client.
- client_supported_versions:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
TLS 1.3 supported versions
- server_supported_version:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
TLS 1.3 supported versions
- psk_key_exchange_modes:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
TLS 1.3 Pre-shared key exchange modes
- client_key_share_groups:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Key share groups from client hello
- server_key_share_group:
count
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Selected key share group from server hello
- client_comp_methods:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Client supported compression methods
- comp_method:
count
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Server chosen compression method
- sigalgs:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Client supported signature algorithms
- hashalgs:
vector
ofcount
&log
&optional
(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)
Client supported hash algorithms
- validation_status:
string
&log
&optional
(present if policy/protocols/ssl/validate-certs.zeek is loaded)
Result of certificate validation for this connection.
- validation_code:
int
&optional
(present if policy/protocols/ssl/validate-certs.zeek is loaded)
Result of certificate validation for this connection, given as OpenSSL validation code.
- valid_chain:
vector
ofopaque
of x509&optional
(present if policy/protocols/ssl/validate-certs.zeek is loaded)
Ordered chain of validated certificate, if validation succeeded.
- ocsp_status:
string
&log
&optional
(present if policy/protocols/ssl/validate-ocsp.zeek is loaded)
Result of ocsp validation for this connection.
- ocsp_response:
string
&optional
(present if policy/protocols/ssl/validate-ocsp.zeek is loaded)
ocsp response as string.
- valid_scts:
count
&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
Number of valid SCTs that were encountered in the connection.
- invalid_scts:
count
&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
Number of SCTs that could not be validated that were encountered in the connection.
- valid_ct_logs:
count
&log
&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
Number of different Logs for which valid SCTs were encountered in the connection.
- valid_ct_operators:
count
&log
&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
Number of different Log operators of which valid SCTs were encountered in the connection.
- valid_ct_operators_list:
set
[string
]&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
List of operators for which valid SCTs were encountered in the connection.
- ct_proofs:
vector
ofSSL::SctInfo
&default
=[]
&optional
(present if policy/protocols/ssl/validate-sct.zeek is loaded)
Information about all SCTs that were encountered in the connection.
- ts:
The record type which contains the fields of the SSL log.
Events
- SSL::log_ssl
-
Event that can be handled to access the SSL record as it is sent on to the logging framework.
Hooks
- SSL::finalize_ssl
- Type:
SSL finalization hook. Remaining SSL info may get logged when it’s called. The
SSL::ssl_finishing
hook may either be called before this finalization hook for established SSL connections or during this finalization hook for SSL connections may have info still left to log.
- SSL::ssl_finishing
- Type:
hook
(c:connection
) :bool
Hook that can be used to perform actions right before the log record is written.
Functions
- SSL::delay_log
-
Delays an SSL record for a specific token: the record will not be logged as long as the token exists or until 15 seconds elapses.