check_ssl_cert(1)

📦
version 48.20250420ubuntu3 · 7 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🎀 NAME 🎀

Hii bestie 💖 welcome to check_ssl_cert(1), straight out of the USER COMMANDS section of the manual — she checks the validity of X.509 certificates and honestly? she ate, no cap.

✨ SYNOPSIS ✨

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

💖 DESCRIPTION 💖

check_ssl_cert is a shell script — and yes, she can absolutely be used as a Nagios/Icinga plugin 🫶 — that checks an SSL/TLS connection.

🌸 ARGUMENTS 🌸

  • -f, --file file — Local file path or URI. And like, with -f you're not limited to a plain x509 certificate file, okay? You can also pass her a certificate revocation list (CRL) to check the validity period, or a Java KeyStore file. versatile queen 💅
  • -H, --host host — the server. that's it, that's the girl.

👑 OPTIONS 👑

  • -A, --noauth — Ignore authority warnings (expiration only).
  • --all — Enable all the possible optional checks at the maximum level. the whole menu, periodt.
  • --all-local — Enable all the possible optional checks at the maximum level (without SSL-Labs). same energy, just not leaving the house.
  • --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). stack her up, she loves it.
  • --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 — shhh 🤫 bestie, this one produces zero output. Not a single peep. Like, absolutely no vibe check feedback. 💅
  • -r, --rootcert cert — the root cert or directory used for validating certs. It gets passed straight to openssl's -CAfile or -CApath. So like, the trust anchor, you know? 🔒
  • --require-client-cert [list] — the server must accept a client cert. The optional list is a comma-separated list of expected client cert CAs. Like, "prove you belong here" energy. 🪪
  • --require-dnssec — require DNSSEC. No DNSSEC, no peace. ✨
  • --require-http-header header — require the specified HTTP header (for example, strict-transport-security). Like, if it's not there, we're gonna have a problem. 😤
  • --require-no-http-header header — require the absence of the specified HTTP header (for example, X-Powered-By). So like, if it shows up, that's a no from me. 🙅‍♀️
  • --require-no-ssl2 — critical if SSL version 2 is offered. Ancient vibes, not in a good way. 💀
  • --require-no-ssl3 — critical if SSL version 3 is offered. Also ancient, also not it. 🚫
  • --require-no-tls1 — critical if TLS 1 is offered. Old news, bestie. 📉
  • --require-no-tls1_1 — critical if TLS 1.1 is offered. Like, why is this still here? 😭
  • --require-no-tls1_2 — critical if TLS 1.2 is offered. Okay this one is still kinda common but if you require it off, we'll flag it. 🔥
  • --require-ocsp-stapling — require OCSP stapling. It's giving "I need that fresh revocation status". 🌿
  • --require-purpose usage — require the specified key usage. Can be specified more than once. Like, stack 'em up. 📚
  • --require-purpose-critical — the key usage must be critical. Periodt. 💅
  • --require-security-header header — require the specified HTTP security header (for example, X-Frame-Options). Security check, bestie. 🛡️
  • --require-security-headers — require all the HTTP security headers. The whole squad:
    • Content-Security-Policy
    • Permissions-Policy
    • Referrer-Policy
    • strict-transport-security
    • X-Content-Type-Options
    • X-Frame-Options Like, if any are missing, it's a whole thing. 👑
  • --resolve ip — provide a custom IP address for the specified host. Like, "I know you said this host, but actually go here." 📍
  • --resolve-over-http [server] — resolve the host over HTTP using Google or the specified server. So like, DNS over HTTP? Google it. 🌐
  • --rootcert-dir dir — root directory used for cert validation (passed to openssl's -CApath). This overrides option -r, --rootcert. So it wins. 🏆
  • --rootcert-file cert — root cert used for cert validation (passed to openssl's -CAfile). Also overrides option -r, --rootcert. Same energy. 📁
  • --rsa — signature algorithm selection: force RSA certificate. Like, "I only want RSA, thanks." 🔑
  • --security-level number — set the security level to the specified value. See SSL_CTX_set_security_level(3) for what each level means. Higher number, higher standards. 💯
  • -s, --selfsigned — allow self-signed certificates. Sometimes you gotta trust yourself. 🪞
  • --serial serialnum — pattern to match the serial number. Like a fingerprint, but for certs. 🔍
  • --skip-element number — skip checks on the Nth cert element. Can be specified multiple times. So like, "ignore that one, and that one too." 🙈
  • --sni name — set the TLS SNI (Server Name Indication) extension in the ClientHello message to name. It's giving "hey server, I'm looking for this name". 📛
  • --ssl2 — force SSL version 2. Danger, bestie. This is ancient and broken. 💀
  • --ssl3 — force SSL version 3. Also ancient and broken. Please don't. 🚫
  • -t, --timeout seconds — timeout after the specified time (defaults to 120 seconds). Like, "I'm not waiting forever." ⏰
  • --temp dir — directory where to store the temporary files. Gotta put the temp stuff somewhere. 📂
  • --terse — terse output. Also see --verbose. Short and sweet, no fluff. ✂️
  • --tls1 — force TLS version 1. Old. 🦖
  • --tls1_1 — force TLS version 1.1. Also old. 🦕
  • --tls1_2 — force TLS version 1.2. Still hanging on. 🧓
  • --tls1_3 — force TLS version 1.3. Fresh and modern. ✨
  • -u, --url URL — HTTP request URL. Like, where we're sending the request. 🔗
  • --user-agent string — user agent that shall be used for HTTPS connections. Like, "I'm a browser, trust me." 🕵️‍♀️
  • -v, --verbose — verbose output. Can be specified more than once. So like, -v -v -v for maximum yapping. 🗣️
  • -V, --version — version. Just tells you what version this is. 📌
  • -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. So if it expires in less than this, warning. ⚠️
  • --xmpphost name — specify the host for the 'to' attribute of the stream element. XMPP vibes. 💬
  • -4 — force IPv4. Old school IP. 📞
  • -6 — force IPv6. New school IP. 📱

💀 DEPRECATED OPTIONS 💀

These are still here, but like, they're deprecated. Use the new ones, bestie. 👵

  • --altnames — match the pattern specified in -n with alternate names too (enabled by default). So it's already on, but you can say it again. 🤷‍♀️
  • -n, --cn name — pattern to match the CN or AltName. Can be specified multiple times. Like, "I'm looking for this name, or this one." 🏷️
  • --curl-user-agent string — user agent that curl shall use to obtain the issuer cert. So curl gets its own disguise. 🎭
  • -d, --days days — minimum number of days a certificate has to be valid (see --critical and --warning). Like --warning but also for critical? Anyway, deprecated. 📅
  • -N, --host-cn — match CN with the host name (enabled by default). Already on. ✅
  • --no_ssl2 — disable SSLv2 (deprecated, use --no-ssl2). Note the underscore, bestie. 🚫
  • --no_ssl3 — disable SSLv3 (deprecated, use --no-ssl3). Underscore again. 🚫
  • --no_tls1 — disable TLSv1 (deprecated, use --no-tls1). Underscore. 🚫
  • --no_tls1_1 — disable TLSv1.1 (deprecated, use --no-tls1_1). Underscore. 🚫
  • --no_tls1_2 — disable TLSv1.1 (deprecated, use --no-tls1_2). Yes, it says 1.1, we're just the messenger 💀
  • --no_tls1_3 — disable TLSv1.1 (deprecated, use --no-tls1_3). Same energy. 💀
  • --ocsp — check revocation via OCSP (enabled by default). Already on. ✅
  • --require-hsts — require HTTP Strict Transport Security (deprecated, use --require-security-header strict-transport-security). Old way. 🗝️
  • --require-security-headers-path path — the path to be used to fetch HTTP security headers. Like, where to look for them. 🛣️
  • --require-san — require the presence of a Subject Alternative Name extension. Like, "I need to see your SANs." 📇
  • --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). So like, check for this header at this path. 🖼️
  • -S, --ssl version — force SSL version (2,3) (see: --ssl2 or --ssl3). Old way to pick SSL version. 🕰️

⚙️ CONFIGURATION ⚙️

You can put command line options in a config file at ${HOME}/.check_ssl_certrc. For example:

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

Options in the config file are read before processing the arguments, and they can be overridden. So like, defaults, but you can still change your mind. 💅

📝 NOTES 📝

If the host has multiple certificates and the installed openssl version supports the -servername option, you can specify the TLS SNI (Server Name Identificator) with the -N (or --host-cn) option. So like, pick which cert you want. 🎯

🚦 EXIT STATUS 🚦

check_ssl_cert returns:

  • 0 if it finds no errors,
  • 1 for warnings,
  • 2 for critical errors,
  • 3 for unknown problems.

So like, zero is good, higher is bad. Got it. 💯

🐛 BUGS 🐛

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

Like, if you find a bug, tell the devs. They wanna know. 🫶

🌟 EXAMPLE 🌟

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

That's it. That's the example. ✨

🔗 SEE ALSO 🔗

openssl(1), openssl-x509(1)

Go read those if you want more. 📚

This page is from version 2.92.0, dated April 2025, and it's the manual for check_ssl_cert(1). Stay secure, bestie! 💖

📦 where this page comes from