Step 1: Testing Connectivity to a Server

Basic Example

Before a server can be scanned, SSLyze must ensure that it is able to reach the server. This is achieved using the ServerConnectivityTester class:

def demo_server_connectivity_tester():
    try:
        server_tester = ServerConnectivityTester(
            hostname='smtp.gmail.com',
            port=587,
            tls_wrapped_protocol=TlsWrappedProtocolEnum.STARTTLS_SMTP
        )
        print(f'\nTesting connectivity with {server_tester.hostname}:{server_tester.port}...')
        server_info = server_tester.perform()
    except ServerConnectivityError as e:
        # Could not establish an SSL connection to the server
        raise RuntimeError(f'Could not connect to {e.server_info.hostname}: {e.error_message}')

    return server_info

If the call to ServerConnectivityTester.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

The ServerConnectivityTester classs provides fine-grained controls regarding how SSLyze should connect to a server. If only a hostname is supplied (like in the example above), default values will be used and SSLyze will assume that the server is an HTTPS server listening on port 443.

Several additional settings can be supplied in order to be more specific about the protocol the SSL/TLS server uses (such as StartTLS) and how to connect to it (for example by supplying an IP address or a client certificate).

The ServerConnectivityTester class

class sslyze.server_connectivity_tester.ServerConnectivityTester(hostname, port=None, ip_address=None, tls_wrapped_protocol=<TlsWrappedProtocolEnum.PLAIN_TLS: 1>, tls_server_name_indication=None, xmpp_to_hostname=None, client_auth_credentials=None, http_tunneling_settings=None)
__init__(hostname, port=None, ip_address=None, tls_wrapped_protocol=<TlsWrappedProtocolEnum.PLAIN_TLS: 1>, tls_server_name_indication=None, xmpp_to_hostname=None, client_auth_credentials=None, http_tunneling_settings=None)

Constructor to specify how to connect to a given SSL/TLS server to be scanned.

Most arguments are optional but can be supplied in order to be more specific about the server’s configuration.

After initialization, the perform() method must be called next to ensure that the server is actually reachable. The ServerConnectivityInfo returned by perform() can then be passed to a SynchronousScanner or ConcurrentScanner in order to run scan commands on the server.

Parameters:
  • hostname (str) – The server’s hostname.
  • port (Optional[int]) – The server’s TLS port number. If not supplied, the default port number for the specified tls_wrapped_protocol will be used.
  • ip_address (Optional[str]) – The server’s IP address. If not supplied, a DNS lookup for the specified hostname will be performed. If http_tunneling_settings is specified, ip_address cannot be supplied as the HTTP proxy will be responsible for looking up and connecting to the server to be scanned.
  • tls_wrapped_protocol (TlsWrappedProtocolEnum) – 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_server_name_indication (Optional[str]) – The hostname to set within the Server Name Indication TLS extension. If not supplied, the specified hostname will be used.
  • xmpp_to_hostname (Optional[str]) – The hostname to set within the to attribute of the XMPP stream. If not supplied, the specified hostname will be used. Should only be set if the supplied tls_wrapped_protocol is an XMPP protocol.
  • client_auth_credentials (Optional[ClientAuthenticationCredentials]) – 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 mutual authentication.
  • http_tunneling_settings (Optional[HttpConnectTunnelingSettings]) – The HTTP proxy configuration to use in order to tunnel the scans through a proxy. If not supplied, sslyze will run the scans by directly connecting to the server.
Raises:
  • ValueError – If xmpp_to_hostname was specified for a non-XMPP protocol.
  • ValueError – If both ip_address and http_tunneling_settings were supplied.
Return type:

None

perform(network_timeout=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:network_timeout (Optional[int]) – Network timeout value in seconds passed to the underlying socket.
Return type:ServerConnectivityInfo
Returns:An object encapsulating all the information needed to connect to the server, to be passed to a SynchronousScanner or ConcurrentScanner in order to run scan commands on the server.
Raises:ServerConnectivityError – If the server was not reachable or an SSL/TLS handshake could not be completed.
class sslyze.server_connectivity_tester.ServerConnectivityError(server_info, error_message)

Generic error for when SSLyze was unable to successfully complete connectivity testing with the server.

server_info

The connectivity tester that failed, containing all the server’s information (hostname, port, etc.) that was used to test connectivity.

error_message

The error that was returned.

class sslyze.server_connectivity_tester.ServerRejectedConnection(server_info)
class sslyze.server_connectivity_tester.ConnectionToServerTimedOut(server_info)
class sslyze.server_connectivity_tester.ServerHostnameCouldNotBeResolved(server_info)
class sslyze.server_connectivity_tester.ServerTlsConfigurationNotSuportedError(server_info, error_message)

The server was online but SSLyze was unable to find one TLS version and cipher suite supported by the server.

This should never happen unless the server has a very exotic TLS configuration (such as supporting a very small set of niche cipher suites).

class sslyze.server_connectivity_tester.ProxyConnectivityError(server_info, error_message)

The proxy was offline, or timed out, or rejected the connection while doing connectivity testing.

Enabling StartTLS and other supported protocols

class sslyze.ssl_settings.TlsWrappedProtocolEnum

The list of TLS-wrapped protocols supported by SSLyze.

SSLyze uses this to figure out how to establish an SSL/TLS connection to the server and what kind of “hello” message to send after the handshake was completed.

PLAIN_TLS = 1
HTTPS = 2
STARTTLS_SMTP = 3
STARTTLS_XMPP = 4
STARTTLS_XMPP_SERVER = 5
STARTTLS_FTP = 6
STARTTLS_POP3 = 7
STARTTLS_LDAP = 8
STARTTLS_IMAP = 9
STARTTLS_RDP = 10
STARTTLS_POSTGRES = 11

Running scan commands through a proxy

class sslyze.ssl_settings.HttpConnectTunnelingSettings(hostname, port, basic_auth_user=None, basic_auth_password=None)

Container for specifying the settings to tunnel all traffic through an HTTP Connect Proxy.

__init__(hostname, port, basic_auth_user=None, basic_auth_password=None)
Parameters:
  • hostname (str) – The proxy’s hostname.
  • port (int) – The proxy’s port.
  • basic_auth_user (Optional[str]) – The username to use if the proxy requires Basic Authentication.
  • basic_auth_password (Optional[str]) – The password to use if the proxy requires Basic Authentication.
Return type:

None

Enabling client authentication

class sslyze.ssl_settings.ClientAuthenticationCredentials(client_certificate_chain_path, client_key_path, client_key_type=<OpenSslFileTypeEnum.PEM: 1>, client_key_password='')

Container for specifying the settings to perform SSL/TLS client authentication with the server.

__init__(client_certificate_chain_path, client_key_path, client_key_type=<OpenSslFileTypeEnum.PEM: 1>, client_key_password='')
Parameters:
  • client_certificate_chain_path (str) – Path to the file containing the client’s certificate.
  • client_key_path (str) – Path to the file containing the client’s private key.
  • client_key_type (OpenSslFileTypeEnum) – The format of the key file.
  • client_key_password (str) – The password to decrypt the private key.
Return type:

None

class nassl.ssl_client.OpenSslFileTypeEnum

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

PEM = 1
ASN1 = 2

The ServerConnectivityInfo class

class sslyze.server_connectivity_info.ServerConnectivityInfo(hostname, port, ip_address, tls_wrapped_protocol, tls_server_name_indication, xmpp_to_hostname, client_auth_credentials, http_tunneling_settings, highest_ssl_version_supported, openssl_cipher_string_supported, client_auth_requirement)

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

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

hostname

The server’s hostname.

Type:str
port

The server’s TLS port number.

Type:int
ip_address

The server’s IP address. None if we are connecting through a proxy.

Type:Optional[str]
tls_wrapped_protocol

The protocol wrapped in TLS (HTTP, XMPP, etc.) that the server expects.

Type:TlsWrappedProtocolEnum
tls_server_name_indication

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

Type:str
xmpp_to_hostname

The hostname to set within the to attribute of the XMPP stream; only used if the tls_wrapped_protocol is an XMPP protocol.

Type:Optional[str]
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 mutual authentication.

Type:Optional[ClientAuthenticationCredentials]
http_tunneling_settings

The HTTP proxy configuration to use in order to tunnel the scans through a proxy. If not supplied, SSLyze will run the scans by directly connecting to the server.

Type:Optional[HttpConnectTunnelingSettings]
highest_ssl_version_supported

The highest version of SSL/TLS supported by the server, as detected when doing connectivity testing.

Type:OpenSslVersionEnum
openssl_cipher_string_supported

An OpenSSL cipher string that contains at least one cipher suite supported by the server, as detected when doing connectivity testing.

Type:str
client_auth_requirement

Whether the support requires client authentication.

Type:ClientAuthenticationServerConfigurationEnum
get_preconfigured_ssl_connection(override_ssl_version=None, ssl_verify_locations=None, should_use_legacy_openssl=None)

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.

Return type:SslConnection