Debian Codegraph @

check_ssl_cert/check_ssl_cert_2.92.0/README.md

raw
1 # check\_ssl\_cert
2
3 © Matteo Corti, ETH Zurich, 2007-2012.
4 © Matteo Corti, 2007-2025.
5
6 see [AUTHORS.md](AUTHORS.md) for the complete list of contributors
7
8 ![](https://img.shields.io/github/v/release/matteocorti/check_ssl_cert) ![](https://img.shields.io/github/downloads/matteocorti/check_ssl_cert/latest/total) ![](https://img.shields.io/github/downloads/matteocorti/check_ssl_cert/total) ![](https://img.shields.io/github/license/matteocorti/check_ssl_cert) ![](https://img.shields.io/github/stars/matteocorti/check_ssl_cert) ![](https://img.shields.io/github/forks/matteocorti/check_ssl_cert)
9
10
11 A POSIX shell script (that can be used as a Nagios/Icinga plugin) to check an SSL/TLS connection and certificate
12
13 ## Usage
14
15 ```text
16 Usage: check_ssl_cert -H host [OPTIONS]
17 check_ssl_cert -f file [OPTIONS]
18
19 Arguments:
20 -f,--file file Local file path or URI.
21 With -f you can not only pass a x509
22 certificate file but also a certificate
23 revocation list (CRL) to check the
24 validity period or a Java KeyStore file
25 -H,--host host Server
26
27 Options:
28 -A,--noauth Ignore authority warnings (expiration
29 only)
30 --all Enable all the possible optional checks
31 at the maximum level
32 --all-local Enable all the possible optional checks
33 at the maximum level (without SSL-Labs)
34 --allow-empty-san Allow certificates without Subject
35 Alternative Names (SANs)
36 -C,--clientcert path Use client certificate to authenticate
37 -c,--critical days Minimum number of days a certificate has
38 to be valid to issue a critical status.
39 Can be a floating point number, e.g., 0.5
40 Default: 15
41 --check-chain The certificate chain cannot contain
42 double or root certificates
43 --check-ciphers grade Check the offered ciphers
44 --check-ciphers-warnings Critical if nmap reports a warning for an
45 offered cipher
46 --check-http-headers Check the HTTP headers for best practices
47 --check-ssl-labs-warn grade SSL Labs grade on which to warn
48 --clientpass phrase Set passphrase for client certificate.
49 --configuration file Read options from the specified file
50 --curl-bin path Path of the curl binary to be used
51 --custom-http-header string Custom HTTP header sent when getting the
52 cert example: 'X-Check-Ssl-Cert: Foobar=1'
53 --default-format Print the default output format and exit
54 --dane Verify that valid DANE records exist
55 (since OpenSSL 1.1.0)
56 --dane 211 Verify that a valid DANE-TA(2) SPKI(1)
57 SHA2-256(1) TLSA record exists
58 --dane 301 Verify that a valid DANE-EE(3) Cert(0)
59 SHA2-256(1) TLSA record exists
60 --dane 302 Verify that a valid DANE-EE(3) Cert(0)
61 SHA2-512(2) TLSA record exists
62 --dane 311 Verify that a valid DANE-EE(3) SPKI(1)
63 SHA2-256(1) TLSA record exists
64 --dane 312 Verify that a valid DANE-EE(3)
65 SPKI(1) SHA2-512(1) TLSA record exists
66 --date path Path of the date binary to be used
67 -d,--debug Produce debugging output (can be
68 specified more than once)
69 --debug-cert Store the retrieved certificates in the
70 current directory
71 --debug-headers Store the retrieved HTLM headers in the
72 headers.txt file
73 --debug-file file Write the debug messages to file
74 --debug-time Write timing information in the
75 debugging output
76 --dig-bin path Path of the dig binary to be used
77 --do-not-resolve Do not check if the host can be resolved
78 --dtls Use the DTLS protocol
79 --dtls1 Use the DTLS protocol 1.0
80 --dtls1_2 Use the DTLS protocol 1.2
81 -e,--email address Pattern (extended regular expression) to
82 match the email address contained in the
83 certificate. You can specify different
84 addresses separated by a pipe
85 (e.g., 'addr1|addr2')
86 --ecdsa Signature algorithm selection: force ECDSA
87 certificate
88 --element number Check up to the N cert element from the
89 beginning of the chain
90 --file-bin path Path of the file binary to be used
91 --fingerprint hash Pattern to match the fingerprint
92 --fingerprint-alg algorithm Algorithm for fingerprint. Default sha1
93 --first-element-only Verify just the first cert element, not
94 the whole chain
95 --force-dconv-date Force the usage of dconv for date
96 computations
97 --force-perl-date Force the usage of Perl for date
98 computations
99 --format FORMAT Format output template on success, for
100 example: '%SHORTNAME% OK %CN% from
101 %CA_ISSUER_MATCHED%'
102 list of possible variables:
103 - %CA_ISSUER_MATCHED%
104 - %CHECKEDNAMES%
105 - %CN%
106 - %DATE%
107 - %DAYS_VALID%
108 - %DYSPLAY_CN%
109 - %HOST%
110 - %OCSP_EXPIRES_IN_HOURS%
111 - %OPENSSL_COMMAND%
112 - %PORT%
113 - %SELFSIGNEDCERT%
114 - %SHORTNAME%
115 - %SIGALGO%
116 - %SSL_LABS_HOST_GRADE%
117 See --default-format for the default
118 --grep-bin path Path of the grep binary to be used
119 -h,--help,-? This help message
120 --http-headers-path path The path to be used to fetch HTTP headers
121 --http-use-get Use GET instead of HEAD (default) for the
122 HTTP related checks
123 -i,--issuer issuer Pattern (extended regular expression) to
124 match the issuer of the certificate
125 You can specify different issuers
126 separated by a pipe
127 (e.g., 'issuer1|issuer2')
128 --ignore-altnames Ignore alternative names when matching
129 pattern specified in -n (or the host name)
130 --ignore-connection-problems [state] In case of connection problems
131 returns OK or the optional state
132 --ignore-crl Ignore CRLs
133 --ignore-dh Ignore too small DH keys
134 --ignore-exp Ignore expiration date
135 --ignore-http-headers Ignore checks on HTTP headers with --all
136 and --all-local
137 --ignore-host-cn Do not complain if the CN does not match
138 the host name
139 --ignore-incomplete-chain Do not check chain integrity
140 --ignore-maximum-validity Ignore the certificate maximum validity
141 --ignore-ocsp Do not check revocation with OCSP
142 --ignore-ocsp-errors Continue if the OCSP status cannot be
143 checked
144 --ignore-ocsp-timeout Ignore OCSP result when timeout occurs
145 while checking
146 --ignore-sct Do not check for signed certificate
147 timestamps (SCT)
148 --ignore-sig-alg Do not check if the certificate was signed
149 with SHA1 or MD5
150 --ignore-ssl-labs-cache Force a new check by SSL Labs (see -L)
151 --ignore-ssl-labs-errors Ignore errors if SSL Labs is not
152 accessible or times out
153 --ignore-tls-renegotiation Ignore the TLS renegotiation check
154 --ignore-unexpected-eof Ignore unclean TLS shutdowns
155 --inetproto protocol Force IP version 4 or 6
156 --info Print certificate information
157 --init-host-cache Initialize the host cache
158 --issuer-cert-cache dir Directory where to store issuer
159 certificates cache
160 --jks-alias alias Alias name of the Java KeyStore entry
161 (requires --file)
162 -K,--clientkey path Use client certificate key to authenticate
163 -L,--check-ssl-labs grade SSL Labs assessment (please check
164 https://www.ssllabs.com/about/terms.html)
165 --long-output list Append the specified comma separated (no
166 spaces) list of attributes to the plugin
167 output on additional lines
168 Valid attributes are:
169 enddate, startdate, subject, issuer,
170 modulus, serial, hash, email, ocsp_uri
171 and fingerprint.
172 'all' will include all the available
173 attributes.
174 -m,--match Pattern to match the CN or AltName
175 (can be specified multiple times)
176 --maximum-validity [days] The maximum validity of the certificate
177 must not exceed 'days' (default 397)
178 This check is automatic for HTTPS
179 --nmap-bin path Path of the nmap binary to be used
180 --nmap-with-proxy Allow nmap to be used with a proxy
181 --no-perf Do not show performance data
182 --no-proxy Ignore the http_proxy and https_proxy
183 environment variables
184 --no-proxy-curl Ignore the http_proxy and https_proxy
185 environment variables for curl
186 --no-proxy-s_client Ignore the http_proxy and https_proxy
187 environment variables for openssl s_client
188 --no-ssl2 Disable SSL version 2
189 --no-ssl3 Disable SSL version 3
190 --no-tls1 Disable TLS version 1
191 --no-tls1_1 Disable TLS version 1.1
192 --no-tls1_2 Disable TLS version 1.2
193 --no-tls1_3 Disable TLS version 1.3
194 --not-issued-by issuer Check that the issuer of the certificate
195 does not match the given pattern
196 --not-valid-longer-than days Critical if the certificate validity is
197 longer than the specified period
198 -o,--org org Pattern to match the organization of the
199 certificate
200 --ocsp-critical hours Minimum number of hours an OCSP response
201 has to be valid to issue a critical status
202 --ocsp-warning hours Minimum number of hours an OCSP response
203 has to be valid to issue a warning status
204 --openssl path Path of the openssl binary to be used
205 --path path Set the PATH variable to 'path'
206 -p,--port port TCP port (default 443)
207 --precision digits Number of decimal places for durations:
208 defaults to 0 if critical or warning are
209 integers, 2 otherwise
210 -P,--protocol protocol Use the specific protocol:
211 dns, ftp, ftps, http, https (default),
212 h2 (HTTP/2), h3 (HTTP/3), imap, imaps,
213 irc, ircs, ldap, ldaps, mqtts, mysql,
214 pop3, pop3s, postgres, sieve, sips, smtp,
215 smtps, tds, xmpp, xmpp-server.
216 ftp, imap, irc, ldap, pop3, postgres,
217 sieve, smtp: switch to TLS using StartTLS
218 --password source Password source for a local certificate,
219 see the PASS PHRASE ARGUMENTS section
220 openssl(1)
221 --prometheus Generate Prometheus/OpenMetrics output
222 --proxy proxy Set http_proxy and the s_client -proxy
223 option
224 --python-bin path Path of the python binary to be used
225 --quic Use QUIC
226 -q,--quiet Do not produce any output
227 -r,--rootcert path Root certificate or directory to be used
228 for certificate validation
229 --require-client-cert [list] The server must accept a client
230 certificate. 'list' is an optional comma
231 separated list of expected client
232 certificate CAs
233 --require-dnssec Require DNSSEC
234 --require-http-header header Require the specified HTTP header
235 (e.g., strict-transport-security)
236 --require-no-http-header header Require the absence of the specified
237 HTTP header (e.g., X-Powered-By)
238 --require-no-ssl2 Critical if SSL version 2 is offered
239 --require-no-ssl3 Critical if SSL version 3 is offered
240 --require-no-tls1 Critical if TLS 1 is offered
241 --require-no-tls1_1 Critical if TLS 1.1 is offered
242 --require-no-tls1_2 Critical if TLS 1.2 is offered
243 --require-ocsp-stapling Require OCSP stapling
244 --require-purpose usage Require the specified key usage (can be
245 specified more then once)
246 --require-purpose-critical The key usage must be critical
247 --resolve-over-http [server] Resolve the host over HTTP using Google or
248 the specified server
249 --resolve ip Provide a custom IP address for the
250 specified host
251 --rootcert-dir path Root directory to be used for certificate
252 validation
253 --rootcert-file path Root certificate to be used for
254 certificate validation
255 --rsa Signature algorithm selection: force RSA
256 certificate
257 --security-level number Set the security level to specified value
258 See SSL_CTX_set_security_level(3) for a
259 description of what each level means
260 -s,--selfsigned Allow self-signed certificates
261 --serial serialnum Pattern to match the serial number
262 --skip-element number Skip checks on the Nth cert element (can
263 be specified multiple times)
264 --sni name Set the TLS SNI (Server Name Indication)
265 extension in the ClientHello message to
266 'name'
267 --ssl2 Force SSL version 2
268 --ssl3 Force SSL version 3
269 -t,--timeout seconds Timeout after the specified time
270 (defaults to 120 seconds)
271 --temp dir Directory where to store the temporary
272 files
273 --terse Terse output
274 --tls1 Force TLS version 1
275 --tls1_1 Force TLS version 1.1
276 --tls1_2 Force TLS version 1.2
277 --tls1_3 Force TLS version 1.3
278 -u,--url URL HTTP request URL
279 --user-agent string User agent that shall be used for HTTPS
280 connections
281 -v,--verbose Verbose output (can be specified more than
282 once)
283 -V,--version Version
284 -w,--warning days Minimum number of days a certificate has
285 to be valid to issue a warning status.
286 Can be a floating point number, e.g., 0.5
287 Default: 20
288 --xmpphost name Specify the host for the 'to' attribute
289 of the stream element
290 -4 Force IPv4
291 -6 Force IPv6
292
293 Deprecated options:
294 --altnames Match the pattern specified in -n with
295 alternate names too (enabled by default)
296 -n,--cn name Pattern to match the CN or AltName
297 (can be specified multiple times)
298 --crl Check revocation via CRL (enabled by
299 default)
300 --curl-user-agent string User agent that curl shall use to obtain
301 the issuer cert
302 --days days Minimum number of days a certificate has
303 to be valid
304 (see --critical and --warning)
305 -N,--host-cn Match CN with the host name
306 (enabled by default)
307 --no_ssl2 Disable SSLv2 (deprecated use --no-ssl2)
308 --no_ssl3 Disable SSLv3 (deprecated use --no-ssl3)
309 --no_tls1 Disable TLSv1 (deprecated use --no-tls1)
310 --no_tls1_1 Disable TLSv1.1 (deprecated use
311 --no-tls1_1)
312 --no_tls1_2 Disable TLSv1.1 (deprecated use
313 --no-tls1_2)
314 --no_tls1_3 Disable TLSv1.1 (deprecated use
315 --no-tls1_3)
316 --ocsp Check revocation via OCSP (enabled by
317 default)
318 --require-hsts Require HTTP Strict Transport Security
319 (deprecated use --require-security-header
320 strict-transport-security)
321 --require-san Require the presence of a Subject
322 Alternative Name
323 extension
324 --require-security-header header require the specified HTTP
325 security header (e.g., X-Frame-Options)
326 (deprecated use --require-http-header)
327 --require-security-headers Require all the HTTP security headers:
328 Content-Security-Policy
329 Permissions-Policy
330 Referrer-Policy
331 strict-transport-security
332 X-Content-Type-Options
333 X-Frame-Options
334 --require-security-headers-path path the path to be used to fetch HTTP
335 security headers
336 --require-x-frame-options [path] Require the presence of the
337 X-Frame-Options HTTP header
338 'path' is the optional path to be used
339 in the URL to check for the header
340 (deprecated use --require-security-header
341 X-Frame-Options and
342 --require-security-headers-path path)
343 -S,--ssl version Force SSL version (2,3)
344 (see: --ssl2 or --ssl3)
345
346 Report bugs to https://github.com/matteocorti/check_ssl_cert/issues
347 ```
348
349 ## Configuration
350
351 Command line options can be specified in a configuration file (```${HOME}/.check_ssl_certrc```). For example
352
353 ```text
354 $ cat ${HOME}/.check_ssl_certrc
355 --verbose
356 --critical 20
357 --warning 40
358 ```
359
360 Options specified in the configuration file are read before processing the arguments and can be overridden.
361
362 ## Expect & timeout
363
364 check\_ssl\_cert requires [```expect```](http://en.wikipedia.org/wiki/Expect) or [```timeout```](https://man7.org/linux/man-pages/man1/timeout.1.html) to enable timeouts. If ```expect``` or ```timeout``` are not present on your system, timeouts will be disabled.
365
366 ## Virtual servers
367
368 check\_ssl\_cert supports the servername TLS extension in ```ClientHello```
369 if the installed OpenSSL version provides it. This is needed if you
370 are checking a server with virtual hosts.
371
372 ## SSL Labs
373
374 If `-L` or `--check-ssl-labs` are specified, the plugin will check the
375 cached status using the [SSL Labs Assessment API](https://www.ssllabs.com/about/terms.html).
376
377 The plugin will ask for a cached result (maximum age 1 day) to avoid
378 too many checks. The first time you issue the check you could therefore
379 get an outdated result.
380
381 ## Root Certificate
382
383 The root certificate corresponding to the checked certificate must be
384 available to OpenSSL or must be specified with the `-r cabundle` or
385 `--rootcert cabundle` option, where ```cabundle``` is either a file for `-CAfile`
386 or a directory for `-CApath`.
387
388 On macOS the root certificates bundle is stored in the Keychain and
389 OpenSSL will complain with:
390
391 ```text
392 verification error: unable to get local issuer certificate
393 ```
394
395 The bundle can be extracted with:
396
397 ```text
398 $ sudo security find-certificate -a \
399 -p /System/Library/Keychains/SystemRootCertificates.keychain > cabundle.crt
400 ```
401
402 and then submitted to `check_ssl_cert` with the `-r,--rootcert path` option
403
404 ```text
405 ./check_ssl_cert -H www.google.com -r ./cabundle.crt
406 ```
407
408 ## Quoting in Nagios
409
410 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''```)
411
412 ## bash completion and caching
413
414 Once the host name cache (```${HOME}/.check_ssl_cert-cache```) is initialized (with the ```--init-host-cache``` option), every specified host is cached.
415
416 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).
417
418 When using bash completion with the ```--host``` command line option the cache is then read and used as a suggestion.
419
420 ## Development
421
422 ### Testing
423
424 To run the test suite you will need [shUnit2](https://github.com/kward/shunit2)
425
426 * Manual install: [github](https://github.com/kward/shunit2)
427 * macOS with [Homebrew](https://brew.sh): ```brew install shunit2```
428 * Debian, Ubuntu: ```apt-get install shunit2```
429 * Fedora: ```dnf install shunit2```
430
431 Run ```make test``` to execute the whole test suite.
432
433 To enable debugging output for the tests set the ```TEST_DEBUG``` environment variable to ```--debug```:
434
435 ```text
436 export TEST_DEBUG=--debug
437 make test
438 ```
439
440 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.
441
442 With ```make codespell``` ypu can perform a spell check on the code and documentation.
443
444 To run a single test:
445
446 * set the ```SHUNIT2``` environment variable with the location of the shUnit2 binary
447 * change the directory to the test suite: ```cd test```
448 * execute the test suite with the tests to be run as argument after ```--```. For example ```./unit_tests.sh -- testName```
449
450 ## Documentation
451
452 The majority of the documentation files are written using the [GitHub Flavored Markdown](https://github.github.com/gfm/) language.
453
454 ## Supporters
455
456 We are very grateful to our amazing supporters and sponsors!
457
458 * [Łukasz Wąsikowski](https://github.com/IdahoPL)
459 * [Claus-Theodor Riegg](https://github.com/crigertg)
460 * [wols](https://github.com/wols)
461 * [Netzkommune](https://github.com/netzkommune)
462 * [Nicolas Wimmer](https://github.com/naiz0)
463
464 If you'd like to support this script, please visit [our sponsorship page](https://github.com/sponsors/matteocorti) on GitHub.
465
466 ## Bugs
467
468 Report bugs to [https://github.com/matteocorti/check_ssl_cert/issues](https://github.com/matteocorti/check_ssl_cert/issues)