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)

An enumeration.

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.

Type

pathlib.Path

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.

Type

str

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.

Type

List[sslyze.plugins.certificate_info._cert_chain_analyzer.CertificateDeploymentAnalysisResult]

Parameters
class sslyze.CertificateDeploymentAnalysisResult(received_certificate_chain, leaf_certificate_subject_matches_hostname, 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.

Type

List[cryptography.x509.base.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 built by OpenSSL can be retrieved from the PathValidationResult.

Type

List[sslyze.plugins.certificate_info._cert_chain_analyzer.PathValidationResult]

leaf_certificate_subject_matches_hostname

True if the leaf certificate’s Common Name or Subject Alternative Names match the server’s hostname.

Type

bool

leaf_certificate_is_ev

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

Type

bool

leaf_certificate_has_must_staple_extension

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

Type

bool

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.

Type

Optional[int]

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.

Type

Optional[bool]

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.

Type

Optional[bool]

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.

Type

Optional[bool]

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.

Type

Optional[bool]

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

Type

Optional[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.

Type

Optional[bool]

Parameters

  • received_certificate_chain (List[Certificate]) –

  • leaf_certificate_subject_matches_hostname (bool) –

  • 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, openssl_error_string)

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

trust_stores

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.

Type

Optional[List[cryptography.x509.base.Certificate]]

openssl_error_string

The result string returned by OpenSSL’s validation function; None if validation was successful.

Type

Optional[str]

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]]) –

  • openssl_error_string (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.

Type

pathlib.Path

name

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

Type

str

version

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

Type

str

Parameters

  • path (Path) –

  • name (str) –

  • version (str) –

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

path: pathlib.Path
name: str
version: str
ev_oids: Optional[List[cryptography.hazmat._oid.ObjectIdentifier]] = None
is_certificate_extended_validation(certificate)

Is the supplied server certificate EV?

Parameters

certificate (Certificate) –

Return type

bool

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.

Type

sslyze.server_connectivity.TlsVersionEnum

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)

An enumeration.

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.

Type

bool

supported_curves

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

Type

Optional[List[sslyze.plugins.elliptic_curves_plugin.EllipticCurve]]

rejected_curves

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

Type

Optional[List[sslyze.plugins.elliptic_curves_plugin.EllipticCurve]]

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.

Type

str

openssl_nid

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

Type

int

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)

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)

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.

Type

int

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.

Type

sslyze.plugins.session_resumption._resumption_with_id.TlsResumptionSupportEnum

session_id_attempted_resumptions_count

The total number of session ID resumptions that were attempted.

Type

int

session_id_successful_resumptions_count

The number of session ID resumptions that were successful.

Type

int

tls_ticket_resumption_result

The overall result of TLS ticket resumption testing.

Type

sslyze.plugins.session_resumption._resumption_with_id.TlsResumptionSupportEnum

tls_ticket_attempted_resumptions_count

The total number of TLS ticket resumptions that were attempted.

Type

int

tls_ticket_successful_resumptions_count

The number of TLS ticket resumptions that were successful.

Type

int

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.

Type

bool

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.

Type

bool

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.

Type

bool

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.

Type

bool

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, expect_ct_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.

Type

str

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.

Type

Optional[traceback.TracebackException]

http_path_redirected_to

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

Type

Optional[str]

strict_transport_security_header

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

Type

Optional[sslyze.plugins.http_headers_plugin.StrictTransportSecurityHeader]

expect_ct_header

The Expect-CT header returned by the server.

Type

Optional[sslyze.plugins.http_headers_plugin.ExpectCtHeader]

Parameters

  • http_request_sent (str) –

  • http_error_trace (Optional[TracebackException]) –

  • http_path_redirected_to (Optional[str]) –

  • strict_transport_security_header (Optional[StrictTransportSecurityHeader]) –

  • expect_ct_header (Optional[ExpectCtHeader]) –

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.

Type

bool

include_subdomains

True if the includesubdomains directive is set.

Type

bool

max_age

The content of the max-age field.

Type

Optional[int]

Parameters

  • max_age (Optional[int]) –

  • preload (bool) –

  • include_subdomains (bool) –

class sslyze.ExpectCtHeader(max_age, report_uri, enforce)

An Expect-CT header parsed from a server’s HTTP response.

max-age

The content of the max-age field.

report-uri

The content of report-uri field.

enforce

True if enforce directive is set.

Type

bool

Parameters

  • max_age (Optional[int]) –

  • report_uri (Optional[str]) –

  • enforce (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.

Type

bool

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.

Type

bool

Parameters

  • supports_secure_renegotiation (bool) –

  • is_vulnerable_to_client_renegotiation_dos (bool) –