check_ssl_cert - Man Page

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
--dtls: Use the DTLS protocol
--dtls1: Use the DTLS protocol 1.0
--dtls1_2: Use the DTLS protocol 1.2
-e,--email address: Pattern to match the email address contained in the certificate
--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 SHA1: Pattern to match the SHA1-Fingerprint
--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 to match the issuer of the certificate
--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-exp: Ignore expiration date
--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-tls-renegotiation: Ignore the TLS renegotiation check
--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
--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: ftp, ftps, http, https (default), h2 (HTTP/2), imap, imaps, irc, ircs, ldap, ldaps, mysql, pop3, pop3s, postgres, sieve, 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.
--password source: Password source for a local certificate, see the PASS PHRASE Arguments section openssl(1) TP --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
-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., X-Frame-Options)
--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-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
--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
-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.

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.