Expecting a TLS error condition

[eljoest]

I'd like to configure an endpoint to expect a TLS failure, i.e. accessing a service configured for mTLS should fail when accessing the endpoint without a certificate.

The TLS check succeeds despite the TLS errror, which is great, because I can check the certificate expiry without adding a client certificate to gatus.

The https check creates an error but will succeed, when I add the condition [CONNECTED] == false.

It also shows (as expected)

Errors
• Get "https://example.com": remote error: tls: certificate required

I tried a naive approach hoping the placeholder from some alerts might be available:

[RESULT_ERRORS] == pat(*remote error: tls: certificate required*)

Unfortunately it's not and I couldn't find a specific condition.

Is there a way to configure this negative mTLS check I'm overlooking? I'd like the check to be more specific than connected = false because that would also trigger for other connection failures.

[ska2704]

There's no placeholder for the error text (the list is [STATUS], [RESPONSE_TIME], [IP], [BODY], [CONNECTED], [CERTIFICATE_EXPIRATION], [DOMAIN_EXPIRATION], [DNS_RCODE]), so [RESULT_ERRORS] can't work. But you can get a more specific check than [CONNECTED] == false with a tls:// endpoint that sends a body:

endpoints:
  - name: mtls-rejects-anonymous
    url: "tls://example.com:443"
    body: "GET / HTTP/1.0\r\n\r\n"
    conditions:
      - "[CONNECTED] == true"
      - "has([BODY]) == false"

Why this works: certificate required is a TLS 1.3 alert. In TLS 1.3 the client finishes its side of the handshake before the server checks for a client cert, and the alert only arrives on the first read. That's why your plain tls:// check passes. For a tls:// endpoint with a body, gatus (CanPerformTLS in client/client.go) sets connected after the handshake, then writes the body and reads, and that read is where the alert shows up. So you get:

• mTLS enforced: [CONNECTED] true, body empty, error remote error: tls: certificate required → passes
• mTLS accidentally off: the server answers the request, so the body starts with HTTP/1.0 ... → has([BODY]) == false fails
• host down / port closed / DNS / handshake problems: [CONNECTED] false → fails

I checked those three cases against a local Go TLS 1.3 server with RequireAnyClientCert, using the same dial/write/read sequence gatus uses.

Caveats:

• It relies on TLS 1.3. Against a TLS 1.2 server the rejection happens during the handshake, so [CONNECTED] would be false. Your certificate required error only exists in 1.3, so you should be fine.
• A server that completes the handshake and then never answers (read timeout) would also pass, since that's also connected with an empty body.
• [CERTIFICATE_EXPIRATION] isn't set on this endpoint, because gatus returns early on the read error. Keep your existing tls:// check without a body for the expiry.

If you want to match on the exact error, that would need a new placeholder, which is probably worth a feature request.

[eljoest]

Thank you, works like a charm. The additional failure modes (TLS negotiation works but no response) are no deal breaker for me.