Debian Codegraph @

check_ssl_cert/src/check_ssl_cert.1

raw
1 .\" Process this file with
2 .\" groff -man -Tascii check_ssl_cert.1
3 .\"
4 .TH "check_ssl_cert" 1 "April, 2025" "2.92.0" "USER COMMANDS"
5 .SH NAME
6 check_ssl_cert \- checks the validity of X.509 certificates
7 .SH SYNOPSIS
8 .BR "check_ssl_cert " "-H host [OPTIONS]"
9 .br
10 .BR "check_ssl_cert " "-f file [OPTIONS]"
11 .SH DESCRIPTION
12 .B check_ssl_cert
13 A shell script (that can be used as a Nagios/Icinga plugin) to check an SSL/TLS connection
14 .SH ARGUMENTS
15 .TP
16 .BR "-f,--file" " file"
17 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
18 .TP
19 .BR "-H,--host" " host"
20 server
21 .SH OPTIONS
22 .TP
23 .BR "-A,--noauth"
24 Ignore authority warnings (expiration only)
25 .TP
26 .BR " --all"
27 Enable all the possible optional checks at the maximum level
28 .TP
29 .BR " --all-local"
30 Enable all the possible optional checks at the maximum level (without SSL-Labs)
31 .TP
32 .BR " --allow-empty-san"
33 Allow certificates without Subject Alternative Names (SANs)
34 .TP
35 .BR "-C,--clientcert" " path"
36 Use client certificate to authenticate
37 .TP
38 .BR "-c,--critical" " days"
39 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
40 .TP
41 .BR " --check-chain"
42 The certificate chain cannot contain double or root certificates
43 .TP
44 .BR " --check-ciphers" " grade"
45 Check the offered ciphers
46 .TP
47 .BR " --check-ciphers-warnings"
48 Critical if nmap reports a warning for an offered cipher
49 .TP
50 .BR " --check-http-headers"
51 Check the HTTP headers for best practices
52 .TP
53 .BR " --check-ssl-labs-warn grade"
54 SSL Labs grade on which to warn
55 .TP
56 .BR " --clientpass" " phrase"
57 Set passphrase for client certificate.
58 .TP
59 .BR " --configuration" " file"
60 Read options from the specified file
61 .TP
62 .BR " --crl"
63 Check revocation via CRL (requires --rootcert-file)
64 .TP
65 .BR " --curl-bin" " path"
66 Path of the curl binary to be used
67 .TP
68 .BR " --custom-http-header" " string"
69 Custom HTTP header sent when getting the cert example: 'X-Check-Ssl-Cert: Foobar=1'
70 .TP
71 .BR " --dane"
72 Verify that valid DANE records exist (since OpenSSL 1.1.0)
73 .TP
74 .BR " --dane 211"
75 Verify that a valid DANE-TA(2) SPKI(1) SHA2-256(1) TLSA record exists
76 .TP
77 .BR " --dane 301"
78 Verify that a valid DANE-EE(3) Cert(0) SHA2-256(1) TLSA record exists
79 .TP
80 .BR " --dane 302"
81 Verify that a valid DANE-EE(3) Cert(0) SHA2-512(2) TLSA record exists
82 .TP
83 .BR " --dane 311"
84 Verify that a valid DANE-EE(3) SPKI(1) SHA2-256(1) TLSA record exists
85 .TP
86 .BR " --dane 312"
87 Verify that a valid DANE-EE(3) SPKI(1) SHA2-512(1) TLSA record exists
88 .TP
89 .BR " --date" " path"
90 Path of the date binary to be used
91 .TP
92 .BR "-d,--debug"
93 Produce debugging output (can be specified more than once)
94 .TP
95 .BR " --debug-cert"
96 Store the retrieved certificates in the current directory
97 .TP
98 .BR " --debug-file" " file"
99 Write the debug messages to file
100 .TP
101 .BR " --debug-headers"
102 Store the retrieved HTLM headers in the headers.txt file
103 .TP
104 .BR " --debug-time"
105 Write timing information in the debugging output
106 .TP
107 .BR " --default-format"
108 Print the default output format and exit
109 .TP
110 .BR " --dig-bin" " path"
111 Path of the dig binary to be used
112 .TP
113 .BR " --do-not-resolve"
114 Do not check if the host can be resolved
115 .TP
116 .BR " --dtls"
117 Use the DTLS protocol
118 .TP
119 .BR " --dtls1"
120 Use the DTLS protocol 1.0
121 .TP
122 .BR " --dtls1_2"
123 Use the DTLS protocol 1.2
124 .TP
125 .BR "-e,--email" " address"
126 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')
127 .TP
128 .BR " --ecdsa"
129 Signature algorithm selection: force ECDSA certificate
130 .TP
131 .BR " --element" " number"
132 Check up to the N cert element from the beginning of the chain
133 .TP
134 .BR " --file-bin" " path"
135 Path of the file binary to be used
136 .TP
137 .BR " --fingerprint" " hash"
138 Pattern to match the fingerprint
139 .TP
140 .BR " --fingerprint-alg" " algorithm"
141 Algorithm for fingerprint. Default sha1
142 .TP
143 .BR " --first-element-only"
144 Verify just the first cert element, not the whole chain
145 .TP
146 .BR " --force-dconv-date"
147 Force the usage of dconv for date computations
148 .TP
149 .BR " --force-perl-date"
150 Force the usage of Perl for date computations
151 .TP
152 .BR " --format" " FORMAT"
153 Format output template on success, for example: '%SHORTNAME% OK %CN% from %CA_ISSUER_MATCHED%'
154 .br
155 List of possible variables:
156 .br
157 - %CA_ISSUER_MATCHED%
158 .br
159 - %CHECKEDNAMES%
160 .br
161 - %CN%
162 .br
163 - %DATE%
164 .br
165 - %DAYS_VALID%
166 .br
167 - %DYSPLAY_CN%
168 .br
169 - %HOST%
170 .br
171 - %OCSP_EXPIRES_IN_HOURS%
172 .br
173 - %OPENSSL_COMMAND%
174 .br
175 - %PORT%
176 .br
177 - %SELFSIGNEDCERT%
178 .br
179 - %SHORTNAME%
180 .br
181 - %SIGALGO%
182 .br
183 - %SSL_LABS_HOST_GRADE%
184 .br
185 See --default-format for the default
186 .TP
187 .BR " --grep-bin" " path"
188 Path of the grep binary to be used
189 .TP
190 .BR "-h,--help,-?"
191 This help message
192 .TP
193 .BR " --http-headers-path" " path"
194 The path to be used to fetch HTTP headers
195 .TP
196 .BR " --http-use-get"
197 Use GET instead of HEAD (default) for the HTTP related checks
198 .TP
199 .BR "-i,--issuer" " issuer"
200 Pattern (extended regular expression) to match the issuer of the certificate. You can specify different issuers separated by a pipe (e.g., 'issuer1|issuer2')
201 .TP
202 .BR " --ignore-altnames"
203 Ignore alternative names when matching pattern specified in -n (or the host name)
204 .TP
205 .BR " --ignore-connection-problems" " [state]"
206 In case of connection problems returns OK or the optional state
207 .TP
208 .BR " --ignore-crl"
209 Ignore CRLs
210 .TP
211 .BR " --ignore-dh"
212 Ignore too small DH keys
213 .TP
214 .BR " --ignore-exp"
215 Ignore expiration date
216 .TP
217 .BR " --ignore-http-headers"
218 Ignore checks on HTTP headers with --all and --all-local
219 .TP
220 .BR " --ignore-host-cn"
221 Do not complain if the CN does not match the host name
222 .TP
223 .BR " --ignore-incomplete-chain"
224 Do not check chain integrity
225 .TP
226 .BR " --ignore-maximum-validity"
227 Ignore the certificate maximum validity
228 .TP
229 .BR " --ignore-ocsp"
230 Do not check revocation with OCSP
231 .TP
232 .BR " --ignore-ocsp-errors"
233 Continue if the OCSP status cannot be checked
234 .TP
235 .BR " --ignore-ocsp-timeout"
236 Ignore OCSP result when timeout occurs while checking
237 .TP
238 .BR " --ignore-sct"
239 Do not check for signed certificate timestamps (SCT)
240 .TP
241 .BR " --ignore-sig-alg"
242 Do not check if the certificate was signed with SHA1 or MD5
243 .TP
244 .BR " --ignore-ssl-labs-cache"
245 Force a new check by SSL Labs (see -L)
246 .TP
247 .BR " --ignore-ssl-labs-errors"
248 Ignore errors if SSL Labs is not accessible or times out
249 .TP
250 .BR " --ignore-tls-renegotiation"
251 Ignore the TLS renegotiation check
252 .TP
253 .BR " --ignore-unexpected-eof"
254 Ignore unclean TLS shutdowns
255 .TP
256 .BR " --inetproto protocol"
257 Force IP version 4 or 6
258 .TP
259 .BR " --info"
260 Print certificate information
261 .TP
262 .BR " --init-host-cache"
263 Initialize the host cache
264 .TP
265 .BR " --issuer-cert-cache" " dir"
266 Directory where to store issuer certificates cache
267 .TP
268 .BR " --jks-alias" " alias"
269 Alias name of the Java KeyStore entry (requires --file)
270 .TP
271 .BR "-K,--clientkey" " path"
272 Use client certificate key to authenticate
273 .TP
274 .BR "-L,--check-ssl-labs grade"
275 SSL Labs assessment (please check https://www.ssllabs.com/about/terms.html). Critical if the grade is lower than specified.
276 .TP
277 .BR " --long-output" " list"
278 Append the specified comma separated (no spaces) list of attributes to the plugin output on additional lines.
279 Valid attributes are: enddate, startdate, subject, issuer, modulus, serial, hash, email, ocsp_uri and fingerprint. 'all' will include all the available attributes.
280 .TP
281 .BR "-m,--match" " name"
282 Pattern to match the CN or AltName (can be specified multiple times)
283 .TP
284 .BR " --maximum-validity" " [days]"
285 The maximum validity of the certificate must not exceed 'days' (default 397). This check is automatic for HTTPS
286 .TP
287 .BR " --nmap-bin" " path"
288 Path of the nmap binary to be used
289 .TP
290 .BR " --nmap-with-proxy"
291 Allow nmap to be used with a proxy
292 .TP
293 .BR " --no-perf"
294 Do not show performance data
295 .TP
296 .BR " --no-proxy"
297 Ignore the http_proxy and https_proxy environment variables
298 .TP
299 .BR " --no-proxy-curl"
300 Ignore the http_proxy and https_proxy environment variables for curl
301 .TP
302 .BR " --no-proxy-s_client"
303 Ignore the http_proxy and https_proxy environment variables for openssl s_client
304 .TP
305 .BR " --no-ssl2"
306 Disable SSL version 2
307 .TP
308 .BR " --no-ssl3"
309 Disable SSL version 3
310 .TP
311 .BR " --no-tls1"
312 Disable TLS version 1
313 .TP
314 .BR " --no-tls1_1"
315 Disable TLS version 1.1
316 .TP
317 .BR " --no-tls1_3"
318 Disable TLS version 1.3
319 .TP
320 .BR " --no-tls1_2"
321 Disable TLS version 1.2
322 .TP
323 .BR " --not-issued-by" " issuer"
324 Check that the issuer of the certificate does not match the given pattern
325 .TP
326 .BR " --not-valid-longer-than" " days"
327 Critical if the certificate validity is longer than the specified period
328 .TP
329 .BR "-o,--org" " org"
330 Pattern to match the organization of the certificate
331 .TP
332 .BR " --ocsp-critical" " hours"
333 Minimum number of hours an OCSP response has to be valid to issue a critical status
334 .TP
335 .BR " --ocsp-warning" " hours"
336 Minimum number of hours an OCSP response has to be valid to issue a warning status
337 .TP
338 .BR " --openssl" " path"
339 Path of the openssl binary to be used
340 .TP
341 .BR "-p,--port" " port"
342 TCP port (default 443)
343 .TP
344 .BR "--precision" " digits"
345 Number of decimal places for durations: defaults to 0 if critical or warning are integers, 2 otherwise
346 .TP
347 .BR "-P,--protocol" " protocol"
348 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.
349 .BR
350 These protocols switch to TLS using StartTLS: ftp, imap, irc, ldap, mysql, pop3, smtp.
351 .TP
352 .BR " --path" " path"
353 Set the PATH variable to 'path'
354 .TP
355 .BR " --password" " source"
356 Password source for a local certificate, see the PASS PHRASE ARGUMENTS section openssl(1)
357 .TP
358 .BR " --prometheus"
359 Generate Prometheus/OpenMetrics output
360 .TP
361 .BR " --proxy" " proxy"
362 Set http_proxy and the s_client -proxy option
363 .TP
364 .BR " --python-bin" " path"
365 Path of the python binary to be used
366 .TP
367 .BR " --quic"
368 Use QUIC
369 .TP
370 .BR "-q,--quiet"
371 Do not produce any output
372 .TP
373 .BR "-r,--rootcert" " cert"
374 Root certificate or directory to be used for certificate validation (passed to openssl's -CAfile or -CApath)
375 .TP
376 .BR " --require-client-cert" " [list]"
377 The server must accept a client certificate. 'list' is an optional comma separated list of expected client certificate CAs
378 .TP
379 .BR " --require-dnssec"
380 Require DNSSEC
381 .TP
382 .BR " --require-http-header" " header"
383 Require the specified HTTP header (e.g., strict-transport-security)
384 .TP
385 .BR " --require-no-http-header" " header"
386 Require the absence of the specified HTTP header (e.g., X-Powered-By)
387 .TP
388 .BR " --require-no-ssl2"
389 Critical if SSL version 2 is offered
390 .TP
391 .BR " --require-no-ssl3"
392 Critical if SSL version 3 is offered
393 .TP
394 .BR " --require-no-tls1"
395 Critical if TLS 1 is offered
396 .TP
397 .BR " --require-no-tls1_1"
398 Critical if TLS 1.1 is offered
399 .TP
400 .BR " --require-no-tls1_2"
401 Critical if TLS 1.2 is offered
402 .TP
403 .BR " --require-ocsp-stapling"
404 Require OCSP stapling
405 .TP
406 .BR " --require-purpose" " usage"
407 Require the specified key usage (can be specified more then once)
408 .TP
409 .BR " --require-purpose-critical"
410 The key usage must be critical
411 .TP
412 .BR " --require-security-header" " header"
413 Require the specified HTTP security header (e.g., X-Frame-Options)
414 .TP
415 .BR " --require-security-headers"
416 Require all the HTTP security headers:
417 Content-Security-Policy
418 Permissions-Policy
419 Referrer-Policy
420 strict-transport-security
421 X-Content-Type-Options
422 X-Frame-Options
423 .TP
424 .BR " --resolve" " ip"
425 Provide a custom IP address for the specified host
426 .TP
427 .BR " --resolve-over-http" " [server]"
428 Resolve the host over HTTP using Google or the specified server
429 .TP
430 .BR " --rootcert-dir" " dir"
431 Root directory to be used for certificate validation (passed to openssl's -CApath)
432 overrides option -r,--rootcert
433 .TP
434 .BR " --rootcert-file" " cert"
435 Root certificate to be used for certificate validation (passed to openssl's -CAfile)
436 overrides option -r,--rootcert
437 .TP
438 .BR " --rsa"
439 Signature algorithm selection: force RSA certificate
440 .TP
441 .BR " --security-level" " number"
442 Set the security level to specified value. See SSL_CTX_set_security_level(3) for a description of what each level means
443 .TP
444 .BR "-s,--selfsigned"
445 Allow self-signed certificates
446 .TP
447 .BR " --serial" " serialnum"
448 Pattern to match the serial number
449 .TP
450 .BR "--skip-element" " number"
451 Skip checks on the Nth cert element (can be specified multiple times)
452 .TP
453 .BR " --sni" " name"
454 Set the TLS SNI (Server Name Indication) extension in the ClientHello message to 'name'
455 .TP
456 .BR " --ssl2"
457 Force SSL version 2
458 .TP
459 .BR " --ssl3"
460 Force SSL version 3
461 .TP
462 .BR "-t,--timeout" " seconds"
463 Timeout after the specified time (defaults to 120 seconds)
464 .TP
465 .BR " --temp" " dir"
466 Directory where to store the temporary files
467 .TP
468 .BR " --terse"
469 Terse output (also see --verbose)
470 .TP
471 .BR " --tls1"
472 Force TLS version 1
473 .TP
474 .BR " --tls1_1"
475 Force TLS version 1.1
476 .TP
477 .BR " --tls1_2"
478 Force TLS version 1.2
479 .TP
480 .BR " --tls1_3"
481 Force TLS version 1.3
482 .TP
483 .BR "-u,--url" " URL"
484 HTTP request URL
485 .TP
486 .BR " --user-agent" " string"
487 User agent that shall be used for HTTPS connections
488 .TP
489 .BR "-v,--verbose"
490 Verbose output (can be specified more than once)
491 .TP
492 .BR "-V,--version"
493 Version
494 .TP
495 .BR "-w,--warning" " days"
496 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
497 .TP
498 .BR " --xmpphost" " name"
499 Specify the host for the 'to' attribute of the stream element
500 .TP
501 .BR "-4"
502 Force IPv4
503 .TP
504 .BR "-6"
505 Force IPv6
506 .SH DEPRECATED OPTIONS
507 .TP
508 .BR " --altnames"
509 Match the pattern specified in -n with alternate names too (enabled by default)
510 .TP
511 .BR "-n,--cn" " name"
512 Pattern to match the CN or AltName (can be specified multiple times)
513 .TP
514 .BR " --curl-user-agent" " string"
515 User agent that curl shall use to obtain the issuer cert
516 .TP
517 .BR "-d,--days" " days"
518 Minimum number of days a certificate has to be valid (see --critical and --warning)
519 .TP
520 .BR "-N,--host-cn"
521 Match CN with the host name (enabled by default)
522 .TP
523 .BR " --no_ssl2"
524 Disable SSLv2 (deprecated use --no-ssl2)
525 .TP
526 .BR " --no_ssl3"
527 Disable SSLv3 (deprecated use --no-ssl3)
528 .TP
529 .BR " --no_tls1"
530 Disable TLSv1 (deprecated use --no-tls1)
531 .TP
532 .BR " --no_tls1_1"
533 Disable TLSv1.1 (deprecated use --no-tls1_1)
534 .TP
535 .BR " --no_tls1_2"
536 Disable TLSv1.1 (deprecated use --no-tls1_2)
537 .TP
538 .BR " --no_tls1_3"
539 Disable TLSv1.1 (deprecated use --no-tls1_3)
540 .TP
541 .BR " --ocsp"
542 Check revocation via OCSP (enabled by default)
543 .TP
544 .BR " --require-hsts"
545 Require HTTP Strict Transport Security (deprecated use --require-security-header strict-transport-security)
546 .TP
547 .BR " --require-security-headers-path" " path"
548 the path to be used to fetch HTTP security headers
549 .TP
550 .BR " --require-san"
551 Require the presence of a Subject Alternative Name extension
552 .TP
553 .BR " --require-x-frame-options [path]"
554 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)
555 .TP
556 .BR "-S,--ssl" " version"
557 Force SSL version (2,3) (see: --ssl2 or --ssl3)
558
559 .SH CONFIGURATION
560
561 Command line options can be specified in a configuration file (${HOME}/.check_ssl_certrc). For example
562
563 $ cat ${HOME}/.check_ssl_certrc
564 --verbose
565 --critical 20
566 --warning 40
567
568 Options specified in the configuration file are read before processing the arguments and can be overridden.
569
570 .SH NOTES
571 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.
572
573 .SH "EXIT STATUS"
574 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
575 .SH BUGS
576 Please report bugs to:
577 https://github.com/matteocorti/check_ssl_cert/issues
578
579 .SH "EXAMPLE"
580 check_ssl_cert --host github.com --all-local
581
582 .SH "SEE ALSO"
583 openssl(1), openssl-x509(1)