Experimental TLS/SSL certificate command-line checker
docker run josebovet/tlschecker:1.1.0 jpbd.devIf you are utilizing M1 or higher, please add the option --platform linux/x86_64.
docker run --platform linux/x86_64 josebovet/tlschecker:1.1.0 jpbd.devLinux
curl -LO https://github.com/jbovet/tlschecker/releases/download/v1.1.0/tlschecker-linux.zip
unzip tlschecker-linux.zip
chmod 755 tlschecker
sudo install tlschecker /usr/local/bin/tlscheckerOsx
curl -LO https://github.com/jbovet/tlschecker/releases/download/v1.1.0/tlschecker-macos.zip
unzip tlschecker-macos.zip
chmod 755 tlschecker
sudo install tlschecker /usr/local/bin/tlschecker➜ tlschecker --helpBasic usage:
➜ tlschecker --check-revocation x.com revoked.badssl.com jpbd.dev expired.badssl.com Using custom ports:
➜ tlschecker example.com:8443 secure-service.internal:9443You can specify the port in three ways:
- Using hostname:port format:
example.com:8443 - Using a full URL:
https://example.com:8443 - Using the default port (443) by just specifying the hostname:
example.com
TLSChecker supports comprehensive certificate revocation checking via both OCSP (Online Certificate Status Protocol) and CRL (Certificate Revocation List). These features allow you to verify if a certificate has been revoked by its issuing Certificate Authority.
To enable revocation checking, use the --check-revocation flag:
➜ tlschecker --check-revocation jpbd.devWhen you enable revocation checking, TLSChecker will:
- First check certificate status via OCSP, which provides real-time revocation information
- If OCSP doesn't provide a definitive answer, fall back to CRL checking
- Report the certificate as revoked if either method indicates revocation
The revocation status will be displayed in the output:
- Valid: Certificate is not revoked (confirmed by OCSP or CRL)
- Revoked: Certificate has been revoked (with reason if available)
- Unknown: Revocation status couldn't be determined
- Not Checked: Revocation status was not checked (default when not using the flag)
Example with a revoked certificate:
➜ tlschecker --check-revocation revoked.badssl.comOCSP (Online Certificate Status Protocol):
- Real-time check with the certificate authority
- Faster and more up-to-date than CRLs
- May not be supported by all certificate authorities
CRL (Certificate Revocation List):
- Downloads and checks the CA's published list of revoked certificates
- More widely supported than OCSP
- Lists may be larger and less frequently updated
Note: Revocation checking requires network connections to OCSP responders and CRL distribution points, which adds some latency to the checks.
When using Prometheus integration, the revocation status is included in the metrics:
tlschecker --prometheus --prometheus-address http://localhost:9091 --check-revocation example.comA tlschecker_revocation_status metric is exported with the following values:
- 0 = Not checked
- 1 = Good (not revoked)
- 2 = Unknown
- 3 = Revoked
Additionally, a revoked label is added to all metrics with a boolean value indicating whether the certificate is revoked.
If you encounter connection problems, here are some common error messages and solutions:
-
"Cannot resolve hostname"
- Check that the hostname is spelled correctly
- Verify your network and DNS configuration
- Try using an IP address instead if DNS resolution is not available
-
"Connection refused"
- Verify the host is running a TLS service on the specified port
- Check if a firewall might be blocking the connection
- Confirm the service is publicly accessible
-
"TLS handshake failed"
- The server might be using an unsupported TLS version
- There might be an issue with the server's certificate configuration
- Your network might be intercepting the TLS connection
You can use a TOML configuration file to check multiple hosts. Create a file like tlschecker.toml:
hosts = [
"example.com",
"example.com:8443",
"secure-service.internal:9443"
]
# Optional settings
check_revocation = true
output_format = "json"
prometheus = false
prometheus_address = "http://localhost:9091"Then run TLSChecker with the config file:
➜ tlschecker -c example-tlschecker.tomlSee tlschecker-example.toml for a complete configuration example.