check_ssl_cert(1)

NAME

check_ssl_cert - checks the validity of X.509 certificates

SYNOPSIS

check_ssl_cert -H host [OPTIONS]
check_ssl_cert -f file [OPTIONS]

DESCRIPTION

check_ssl_cert A shell script (that can be used as a Nagios/Icinga plugin) to check an SSL/TLS connection

ARGUMENTS

-f,--file file

Local file path or URI. With -f you can not only pass a x509 certificate file but also a certificate revocation list (CRL) to check the validity period or a Java KeyStore file

-H,--host host

server

OPTIONS

-A,--noauth

Ignore authority warnings (expiration only)

--all

Enable all the possible optional checks at the maximum level

--all-local

Enable all the possible optional checks at the maximum level (without SSL-Labs)

--allow-empty-san

Allow certificates without Subject Alternative Names (SANs)

-C,--clientcert path

Use client certificate to authenticate

-c,--critical days

Minimum number of days a certificate has to be valid to issue a critical status. Can be a floating point number, e.g., 0.5. Default: 15

--check-chain

The certificate chain cannot contain double or root certificates

--check-ciphers grade

Check the offered ciphers

--check-ciphers-warnings

Critical if nmap reports a warning for an offered cipher

--check-http-headers

Check the HTTP headers for best practices

--check-ssl-labs-warn grade

SSL Labs grade on which to warn

--clientpass phrase

Set passphrase for client certificate.

--configuration file

Read options from the specified file

--crl

Check revocation via CRL (requires --rootcert-file)

--curl-bin path

Path of the curl binary to be used

--custom-http-header string

Custom HTTP header sent when getting the cert example: 'X-Check-Ssl-Cert: Foobar=1'

--dane

Verify that valid DANE records exist (since OpenSSL 1.1.0)

--dane 211

Verify that a valid DANE-TA(2) SPKI(1) SHA2-256(1) TLSA record exists

--dane 301

Verify that a valid DANE-EE(3) Cert(0) SHA2-256(1) TLSA record exists

--dane 302

Verify that a valid DANE-EE(3) Cert(0) SHA2-512(2) TLSA record exists

--dane 311

Verify that a valid DANE-EE(3) SPKI(1) SHA2-256(1) TLSA record exists

--dane 312

Verify that a valid DANE-EE(3) SPKI(1) SHA2-512(1) TLSA record exists

--date path

Path of the date binary to be used

-d,--debug

Produce debugging output (can be specified more than once)

--debug-cert

Store the retrieved certificates in the current directory

--debug-file file

Write the debug messages to file

--debug-headers

Store the retrieved HTLM headers in the headers.txt file

--debug-time

Write timing information in the debugging output

--default-format

Print the default output format and exit

--dig-bin path

Path of the dig binary to be used

--do-not-resolve

Do not check if the host can be resolved

--dtls

Use the DTLS protocol

--dtls1

Use the DTLS protocol 1.0

--dtls1_2

Use the DTLS protocol 1.2

-e,--email address

Pattern (extended regular expression) to match the email address contained in the certificate. You can specify different addresses separated by a pipe (e.g., 'addr1|addr2')

--ecdsa

Signature algorithm selection: force ECDSA certificate

--element number

Check up to the N cert element from the beginning of the chain

--file-bin path

Path of the file binary to be used

--fingerprint hash

Pattern to match the fingerprint

--fingerprint-alg algorithm

Algorithm for fingerprint. Default sha1

--first-element-only

Verify just the first cert element, not the whole chain

--force-dconv-date

Force the usage of dconv for date computations

--force-perl-date

Force the usage of Perl for date computations

--format FORMAT

Format output template on success, for example: '%SHORTNAME% OK %CN% from %CA_ISSUER_MATCHED%'
List of possible variables:
- %CA_ISSUER_MATCHED%
- %CHECKEDNAMES%
- %CN%
- %DATE%
- %DAYS_VALID%
- %DYSPLAY_CN%
- %HOST%
- %OCSP_EXPIRES_IN_HOURS%
- %OPENSSL_COMMAND%
- %PORT%
- %SELFSIGNEDCERT%
- %SHORTNAME%
- %SIGALGO%
- %SSL_LABS_HOST_GRADE%
See --default-format for the default

--grep-bin path

Path of the grep binary to be used

-h,--help,-?

This help message

--http-headers-path path

The path to be used to fetch HTTP headers

--http-use-get

Use GET instead of HEAD (default) for the HTTP related checks

-i,--issuer issuer

Pattern (extended regular expression) to match the issuer of the certificate. You can specify different issuers separated by a pipe (e.g., 'issuer1|issuer2')

--ignore-altnames

Ignore alternative names when matching pattern specified in -n (or the host name)

--ignore-connection-problems [state]

In case of connection problems returns OK or the optional state

