> ## Documentation Index
> Fetch the complete documentation index at: https://www.checklyhq.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SSL Monitor Configuration

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

<Tip>
  To configure an SSL monitor using code, learn more about the [SSL Monitor Construct](/constructs/ssl-monitor).
</Tip>

### 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.

<Note>
  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.
</Note>

### 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`.

<Note>
  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.).
</Note>

For more details, see our documentation on [Assertions](/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](/concepts/scheduling).
* **Locations:** Select [public](/concepts/locations/#public-locations) or [private](/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](/ai/rocky-ai) uses the description to provide more accurate [root cause and user impact analysis](/resolve/ai-root-cause-analysis/overview).
* **Tags:** Use tags to organize monitors across [dashboards](/communicate/dashboards/overview/) and [maintenance windows](/communicate/maintenance-windows/overview).
* **Retries:** Define how failed runs should be retried. See [retry strategies](/communicate/alerts/retries).
* **Alerting:** Configure your [alert settings](/communicate/alerts/configuration), [alert channels](/communicate/alerts/channels), or set up [webhooks](/integrations/alerts/webhooks) for custom integrations.