© Matteo Corti, ETH Zurich, 2007-2012
© Matteo Corti, 2007-2021 see AUTHORS for the complete list of contributors
A shell script (that can be used as a Nagios/Icinga plugin) to check an SSL/TLS connection
Usage: check_ssl_cert -H host [OPTIONS]
Arguments:
-H,--host host server
Options:
-A,--noauth ignore authority warnings (expiration only)
--all enables all the possible optional checks at the maximum level
--altnames matches the pattern specified in -n with
alternate names too
--check-ciphers grade checks the offered ciphers
--check-ciphers-warnings critical if nmap reports a warning for an offered cipher
-C,--clientcert path use client certificate to authenticate
--clientpass phrase set passphrase for client certificate.
-c,--critical days minimum number of days a certificate has to
be valid to issue a critical status. Default: 15
--crl checks revokation via CRL (requires --rootcert-file)
--curl-bin path path of the curl binary to be used
--curl-user-agent string user agent that curl shall use to obtain the
issuer cert
--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
--date path path of the date binary to be used
-d,--debug produces debugging output (can be specified more than once)
--debug-cert stores the retrieved certificates in the current directory
--debug-file file writes the debug messages to file
--dig-bin path path of the dig binary to be used
--ecdsa signature algorithm selection: force ECDSA certificate
--element number checks N cert element from the begining of the chain
-e,--email address pattern to match the email address contained
in the certificate
-f,--file file local file path (works with -H localhost only)
with -f you can not only pass a x509
certificate file but also a certificate
revocation list (CRL) to check the validity
period
--file-bin path path of the file binary to be used
--fingerprint SHA1 pattern to match the SHA1-Fingerprint
--first-element-only verify just the first cert element, not the whole chain
--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%'"
-h,--help,-? this help message
--http-use-get use GET instead of HEAD (default) for the HTTP
related checks
--ignore-altnames ignores alternative names when matching pattern specified in -n (or the host name)
--ignore-exp ignore expiration date
--ignore-host-cn do not complain if the CN does not match the host name
--ignore-ocsp do not check revocation with OCSP
--ignore-ocsp-timeout ignore OCSP result when timeout occurs while checking
--ignore-sig-alg do not check if the certificate was signed with SHA1
or MD5
--ignore-sct do not check for signed certificate timestamps (SCT)
--ignore-ssl-labs-cache Forces a new check by SSL Labs (see -L)
--ignore-tls-renegotiation Ignores the TLS renegotiation check
--inetproto protocol Force IP version 4 or 6
-i,--issuer issuer pattern to match the issuer of the certificate
--issuer-cert-cache dir directory where to store issuer certificates cache
-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)
--check-ssl-labs-warn grade SSL-Labs grade on which to warn
--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.
-n,--cn name pattern to match the CN of the certificate (can be
specified multiple times)
--nmap-bin path path of the nmap binary to be used
--no-perf do not show performance data
--no-proxy ignores the http_proxy and https_proxy environment variables
--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_2 disable TLS version 1.2
--no_tls1_3 disable TLS version 1.3
--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
-N,--host-cn match CN with the host name
--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
-o,--org org pattern to match the organization of the certificate
--openssl path path of the openssl binary to be used
--password source password source for a local certificate, see the PASS PHRASE ARGUMENTS section
openssl(1)
-p,--port port TCP port
-P,--protocol protocol use the specific protocol
{ftp|ftps|http|https|h2|imap|imaps|irc|ircs|ldap|ldaps|pop3|pop3s|
postgres|sieve|smtp|smtps|xmpp|xmpp-server}
https: default
h2: forces HTTP/2
ftp,imap,irc,ldap,pop3,postgres,sieve,smtp: switch to
TLS using StartTLS
--proxy proxy sets http_proxy and the s_client -proxy option
--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
--resolve ip provides a custom IP address for the specified host
-s,--selfsigned allows self-signed certificates
--serial serialnum pattern to match the serial number
--skip-element number skip checks on N cert element from the begining of the chain
--sni name sets the TLS SNI (Server Name Indication) extension
in the ClientHello message to 'name'
--ssl2 forces SSL version 2
--ssl3 forces SSL version 3
--require-ocsp-stapling require OCSP stapling
--require-san require the presence of a Subject Alternative Name
extension
-r,--rootcert path root certificate or directory to be used for
certificate validation
--rootcert-dir path root directory to be used for certificate validation
--rootcert-file path root certificate to be used for certificate validation
--rsa signature algorithm selection: force RSA certificate
--temp dir directory where to store the temporary files
--terse terse output
-t,--timeout seconds timeout after the specified time
(defaults to 120 seconds)
--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
-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. Default: 20
--xmpphost name specifies the host for the 'to' attribute of the stream element
-4 force IPv4
-6 force IPv6
Deprecated options:
--days days minimum number of days a certificate has to be valid
(see --critical and --warning)
--ocsp check revocation via OCSP
-S,--ssl version force SSL version (2,3)
(see: --ssl2 or --ssl3)
Report bugs to https://github.com/matteocorti/check_ssl_cert/issues
check_ssl_cert requires 'expect' or 'timeout' to enable timeouts. If 'expect' or 'timeout' is not present on your system timeouts will be disabled.
See: http://en.wikipedia.org/wiki/Expect and https://man7.org/linux/man-pages/man1/timeout.1.html
check_ssl_cert supports the servername TLS extension in ClientHello if the installed openssl version provides it. This is needed if you are checking a machine with virtual hosts.
If -L
or --check-ssl-labs
are specified the plugin will check the
cached status using the SSL Labs Assessment API (see
https://www.ssllabs.com/about/terms.html).
The plugin will ask for a cached result (maximum age 1 day) to avoid to many checks. The first time you issue the check you could therefore get an outdated result.
The root certificate corresponding to the checked certificate must be
available to openssl or specified with the -r cabundle
or
--rootcert cabundle
option, where cabundle is either a file for -CAfile
or a directory for -CApath
.
On macOS the root certificates bundle is stored in the Keychain and openssl will complain with:
verification error: unable to get local issuer certificate
The bundle can be extracted with:
$ sudo security find-certificate -a \
-p /System/Library/Keychains/SystemRootCertificates.keychain > cabundle.crt
and then submitted to check_ssl_cert
with the -r,--rootcert path
option
./check_ssl_cert -H www.google.com -r ./cabundle.crt
The timeout is applied to each action involving a download.
Report bugs to https://github.com/matteocorti/check_ssl_cert/issues