For the complete documentation index, see llms.txt. This page is also available as Markdown.

Bot Connectivity Issues

Use this page when a CERTInext Bot stops reporting to CERTInext, or when it reports but cannot reach the servers and platforms it manages. Work through the steps in order. Each step tells you what to check and what the result means.

The full list of host names, ports, proxy settings and TLS inspection settings is in Network and Firewall Requirements. This page shows how to test them.


Common symptoms

  • The Bot shows Stopped on the Bots page.

  • Last Bot Update is not refreshing. A Bot reports at its reporting interval, which is one minute by default.

  • A provisioning target shows Bot Offline - Deployment Pending.

  • Scans do not start, or deployments stay in Deployment In Progress.

  • Test Connection fails for a server or platform.

  • The Bot logs show timeout, connection, proxy or certificate errors.

Step 1: Check the Bot in the console

Open the Bots page and check the Status of the Bot.

Status
What it means
What to do

Active

The Bot is reporting

If tasks still fail, go to Step 3 and then Step 6

Stopped

The last report is older than the reporting interval plus two minutes

Go to Step 2

Inactive

An administrator deactivated the Bot

Reactivate it if it should run. Allow up to 15 minutes for the status to return to Active

Configuration Pending

The Bot has registered but is not yet configured in the console

Finish the Bot configuration in the console

Activation Pending

The configuration is saved and CERTInext is waiting for the first report from the Bot

Check that the Bot service is running (Step 3) and test the connection (Step 2)

Also check that Bot Version is current.

Step 2: Test the connection to CERTInext

The Bot connects out to CERTInext on HTTPS, TCP 443. No inbound rule to the Bot host is needed. Test from the Bot host itself, using the host name for your deployment.

Deployment
Bot host name

US region

us-discovery-api.certinext.io

India region

api-discovery.certinext.io

Sandbox

sandbox-us-discovery.certinext.io

On-premises

The Bot host name agreed during installation, for example discovery.certinext.example.com

On a Windows Bot host, in PowerShell:

Type curl.exe, not curl. In Windows PowerShell, curl runs a different command and the test fails. Windows Server 2016 has no curl.exe, so use this instead:

On a Linux Bot host:

If the Bot uses a proxy, test through the proxy. Add -x http://proxy.example.com:8080 to the curl command, or -Proxy http://proxy.example.com:8080 to Invoke-WebRequest. A direct test from a host that may only use the proxy fails even when the Bot is set up correctly.

If this Bot relays through another Bot, test TCP 5777 to that Bot host instead, for example Test-NetConnection relaybot.example.com -Port 5777.

Result
What it means
What to do

200

The network path to CERTInext works

Go to Step 3

Host name not resolved

DNS on the Bot host cannot resolve the name

Check the DNS servers set on the Bot host. Where internal and public DNS differ, check the answer with nslookup

Timeout or connection refused

A firewall rule is missing, or the host must use a proxy and the test did not

Allow the host name on TCP 443 from the Bot host, or repeat the test through the proxy

407

The proxy requires authentication

Allow the Bot host address on the proxy for the destinations it needs, or use Digest authentication. Basic authentication is supported for the connection to CERTInext only. For NTLM or Kerberos proxies, use an allow rule

Certificate error

TLS inspection is replacing the CERTInext certificate with one the Bot host does not trust

Trust the inspection CA on the Bot host, or exclude the host name from inspection

A Bot host must have a route to CERTInext, directly or through a proxy. For networks with no internet route, use an on-premises deployment or place the Bot host in a zone that can reach CERTInext.

Step 3: Check the Bot host

  • The Bot service is running. On Windows, run Get-Service CERTInextBot (display name CERTInext Bot Service). On Linux, run systemctl status certbotd.

  • The clock is in sync with NTP. If the Bot shows Active but scan results and deployments never arrive, check the clock first. A host whose clock is out of sync can keep reporting while its results are rejected.

  • The disk has free space for logs and the local database.

  • Endpoint protection is not blocking or quarantining files in the Bot program folder or data folder.

Step 4: Check the installation token

Each installation token has a Max Enrollments (Bot Limit). When the limit is reached, no further Bot can register with that token. Generate a new token, or raise the limit, and set it to the number of Bots you plan to install with the token. If an installation was rejected because the limit was reached, allow up to 15 minutes after you raise the limit before you retry.

Reinstalling the Bot on the same host, under the same account, returns the same Bot with its name and history, unless the Bot was deleted in the console.

