Appendix: Scan Commands

Every type of TLS check that SSLyze can run against a server (supported cipher suites, session renegotiation, etc.) is represented by a ScanCommand, which, when run against a server, will return a specific result.

This page lists all the ScanCommand and their corresponding results available in the current release of SSLyze.

For an example on how to run a scan via the Python API, see Running a Scan in Python.

The following scan commands are available in the current version of SSLyze:

class sslyze.ScanCommand(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
CERTIFICATE_INFO = 'certificate_info'
SESSION_RESUMPTION = 'session_resumption'
SSL_2_0_CIPHER_SUITES = 'ssl_2_0_cipher_suites'
SSL_3_0_CIPHER_SUITES = 'ssl_3_0_cipher_suites'
TLS_1_0_CIPHER_SUITES = 'tls_1_0_cipher_suites'
TLS_1_1_CIPHER_SUITES = 'tls_1_1_cipher_suites'
TLS_1_2_CIPHER_SUITES = 'tls_1_2_cipher_suites'
TLS_1_3_CIPHER_SUITES = 'tls_1_3_cipher_suites'
TLS_COMPRESSION = 'tls_compression'
TLS_1_3_EARLY_DATA = 'tls_1_3_early_data'
OPENSSL_CCS_INJECTION = 'openssl_ccs_injection'
TLS_FALLBACK_SCSV = 'tls_fallback_scsv'
HEARTBLEED = 'heartbleed'
ROBOT = 'robot'
SESSION_RENEGOTIATION = 'session_renegotiation'
HTTP_HEADERS = 'http_headers'
ELLIPTIC_CURVES = 'elliptic_curves'

The next sections describe the result class that corresponds to each scan command.

Certificate Information

ScanCommand.CERTIFICATE_INFO: Retrieve and analyze a server’s certificate(s) to verify its validity.

Optional arguments

class sslyze.CertificateInfoExtraArgument(custom_ca_file)

Additional configuration for running the certificate_info scan command.

custom_ca_file

The path to a custom trust store file to use for certificate validation. The file should contain PEM-formatted root certificates.

Parameters:

custom_ca_file (Path) –

Result class

class sslyze.CertificateInfoScanResult(hostname_used_for_server_name_indication, certificate_deployments)

The result of retrieving and analyzing a server’s certificates to verify their validity.

hostname_used_for_server_name_indication

The hostname sent by SSLyze as the Server Name Indication extension.

certificate_deployments

A list of leaf certificates detected by SSLyze and the corresponding analysis. Most servers only deploy one leaf certificate, but some websites (such as Facebook) return different leaf certificates depending on the client, as a way to maximize compatibility with older clients/devices.

Parameters:
class sslyze.CertificateDeploymentAnalysisResult(received_certificate_chain, leaf_certificate_has_must_staple_extension, leaf_certificate_is_ev, leaf_certificate_signed_certificate_timestamps_count, received_chain_contains_anchor_certificate, received_chain_has_valid_order, path_validation_results, verified_chain_has_sha1_signature, verified_chain_has_legacy_symantec_anchor, ocsp_response, ocsp_response_is_trusted)

The result of analyzing a server’s certificate to verify its validity.

Any certificate available within the fields that follow is parsed as a Certificate object using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/reference.html?highlight=Certificate#cryptography.x509.Certificate

received_certificate_chain

The certificate chain sent by the server; index 0 is the leaf certificate.

verified_certificate_chain

The verified certificate chain returned by OpenSSL for one of the trust stores packaged within SSLyze. Will be None if the validation failed with all of the available trust stores (Apple, Mozilla, etc.). This is essentially a shortcut to path_validation_result_list[0].verified_certificate_chain.

path_validation_results

The result of validating the server’s certificate chain using each trust store that is packaged with SSLyze (Mozilla, Apple, etc.). If for a given trust store, the validation was successful, the verified certificate chain can be

retrieved from the PathValidationResult.

leaf_certificate_is_ev

True if the leaf certificate is Extended Validation, according to Mozilla.

leaf_certificate_has_must_staple_extension

True if the OCSP must-staple extension is present in the leaf certificate.

leaf_certificate_signed_certificate_timestamps_count

The number of Signed Certificate Timestamps (SCTs) for Certificate Transparency embedded in the leaf certificate. None if the version of OpenSSL installed on the system is too old to be able to parse the SCT extension.

received_chain_has_valid_order

True if the certificate chain returned by the server was sent in the right order. None` if any of the certificates in the chain could not be parsed.

received_chain_contains_anchor_certificate

True if the server included the anchor/root certificate in the chain it sends back to clients. None if the verified chain could not be built.

verified_chain_has_sha1_signature

True if any of the leaf or intermediate certificates are signed using the SHA-1 algorithm. None if the verified chain could not be built.

verified_chain_has_legacy_symantec_anchor

True if the certificate chain contains a distrusted Symantec anchor (https://blog.qualys.com/ssllabs/2017/09/26/google-and-mozilla-deprecating-existing-symantec-certificates). None if the verified chain could not be built.

ocsp_response

The OCSP response returned by the server. None if no response was sent by the server or if the scan was run through an HTTP proxy (the proxy will not forward the server’s OCSP response). If present, the OCSP response is an OCSPResponse object parsed using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/ocsp.html?highlight=OCSPResponse#cryptography.x509.ocsp.OCSPResponse

ocsp_response_is_trusted

True if the OCSP response is trusted using the Mozilla trust store. None if no OCSP response was sent by the server.

Parameters:

  • received_certificate_chain (List[Certificate]) –

  • leaf_certificate_has_must_staple_extension (bool) –

  • leaf_certificate_is_ev (bool) –

  • leaf_certificate_signed_certificate_timestamps_count (Optional[int]) –

  • received_chain_contains_anchor_certificate (Optional[bool]) –

  • received_chain_has_valid_order (Optional[bool]) –

  • path_validation_results (List[PathValidationResult]) –

  • verified_chain_has_sha1_signature (Optional[bool]) –

  • verified_chain_has_legacy_symantec_anchor (Optional[bool]) –

  • ocsp_response (Optional[OCSPResponse]) –

  • ocsp_response_is_trusted (Optional[bool]) –

class sslyze.PathValidationResult(trust_store, verified_certificate_chain, validation_error)

The result of trying to validate a server’s certificate chain using a specific trust store.

trust_store

The trust store used for validation.

verified_certificate_chain

The verified certificate chain returned by OpenSSL. Index 0 is the leaf certificate and the last element is the anchor/CA certificate from the trust store. Will be None if the validation failed or the verified chain could not be built. Each certificate is parsed using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/reference/#x-509-certificate-object.

validation_error

The error returned by the cryptography module’s validation function; None if validation was successful.

was_validation_successful

Whether the certificate chain is trusted when using supplied the trust_stores.

Parameters:

  • trust_store (TrustStore) –

  • verified_certificate_chain (Optional[List[Certificate]]) –

  • validation_error (Optional[str]) –

class sslyze.TrustStore(path, name, version, ev_oids=None)

A set of root certificates to be used for certificate validation.

path

The path on the local system to the PEM-formatted file containing the root certificates.

name

The human-readable name of the trust store (such as “Mozilla”).

version

The human-readable version or date of the trust store (such as “09/2016”).

Parameters:

  • path (Path) –

  • name (str) –

  • version (str) –

  • ev_oids (Optional[List[ObjectIdentifier]]) –

is_certificate_extended_validation(certificate)

Is the supplied server certificate EV?

Parameters:

certificate (Certificate) –

Return type:

bool

verify_certificate_chain(certificate_chain_as_pem, server_hostname, validation_time=None)
Parameters:

  • certificate_chain_as_pem (List[str]) –

  • server_hostname (str) –

  • validation_time (Optional[datetime]) –

Return type:

PathValidationResult

Cipher Suites

ScanCommand.SSL_2_0_CIPHER_SUITES: Test a server for SSL 2.0 support. ScanCommand.SSL_3_0_CIPHER_SUITES: Test a server for SSL 3.0 support. ScanCommand.TLS_1_0_CIPHER_SUITES: Test a server for TLS 1.0 support. ScanCommand.TLS_1_1_CIPHER_SUITES: Test a server for TLS 1.1 support. ScanCommand.TLS_1_2_CIPHER_SUITES: Test a server for TLS 1.2 support. ScanCommand.TLS_1_3_CIPHER_SUITES: Test a server for TLS 1.3 support.

Result class

class sslyze.CipherSuitesScanResult(tls_version_used, accepted_cipher_suites, rejected_cipher_suites)

The result of testing a server for cipher suites with a specific version of SSL/TLS.

tls_version_used

The SSL/TLS version used to connect to the server.

accepted_ciphers

The list of cipher suites supported supported by both SSLyze and the server.

rejected_ciphers

The list of cipher suites supported by SSLyze that were rejected by the server.

Parameters:
class sslyze.CipherSuiteRejectedByServer(cipher_suite, error_message)
Parameters:

  • cipher_suite (CipherSuite) –

  • error_message (str) –

class sslyze.CipherSuiteAcceptedByServer(cipher_suite, ephemeral_key)
ephemeral_key: The ephemeral key negotiated with the server when using (EC) DH cipher suites. None if the cipher

suite does not use ephemeral keys or if the ephemeral key could not be retrieved.

Parameters:
class sslyze.EphemeralKeyInfo(type, size, public_bytes)

Common fields shared by all kinds of TLS key exchanges.

Parameters:

  • type (OpenSslEvpPkeyEnum) –

  • size (int) –

  • public_bytes (bytearray) –

class sslyze.CipherSuite(name, is_anonymous, key_size, openssl_name)
Parameters:

  • name (str) –

  • is_anonymous (bool) –

  • key_size (int) –

  • openssl_name (str) –

class sslyze.TlsVersionEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
SSL_2_0 = 1
SSL_3_0 = 2
TLS_1_0 = 3
TLS_1_1 = 4
TLS_1_2 = 5
TLS_1_3 = 6

Supported Elliptic Curves

ScanCommand.ELLIPTIC_CURVES: Test a server for supported elliptic curves.

Result class

class sslyze.SupportedEllipticCurvesScanResult(supports_ecdh_key_exchange, supported_curves, rejected_curves)

The result of testing a server for supported elliptic curves.

supports_ecdh_key_exchange

True if the server supports at least one cipher suite with an ECDH key exchange.

supported_curves

A list of EllipticCurve that were accepted by the server or None if the server does not support ECDH cipher suites.

rejected_curves

A list of EllipticCurve that were rejected by the server or None if the server does not support ECDH cipher suites.

Parameters:

  • supports_ecdh_key_exchange (bool) –

  • supported_curves (Optional[List[EllipticCurve]]) –

  • rejected_curves (Optional[List[EllipticCurve]]) –

class sslyze.EllipticCurve(name, openssl_nid)

A specific elliptic curve.

name

The ANSI X9.62 name if available, otherwise the SECG name.

openssl_nid

The OpenSSL NID_XXX value valid for OpenSslEvpPkeyEnum.EC (obj_mac.h).

Parameters:

  • name (str) –

  • openssl_nid (int) –

ROBOT

ScanCommand.ROBOT: Test a server for the ROBOT vulnerability.

Result class

class sslyze.RobotScanResult(robot_result)

The result of testing a server for the ROBOT vulnerability.

result

An Enum providing the result of the ROBOT scan.

Parameters:

robot_result (RobotScanResultEnum) –

class sslyze.RobotScanResultEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The result of attempting exploit the ROBOT issue on the server.

VULNERABLE_WEAK_ORACLE

The server is vulnerable but the attack would take too long.

VULNERABLE_STRONG_ORACLE

The server is vulnerable and real attacks are feasible.

NOT_VULNERABLE_NO_ORACLE

The server supports RSA cipher suites but does not act as an oracle.

NOT_VULNERABLE_RSA_NOT_SUPPORTED

The server does not supports RSA cipher suites.

UNKNOWN_INCONSISTENT_RESULTS

Could not determine whether the server is vulnerable or not.

VULNERABLE_WEAK_ORACLE = 'VULNERABLE_WEAK_ORACLE'
VULNERABLE_STRONG_ORACLE = 'VULNERABLE_STRONG_ORACLE'
NOT_VULNERABLE_NO_ORACLE = 'NOT_VULNERABLE_NO_ORACLE'
NOT_VULNERABLE_RSA_NOT_SUPPORTED = 'NOT_VULNERABLE_RSA_NOT_SUPPORTED'
UNKNOWN_INCONSISTENT_RESULTS = 'UNKNOWN_INCONSISTENT_RESULTS'

Session Resumption Support

ScanCommand.SESSION_RESUMPTION: Test a server for TLS 1.2 session resumption support using session IDs and TLS tickets.

Result class

class sslyze.TlsResumptionSupportEnum(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

The result of attempting to resume TLS sessions with the server.

FULLY_SUPPORTED

All the session resumption attempts were successful.

PARTIALLY_SUPPORTED

Only some of the session resumption attempts were successful.

NOT_SUPPORTED

None of the session resumption attempts were successful.

SERVER_IS_TLS_1_3_ONLY

The server only supports TLS 1.3, which does not support Session ID nor TLS Tickets resumption.

class sslyze.SessionResumptionSupportExtraArgument(number_of_resumptions_to_attempt)

Additional configuration for running the SESSION_RESUMPTION scan command.

number_of_resumptions_to_attempt

The number of session resumptions (both with Session IDs and TLS Tickets) that SSLyze should attempt. The default value is 5, but a higher value such as 100 can be used to get a more accurate measure of how often session resumption succeeds or fails with the server.

Parameters:

number_of_resumptions_to_attempt (int) –

class sslyze.SessionResumptionSupportScanResult(session_id_resumption_result, session_id_attempted_resumptions_count, session_id_successful_resumptions_count, tls_ticket_resumption_result, tls_ticket_attempted_resumptions_count, tls_ticket_successful_resumptions_count)

The result of testing a server for TLS 1.2 session resumption support, using Session IDs and TLS tickets.

session_id_resumption_result

The overall result of session ID resumption testing.

session_id_attempted_resumptions_count

The total number of session ID resumptions that were attempted.

session_id_successful_resumptions_count

The number of session ID resumptions that were successful.

tls_ticket_resumption_result

The overall result of TLS ticket resumption testing.

tls_ticket_attempted_resumptions_count

The total number of TLS ticket resumptions that were attempted.

tls_ticket_successful_resumptions_count

The number of TLS ticket resumptions that were successful.

Parameters:

  • session_id_resumption_result (TlsResumptionSupportEnum) –

  • session_id_attempted_resumptions_count (int) –

  • session_id_successful_resumptions_count (int) –

  • tls_ticket_resumption_result (TlsResumptionSupportEnum) –

  • tls_ticket_attempted_resumptions_count (int) –

  • tls_ticket_successful_resumptions_count (int) –

CRIME

ScanCommand.TLS_COMPRESSION: Test a server for TLS compression support, which can be leveraged to perform a CRIME attack.

Result class

class sslyze.CompressionScanResult(supports_compression)

The result of testing a server for TLS compression support.

supports_compression

True if TLS compression is supported by the server, thereby enabling the CRIME attack.

Parameters:

supports_compression (bool) –

TLS 1.3 Early Data

ScanCommand.TLS_1_3_EARLY_DATA: Test the server(s) for TLS 1.3 early data support.

Result class

class sslyze.EarlyDataScanResult(supports_early_data)

The result of testing a server for TLS 1.3 early data support.

supports_early_data

True if the server accepted early data.

Parameters:

supports_early_data (bool) –

Downgrade Prevention

ScanCommand.TLS_FALLBACK_SCSV: Test a server for the TLS_FALLBACK_SCSV mechanism to prevent downgrade attacks.

Result class

class sslyze.FallbackScsvScanResult(supports_fallback_scsv)

The result of testing a server for the TLS_FALLBACK_SCSV mechanism to prevent downgrade attacks.

supports_fallback_scsv

True if the server supports the TLS_FALLBACK_SCSV mechanism.

Parameters:

supports_fallback_scsv (bool) –

Heartbleed

ScanCommand.HEARTBLEED: Test a server for the OpenSSL Heartbleed vulnerability.

Result class

class sslyze.HeartbleedScanResult(is_vulnerable_to_heartbleed)

The result of testing a server for the OpenSSL Heartbleed vulnerability.

is_vulnerable_to_heartbleed

True if the server is vulnerable to the Heartbleed attack.

Parameters:

is_vulnerable_to_heartbleed (bool) –

HTTP Security Headers

ScanCommand.HTTP_HEADERS: Test a server for the presence of security-related HTTP headers.

Result class

class sslyze.HttpHeadersScanResult(http_request_sent, http_error_trace, http_path_redirected_to, strict_transport_security_header)

The result of testing a server for the presence of security-related HTTP headers.

Each HTTP header described below will be None if the server did not return a valid HTTP response, or if the server returned an HTTP response without the HTTP header.

http_request_sent

The initial HTTP request sent to the server by SSLyze.

http_error_trace

An error the server returned after receiving the initial HTTP request. If this field is set, all the subsequent fields will be None as SSLyze did not receive a valid HTTP response from the server.

http_path_redirected_to

The path SSLyze was eventually redirected to after sending the initial HTTP request.

strict_transport_security_header

The Strict-Transport-Security header returned by the server.

Parameters:

  • http_request_sent (str) –

  • http_error_trace (Optional[TracebackException]) –

  • http_path_redirected_to (Optional[str]) –

  • strict_transport_security_header (Optional[StrictTransportSecurityHeader]) –

class sslyze.StrictTransportSecurityHeader(max_age, preload, include_subdomains)

A Strict-Transport-Security header parsed from a server’s HTTP response.

preload

True if the preload directive is set.

include_subdomains

True if the includesubdomains directive is set.

max_age

The content of the max-age field.

Parameters:

  • max_age (Optional[int]) –

  • preload (bool) –

  • include_subdomains (bool) –

OpenSSL CCS Injection

ScanCommand.OPENSSL_CCS_INJECTION: Test a server for the OpenSSL CCS Injection vulnerability (CVE-2014-0224).

Result class

class sslyze.OpenSslCcsInjectionScanResult(is_vulnerable_to_ccs_injection)

The result of testing a server for the OpenSSL CCS Injection vulnerability (CVE-2014-0224).

is_vulnerable_to_ccs_injection

True if the server is vulnerable to the OpenSSL CCS Injection vulnerability.

Parameters:

is_vulnerable_to_ccs_injection (bool) –

Insecure Renegotiation

ScanCommand.SESSION_RENEGOTIATION: Test a server for for insecure TLS renegotiation and client-initiated renegotiation.

Result class

class sslyze.SessionRenegotiationScanResult(supports_secure_renegotiation, is_vulnerable_to_client_renegotiation_dos)

The result of testing a server for insecure TLS renegotiation and client-initiated renegotiation.

accepts_client_renegotiation

True if the server honors client-initiated renegotiation attempts.

supports_secure_renegotiation

True if the server supports secure renegotiation.

Parameters:

  • supports_secure_renegotiation (bool) –

  • is_vulnerable_to_client_renegotiation_dos (bool) –