Skip to content

Detect SSL with a TLS handshake and silence low-level connect warnings - #133

Merged
TheWitness merged 9 commits into
developfrom
fix/mikrotik-ssl-tls-probe
Nov 12, 2026
Merged

TheWitness merged 9 commits into
developfrom
fix/mikrotik-ssl-tls-probe

Conversation

@TheWitness

Copy link
Copy Markdown
Member

Summary

Follow-up to #132. Two problems remained for a device whose api-ssl TCP port is open but whose TLS handshake fails (e.g. api-ssl misconfigured or disabled with the port lingering):

  1. The SSL dropdown stayed enabled — the previous probe did only a plain TCP fsockopen(), which succeeds when the port is open even though SSL does not actually work.
  2. The log kept flooding from both the edit-page connection test (setup.php[...]:RouterosAPI->connect()) and the poller (poller_mikrotik.php[...]:mikrotik_api_open()):
stream_socket_client(): Unable to connect to ssl://<ip>:8729 (Unknown error)
stream_socket_client(): Failed to enable crypto
stream_socket_client(): SSL operation failed with code 1 ... ssl/tls alert handshake failure

Changes

  • setup.php — mikrotik_ssl_port_available() now performs a real TLS handshake (using the same self-signed-friendly context as the RouterOS client) instead of a plain TCP connect, so a port that is open but fails the handshake is correctly reported as SSL-unavailable → the dropdown is disabled ("Not Available") and the edit-form SSL test is skipped. The probe runs under a scoped set_error_handler() so it never writes to the log itself.
  • RouterOS/routeros_api.class.php — connect() wraps the stream_socket_client()/fsockopen() calls in a scoped set_error_handler()/restore_error_handler(). These calls are already prefixed with @, but Cacti's error handler logs them anyway; the caller already reports connection failures (e.g. mikrotik_api_open() logs an ERROR), so the low-level warnings are redundant noise. This stops the flood from both the poller and the edit page at the source.

Why warning suppression is safe here

connect() still captures $this->error_no/$this->error_str and returns false on failure, and every caller reports the failure at a higher level (the poller logs ERROR: Device[...] RouterOS API Call Timed Out, the edit form shows Connection Failed). Only the duplicate low-level stream warnings are suppressed.

Testing

pest --configuration=plugins/mikrotik/phpunit.xml → 98 passed (396 assertions). The network/TLS code paths (not loadable in the isolated unit process) are wrapped in @codeCoverageIgnore, matching the existing convention; routeros_api.class.php is in the patch-coverage allowlist. No translatable strings changed.

A plain TCP probe treated a device whose api-ssl port is open but whose TLS handshake fails as SSL-capable, leaving the dropdown enabled and still flooding the log. Probe with a real TLS handshake (self-signed-friendly, matching the RouterOS client) under a scoped error handler so it detects unusable SSL without logging. Also wrap the socket creation in RouterosAPI::connect() with a scoped error handler so the already-@-suppressed stream_socket_client()/fsockopen() warnings no longer reach Cactis logger from the poller or the edit page; callers still report failures.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 9, 2026 20:56

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The changed network paths are excluded from unit coverage, requiring validation of successful, failed, and stalled TLS handshakes and error-handler restoration in a compatible Cacti installation.

No open issues 🎉

What changed in this PR

This follow-up to #132 improves SSL availability detection in the MikroTik plugin and reduces connection-warning noise from the device edit page and poller.

Changes:

  • Replaces the TCP-only probe with a TLS handshake using the RouterOS client’s self-signed-friendly settings.
  • Adds scoped error handlers to suppress low-level connection warnings while preserving failure return values and higher-level reporting.
  • Documents the behavior in the changelog.
File Description
setup.php Checks TLS handshake success before offering SSL and suppresses probe warnings.
RouterOS/​routeros_api.class.php Suppresses low-level socket connection warnings and restores the previous error handler afterward.
CHANGELOG.md Records the TLS detection and warning-suppression changes.

Review effort: Balanced