--ignore-crl

Ignore CRLs

--ignore-dh

Ignore too small DH keys

--ignore-exp

Ignore expiration date

--ignore-http-headers

Ignore checks on HTTP headers with --all and --all-local

--ignore-host-cn

Do not complain if the CN does not match the host name

--ignore-incomplete-chain

Do not check chain integrity

--ignore-maximum-validity

Ignore the certificate maximum validity

--ignore-ocsp

Do not check revocation with OCSP

--ignore-ocsp-errors

Continue if the OCSP status cannot be checked

--ignore-ocsp-timeout

Ignore OCSP result when timeout occurs while checking

--ignore-sct

Do not check for signed certificate timestamps (SCT)

--ignore-sig-alg

Do not check if the certificate was signed with SHA1 or MD5

--ignore-ssl-labs-cache

Force a new check by SSL Labs (see -L)

--ignore-ssl-labs-errors

Ignore errors if SSL Labs is not accessible or times out

--ignore-tls-renegotiation

Ignore the TLS renegotiation check

--ignore-unexpected-eof

Ignore unclean TLS shutdowns

--inetproto protocol

Force IP version 4 or 6

--info

Print certificate information

--init-host-cache

Initialize the host cache

--issuer-cert-cache dir

Directory where to store issuer certificates cache

--jks-alias alias

Alias name of the Java KeyStore entry (requires --file)

-K,--clientkey path

Use client certificate key to authenticate

-L,--check-ssl-labs grade

