feat: the option to expect a certain TLS error for the TCP monitor

[MkDev11]

feat: add TLS monitor type for mTLS endpoint monitoring

Summary

Adds a new TLS monitor type that allows monitoring mTLS endpoints to verify they properly reject connections without client certificates.

Closes #5837

Features

• New TLS monitor type with hostname and port configuration
• Expected TLS Alert dropdown to specify which TLS alert to expect
• Support for certificate_required (116) alert for mTLS verification
• Optional certificate expiry monitoring when connection succeeds
• Ignore TLS errors option

Use Case

Users can now:

1. Monitor TLS endpoints and verify successful connections
2. Verify mTLS endpoints properly reject connections without client certificates by expecting specific TLS alerts (e.g., certificate_required)
3. Optionally monitor certificate expiration when connection succeeds

Files Changed

File	Description
server/monitor-types/tls.js	New TLS monitor type implementation
server/uptime-kuma-server.js	Register TLS monitor type
server/server.js	Save handler for expected_tls_alert field
server/model/monitor.js	Add expectedTlsAlert to toJSON
src/pages/EditMonitor.vue	Frontend UI for TLS monitor configuration
src/lang/en.json	English translations
db/knex_migrations/2026-01-05-0000-add-tls-monitor.js	Database migration

Screenshots

To be added after testing

Checklist

• Linting passes (npm run lint)
• Tests pass (npm test)
• Translations added to en.json only
• Database migration included
• Follows existing code patterns
• Screenshots added (pending)

Testing Instructions

1. Run npm ci to install dependencies
2. Run npm run dev to start dev server
3. Create a new monitor with type "TLS"
4. Configure hostname, port, and expected TLS alert
5. For mTLS testing, select "certificate_required" to verify the server rejects unauthenticated connections

---

Contribution by Gittensor, see my contribution statistics at https://gittensor.io/miners/details?githubId=94194147

[MkDev11]

Hi @louislam @CommanderStorm! 👋

Happy New Year 2026! 🎉🎊 Wishing you and the Uptime Kuma community a wonderful year ahead filled with success and great contributions!

I'd really appreciate it if you could take a look when you have a moment. Please let me know if there are any changes needed or if you have any feedback!

Thank you for maintaining such an amazing project! 🙏

[CommanderStorm]

how does it differ form the current tcp monitor?

[MkDev11]

form the current tcp monitor?

Hi @CommanderStorm! Great question! 👋

Key Differences from TCP Monitor

The main difference is the expected behavior on failure:

TCP Monitor (existing)

• ✅ UP = Connection succeeds
• ❌ DOWN = Connection fails (any error)

TLS Monitor (new)

• ✅ UP = Specific TLS alert received (e.g., certificate_required)
• ❌ DOWN = Wrong alert or unexpected success

Use Case: mTLS Verification

For mTLS endpoints, you want to verify the server correctly rejects connections without a client certificate. With the TCP monitor:

Server rejects connection → TCP shows DOWN ❌ (but this is actually correct behavior!)

With the TLS monitor:

Server returns "certificate_required" alert → TLS shows UP ✅ (server is correctly enforcing mTLS)
Server accepts connection without cert → TLS shows DOWN ❌ (security misconfiguration!)

Why Not Extend TCP Monitor?

1. Different semantics: TCP monitor expects success = UP. TLS monitor can expect failure = UP.
2. TLS-specific features: Parsing TLS alert codes (RFC 5246/8446), mapping alert numbers to names.
3. Cleaner UX: Users selecting "TLS" monitor type immediately understand it's for TLS/mTLS testing.

Summary

Feature	TCP Monitor	TLS Monitor
Success = UP	✅	✅ (optional)
Specific TLS alert = UP	❌	✅
Parse TLS alert codes	❌	✅
mTLS rejection testing	❌	✅

Let me know if you'd like me to make any changes or if you have other questions!

[CommanderStorm]

Since TCP already supports TLS, introducing a separate “TLS monitor” needs a very clear justification.

Please explain briefly what cannot be implemented in the existing TCP monitor without breaking its semantics or UX.

To be explicit about expectations:

• AI tools are fine for mechanical tasks such as translation or spelling/grammar fixes.
• They are not acceptable for design discussions, architectural justification, or review responses.

For those, I need human-written answers that demonstrate direct understanding of this codebase. Generic or AI-style responses undermine trust and make maintenance harder.

If you want to continue this discussion, please respond concisely and in your own words.

[MkDev11]

Since TCP already supports TLS, introducing a separate “TLS monitor” needs a very clear justification.

Please explain briefly what cannot be implemented in the existing TCP monitor without breaking its semantics or UX.

To be explicit about expectations: – AI tools are fine for mechanical tasks such as translation or spelling/grammar fixes. – They are not acceptable for design discussions, architectural justification, or review responses.

For those, I need human-written answers that demonstrate direct understanding of this codebase. Generic or AI-style responses undermine trust and make maintenance harder.

If you want to continue this discussion, please respond concisely and in your own words.

@CommanderStorm, thanks for the feedback. I'll try to explain my thinking.

The main issue is that TCP monitor's logic is "connection works = UP". But for mTLS verification, I actually want the connection to fail in a specific way - that's the success case.

Let me give a concrete example: I have an mTLS endpoint that should reject anyone without a client certificate. With TCP monitor, if the server rejects me (which is correct behavior), it shows as DOWN. But that's actually what I want to happen - the server is working correctly by rejecting me.

So I need something that says "if the server returns a certificate_required TLS alert, that means it's properly configured and should be UP." That's basically the opposite of what TCP does.

I looked at adding this to TCP, but it felt wrong. TCP is straightforward - "can I reach this port?" Adding "but sometimes failure is success" logic would make it confusing for existing users. Plus I'd need to add TLS alert parsing code that doesn't really belong there.

I'm open to other approaches though. If you think there's a cleaner way to handle this within TCP (maybe a checkbox like "expect TLS rejection"?), I'm happy to try that instead. Just let me know what you'd prefer.

[CommanderStorm]

I think adding it to TLS makes sense since there we already have some code for TLS.
Not much, but some.

In general, I don't want two extremely close monitors due to bugs and things.

[CommanderStorm]

A checkbox in the UI sounds resonable for this

[MkDev11]

@CommanderStorm Thanks for the feedback! I've refactored the PR to integrate the TLS alert checking directly into the TCP monitor instead of creating a separate monitor type.

Now there's just a dropdown in the TCP monitor settings called "Expected TLS Alert" - if you pick something like certificate_required, the monitor will mark it as UP when the server rejects the connection with that specific alert. Otherwise it works exactly like before.

This keeps everything in one place and avoids the duplicate monitor type issue you mentioned. Let me know if this approach works better or if you'd like any changes.

[CommanderStorm]

Nice work!

Code looks very solid and mergable to me, but I would like a short sanitiy-check from @shanto on this one, if possible 😉

[MkDev11]

@CommanderStorm Please have a look at the updates and let me know your feedback.

[CommanderStorm]

LGTM from the code perspecitve, as said.

I would really like to have testcases for this. Does not have to be a long testcase, just verifying basic functionality (similarly how the existing testcase works).

Also, could you comment on the TLS_ALERT_CODES question that I had (this is not a quesion if this should be changed, more of a why you chose to do it like this)

[MkDev11]

@CommanderStorm please review the update and let me know your feedback

[CommanderStorm]

LGTM, thank you ❤️

[shanto]

Looks like we are missing a positive test case.

Also, while what has been done (added) doesn't harm, I have a feeling that the same result could be achieved with less code and UI changes because we will almost always care about the certificate_required and nothing else. Other cases are synonymous to DOWN.