# SSL Monitor Configuration - Checkly Docs

> Configure your SSL monitor to track certificate health, expiry, and TLS security posture.

Source: https://www.checklyhq.com/docs/detect/uptime-monitoring/ssl-monitors/configuration/

---

- Basic Setup
- SSL Configuration
- Client Certificate / mTLS
- Security Baseline
- Assertions
- Response Time Limits
- Frequency
- Scheduling & Locations
- Additional Settings

SSL Monitors

# SSL Monitor Configuration

Configure your SSL monitor to track certificate health, expiry, and TLS security posture.

To configure an SSL monitor using code, learn more about the [SSL Monitor Construct](https://www.checklyhq.com/docs/constructs/ssl-monitor).

### ​ Basic Setup

Configure your SSL monitor by specifying the target host:

- **Hostname:** The domain or IP address to connect to (e.g. `api.example.com`). Do not include a scheme or port.

- **Port:** The TCP port to connect to. Defaults to `443`.

- **IP family:** Choose between IPv4 (default) or IPv6.

### ​ SSL Configuration

Fine-grained control over the TLS handshake behavior:

- **SNI server name (`serverName`):** Override the Server Name Indication sent during the TLS handshake. Useful when a single IP serves multiple certificates and you want to request a specific one. Defaults to the configured hostname when unset.

- **Handshake timeout:** Maximum time in milliseconds to wait for the TLS handshake to complete. Range: 1,000–30,000 ms. Default: 10,000 ms.

- **Alert days before expiry (`alertDaysBeforeExpiry`):** Raise a degraded alert when the certificate is within this many days of expiry. Range: 1–365 days. Default: 20 days. The monitor always fails immediately if the certificate is already expired.

- **Skip chain validation:** When enabled, Checkly does not verify the certificate chain against trusted roots. The certificate is still inspected for expiry and the security baseline. Use this when monitoring internal or self-signed certificates.

### ​ Client Certificate / mTLS

SSL monitors can present a client certificate during the TLS handshake to verify mTLS-protected endpoints:

- **`clientCertificateMode: 'auto'`** — Checkly automatically selects a stored client certificate for the target host.

- **`clientCertificateMode: 'explicit'`** — Use the specific certificate identified by `sslClientCertificateId`.

Omit `clientCertificateMode` to connect without a client certificate (the default).
Client certificates are stored at the account level under **Settings → Client Certificates**.

### ​ Security Baseline

The security baseline is a configurable rule set that evaluates the negotiated TLS session against best-practice requirements. It runs on each successful handshake and certificate verification, and produces a **verdict** (`pass` / `warn` / `fail`) and a **grade** (`A-`, `B`, or `F`). It is skipped when an earlier step fails (e.g. hostname mismatch or chain untrusted).
You can override the default severity for each rule:
Rule Default severity Configurable

`minTLSVersion` `fail` ✅

`minKeySizeBits` `fail` ✅

`weakSignatureAlgorithm` `fail` ✅

`weakCipherSuite` `fail` ✅

`knownBadCA` `fail` ✅

`recommendedTLSVersion` `ignore` ✅

`recommendedKeySizeBits` `ignore` ✅

`ocspMustStapleRespected` `ignore` ✅

`sctPresent` `ignore` ✅

Each rule accepts a `severity` of `fail`, `degrade`, or `ignore`. Set `enabled: false` to disable the baseline entirely for a monitor.

Omitting the `securityBaseline` field applies Checkly’s built-in default baseline (the defaults listed above). Override it on a per-monitor basis only when you need non-standard thresholds for a specific endpoint.

### ​ Assertions

Use assertions to validate specific certificate and TLS handshake properties beyond what the security baseline covers.
Each assertion has a `source`, an optional `property` (a field selector), a `comparison`, and a `target`. Available sources:
Source `property` Description

`CERTIFICATE` a certificate field (see below) Assert on a leaf-certificate field

`CONNECTION` a connection field (see below) Assert on a TLS handshake / connection field

`RESPONSE_TIME` — TLS handshake duration in milliseconds

`JSON_RESPONSE` JSONPath Assert on any field of the response document via a JSONPath expression (e.g. `$.chain[0].keySizeBits`)

`TEXT_RESPONSE` regex Extract a value from the serialized response with a regex, then compare

`CERTIFICATE` `property` values:
`property` Type Description

`daysUntilExpiry` number Days until the certificate expires

`subjectCN` string Certificate subject common name

`issuerCN` string Common name of the certificate issuer

`serialNumber` exact Certificate serial number

`fingerprintSha256` exact SHA-256 fingerprint of the leaf certificate

`issuerFingerprintSha256` exact SHA-256 fingerprint of the issuer certificate

`keySizeBits` number Leaf certificate public key size in bits

`keyAlgorithm` exact Public key algorithm (e.g. `RSA`, `ECDSA`)

`signatureAlgorithm` exact Leaf certificate signature algorithm (e.g. `SHA256-RSA`, `ECDSA-SHA256`)

`sans` list Subject Alternative Names

`selfSigned` boolean The leaf certificate is self-signed

`isCA` boolean The leaf certificate is a CA certificate

`CONNECTION` `property` values:
`property` Type Description

`tlsVersion` version Negotiated TLS protocol version (e.g. `TLS1.2`, `TLS1.3`)

`cipherSuite` string IANA cipher suite name negotiated during the handshake

`hostnameVerified` boolean The certificate’s SANs cover the monitored hostname

`chainTrusted` boolean The full certificate chain is trusted by the system root store

`ocspStapled` boolean A stapled OCSP response was included in the handshake

`ocspStatus` exact Decoded stapled-OCSP status: `good`, `revoked`, or `unknown`

`resolvedIp` string The IP address the hostname resolved to

The comparisons available depend on the property’s type:
Type Comparisons

`number` `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN`

`version` `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN` (ordered `TLS1.0` < `TLS1.1` < `TLS1.2` < `TLS1.3`)

`string` `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`

`exact` `EQUALS`, `NOT_EQUALS`

`list` `CONTAINS`, `NOT_CONTAINS` (SAN membership)

`boolean` `EQUALS`

The other sources take their own comparison sets: `RESPONSE_TIME` uses the `number` set; `JSON_RESPONSE` accepts `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN`, `CONTAINS`, `NOT_CONTAINS`, `IS_EMPTY`, `NOT_EMPTY`, `IS_NULL`, `NOT_NULL`; `TEXT_RESPONSE` accepts `EQUALS`, `NOT_EQUALS`, `CONTAINS`, `NOT_CONTAINS`, `IS_EMPTY`, `NOT_EMPTY`, `GREATER_THAN`, `LESS_THAN`.

Certificate validity, minimum TLS version and minimum key size are also enforced by the security baseline above — reach for assertions when you need an exact value check (a specific issuer, fingerprint pinning, a SAN, etc.).

For more details, see our documentation on [Assertions](https://www.checklyhq.com/docs/detect/assertions).

### ​ Response Time Limits

Set performance thresholds based on the TLS handshake duration:

- **Degraded After:** Handshake time (in milliseconds) at or above which the monitor is marked as degraded but not failed. Range: 0–30,000 ms. Default: 3,000 ms.

- **Failed After:** Handshake time at or above which the monitor fails. Must be greater than or equal to the degraded threshold. Range: 0–30,000 ms. Default: 10,000 ms.

### ​ Frequency

Set how often the monitor runs. SSL monitors run at most **once per minute** (every 1 minute to 24 hours) — sub-minute frequencies aren’t available, since certificate state changes slowly.

### ​ Scheduling & Locations

- **Strategy:** Choose between round-robin or parallel execution. Learn more about [scheduling strategies](https://www.checklyhq.com/docs/concepts/scheduling).

- **Locations:** Select [public](https://www.checklyhq.com/docs/concepts/locations#public-locations) or [private](https://www.checklyhq.com/docs/platform/private-locations/overview) locations to run the monitor from.

### ​ Additional Settings

- **Name:** Give your monitor a clear name to identify it in dashboards and alerts.

- **Description:** Add context about what this monitor does and why it matters. Supports markdown, max 500 characters. When a failure occurs, [Rocky AI](https://www.checklyhq.com/docs/ai/rocky-ai) uses the description to provide more accurate [root cause and user impact analysis](https://www.checklyhq.com/docs/resolve/ai-root-cause-analysis/overview).

- **Tags:** Use tags to organize monitors across [dashboards](https://www.checklyhq.com/docs/communicate/dashboards/overview) and [maintenance windows](https://www.checklyhq.com/docs/communicate/maintenance-windows/overview).

- **Retries:** Define how failed runs should be retried. See [retry strategies](https://www.checklyhq.com/docs/communicate/alerts/retries).

- **Alerting:** Configure your [alert settings](https://www.checklyhq.com/docs/communicate/alerts/configuration), [alert channels](https://www.checklyhq.com/docs/communicate/alerts/channels), or set up [webhooks](https://www.checklyhq.com/docs/integrations/alerts/webhooks) for custom integrations.

Was this page helpful?

[Suggest edits](https://github.com/checkly/docs/edit/main/detect/uptime-monitoring/ssl-monitors/configuration.mdx)[Raise issue](https://github.com/checkly/docs/issues/new?title=Issue%20on%20docs&body=Path:%20/detect/uptime-monitoring/ssl-monitors/configuration)

[SSL Monitor Overview Previous](https://www.checklyhq.com/docs/detect/uptime-monitoring/ssl-monitors/overview)[Heartbeat Monitors Next](https://www.checklyhq.com/docs/detect/uptime-monitoring/heartbeat-monitors/overview)

[x](https://x.com/checklyhq)[github](https://github.com/checkly)[linkedin](https://linkedin.com/company/checkly)

[Powered by This documentation is built and hosted on Mintlify, a developer documentation platform](https://www.mintlify.com/?utm_campaign=poweredBy&utm_medium=referral&utm_source=checkly-422f444a)