check_ssl_cert

© Matteo Corti, ETH Zurich, 2007-2012. © Matteo Corti, 2007-2025.

see AUTHORS.md for the complete list of contributors

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

Usage

```text Usage: checksslcert -H host [OPTIONS] checksslcert -f file [OPTIONS]

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) --assume-online Do not check if the port is open -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 --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' --default-format Print the default output format and exit --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-headers Store the retrieved HTLM headers in the headers.txt file --debug-file file Write the debug messages to file --debug-time Write timing information in the debugging output --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 --dtls12 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 %CAISSUERMATCHED%' list of possible variables: - %CAISSUERMATCHED% - %CHECKEDNAMES% - %CN% - %DATE% - %DAYSVALID% - %DYSPLAYCN% - %HOST% - %OCSPEXPIRESINHOURS% - %OPENSSLCOMMAND% - %PORT% - %SELFSIGNEDCERT% - %SHORTNAME% - %SIGALGO% - %SSLLABSHOSTGRADE% 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) --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, ocspuri and fingerprint. 'all' will include all the available attributes. -m,--match 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 httpproxy and httpsproxy environment variables --no-proxy-curl Ignore the httpproxy and httpsproxy environment variables for curl --no-proxy-sclient Ignore the httpproxy and httpsproxy environment variables for openssl sclient --no-ssl2 Disable SSL version 2 --no-ssl3 Disable SSL version 3 --no-tls1 Disable TLS version 1 --no-tls11 Disable TLS version 1.1 --no-tls12 Disable TLS version 1.2 --no-tls13 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 -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 --path path Set the PATH variable to 'path' -p,--port port TCP port number (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 --password source Password source for a local certificate, see the PASS PHRASE ARGUMENTS section openssl(1) --prometheus Generate Prometheus/OpenMetrics output --proxy proxy Set httpproxy and the sclient -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 path Root certificate or directory to be used for certificate validation --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-tls11 Critical if TLS 1.1 is offered --require-no-tls12 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 --resolve-over-http [server] Resolve the host over HTTP using Google or the specified server --resolve ip Provide a custom IP address for the specified host --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 --security-level number Set the security level to specified value See SSLCTXsetsecuritylevel(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 --tls1 Force TLS version 1 --tls11 Force TLS version 1.1 --tls12 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. Can 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) --crl Check revocation via CRL (enabled by default) --curl-user-agent string User agent that curl shall use to obtain the issuer cert --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) --nossl2 Disable SSLv2 (deprecated use --no-ssl2) --nossl3 Disable SSLv3 (deprecated use --no-ssl3) --notls1 Disable TLSv1 (deprecated use --no-tls1) --notls11 Disable TLSv1.1 (deprecated use --no-tls11) --notls12 Disable TLSv1.1 (deprecated use --no-tls12) --notls13 Disable TLSv1.1 (deprecated use --no-tls13) --ocsp Check revocation via OCSP (enabled by default) --require-hsts Require HTTP Strict Transport Security (deprecated use --require-security-header strict-transport-security) --require-san Require the presence of a Subject Alternative Name extension --require-security-header header require the specified HTTP security header (e.g., X-Frame-Options) (deprecated use --require-http-header) --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 --require-security-headers-path path the path to be used to fetch HTTP security headers --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)

Report bugs to https://github.com/matteocorti/checksslcert/issues ```

Configuration

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

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

Expect & timeout

check_ssl_cert requires expect or timeout to enable timeouts. If expect or timeout are not present on your system, timeouts will be disabled.

Virtual servers

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 server with virtual hosts.

SSL Labs

If -L or --check-ssl-labs are specified, the plugin will check the cached status using the SSL Labs Assessment API.

The plugin will ask for a cached result (maximum age 1 day) to avoid too many checks. The first time you issue the check you could therefore get an outdated result.

Root Certificate

The root certificate corresponding to the checked certificate must be available to OpenSSL or must be 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:

text verification error: unable to get local issuer certificate

The bundle can be extracted with:

text $ 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

text ./check_ssl_cert -H www.google.com -r ./cabundle.crt

Quoting in Nagios

An asterisk * is automatically escaped by nagios. If you need to specify an option (e.g., --cn) with an argument containing an asterisk you need to enclose it in double quotes (e.g., ''*.github.com'')

bash completion and caching

Once the host name cache (${HOME}/.check_ssl_cert-cache) is initialized (with the --init-host-cache option), every specified host is cached.

The host name cache is a plain text file which contains an host name per line. Each time a new host is specified, it is automatically added to the cache. The file can be edited with a text editor (to delete or edit entries).

When using bash completion with the --host command line option the cache is then read and used as a suggestion.

Development

Testing

To run the test suite you will need shUnit2

• Manual install: github
• macOS with Homebrew: brew install shunit2
• Debian, Ubuntu: apt-get install shunit2
• Fedora: dnf install shunit2

Run make test to execute the whole test suite.

To enable debugging output for the tests set the TEST_DEBUG environment variable to --debug:

text export TEST_DEBUG=--debug make test

With make disttest you can check the formatting of the files (e.g. tabs and blanks at the end of the lines) and run ShellCheck to lint the scripts.

With make codespell ypu can perform a spell check on the code and documentation.

To run a single test:

• set the SHUNIT2 environment variable with the location of the shUnit2 binary
• change the directory to the test suite: cd test
• execute the test suite with the tests to be run as argument after --. For example ./unit_tests.sh -- testName

Documentation

The majority of the documentation files are written using the GitHub Flavored Markdown language.

Supporters

We are very grateful to our amazing supporters and sponsors!

• Łukasz Wąsikowski
• Claus-Theodor Riegg
• wols
• Netzkommune
• Nicolas Wimmer

If you'd like to support this script, please visit our sponsorship page on GitHub.

Bugs

Report bugs to https://github.com/matteocorti/checksslcert/issues