Appendix: Available Scan Commands¶
Every type of scan that SSLyze can run against a server (supported cippher suites, session renegotiation, etc.) is represented by a ScanCommand, which is implemented using a plugin system. Each ScanCommand will return a ScanResult when run against a server.
This page lists all the ScanCommands and corresponding ScanResults available in the current release of SSLyze.
CertificateInfoPlugin¶
-
class
sslyze.plugins.certificate_info_plugin.
CertificateInfoScanCommand
(ca_file=None)¶ Verify the validity of the server(s) certificate(s) against various trust stores (Mozilla, Apple, etc.), and check for OCSP stapling support.
-
__init__
(ca_file=None)¶ - Parameters
ca_file (
Optional
[str
]) – The path to a custom trust store file to use for certificate validation. The file should contain PEM-formatted root certificates.- Return type
None
-
-
class
sslyze.plugins.certificate_info_plugin.
CertificateInfoScanResult
(server_info, scan_command, received_certificate_chain, path_validation_result_list, path_validation_error_list, ocsp_response)¶ The result of running a CertificateInfoScanCommand on a specific server.
Any certificate available as an attribute is parsed using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/reference/#x-509-certificate-object
-
received_certificate_chain
¶ The certificate chain sent by the server; index 0 is the leaf certificate.
- Type
List[cryptography.x509.Certificate]
-
verified_certificate_chain
¶ (Optional[List[cryptography.x509.Certificate]]): The verified certificate chain returned by OpenSSL for one of the trust stores packaged within SSLyze. Will be None if the validation failed with all of the available trust stores (Apple, Mozilla, etc.). This is essentially a shortcut to path_validation_result_list[0].verified_certificate_chain.
-
path_validation_result_list
¶ The result of validating the server’s certificate chain using each trust store that is packaged with SSLyze (Mozilla, Apple, etc.). If for a given trust store, the validation was successful, the verified certificate chain built by OpenSSL can be retrieved from the PathValidationResult.
- Type
List[PathValidationResult]
-
path_validation_error_list
¶ The list of attempts at validating the server’s certificate chain path that triggered an unexpected error.
- Type
List[PathValidationError]
-
leaf_certificate_subject_matches_hostname
¶ - Type
bool
-
leaf_certificate_is_ev
¶ True if the leaf certificate is Extended Validation according to Mozilla.
- Type
bool
-
leaf_certificate_has_must_staple_extension
¶ - Type
bool
-
leaf_certificate_signed_certificate_timestamps_count
¶ The number of Signed Certificate Timestamps (SCTs) for Certificate Transparency embedded in the leaf certificate. None if the version of OpenSSL installed on the system is too old to be able to parse the SCT extension.
- Type
Optional[int]
-
received_chain_has_valid_order
¶ - Type
bool
-
received_chain_contains_anchor_certificate
¶ True if the server included the anchor/root certificate in the chain it sends back to clients. None if the verified chain could not be built.
- Type
Optional[bool]
-
verified_chain_has_sha1_signature
¶ True if any of the leaf or intermediate certificates are signed using the SHA-1 algorithm. None if the verified chain could not be built.
- Type
Optional[bool]
-
verified_chain_has_legacy_symantec_anchor
¶ True if the certificate chain contains a distrusted Symantec anchor (https://blog.qualys.com/ssllabs/2017/09/26/google-and-mozilla-deprecating-existing-symantec-certificates). None if the verified chain could not be built.
- Type
Optional[bool]
-
ocsp_response
¶ The OCSP response returned by the server. None if no response was sent by the server.
- Type
Optional[Dict[Text, Any]]
-
ocsp_response_status
¶ The status of the OCSP response returned by the server. None if no response was sent by the server.
- Type
Optional[OcspResponseStatusEnum]
-
ocsp_response_is_trusted
¶ True if the OCSP response is trusted using the Mozilla trust store. None if no OCSP response was sent by the server.
- Type
Optional[bool]
-
Additional helper classes¶
-
class
sslyze.plugins.certificate_info_plugin.
PathValidationResult
(trust_store, verified_chain, verify_string)¶ The result of trying to validate a server’s certificate chain using a specific trust store.
-
trust_store
¶ The trust store used for validation.
- Type
-
verified_certificate_chain
¶ (Optional[List[cryptography.x509.Certificate]]): The verified certificate chain returned by OpenSSL. Index 0 is the leaf certificate and the last element is the anchor/CA certificate from the trust store. Will be None if the validation failed or the verified chain could not be built. Each certificate is parsed using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/reference/#x-509-certificate-object.
-
verify_string
¶ The result string returned by OpenSSL’s validation function.
- Type
str
-
was_validation_successful
¶ Whether the certificate chain is trusted when using supplied the trust_store.
- Type
bool
-
-
class
sslyze.plugins.certificate_info_plugin.
PathValidationError
(trust_store, exception)¶ An exception was raised while trying to validate a server’s certificate using a specific trust store; should never happen.
-
trust_store
¶ The trust store used for validation.
- Type
-
error_message
¶ The exception that was raised formatted as a string.
- Type
Text
-
-
class
sslyze.plugins.certificate_info_plugin.
OcspResponseStatusEnum
¶ An enumeration.
-
SUCCESSFUL
= 0¶
-
MALFORMED_REQUEST
= 1¶
-
INTERNAL_ERROR
= 2¶
-
TRY_LATER
= 3¶
-
SIG_REQUIRED
= 5¶
-
UNAUTHORIZED
= 6¶
-
-
class
sslyze.plugins.certificate_info_plugin.
SymantecDistrustTimelineEnum
¶ An enumeration.
-
MARCH_2018
= 1¶
-
SEPTEMBER_2018
= 2¶
-
-
class
sslyze.plugins.certificate_info_plugin.
CertificateChainDeploymentAnalyzer
(server_hostname, received_chain, verified_chain, trust_store_used_to_build_verified_chain, received_ocsp_response)¶ Utility class for analyzing a certificate chain as deployed on a specific server.
Useful for checking a server’s certificate chain without having to use the CertificateInfoPlugin.
-
perform
()¶ Run the analysis.
- Return type
-
-
class
sslyze.plugins.certificate_info_plugin.
CertificateChainDeploymentAnalysisResult
(leaf_certificate_subject_matches_hostname, leaf_certificate_has_must_staple_extension, leaf_certificate_is_ev, leaf_certificate_signed_certificate_timestamps_count, received_chain_contains_anchor_certificate, received_chain_has_valid_order, verified_chain_has_sha1_signature, verified_chain_has_legacy_symantec_anchor, ocsp_response_is_trusted, ocsp_response_status)¶ CertificateChainDeploymentAnalysisResult(leaf_certificate_subject_matches_hostname:bool, leaf_certificate_has_must_staple_extension:bool, leaf_certificate_is_ev:bool, leaf_certificate_signed_certificate_timestamps_count:Union[int, NoneType], received_chain_contains_anchor_certificate:Union[bool, NoneType], received_chain_has_valid_order:bool, verified_chain_has_sha1_signature:Union[bool, NoneType], verified_chain_has_legacy_symantec_anchor:Union[bool, NoneType], ocsp_response_is_trusted:Union[bool, NoneType], ocsp_response_status:Union[nassl.ocsp_response.OcspResponseStatusEnum, NoneType])
-
class
sslyze.plugins.utils.trust_store.trust_store.
TrustStore
(path, name, version, ev_oids=None)¶ A set of root certificates to be used for certificate validation.
By default, SSLyze packages the following trust stores: Mozilla, Microsoft, Apple, Android and Java.
-
path
¶ The path to the PEM-formatted file containing the root certificates.
- Type
Path
-
name
¶ The human-readable name of the trust store (such as “Mozilla”).
- Type
str
-
version
¶ The human-readable version or date of the trust store (such as “09/2016”).
- Type
str
-
Updating the trust stores¶
-
class
sslyze.plugins.utils.trust_store.trust_store_repository.
TrustStoresRepository
(repository_path)¶ The list of default trust stores used by SSLyze for certificate validation.
-
classmethod
update_default
()¶ Update the default trust stores used by SSLyze.
The latest stores will be downloaded from https://github.com/nabla-c0d3/trust_stores_observatory.
- Return type
-
classmethod
OpenSslCipherSuitesPlugin¶
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Sslv20ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the SSL 2.0 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Sslv30ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the SSL 3.0 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Tlsv10ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the TLS 1.0 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Tlsv11ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the TLS 1.1 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Tlsv12ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the TLS 1.2 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
Tlsv13ScanCommand
(http_get=False, hide_rejected_ciphers=False)¶ List the TLS 1.3 OpenSSL cipher suites supported by the server(s).
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
CipherSuiteScanResult
(server_info, scan_command, preferred_cipher, accepted_cipher_list, rejected_cipher_list, errored_cipher_list)¶ The result of running a CipherSuiteScanCommand on a specific server.
-
accepted_cipher_list
¶ The list of cipher suites supported supported by both SSLyze and the server.
- Type
List[AcceptedCipherSuite]
-
rejected_cipher_list
¶ The list of cipher suites supported by SSLyze that were rejected by the server.
- Type
List[RejectedCipherSuite]
-
errored_cipher_list
¶ The list of cipher suites supported by SSLyze that triggered an unexpected error during the TLS handshake with the server.
- Type
List[ErroredCipherSuite]
-
preferred_cipher
¶ The server’s preferred cipher suite among all the cipher suites supported by SSLyze. None if the server follows the client’s preference or if none of SSLyze’s cipher suites are supported by the server.
- Type
Optional[AcceptedCipherSuite]
-
Additional helper classes¶
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
AcceptedCipherSuite
(openssl_name, ssl_version, key_size, post_handshake_response=None)¶ An SSL cipher suite the server accepted.
-
name
¶ The cipher suite’s RFC name.
- Type
str
-
openssl_name
¶ The cipher suite’s OpenSSL name.
- Type
str
-
ssl_version
¶ The cipher suite’s corresponding SSL/TLS version.
- Type
OpenSslVersionEnum
-
is_anonymous
¶ True if the cipher suite is an anonymous cipher suite (ie. no server authentication).
- Type
bool
-
key_size
¶ The key size of the cipher suite’s algorithm in bits. None if the key size could not be looked up for this cipher suite.
- Type
Optional[int]
-
post_handshake_response
¶ The server’s response after completing the SSL/TLS handshake and sending a request, based on the TlsWrappedProtocolEnum set for this server. For example, this will contain an HTTP response when scanning an HTTPS server with TlsWrappedProtocolEnum.HTTPS as the tls_wrapped_protocol.
- Type
Optional[str]
-
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
RejectedCipherSuite
(openssl_name, ssl_version, handshake_error_message)¶ An SSL cipher suite the server explicitly rejected.
-
name
¶ The cipher suite’s RFC name.
- Type
str
-
openssl_name
¶ The cipher suite’s OpenSSL name.
- Type
str
-
ssl_version
¶ The cipher suite’s corresponding SSL/TLS version.
- Type
OpenSslVersionEnum
-
is_anonymous
¶ True if the cipher suite is an anonymous cipher suite (ie. no server authentication).
- Type
bool
-
handshake_error_message
¶ The SSL/TLS error returned by the server to close the handshake.
- Type
str
-
-
class
sslyze.plugins.openssl_cipher_suites_plugin.
ErroredCipherSuite
(openssl_name, ssl_version, exception)¶ An SSL cipher suite that triggered an unexpected error during the SSL handshake with the server.
-
name
¶ The cipher suite’s RFC name.
- Type
Text
-
openssl_name
¶ The cipher suite’s OpenSSL name.
- Type
str
-
ssl_version
¶ The cipher suite’s corresponding SSL/TLS version.
- Type
OpenSslVersionEnum
-
is_anonymous
¶ True if the cipher suite is an anonymous cipher suite (ie. no server authentication).
- Type
bool
-
error_message
¶ The text-formatted exception that was raised during the handshake.
- Type
str
-
CompressionPlugin¶
-
class
sslyze.plugins.compression_plugin.
CompressionScanCommand
¶ Test the server(s) for Zlib compression support.
-
class
sslyze.plugins.compression_plugin.
CompressionScanResult
(server_info, scan_command, compression_name)¶ The result of running a CompressionScanCommand on a specific server.
-
compression_name
¶ The name of the compression algorithm supported by the server. None if compression is not supported by the server.
- Type
str
-
FallbackScsvPlugin¶
-
class
sslyze.plugins.fallback_scsv_plugin.
FallbackScsvScanCommand
¶ Test the server(s) for support of the TLS_FALLBACK_SCSV cipher suite which prevents downgrade attacks.
-
class
sslyze.plugins.fallback_scsv_plugin.
FallbackScsvScanResult
(server_info, scan_command, supports_fallback_scsv)¶ The result of running a FallbackScsvScanCommand on a specific server.
-
supports_fallback_scsv
¶ True if the server supports the TLS_FALLBACK_SCSV mechanism to block downgrade attacks.
- Type
bool
-
HeartbleedPlugin¶
-
class
sslyze.plugins.heartbleed_plugin.
HeartbleedScanCommand
¶ Test the server(s) for the OpenSSL Heartbleed vulnerability.
HttpHeadersScanPlugin¶
-
class
sslyze.plugins.http_headers_plugin.
HttpHeadersScanCommand
¶ Check for the HTTP Strict Transport Security (HSTS) and HTTP Public Key Pinning (HPKP) HTTP headers within the response sent back by the server(s). Also compute the HPKP pins for the server(s)’ current certificate chain.
-
class
sslyze.plugins.http_headers_plugin.
HttpHeadersScanResult
(server_info, scan_command, strict_transport_security_header, public_key_pins_header, public_key_pins_report_only_header, expect_ct_header, verified_chain)¶ The result of running a HttpHeadersScanCommand on a specific server.
Each HTTP header described below will be None if the server did not return it.
-
strict_transport_security_header
¶ The Strict-Transport-Security header returned by the server.
- Type
Optional[StrictTransportSecurityHeader]
-
public_key_pins_header
¶ The Public-Key-Pins header returned by the server.
- Type
Optional[PublicKeyPinsHeader]
-
public_key_pins_report_only_header
¶ The Public-Key-Pins-Report-Only header returned by the server.
- Type
Optional[PublicKeyPinsReportOnlyHeader]
-
expect_ct_header
¶ The Expect-CT header returned by the server.
- Type
Optional[ExpectCtHeader]
-
is_valid_pin_configured
¶ True if at least one of the configured pins was found in the server’s verified certificate chain. None if the verified chain could not be built or no HPKP header was returned.
- Type
Optional[bool]
-
is_backup_pin_configured
¶ True if if at least one of the configured pins was NOT found in the server’s verified certificate chain. None if the verified chain could not be built or no HPKP header was returned.
- Type
Optional[bool]
-
verified_certificate_chain
¶ The verified certificate chain; index 0 is the leaf certificate and the last element is the anchor/CA certificate from the Mozilla trust store. Will be None if validation failed or the verified chain could not be built. The HPKP pin for each certificate is available in the certificate’s hpkp_pin attribute. Each certificate is parsed using the cryptography module; documentation is available at https://cryptography.io/en/latest/x509/reference/#x-509-certificate-object.
- Type
Optional[List[cryptography.x509.Certificate]]
-
Additional helper classes¶
OpenSslCcsInjectionPlugin¶
-
class
sslyze.plugins.openssl_ccs_injection_plugin.
OpenSslCcsInjectionScanCommand
¶ Test the server(s) for the OpenSSL CCS injection vulnerability (CVE-2014-0224).
-
class
sslyze.plugins.openssl_ccs_injection_plugin.
OpenSslCcsInjectionScanResult
(server_info, scan_command, is_vulnerable_to_ccs_injection)¶ The result of running an OpenSslCcsInjectionScanCommand on a specific server.
-
is_vulnerable_to_ccs_injection
¶ True if the server is vulnerable to OpenSSL’s CCS injection issue.
- Type
bool
-
SessionRenegotiationPlugin¶
-
class
sslyze.plugins.session_renegotiation_plugin.
SessionRenegotiationScanCommand
¶ Test the server(s) for client-initiated renegotiation and secure renegotiation support.
-
class
sslyze.plugins.session_renegotiation_plugin.
SessionRenegotiationScanResult
(server_info, scan_command, accepts_client_renegotiation, supports_secure_renegotiation)¶ The result of running a SessionRenegotiationScanCommand on a specific server.
-
accepts_client_renegotiation
¶ True if the server honors client-initiated renegotiation attempts.
- Type
bool
-
supports_secure_renegotiation
¶ True if the server supports secure renegotiation.
- Type
bool
-
SessionResumptionPlugin¶
-
class
sslyze.plugins.session_resumption_plugin.
SessionResumptionSupportScanCommand
¶ Test the server(s) for session resumption support using session IDs and TLS session tickets (RFC 5077).
-
class
sslyze.plugins.session_resumption_plugin.
SessionResumptionSupportScanResult
(server_info, scan_command, attempted_resum_nb, successful_resum_nb, errored_resumptions_list, is_ticket_resumption_supported, ticket_resumption_failed_reason=None, ticket_resumption_exception=None)¶ The result of running SessionResumptionRateScanCommand on a specific server.
-
attempted_resumptions_nb
¶ The total number of session ID resumptions that were attempted, which is 5.
- Type
int
-
successful_resumptions_nb
¶ The number of session ID resumptions that were successful.
- Type
int
-
failed_resumptions_nb
¶ The number of session ID resumptions that failed.
- Type
int
-
errored_resumptions_list
¶ A list of unexpected errors triggered while trying to perform session ID resumption with the server (should always be empty).
- Type
Optional[List[(Text)]
-
is_ticket_resumption_supported
¶ True if the server support TLS ticket resumption.
- Type
bool
-
ticket_resumption_failed_reason
¶ A message explaining why TLS ticket resumption failed.
- Type
str
-
ticket_resumption_exception
¶ An unexpected error that was raised while trying to perform ticket resumption (should never happen).
- Type
Optional[str]
-
-
class
sslyze.plugins.session_resumption_plugin.
SessionResumptionRateScanCommand
¶ Perform 100 session ID resumptions with the server(s), in order to estimate the rate for successful resumptions.
-
class
sslyze.plugins.session_resumption_plugin.
SessionResumptionRateScanResult
(server_info, scan_command, attempted_resum_nb, successful_resum_nb, errored_resumptions_list)¶ The result of running SessionResumptionRateScanCommand on a specific server.
-
attempted_resumptions_nb
¶ The total number of session ID resumptions that were attempted, which is 100.
- Type
int
-
successful_resumptions_nb
¶ The number of session ID resumptions that were successful.
- Type
int
-
failed_resumptions_nb
¶ The number of session ID resumptions that failed.
- Type
int
-
errored_resumptions_list
¶ A list of unexpected errors triggered while trying to perform session ID resumption with the server (should always be empty).
- Type
Optional[List[(str)]
-
RobotPlugin¶
-
class
sslyze.plugins.robot_plugin.
RobotScanCommand
¶ Test the server(s) for the Return Of Bleichenbacher’s Oracle Threat vulnerability.
-
class
sslyze.plugins.robot_plugin.
RobotScanResultEnum
¶ An enum to provide the result of running a RobotScanCommand.
-
VULNERABLE_WEAK_ORACLE
= 1¶ The server is vulnerable but the attack would take too long
-
VULNERABLE_STRONG_ORACLE
= 2¶ The server is vulnerable and real attacks are feasible
-
NOT_VULNERABLE_NO_ORACLE
= 3¶ The server supports RSA cipher suites but does not act as an oracle
-
NOT_VULNERABLE_RSA_NOT_SUPPORTED
= 4¶ The server does not supports RSA cipher suites
-
UNKNOWN_INCONSISTENT_RESULTS
= 5¶ Could not determine whether the server is vulnerable or not
-