Step 1: Testing Connectivity to a Server

Basic Example

Before a server can be scanned, SSLyze must validate that it is able to connect to the server. This is done using the ServerConnectivityTester class:

def basic_example_connectivity_testing() -> None:
    # Define the server that you want to scan
    server_location = ServerNetworkLocationViaDirectConnection.with_ip_address_lookup("", 443)

    # Do connectivity testing to ensure SSLyze is able to connect
        server_info = ServerConnectivityTester().perform(server_location)
    except ConnectionToServerFailed as e:
        # Could not connect to the server; abort
        print(f"Error connecting to {server_location}: {e.error_message}")
    print(f"Connectivity testing completed: {server_info}")

If the call to perform() is successful, it returns a ServerConnectivityInfo object that can then be used for scanning the server.

This is described in Step 2: Running Scan Commands Against a Server.

Advanced Usage

When calling ServerConnectivityTester.perform(), a ServerNetworkConfiguration can be optionally provided as the second argument, in order to have more control on how SSLyze should connect to the server. This configuration object allows for example to configure StarTLS or a client certificate SSL/TLS client authentication.

Main classes for connectivity testing

class sslyze.ServerNetworkLocationViaDirectConnection(hostname, port, ip_address)

All the information needed to connect to a server directly.


The server’s hostname.


The server’s TLS port number.


The server’s IP address. If you do not have the server’s IP address, instantiate this class using with_ip_address_lookup() to do a DNS lookup for the specified hostname.

  • hostname (str) –

  • port (int) –

  • ip_address (str) –

classmethod with_ip_address_lookup(hostname, port)

Helper factory method to automatically do a DNS lookup of the supplied hostname.

  • hostname (str) –

  • port (int) –

Return type


class sslyze.ServerConnectivityTester

Utility class to ensure that SSLyze is able to connect to a server before scanning it.

perform(server_location, network_configuration=None)

Attempt to perform a full SSL/TLS handshake with the server.

This method will ensure that the server can be reached, and will also identify one SSL/TLS version and one cipher suite that is supported by the server.

  • server_location (ServerNetworkLocation) –

  • network_configuration (Optional[ServerNetworkConfiguration]) –

Return type



An object encapsulating all the information needed to connect to the server, to be passed to a Scanner in order to run scan commands against the server.


ServerConnectivityError – If the server was not reachable or an SSL/TLS handshake could not be completed.

class sslyze.ServerConnectivityInfo(server_location, network_configuration, tls_probing_result)

All the settings (hostname, port, SSL version, etc.) needed to successfully connect to a given SSL/TLS server.

Such objects should never be instantiated directly and are instead returned by ServerConnectivityTester.perform() when connectivity testing was successful.


The minimum information needed to establish a connection to the server.


Some additional configuration regarding how to connect to the server.


Some additional details about the server’s TLS configuration.

  • server_location (ServerNetworkLocation) –

  • network_configuration (ServerNetworkConfiguration) –

  • tls_probing_result (ServerTlsProbingResult) –

server_location: sslyze.server_setting.ServerNetworkLocation
network_configuration: sslyze.server_setting.ServerNetworkConfiguration
tls_probing_result: sslyze.server_connectivity.ServerTlsProbingResult
get_preconfigured_tls_connection(override_tls_version=None, ca_certificates_path=None, should_use_legacy_openssl=None, should_enable_server_name_indication=True)

Get an SSLConnection instance with the right SSL configuration for successfully connecting to the server.

Used by all plugins to connect to the server and run scans.

  • override_tls_version (Optional[TlsVersionEnum]) –

  • ca_certificates_path (Optional[Path]) –

  • should_use_legacy_openssl (Optional[bool]) –

  • should_enable_server_name_indication (bool) –

Return type


Additional settings: StartTLS, SNI, etc.

class sslyze.ServerNetworkConfiguration(tls_server_name_indication, tls_opportunistic_encryption=None, tls_client_auth_credentials=None, xmpp_to_hostname=None, network_timeout=5, network_max_retries=3)

Additional network settings to provide fine-grained control on how to connect to a specific server.


The hostname to set within the Server Name Indication TLS extension.


The protocol wrapped in TLS that the server expects. It allows SSLyze to figure out how to establish a (Start)TLS connection to the server and what kind of “hello” message (SMTP, XMPP, etc.) to send to the server after the handshake was completed. If not supplied, standard TLS will be used.


The client certificate and private key needed to perform mutual authentication with the server. If not supplied, SSLyze will attempt to connect to the server without performing client authentication.


The hostname to set within the to attribute of the XMPP stream. If not supplied, the server’s hostname will be used. Should only be set if the supplied tls_wrapped_protocol is an XMPP protocol.


The timeout (in seconds) to be used when attempting to establish a connection to the server.


The number of retries SSLyze will perform when attempting to establish a connection to the server.

  • tls_server_name_indication (str) –

  • tls_opportunistic_encryption (Optional[ProtocolWithOpportunisticTlsEnum]) –

  • tls_client_auth_credentials (Optional[ClientAuthenticationCredentials]) –

  • xmpp_to_hostname (Optional[str]) –

  • network_timeout (int) –

  • network_max_retries (int) –

class sslyze.ProtocolWithOpportunisticTlsEnum(value)

The list of plaintext protocols supported by SSLyze for opportunistic TLS upgrade (such as STARTTLS).

This allows SSLyze to figure out how to complete an SSL/TLS handshake with the server.

SMTP = 1
XMPP = 2
FTP = 4
POP3 = 5
LDAP = 6
IMAP = 7
RDP = 8
classmethod from_default_port(port)

Given a port number, return the protocol that uses this port number by default.


port (int) –

Return type


Running a scan through a proxy

class sslyze.ServerNetworkLocationViaHttpProxy(hostname, port, http_proxy_settings)

All the information needed to connect to a server by tunneling the traffic through an HTTP proxy.


The server’s hostname.


The server’s TLS port number.


The HTTP proxy configuration to use in order to tunnel the scans through a proxy. The proxy will be responsible for looking up the server’s IP address and connecting to it.

  • hostname (str) –

  • port (int) –

  • http_proxy_settings (HttpProxySettings) –

class sslyze.HttpProxySettings(hostname, port, basic_auth_user=None, basic_auth_password=None)
  • hostname (str) –

  • port (int) –

  • basic_auth_user (Optional[str]) –

  • basic_auth_password (Optional[str]) –

Enabling SSL/TLS client authentication

class sslyze.ClientAuthenticationCredentials(certificate_chain_path, key_path, key_password='', key_type=<OpenSslFileTypeEnum.PEM: 1>)

Everything needed by a client to perform SSL/TLS client authentication with the server.


Path to the file containing the client’s certificate.


Path to the file containing the client’s private key.


The password to decrypt the private key.


The format of the key file.

  • certificate_chain_path (Path) –

  • key_path (Path) –

  • key_password (str) –

  • key_type (OpenSslFileTypeEnum) –

class sslyze.OpenSslFileTypeEnum(value)

Certificate and private key format constants which map to the SSL_FILETYPE_XXX OpenSSL constants.

PEM = 1
ASN1 = 2