Repository navigation
Diagnose proxy, TLS and client-certificate failures with mcp doctor --network - #355
Merged
yiftach-armis merged 5 commits intoNov 4, 2026
Merged
Conversation
- Add `armis-cli mcp doctor --network`, which reports the proxy in use and where it comes from, DNS, TCP connect, TLS handshake and certificate issuer. When a proxy is in use it also tries a direct connection, so users can tell whether the proxy is the cause. No credentials are sent. - Run the same check as a "CLI network" row in the regular `mcp doctor`. The CLI follows the Windows system proxy and PAC file but the server's Python runtime does not, so one can work while the other fails. - Explain "TLS handshake timeout" and "proxyconnect" errors in auth, device and IdP calls. The message names the proxy, its source, and the exact override to try. - Add `ARMIS_NO_SYSTEM_PROXY` to ignore OS proxy settings and `ARMIS_TLS_HANDSHAKE_TIMEOUT` to raise the 10s handshake limit for slow inspecting proxies. - Document both in the README.
- Detect x509 verification failures in ExplainTransportError and tell the user the machine does not trust the certificate, with OS-specific guidance for installing the organization's root CA. - Skip the "bypass the system proxy" hint for trust errors, since skipping the proxy does not fix them. - In 'mcp doctor --network', re-handshake without verification to read the presented chain and name the issuing authority in the report.
- Record the proxy source at selection time so errors name the real origin (env, Windows, macOS) instead of guessing afterward. - Add BypassProxyAdvice: ARMIS_NO_SYSTEM_PROXY does not affect a proxy from HTTPS_PROXY/HTTP_PROXY, so point to NO_PROXY or unsetting instead. - Clamp ARMIS_TLS_HANDSHAKE_TIMEOUT to 5m, avoid int overflow on huge values, and warn once on unusable values rather than silently ignoring them. - Stop wrapping Client.Do errors after retries, so a 5xx response body mentioning "TLS handshake timeout" is not misreported as a proxy failure. - netcheck: guard nil Out, make httptrace event capture goroutine-safe, close idle connections, and redact credentials in scheme-less proxy URLs like user:pass@host:8080. - mcp doctor --network: also reject --timeout and --verbose, and check flags in a stable order. - README: document the macOS cgo proxy behavior and the new timeout rules.
- Recognize "tls: certificate required" and "tls: bad certificate" errors and explain that the CLI cannot present a client certificate or use the OS certificate store, which is why browsers and Windows-stack tools may work. - Skip the proxy-bypass advice for this case, since avoiding the proxy is not the fix. - In netcheck, record when the server or an intercepting proxy requests a client certificate, including the issuers it accepts, and print a dedicated verdict telling the user to ask their network team for an exemption.
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Test Coverage Reporttotal: (statements) 73.9% Coverage by function |
- Read the unverified chain from tls.CertificateVerificationError rather than opening a second connection with InsecureSkipVerify. - Drops presentedChain and its extra handshake, and no longer matches on the "x509:" error string.
7 of 15 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Related Issue
Type of Change
Problem
Behind a corporate proxy or firewall, logins and scans can fail with
TLS handshake timeout,EOF,proxyconnect, or certificate errors. The messages don't say which proxy the CLI used, where the connection stopped, or what to ask the network team to change. Users and support have to guess.Solution
The CLI now explains these failures and can run a connection check.
armis-cli mcp doctor --networkruns a step-by-step check of how the CLI reaches the Armis API. It prints the proxy in use and where that setting comes from, DNS, TCP, the TLS handshake, and who issued the server certificate. If a proxy is in use it also tries a direct connection for comparison. It sends no credentials and needs no MCP install. Plainmcp doctorruns the same check as a "CLI network" row, and the report goes into the support bundle.httpclient.ExplainTransportError). It covers handshake timeouts, an unreachable proxy, untrusted certificates (with per-OS advice on trusting a root CA), and required client certificates. Proxy passwords are redacted.--networkon handshake timeouts and proxy-connect failures.ARMIS_NO_SYSTEM_PROXY=1makes the CLI ignore OS proxy settings and use onlyHTTPS_PROXY,HTTP_PROXYandNO_PROXY.ARMIS_TLS_HANDSHAKE_TIMEOUToverrides the 10s handshake limit. It takes a Go duration or seconds and is capped at 5 minutes. Invalid values are warned about once and ignored.Testing
Automated Tests
New tests cover:
internal/netcheck: direct success, a proxy that stalls while direct works, a dead proxy, an untrusted certificate, a required client certificate, a closed port, and credential redaction.internal/httpclient: timeout parsing and clamping, the bypass-proxy advice,ARMIS_NO_SYSTEM_PROXY,DescribeProxy, the error explanations, and that a 5xx response body is not mistaken for a transport failure.mcp doctor --networkflag handling, andcheckCLINetworkininternal/install.Manual Testing
TODO: run
armis-cli mcp doctor --networkon a machine behind a proxy.Reviewer Notes
presentedChainininternal/netcheck/netcheck.gousesInsecureSkipVerify. It only reads the certificate chain to name the issuer, abandons the handshake right after, and sends no request. It carries anolintand anarmis:ignoremarker.sync.Mapkeyed by request host, so errors can name it.--networkrejects--watch,--fix,--bundle,--deep,--no-handshake,--timeout,--verboseand non-plain--format.Checklist
Screenshots (if applicable)
N/A