Troubleshoot Scanner Appliance Connection Failures
A Qualys Scanner Appliance needs a secure connection to the Qualys Cloud Platform to activate, run vulnerability scans, and synchronize data. When the connection fails, you cannot activate, update, or scan with the scanner appliance. This topic lists common connection error messages, explains their typical causes, and describes how to restore communication with the Qualys Cloud Platform.
Error Messages
You may see one or more of these errors:
- Scanner not activated
- Cannot connect to Qualys platform
- No heartbeat from scanner
- Activation failed
- Unable to reach cloud platform
- Connection timeout
- SSL handshake failed
These errors typically indicate a network communication problem between the scanner appliance and the Qualys Cloud Platform.
Network Requirements
The scanner appliance needs outbound HTTPS connectivity to the Qualys Cloud Platform. It must be able to start outbound connections without being blocked by firewalls or other network security controls.
Minimum requirements
- Outbound access to the Qualys domain
- Port 443/TCP
- No inbound connections required
- DNS resolution enabled
- Time synchronization (NTP)
Ports Required
|
Port |
Protocol |
Direction |
Purpose |
| 443 | TCP | Outbound | Communication with the Qualys Cloud Platform |
| 53 | UDP/TCP | Outbound | DNS resolution |
| 123 | UDP | Outbound | NTP time synchronization (recommended) |
No inbound ports are required for normal operation.
Proxy Issues
If your network uses a proxy, you must explicitly configure the scanner appliance to use it.
Cause
Common proxy problems include:
- The proxy requires authentication.
- The proxy blocks SSL tunnels.
- The proxy performs TLS inspection.
- The proxy does not allowlist the Qualys domains.
Solution
- Verify the proxy IP address and port.
- Confirm that the proxy supports HTTPS CONNECT.
- Make sure the proxy credentials are valid, if the proxy requires them.
- Test direct internet access by bypassing the proxy.
DNS Issues
DNS resolution failures prevent the scanner appliance from locating the Qualys Cloud Platform.
Symptoms
- Activation fails.
- The scanner appliance cannot resolve the Qualys domain.
- Connection timeouts occur.
Solution
- Verify the DNS server configuration.
- Confirm the DNS resolution manually.
- Ensure the external DNS is reachable.
- Avoid internal-only DNS zones.
TLS or SSL Inspection Issues
TLS inspection is one of the most common hidden causes of scanner appliance connection failures.
Cause
Qualys requires end-to-end TLS encryption. If a firewall or proxy intercepts SSL traffic, the scanner appliance cannot validate the server certificate.
Symptoms
- SSL handshake failed
- Certificate validation error
- The scanner appliance shows as connected but never synchronizes.
Solution
- Disable SSL inspection for Qualys traffic.
- Add the Qualys domains to the TLS bypass list.
- Allow direct encrypted traffic.
Qualys Domains to Allow list
The scanner appliance must be able to reach the correct Qualys Cloud Platform for your subscription region. For example:
*.qualys.com*.qualys.eu*.qualysguard.com*.qgX.apps.qualys.com(platform-specific)
The exact domain depends on your subscription region. To find the URLs your scanner appliance must reach on port 443, go to Help > About. For more information, see Check Network Access to Scanners.
Time Synchronization (NTP)
Incorrect system time can cause TLS failures.
Symptoms
- Certificate validation errors
- Intermittent connectivity
Solution
- Allow outbound NTP on port 123/UDP.
- Synchronize the scanner appliance with reliable time servers.
Validation Steps
To verify scanner appliance connectivity:
- Check the scanner appliance status in the Qualys user interface.
For more information, refer to Check Scanner Appliance Status. - Confirm that outbound port 443 is open.
- Test DNS resolution.
- Disable the proxy temporarily.
- Bypass TLS inspection.
- Review the scanner appliance logs.
- Restart the scanner service.
Best Practices
- Place scanner appliances in a DMZ or a trusted subnet.
- Avoid deep packet inspection.
- Use direct outbound internet access where possible.
- Monitor the scanner appliance heartbeat. For more information, see Scanner Appliance Heartbeat Check Notification.
- Keep the scanner appliance updated.
- Use multiple scanner appliances for redundancy.
Most scanner appliance connection issues are caused by network restrictions, proxy misconfiguration, DNS failures, or TLS inspection. Clean outbound HTTPS access to the Qualys Cloud Platform resolves most of these problems.
Good to know