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("www.google.com", 443)

    # Do connectivity testing to ensure SSLyze is able to connect
    try:
        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}")
        return
    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.

hostname

The server’s hostname.

Type

str

port

The server’s TLS port number.

Type

int

ip_address

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.

Type

str

Parameters

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

Parameters

  • hostname (str) –

  • port (int) –

Return type

ServerNetworkLocationViaDirectConnection

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.

Parameters

  • server_location (ServerNetworkLocation) –

  • network_configuration (Optional[ServerNetworkConfiguration]) –

Return type

ServerConnectivityInfo

Returns

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.

Raises

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.

server_location

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

Type

sslyze.server_setting.ServerNetworkLocation

network_configuration

Some additional configuration regarding how to connect to the server.

Type

sslyze.server_setting.ServerNetworkConfiguration

tls_probing_result

Some additional details about the server’s TLS configuration.

Type

sslyze.server_connectivity.ServerTlsProbingResult

Parameters

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

Parameters

  • override_tls_version (Optional[TlsVersionEnum]) –

  • ca_certificates_path (Optional[Path]) –

  • should_use_legacy_openssl (Optional[bool]) –

  • should_enable_server_name_indication (bool) –

Return type

SslConnection

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.

tls_server_name_indication

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

Type

str

tls_wrapped_protocol

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.

tls_client_auth_credentials

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.

Type

Optional[sslyze.server_setting.ClientAuthenticationCredentials]

xmpp_to_hostname

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.

Type

Optional[str]

network_timeout

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

Type

int

network_max_retries

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

Type

int

Parameters

  • 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
XMPP_SERVER = 3
FTP = 4
POP3 = 5
LDAP = 6
IMAP = 7
RDP = 8
POSTGRES = 9
classmethod from_default_port(port)

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

Parameters

port (int) –

Return type

Optional[ProtocolWithOpportunisticTlsEnum]

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.

hostname

The server’s hostname.

Type

str

port

The server’s TLS port number.

Type

int

http_proxy_settings

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.

Type

sslyze.server_setting.HttpProxySettings

Parameters

  • hostname (str) –

  • port (int) –

  • http_proxy_settings (HttpProxySettings) –

class sslyze.HttpProxySettings(hostname, port, basic_auth_user=None, basic_auth_password=None)
Parameters

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

certificate_chain_path

Path to the file containing the client’s certificate.

Type

pathlib.Path

key_path

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

Type

pathlib.Path

key_password

The password to decrypt the private key.

Type

str

key_type

The format of the key file.

Type

nassl.ssl_client.OpenSslFileTypeEnum

Parameters

  • 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