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

SSL::ct_logs: table &redef

The Certificate Transparency log bundle.

SSL::disable_analyzer_after_detection: bool &redef

If true, detach the SSL analyzer from the connection to prevent continuing to process encrypted traffic.

SSL::max_ssl_history_length: count &redef

Maximum length of the ssl_history field to prevent unbounded growth when the parser is running into unexpected situations.

Redefinable Options

SSL::root_certs: table &redef

The default root CA bundle.

Types

SSL::CTInfo: record

The record type which contains the field for the Certificate Transparency log bundle.

SSL::Info: record

The record type which contains the fields of the SSL log.

Redefinitions

Log::ID: enum

SSL::Info: record
New Fields:

SSL::Info

delay_tokens: set [string] &optional

connection: record
New Fields:

connection

ssl: SSL::Info &optional

likely_server_ports: set &redef

Events

SSL::log_ssl: event

Event that can be handled to access the SSL record as it is sent on to the logging framework.

Hooks

SSL::finalize_ssl: Conn::RemovalHook

SSL finalization hook.

SSL::log_policy: Log::PolicyHook

SSL::ssl_finishing: hook

Hook that can be used to perform actions right before the log record is written.

Functions

SSL::delay_log: function

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.

SSL::undelay_log: function

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] of SSL::CTInfo

Attributes:

&redef

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:

bool

Attributes:

&redef

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
Type:

count

Attributes:

&redef

Default:

100

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:

table [string] of string

Attributes:

&redef

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:

record

description: string

Description of the Log

operator: string

Operator of the Log

key: string

Public key of the Log.

maximum_merge_delay: count

Maximum merge delay of the Log

url: string

URL of the Log

The record type which contains the field for the Certificate Transparency log bundle.

SSL::Info
Type:

record

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 of Files::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 of string &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 of Files::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 of string &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 of string &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 of count &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 of count &log &optional

(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)

SSL Client extensions

ssl_server_exts: vector of count &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 of count &log &optional

(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)

supported elliptic curve point formats

client_curves: vector of count &log &optional

(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)

The curves supported by the client.

orig_alpn: vector of string &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 of count &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 of count &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 of count &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 of count &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 of count &log &optional

(present if policy/protocols/ssl/ssl-log-ext.zeek is loaded)

Client supported signature algorithms

hashalgs: vector of count &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 of opaque 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 of SSL::SctInfo &default = [] &optional

(present if policy/protocols/ssl/validate-sct.zeek is loaded)

Information about all SCTs that were encountered in the connection.

The record type which contains the fields of the SSL log.

Events

SSL::log_ssl
Type:

event (rec: SSL::Info)

Event that can be handled to access the SSL record as it is sent on to the logging framework.

Hooks

SSL::finalize_ssl
Type:

Conn::RemovalHook

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::log_policy
Type:

Log::PolicyHook

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
Type:

function (info: SSL::Info, token: string) : void

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.

SSL::undelay_log
Type:

function (info: SSL::Info, token: string) : void

Undelays an SSL record for a previously inserted token, allowing the record to be logged.