Do not clone a virtual machine image that already has the Bot installed. Install the Bot on each host after cloning.

Step 5: Check the proxy and TLS inspection

If the Bot connects through a proxy:

  • The proxy is an HTTP proxy that allows CONNECT to TCP 443. SOCKS proxies are not supported.

  • Idle and response timeouts are at least 180 seconds.

  • On Windows the proxy is set during installation. On Linux it is set in the Bot configuration after installation. Restart the Bot service after any proxy change.

  • If TLS inspection is on, the inspection CA is trusted on the Bot host. On Windows, add it to the Local Computer Trusted Root store. On Linux, add it to the Bot's Java trust store again after each install and upgrade.

The full proxy and inspection settings are in Section 2.4 of Network and Firewall Requirements.

Step 6: Check connections to targets

If the Bot is active but scans, deployments or test connections fail, the problem is usually between the Bot host and the target. Run Test Connection in the console first, then test the port from the Bot host.

On Windows:

On Linux:

If nc is not installed, which is common on minimal RHEL, Rocky, AlmaLinux and Debian hosts, use:

Target
Port to test

Linux and Unix servers

SSH, TCP 22

Windows servers

WinRM, TCP 5986 or 5985, and SMB, TCP 445

F5 BIG-IP, NetScaler, FortiGate, Palo Alto

Management port, TCP 443 by default

Kubernetes, OpenShift and AKS

API server, TCP 443 or 6443

Directory servers

LDAPS, TCP 636

Cloud and SaaS platforms

HTTPS, TCP 443, to the platform API

The full list is in Sections 2.2 and 2.3 of Network and Firewall Requirements. Also check:

  • The firewall on the target allows the Bot host address.

  • The Bot host address is in the management access list of the appliance, and in the authorized IP ranges of AKS clusters.

  • Cloud API credentials are not limited to source addresses that leave out the Bot host.

  • The service account for the target has the rights listed in CERTInext Bot Workflow.

Windows targets. The Bot signs in to WinRM with the user name and password set for the server in the console, using NTLM. Enter domain accounts in the user@domain form. If your policy restricts NTLM, allow it as an exception for connections from the Bot host to the target servers only, and keep it restricted elsewhere. The Bot uses WinRM over HTTPS when the WinRM port of the server is set to 5986. If no port is set it uses TCP 5985, so a server with only an HTTPS listener fails until 5986 is set. With the standard Bot configuration the Bot checks the WinRM listener certificate, so issue it from a CA the Bot host trusts.

Linux targets. If the port test passes but Test Connection fails, check that the account set for the server can sign in over SSH from the Bot host and has the rights listed in CERTInext Bot Workflow.

Step 7: Review the Bot logs

Bot host
Log folder

Windows

C:\ProgramData\Certinext\CERTInextBot\logs

Linux, installed from the DEB or RPM package

/var/log/certbotd

The main files are error.log and info.log. Look for:

  • Authentication errors, which point to the token (Step 4) or the clock (Step 3)

  • Timeouts and connection errors, which point to the firewall or proxy (Steps 2 and 5)

  • Certificate or trust errors, which point to TLS inspection (Step 5)

  • Permission errors on a target, which point to the service account for that target (Step 6)

Step 8: Restart, upgrade or reinstall the Bot

  1. Restart the Bot service and check Last Bot Update again after two minutes.

  2. If the Bot still does not connect, uninstall it and install it again with a current installation token. After any upgrade or reinstall, apply the standard Bot configuration in Section 2.2 of Network and Firewall Requirements.

  3. If the Bot host cannot download the installer, use the manual installation package. See Bot Deployment and Management.

On Windows, run upgrades from an administrator session on the Bot host. The download uses the proxy settings of that session, not the Bot proxy.

On Linux, the Bot may register again after a package upgrade and returns as the same Bot. Keep the Max Enrollments limit of its installation token above the number of installed Bots until the upgrade is done.

When to contact support

Raise a support ticket and include:

  • Bot name, host name and IP address

  • Last Bot Update time, with the time zone

  • The result of the test in Step 2

  • The Bot log files from Step 7, with passwords, keys and tokens removed

  • Whether a proxy or TLS inspection device sits between the Bot host and CERTInext

Good practice

  • Test the connection again after every firewall, proxy or inspection change.

  • Keep the Bot version current.

  • Place one Bot in each network zone whose targets cannot be reached from another zone.

  • Deactivate Bots you no longer use.

Last updated