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

--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: dns, 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.

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

-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

--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)