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