Skip to main content
Monitoring as Code: Learn more about the SSL Monitor Construct.

​
What are SSL Monitors?

SSL monitors verify the health of a TLS certificate by connecting to a hostname, completing a full TLS handshake, and inspecting the resulting certificate and negotiated protocol parameters. Typical use cases include:
  • Detecting certificate expiry before it causes user-facing errors
  • Verifying that a recently-renewed certificate is deployed to all your servers
  • Enforcing minimum TLS version and cipher strength across your infrastructure
  • Catching chain trust failures caused by missing intermediate certificates
  • Alerting on weak or compromised certificate authority usage

​
How do SSL Monitors work?

Each SSL monitor run performs the following steps:
  1. DNS resolution — If a hostname is provided, Checkly resolves it to an IP address
  2. TCP connect — A TCP connection is opened to the target host and port (default: 443)
  3. TLS handshake — A full TLS handshake is performed; an optional SNI server name override can be sent during this step
  4. Certificate inspection — The leaf certificate and chain are examined: expiry date, hostname verification, chain trust, signature algorithm, key size, SANs, and fingerprints are all captured
  5. Security baseline evaluation — On a successful handshake and certificate verification, a configurable rule set evaluates the negotiated protocol (TLS version, cipher suite, CA trust) and produces a per-rule verdict plus an overall grade and verdict (pass / warn / fail). The baseline is skipped when an earlier step fails (e.g. hostname mismatch or chain untrusted).
  6. Assertions — Optional assertions are evaluated against the certificate and handshake data

​
SSL Monitor Results

Select a specific check run to inspect its results:
  • Summary: Shows the target hostname and port, the monitor state (passed, degraded, or failed), and the TLS handshake time
  • Error details: If the run failed, the error category and message explain what went wrong. Categories map to the stage where the failure occurred: dns (name resolution), connect (TCP connection), timeout or handshake (TLS handshake), hostname (certificate does not cover the monitored hostname), or chain (certificate chain not trusted). An expired certificate surfaces as a failure via a negative daysUntilExpiry value rather than a separate category.
  • Handshake data: The negotiated TLS version, cipher suite, and handshake duration in milliseconds
  • Certificate details: Subject, issuer, serial number, validity window (not-before / not-after), days until expiry, signature algorithm, key algorithm and size, subject alternative names (SANs), and SHA-256 fingerprint
  • Security baseline: The per-rule verdict table and the aggregate grade (A-, B, or F) produced by the security baseline evaluation
  • Certificate chain: The intermediate and root certificates presented during the handshake, with their subjects, issuers, validity dates, and fingerprints
Learn more in our documentation on Results.

​
The Security Baseline

The security baseline is a built-in rule set that evaluates each successful handshake and certificate verification against current best practices without requiring explicit assertions. Rules cover: The aggregate grade is computed from the worst rule outcome: You can override the default severity for each rule or disable the baseline entirely in the SSL Config.

​
Troubleshooting Common Issues

This can happen when a server hosts multiple certificates and the default certificate served to Checkly does not cover the monitored hostname. The runner reports this as failure category hostname. Use the SNI server name (serverName) option in the SSL config to explicitly request the certificate for your hostname.If the certificate is legitimately shared across hostnames (e.g. a wildcard *.example.com that covers api.example.com) and hostname verification still fails, confirm the SAN list on the certificate contains the monitored hostname.
A chain trust failure (failure category chain) means one or more intermediate certificates are missing or the root is not trusted. Common causes:
  • The server is not sending the full intermediate chain — verify with openssl s_client -connect hostname:443 -showcerts
  • The certificate was issued by a CA whose root was recently distrusted (e.g. Entrust 2024)
  • Self-signed or internal CA certificates — enable Skip chain validation in the SSL config if you only want to monitor expiry and other properties without trust verification
The alertDaysBeforeExpiry setting (default: 20 days) controls when a degraded alert is raised due to approaching expiry. If you use aggressive certificate rotation you may want to lower this value; if you need more lead time to trigger your renewal process, raise it. The monitor always fails immediately when the certificate is expired (daysUntilExpiry < 0), regardless of this setting.