Step 1: Testing Connectivity to a Server¶
Contents
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
) –
-