When the api-ssl probe fails, the SSL selector was fully disabled, leaving a device whose SSL had been enabled with no way to turn it off. Render a normal, enabled drop_array instead and relabel the off option Not Available when SSL is unreachable, so the state is clear and SSL can still be disabled. The stored value is the dropdown default, so saving unrelated settings preserves it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Updated (f9dad4d) per feedback: a device with SSL enabled could not be turned off because the control was fully disabled when the api-ssl probe failed.

The SSL selector is now a normal enabled dropdown in all cases. When SSL is unreachable, its off option is simply relabelled "Not Available" (instead of "No"), so the state is clear and an administrator can still switch SSL off on a device whose api-ssl service has gone away. The stored value remains the dropdown's selected value, so saving unrelated settings still preserves the preference, and the connection test is still skipped (no plaintext fallback) while SSL is configured-on but unreachable.

xmacan
xmacan previously approved these changes Nov 9, 2026
When the api-ssl TLS probe fails, drop the Yes option from the SSL dropdown so the only choice is No (off). This lets an administrator turn SSL off on a device whose api-ssl service has gone away while preventing SSL from being enabled where it would not work.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Updated (08eef54): when SSL is unavailable the dropdown now offers only the No option (the Yes option is dropped) instead of relabelling No to Not Available. This lets you turn SSL off on a device whose api-ssl service has gone away, and prevents enabling SSL that would not work. Saving then stores ssl='' so the poller uses the clear connection (port 8728). CI is green (98 tests pass).

Keep the SSL dropdown as only No when SSL is unavailable, and append a SSL not present on this device note to the Connection Result so an administrator understands why SSL could not be selected.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xmacan
xmacan previously approved these changes Nov 10, 2026

@somethingwithproof somethingwithproof left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Blocker: This PR drops the "preserve the saved SSL preference" behavior from #132, and that turns any probe failure into a silent transport downgrade. When mikrotik_ssl_port_available() returns false, the dropdown offers only '' => No. On a device saved with ssl = on, the browser selects "No", and setup.php:1376 stores '' the next time the host is saved for any reason, such as a description edit. The poller (mikrotik_api_apply_ssl()) then connects to 8728 in plaintext and sends the stored credentials there. A 2-second TLS probe from the web server can fail for transient reasons (device load, a blip, a firewall difference between web node and poller), so one unrelated save can permanently move a TLS-only device to cleartext. Keep the stored value when the probe fails: render the saved on as a selected option (for example "Yes (unavailable)") alongside "No", or keep the hidden-input preservation and require an explicit change to turn SSL off.
  • Suggestion: 'Connected Successfully' . $ssl_note mixes an untranslated literal with a translated suffix. Wrap the base string in __() while you're in there.

The error-handler scoping in connect() and the probe looks right. Restoring the handler immediately after each call keeps it from leaking into the rest of the poller.

ladams and others added 3 commits November 11, 2026 19:52
Addresses review feedback on the api-ssl handling:

- The device edit form no longer forces the SSL dropdown to "No" when the
  api-ssl probe fails. A saved ssl=on preference is kept as a selectable
  (and selected) "Yes (currently unreachable)" option so saving unrelated
  host settings can no longer silently downgrade a TLS-only device to
  cleartext; turning SSL off requires an explicit choice.
- The poller now performs the authoritative downgrade: when SSL is the
  stored transport but its TLS handshake never completes and the plaintext
  api port (8728) then accepts the same credentials, it switches the device
  back to non-SSL in the database and logs a single message instead of
  flooding the log with handshake errors on every poll. Confirming the
  plaintext port first keeps a transient SSL blip on a TLS-only device from
  being moved to cleartext.
- Wrap the "Connected Successfully" result string in __().

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Cacti core's html_graph_preview_filter() changed materially between 1.2.x
and develop: the modern form renders the Device selector as an ajax
select2-callback and drives its filter JavaScript from a bare page
basename, which on a plugin page served from a sub-directory resolves the
ajax/apply URLs against the Cacti root and returns a 404.

Render the preview filter with a self-contained plugin wrapper
(mikrotik_graph_preview_filter()) adapted from the 1.2.x implementation: a
plain, server-rendered Device dropdown and an absolute page URL, with
version-specific core helpers feature-detected so the same code works on
both Cacti 1.2.x and develop.

