docs: fix SSL monitor accuracy issues from review

- Replace fabricated failure-category strings (EXPIRED_CERT,
  HOSTNAME_MISMATCH, HANDSHAKE_TIMEOUT) with the six real runner
  categories: dns, connect, timeout, handshake, hostname, chain.
  Note that an expired cert is a failure state (daysUntilExpiry < 0),
  not a separate category.
- Fix accordion titles to describe behavior rather than invented enums.
- Clarify security baseline runs only on a successful handshake and
  certificate verification, not on hostname/chain failure.
- Fix ">= threshold" wording: "above which" → "at or above which" for
  degradedResponseTime and maxResponseTime; add 0–30,000 ms range.
- Add sslClientCertificateId as an explicit SslConfig ResponseField
  in the construct reference.
- Expand weak-signature algorithm list to include MD2-RSA and
  ECDSA-SHA1 (matching baseline.go isWeakSignature).

Author: danielpaulus

constructs/ssl-monitor.mdx

@@ -137,7 +137,7 @@ new SslMonitor("my-ssl-monitor", {
 </ResponseField>
 
 <ResponseField name="degradedResponseTime" type="number" default="3000">
-TLS handshake time in milliseconds above which the monitor is marked as degraded (warning state). Must be ≤ `maxResponseTime`.
+TLS handshake time in milliseconds at or above which the monitor is marked as degraded (warning state). Range: 0–30,000 ms. Must be ≤ `maxResponseTime`.
 
 **Usage:**
 
@@ -155,7 +155,7 @@ new SslMonitor("my-ssl", {
 </ResponseField>
 
 <ResponseField name="maxResponseTime" type="number" default="10000">
-TLS handshake time in milliseconds above which the monitor is marked as failed.
+TLS handshake time in milliseconds at or above which the monitor is marked as failed. Range: 0–30,000 ms.
 
 **Usage:**
 
@@ -230,6 +230,17 @@ sslConfig: {
 ```
 </ResponseField>
 
+<ResponseField name="sslClientCertificateId" type="string">
+The ID of the stored client certificate to present during the TLS handshake. Required when `clientCertificateMode` is `'explicit'`. Client certificates are managed under **Settings → Client Certificates** in the Checkly dashboard.
+
+```ts
+sslConfig: {
+  clientCertificateMode: "explicit",
+  sslClientCertificateId: "cert_abc123",
+}
+```
+</ResponseField>
+
 <ResponseField name="securityBaseline" type="SecurityBaseline">
 Override the account-level security baseline for this monitor. Omit to inherit the account default.
 
@@ -254,7 +265,7 @@ sslConfig: {
 | `enabled` | `boolean` | `true` | Enable or disable baseline evaluation |
 | `minTLSVersion` | `{ value?: string, severity? }` | `fail` | Minimum required TLS version (e.g. `'TLS1.2'`) |
 | `minKeySizeBits` | `{ value?: number, severity? }` | `fail` | Minimum RSA key size in bits |
-| `weakSignatureAlgorithm` | `{ severity? }` | `fail` | Reject weak signature algorithms (MD5, SHA-1, DSA-SHA1) |
+| `weakSignatureAlgorithm` | `{ severity? }` | `fail` | Reject weak signature algorithms (MD2-RSA, MD5-RSA, SHA1-RSA, DSA-SHA1, ECDSA-SHA1) on non-root certificates |
 | `weakCipherSuite` | `{ severity? }` | `fail` | Reject known-weak cipher suites |
 | `knownBadCA` | `{ severity? }` | `fail` | Reject distrusted certificate authorities |
 | `recommendedTLSVersion` | `{ value?: string, severity? }` | `ignore` | Advisory minimum TLS version |

detect/uptime-monitoring/ssl-monitors/configuration.mdx

@@ -41,7 +41,7 @@ Client certificates are stored at the account level under **Settings → Client
 
 ### Security Baseline
 
-The security baseline is a configurable rule set that evaluates the negotiated TLS session against best-practice requirements. It runs automatically on every check and produces a **verdict** (`pass` / `warn` / `fail`) and a **grade** (`A-`, `B`, or `F`).
+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:
 
@@ -92,8 +92,8 @@ For more details, see our documentation on [Assertions](/detect/assertions).
 
 Set performance thresholds based on the TLS handshake duration:
 
-* **Degraded After:** Handshake time (in milliseconds) above which the monitor is marked as degraded but not failed. Default: 3,000 ms.
-* **Failed After:** Handshake time above which the monitor fails. Must be greater than or equal to the degraded threshold. Default: 10,000 ms.
+* **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
 

detect/uptime-monitoring/ssl-monitors/overview.mdx

@@ -26,7 +26,7 @@ Each SSL monitor run performs the following steps:
 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** — 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`)
+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
@@ -35,7 +35,7 @@ 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 (e.g., `EXPIRED_CERT`, `HOSTNAME_MISMATCH`, `HANDSHAKE_TIMEOUT`)
+* **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
 
@@ -49,13 +49,13 @@ Learn more in our documentation on [Results](/concepts/results).
 
 ## The Security Baseline
 
-The security baseline is a built-in rule set that evaluates each handshake against current best practices without requiring explicit assertions. Rules cover:
+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:
 
 | Rule | Default severity | What it checks |
 |------|-----------------|----------------|
 | `minTLSVersion` | `fail` | Negotiated TLS version is at or above the required minimum |
 | `minKeySizeBits` | `fail` | RSA key size meets the required minimum |
-| `weakSignatureAlgorithm` | `fail` | No non-root certificate in the chain uses MD2, MD5, SHA-1, or DSA-SHA1 |
+| `weakSignatureAlgorithm` | `fail` | No non-root certificate in the chain uses MD2-RSA, MD5-RSA, SHA1-RSA, DSA-SHA1, or ECDSA-SHA1 |
 | `weakCipherSuite` | `fail` | The negotiated cipher suite is not in the known-weak list |
 | `knownBadCA` | `fail` | No certificate in the chain was issued by a distrusted CA |
 | `recommendedTLSVersion` | `ignore` (advisory) | Negotiated version meets the recommended minimum |
@@ -75,14 +75,14 @@ You can override the default severity for each rule or disable the baseline enti
 
 ## Troubleshooting Common Issues
 
-<Accordion title="The monitor fails with HOSTNAME_MISMATCH but the site loads fine in a browser">
-This can happen when a server hosts multiple certificates and the default certificate served to Checkly does not cover the monitored hostname. Use the **SNI server name** (`serverName`) option in the SSL config to explicitly request the certificate for your hostname.
+<Accordion title="Hostname verification failed but the site loads fine in a browser">
+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.
 </Accordion>
 
-<Accordion title="The monitor fails with CHAIN_UNTRUSTED">
-A chain trust failure means one or more intermediate certificates are missing or the root is not trusted. Common causes:
+<Accordion title="Certificate chain is not trusted">
+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)