SSL Labs assessment (please check https://www.ssllabs.com/about/terms.html). Critical if the grade is lower than specified.

--long-output list

Append the specified comma separated (no spaces) list of attributes to the plugin output on additional lines. Valid attributes are: enddate, startdate, subject, issuer, modulus, serial, hash, email, ocsp_uri and fingerprint. 'all' will include all the available attributes.

-m,--match name

Pattern to match the CN or AltName (can be specified multiple times)

--maximum-validity [days]

The maximum validity of the certificate must not exceed 'days' (default 397). This check is automatic for HTTPS

--nmap-bin path

Path of the nmap binary to be used

--nmap-with-proxy

Allow nmap to be used with a proxy

--no-perf

Do not show performance data

--no-proxy

Ignore the http_proxy and https_proxy environment variables

--no-proxy-curl

Ignore the http_proxy and https_proxy environment variables for curl

--no-proxy-s_client

Ignore the http_proxy and https_proxy environment variables for openssl s_client

--no-ssl2

Disable SSL version 2

--no-ssl3

Disable SSL version 3

--no-tls1

Disable TLS version 1

--no-tls1_1

Disable TLS version 1.1

--no-tls1_3

Disable TLS version 1.3

--no-tls1_2

Disable TLS version 1.2

--not-issued-by issuer

Check that the issuer of the certificate does not match the given pattern

--not-valid-longer-than days

Critical if the certificate validity is longer than the specified period

-o,--org org

Pattern to match the organization of the certificate

--ocsp-critical hours

Minimum number of hours an OCSP response has to be valid to issue a critical status

--ocsp-warning hours

Minimum number of hours an OCSP response has to be valid to issue a warning status

--openssl path

Path of the openssl binary to be used

-p,--port port

TCP port (default 443)

--precision digits

Number of decimal places for durations: defaults to 0 if critical or warning are integers, 2 otherwise

-P,--protocol protocol

Use the specific protocol: dns, ftp, ftps, http, https (default), h2 (HTTP/2), h3 (HTTP/3), imap, imaps, irc, ircs, ldap, ldaps, mqtts, mysql, pop3, pop3s, postgres, sieve, sips, smtp, smtps, tds, xmpp, xmpp-server. ftp, imap, irc, ldap, pop3, postgres, sieve, smtp: switch to TLS using StartTLS. These protocols switch to TLS using StartTLS: ftp, imap, irc, ldap, mysql, pop3, smtp.

--path path

Set the PATH variable to 'path'

--password source

Password source for a local certificate, see the PASS PHRASE ARGUMENTS section openssl(1)

--prometheus

Generate Prometheus/OpenMetrics output

--proxy proxy

Set http_proxy and the s_client -proxy option

--python-bin path

Path of the python binary to be used

--quic

Use QUIC

-q,--quiet

Do not produce any output

-r,--rootcert cert

Root certificate or directory to be used for certificate validation (passed to openssl's -CAfile or -CApath)

--require-client-cert [list]

The server must accept a client certificate. 'list' is an optional comma separated list of expected client certificate CAs

--require-dnssec

Require DNSSEC

--require-http-header header

Require the specified HTTP header (e.g., strict-transport-security)

--require-no-http-header header

Require the absence of the specified HTTP header (e.g., X-Powered-By)

--require-no-ssl2

Critical if SSL version 2 is offered

--require-no-ssl3

Critical if SSL version 3 is offered

--require-no-tls1

Critical if TLS 1 is offered

--require-no-tls1_1

Critical if TLS 1.1 is offered

--require-no-tls1_2

Critical if TLS 1.2 is offered

--require-ocsp-stapling

Require OCSP stapling

--require-purpose usage

Require the specified key usage (can be specified more then once)

--require-purpose-critical

The key usage must be critical

--require-security-header header

Require the specified HTTP security header (e.g., X-Frame-Options)

--require-security-headers

Require all the HTTP security headers:
Content-Security-Policy
Permissions-Policy
Referrer-Policy
strict-transport-security
X-Content-Type-Options
X-Frame-Options

--resolve ip

Provide a custom IP address for the specified host

--resolve-over-http [server]

Resolve the host over HTTP using Google or the specified server

--rootcert-dir dir

Root directory to be used for certificate validation (passed to openssl's -CApath) overrides option -r,--rootcert

--rootcert-file cert

Root certificate to be used for certificate validation (passed to openssl's -CAfile) overrides option -r,--rootcert

--rsa

Signature algorithm selection: force RSA certificate

--security-level number

Set the security level to specified value. See SSL_CTX_set_security_level(3) for a description of what each level means

-s,--selfsigned

Allow self-signed certificates

--serial serialnum

Pattern to match the serial number

--skip-element number

Skip checks on the Nth cert element (can be specified multiple times)

--sni name

Set the TLS SNI (Server Name Indication) extension in the ClientHello message to 'name'

--ssl2

Force SSL version 2

--ssl3

Force SSL version 3

-t,--timeout seconds

Timeout after the specified time (defaults to 120 seconds)

--temp dir

Directory where to store the temporary files

--terse

Terse output (also see --verbose)

--tls1

Force TLS version 1

--tls1_1

Force TLS version 1.1

--tls1_2

Force TLS version 1.2

--tls1_3

Force TLS version 1.3

-u,--url URL

HTTP request URL

--user-agent string

User agent that shall be used for HTTPS connections

-v,--verbose

Verbose output (can be specified more than once)

-V,--version

Version

-w,--warning days

Minimum number of days a certificate has to be valid to issue a warning status. Might be a floating point number, e.g., 0.5. Default: 20

--xmpphost name

Specify the host for the 'to' attribute of the stream element

-4

Force IPv4

-6

Force IPv6

DEPRECATED OPTIONS

--altnames

Match the pattern specified in -n with alternate names too (enabled by default)

-n,--cn name

Pattern to match the CN or AltName (can be specified multiple times)

--curl-user-agent string

User agent that curl shall use to obtain the issuer cert

-d,--days days

Minimum number of days a certificate has to be valid (see --critical and --warning)

-N,--host-cn

Match CN with the host name (enabled by default)

--no_ssl2

Disable SSLv2 (deprecated use --no-ssl2)

--no_ssl3

Disable SSLv3 (deprecated use --no-ssl3)

--no_tls1

Disable TLSv1 (deprecated use --no-tls1)

--no_tls1_1

Disable TLSv1.1 (deprecated use --no-tls1_1)

--no_tls1_2

Disable TLSv1.1 (deprecated use --no-tls1_2)

--no_tls1_3

Disable TLSv1.1 (deprecated use --no-tls1_3)

--ocsp

Check revocation via OCSP (enabled by default)

--require-hsts

Require HTTP Strict Transport Security (deprecated use --require-security-header strict-transport-security)

--require-security-headers-path path

the path to be used to fetch HTTP security headers

--require-san

Require the presence of a Subject Alternative Name extension

--require-x-frame-options [path]

Require the presence of the X-Frame-Options HTTP header. 'path' is the optional path to be used in the URL to check for the header (deprecated use --require-security-header X-Frame-Options and --require-security-headers-path path)

-S,--ssl version

Force SSL version (2,3) (see: --ssl2 or --ssl3)

CONFIGURATION

Command line options can be specified in a configuration file (${HOME}/.check_ssl_certrc). For example

$ cat ${HOME}/.check_ssl_certrc
--verbose
--critical 20
--warning 40

Options specified in the configuration file are read before processing the arguments and can be overridden.

NOTES

If the host has multiple certificates and the installed openssl version supports the -servername option it is possible to specify the TLS SNI (Server Name Identificator) with the -N (or --host-cn) option.

EXIT STATUS

check_ssl_cert returns a zero exist status if it finds no errors, 1 for warnings, 2 for a critical errors and 3 for unknown problems

BUGS

Please report bugs to: https://github.com/matteocorti/check_ssl_cert/issues

EXAMPLE

check_ssl_cert --host github.com --all-local

SEE ALSO

openssl(1), openssl-x509(1)