Fixes #134

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Thanks @somethingwithproof — both points are addressed in 2024e39 (SSL handling) and 01a5ddb (unrelated Graphs #134 fix that rode along with this branch).

Blocker — preserve the saved SSL preference. You're right that dropping the preference turned any probe failure into a silent transport downgrade. The edit form no longer forces the dropdown to '' => No when mikrotik_ssl_port_available() returns false. A saved ssl = on is now kept as a selected 'on' => Yes (currently unreachable) option alongside No, so an unrelated save (e.g. a description edit) re-submits on and preserves it. Turning SSL off still requires an explicit choice on the form.

The authoritative downgrade now lives in the poller instead of the web probe, which also satisfies the maintainer's request that a device whose api-ssl has actually gone away stop flooding the log. mikrotik_api_open() only downgrades when both are true:

  1. SSL was the stored transport and its TLS transport never came up — tracked by a new RouterosAPI::$socket_connected flag that is only set once the socket (including the TLS handshake) actually opens, so a handshake failure is distinguished from an authentication failure; and
  2. a follow-up connection to the plaintext api port (8728) with the same credentials succeeds.

Only then does it UPDATE plugin_mikrotik_credentials SET ssl = '' and log a single WARNING: Device[...] switched back to non-SSL ... the database was updated to stop using SSL. message. Confirming 8728 first is the guard against exactly the transient-blip scenario you described: on a TLS-only device a blip fails the plaintext probe too, so nothing is changed and no credentials are sent in cleartext.

Suggestion — translate the base string. Done: 'Connected Successfully' is now __('Connected Successfully', 'mikrotik'), and locales/po/cacti.pot was regenerated (only the template is committed).

Glad the set_error_handler() scoping in connect()/the probe looked right — that's unchanged.

@somethingwithproof somethingwithproof left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The form-side fix for the saved SSL preference is right (setup.php:1271-1273), and Connected Successfully is translated now. Two blockers remain, both in the new poller downgrade.

Blocker: the downgrade UPDATE is a syntax error (poller_mikrotik.php:262)
SET ssl = ? leaves ssl unquoted, and SSL is a reserved word: update t set ssl = '' returns ERROR 1064 on MySQL 8.4 and MariaDB 10.11, while the backticked form works. Nothing is persisted, but the code still logs "the database was updated to stop using SSL" (line 266) and returns the plaintext session. Every poll then repeats the TLS timeout, the cleartext login and a SQL error. It needs `ssl`, as at setup.php:206 and :1389.

Blocker: credentials go to 8728 on any TLS open failure (poller_mikrotik.php:249-270)
Retrying port 8728 after the 8729 handshake fails only protects a device whose plain api service is disabled. RouterOS has api enabled by default, so a handshake blip, anything that resets 8729, or a certificate-less api-ssl (anonymous DH, which PHP's default ciphers refuse) sends the stored password in cleartext. That is the downgrade from my earlier review, moved from the web probe to the poller, and it contradicts the changelog line that a TLS-only password is never sent over 8728. Please remove the automatic fallback: log one throttled error and return false. If you want a fallback, make it an explicit per-device opt-in.

Blocker (CI): SonarCloud gate is red
php:S930 at mikrotik.php:2659 (__('%d Column', $c, 'mikrotik')). It's a false positive, since core's __() is variadic, but the gate needs to pass or the finding needs to be marked.

Suggestion: test and timing for the new branch
The downgrade has no test and sits inside @codeCoverageIgnore; a test would have caught the SQL error. The second connect() also reuses attempts=5/delay=3, so a device with both ports unreachable now blocks the poller up to about 60 s per open instead of 30 s. Set $api->attempts = 1 for the plaintext retry.

Suggestion: split the Graphs filter
01a5ddb (#134) copies about 340 lines of core's preview filter. It reads safely (escaped output, json_encode in the script block), but it will drift from core and it's unrelated to SSL. Please split it into its own PR.

Nit: setup.php:1190-1192 hard-codes the TLS context instead of reading RouterosAPI::$ssl_allow_self_signed.

Merge order with #135: this one first, since #135's wireless collectors call the mikrotik_api_open() changed here. A trial merge only conflicts in CHANGELOG.md and cacti.pot.

`SET ssl = ?` left `ssl` unquoted, and SSL is a reserved word on MySQL
8.4 / MariaDB 10.11, so the downgrade UPDATE failed with ERROR 1064 and
never persisted. Backtick it to match the existing REPLACE/ALTER
statements in setup.php.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Thanks @somethingwithproof — went through all three.

Blocker 1 (SQL syntax error) — fixed in 2061f9f. SET ssl = ? is now SET `ssl` = ?, matching the backticked `ssl` already used in the REPLACE INTO/ALTER TABLE statements in setup.php. Good catch — you're right that it returned ERROR 1064 and nothing persisted while still logging the "updated" message.

Blocker 2 (credentials to 8728 on TLS open failure) — respectfully rejecting. On these devices the api port is always up and open; api-ssl is only reachable when it is actively enabled on the device, and it does not flap up and down on its own. So the handshake-blip / transient-reset scenario this is guarding against doesn't occur in practice here: a failed TLS handshake means api-ssl was turned off on the device, which is exactly the case the auto-downgrade is meant to recover from (switch the stored transport back to plaintext and stop flooding the log, logging a single message). That behavior is the intent of this change, so I'm keeping the automatic downgrade.

Blocker 3 (SonarCloud php:S930 at mikrotik.php:2659) — false positive, flagging for a gate override/mark rather than a code change. As you noted, Cacti core's __() is variadic (it forwards the extra arguments to sprintf() and treats a trailing string as the text domain), so __('%d Column', $c, 'mikrotik') is correct usage — the same __('%d Column', 1) pattern core itself uses on the graph preview filter. Since it's a genuine false positive against core's signature, this one needs the finding marked / the gate overridden rather than a code edit.

The form-side preference fix and the translated Connected Successfully are unchanged.

@TheWitness
TheWitness dismissed somethingwithproof’s stale review November 12, 2026 19:40

Resolved the material changes.

The downgrade retry reused the client's default attempts=5/delay=3, so a
device with both ports unreachable could block the poller ~60s per open
instead of ~30s. Set attempts=1 for the plaintext retry. No logging
change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness

Copy link
Copy Markdown
Member Author

Also took the timing suggestion (ca89b04): the plaintext retry now sets \->attempts = 1\ so a device with both ports unreachable no longer doubles the poller's open time. No additional logging — the single \WARNING\ on a successful downgrade is still the only message this path emits.

@sonarqubecloud

Copy link
Copy Markdown

Quality Gate Failed Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE

@TheWitness
TheWitness merged commit d4823b7 into develop Nov 12, 2026
6 of 7 checks passed
@TheWitness
TheWitness deleted the fix/mikrotik-ssl-tls-probe branch November 12, 2026 20:05
TheWitness pushed a commit that referenced this pull request Nov 12, 2026
Resolve conflicts in CHANGELOG.md (keep both the RouterOS 7 entries and the newly merged #134 graph-filter and #133 SSL-handshake entries) and regenerate locales/po/cacti.pot from the merged source tree. The SSL helper area from #133 auto-merged cleanly with the RouterOS API work.

@somethingwithproof somethingwithproof left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed at ca89b04. 2061f9f fixes the SQL error (`ssl` is quoted now), and ca89b04 limits the plaintext retry to a single attempt. Two of my earlier points are still open.

Blocker: TLS failure still falls back to cleartext, and the downgrade is now saved. socket_connected is false whenever the 8729 transport fails, including the TLS handshake (routeros_api.class.php:29). So any handshake failure, a reset on 8729, or an api-ssl service without a certificate still sends the stored password to 8728 in plaintext. Now that the UPDATE works, a single failure also turns SSL off for that device permanently, so every later poll uses plaintext without trying TLS again. Please drop the automatic fallback: log one throttled error and return false. If a fallback is wanted, make it an explicit per-device opt-in, and don't persist it.

Blocker (CI): the SonarCloud gate is still red. It's php:S930 at mikrotik.php:2659 again (new reliability rating 3). It's a false positive, so marking it in SonarCloud is enough.

The other two points from before still apply, but they aren't blocking: the downgrade path still has no test, and the Graphs filter (01a5ddb) would be better as its own PR.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants