CERTInext Bot Workflow
CERTInext Cloud is the CERTInext service that eMudhra operates, and administrators manage it through its web console. The CERTInext Bot is eMudhra software that runs as a service on a server in your network. CERTInext Cloud renews the certificates assigned to a Bot, and the Bot installs them on servers, load balancers, Kubernetes clusters and cloud platforms.
This page explains when renewal runs and where the key pair is generated (Section 1), how work reaches the Bot and what the Bot reports back (Section 2), how the Bot installs a certificate on each type of target (Section 3), and the controls available to administrators and security teams (Section 4).
The Bot opens every connection it uses, so the Bot host needs no inbound firewall rule. Host names on this page are for the US region. Accounts in another region use the host names listed in Network and Firewall Requirements.
Figure 1 Overview of the Bot workflow, with section numbers
1. Renewal Workflow
This workflow applies to every certificate the Bot installs, whether the Bot runs on the server itself, connects to a server remotely or calls a platform API (Section 3). CERTInext Cloud decides when renewal is due, obtains the certificate from the issuing CA and passes it to the Bot for installation.
Figure 2 Renewal and deployment across pulses
Step 1, the pulse. The Bot sends a pulse to CERTInext Cloud, every minute by default, and asks whether there is work for it. The interval can be changed for each account.
Step 2, renewal check. Each certificate has a renewal setting on its deployment configuration, set with Enable Renewal: a number of days before expiry, or a specific date and time. On every pulse, CERTInext Cloud checks the certificates assigned to that Bot against this setting and starts the renewal of each certificate that has reached it. The same check picks up deployments that are due, and Run Scan and Test Connection requests made in the console.
Steps 3 and 4, key pair and issuance. A new key pair is generated for every renewal, with the key algorithm and size set on the deployment configuration: RSA 2048, 3072 or 4096, or ECC P-256, P-384 or P-521. The certificate request is built from the new key and the status becomes Initiated. The request then goes to the issuing CA set for the certificate.
Private certificates are issued by emCA, the eMudhra CA service that hosts your private CAs.
Public certificates are issued by emSign, the eMudhra public CA, once domain validation is complete.
Step 5, keystore. The certificate, its chain and the private key are packaged in a PKCS12, JKS or PFX keystore protected by the Key Store Password of the deployment configuration. The status becomes Issued. The deployment then waits until it is due, as set with Enable Deployment: immediately after renewal, or at a scheduled date and time.
Steps 6 and 7, delivery to the Bot. On the first pulse after the deployment is due, the reply to the pulse carries the deployment job and the status becomes Deployment In Progress. The job holds the keystore and the details the Bot needs to complete the installation (Section 2).
Step 8, installation. The Bot installs the certificate and private key on the target, as described in Section 3.
Step 9, outcome. The Bot reports the outcome to CERTInext Cloud. The status becomes Deployed or Deployment Failed, the addresses in Provisioning Alert Emails are notified, and a successful deployment is recorded in the certificate history. At the next renewal the cycle starts again from Step 2, with a new key pair.
Each pulse is a synchronous HTTPS request. Renewal and deployment as a whole are asynchronous. The pulse triggers the renewal, the job reaches the Bot on a later pulse, and the Bot reports the outcome in a separate request after installation.
Where the key pair is generated
By default, CERTInext Cloud generates the key pair and delivers it to the Bot inside the protected keystore. The options below keep key generation on the target platform or in your own hardware.
Default
CERTInext Cloud, delivered to the Bot in the keystore
HSM as the keystore type
Your HSM, through the Bot. The private key does not leave the HSM
F5 BIG-IP with the existing key
The F5. The certificate request is built from the key already held on the F5
Akamai CPS
Akamai
Cloudflare, with Cloudflare generating the request
Cloudflare
iboss
iboss
For certificates requested directly by devices and applications over the REST API, SCEP, EST or ACME, the key pair is generated by the device or application and the private key stays there. See Supported Protocols.
2. CERTInext Cloud to CERTInext Bot
The Bot connects to CERTInext Cloud at us-discovery-api.certinext.io over HTTPS on TCP 443, directly or through a proxy. Each Bot registers with an installation token and receives its own credential for your account.
What the Bot receives
Work reaches the Bot only in the reply to its pulse, as one of the task types below.
Discovery scan
Scans the network ranges, servers and platforms set in the scan
Test Connection
Signs in to a target to confirm the account and network path
Certificate deployment
Installs a certificate and private key on a target (Section 3)
AD CS requests
Submits, collects and revokes certificates on Microsoft AD CS through the AD CS connector
Domain validation file
Places the domain validation file on the web server you set, when HTTP validation is handled by the Bot
Configuration update
Picks up changes to its scans and targets made in the console
A deployment job carries the encrypted keystore and its password. For a remote target it also carries the sign-in details for that target, such as a server service account, an F5 user name and password, a Kubernetes client certificate or service account token, or a cloud API credential. Sign-in details held in a vault are not included, because the Bot reads them from the vault.
The Bot acts only on the targets you give it an account for, and only within the rights of that account. Firewall rules on the Bot host limit what it can reach.
Where sign-in details come from
Target sign-in details can be read from HashiCorp Vault or CyberArk, or entered in the console. With a vault, CERTInext holds only the vault reference, such as a read-only HashiCorp Vault token or a CyberArk application ID, and the Bot reads each secret from inside your network when it needs it. Limit the vault policy to the secret paths that CERTInext uses.
Vault sources are available for the integrations below, for discovery, deployment or both.
Servers
Agentless Windows and Linux servers, and SSH, Remote Desktop and remote file system discovery
Load balancers and firewalls
F5 BIG-IP and BIG-IQ, FortiGate, Palo Alto, Imperva on-premises (MX)
Kubernetes
Kubernetes, AKS and OpenShift
Cloud and SaaS
AWS, Azure Key Vault and Application Gateway, Google Cloud key management, Oracle Cloud load balancers, Akamai, Cloudflare, Imperva Cloud WAF, iboss and Netskope
Directories, databases and HSMs
LDAP, AD FS, databases and HSMs
File transfer
FTP and SFTP
Other
Git repositories, Elastic Stack and Wazuh
Sign-in details for scheduled discovery scans are held in the Bot's local data store on the Bot host, so that scans can run on schedule. The data store sits in the Bot data folder, covered by the access controls in Section 2.2 of Network and Firewall Requirements.
What the Bot sends to CERTInext Cloud
Status
Bot version, host name, IP address and status, on every pulse
Discovery results
Certificates and chains, where each was found (host, port, store or file path), TLS settings, and the connection details of each discovered platform so that a deployment can be configured from the result
Existing keys brought under management
For Kubernetes and OpenShift, the TLS Secrets in the namespaces the discovery account can read, so that CERTInext can renew them. For keystore files, only those you supply a password for in the console. Key material is sent to CERTInext over TLS. Grant the discovery account access only to the namespaces you want CERTInext to manage
Outcomes
Results of deployments and test connections
Error entries
Error log entries, to support troubleshooting. This can be turned off in the standard Bot configuration (Network and Firewall Requirements, Section 2.2)
Permissions and network
The Bot runs as a service under the local system account on Windows, or under its own certbotd service account on Linux. It needs no domain account. In agent-based deployment the Bot runs on the server that uses the certificate, so no extra host is needed.
Allow one outbound rule, HTTPS on TCP 443 from the Bot host to us-discovery-api.certinext.io. Installation and upgrade also need the installer host listed in Network and Firewall Requirements.
3. CERTInext Bot to the Target
How the Bot installs the certificate depends on where it runs and what the target is.
a. Agent-based
The Bot is installed on the server that uses the certificate and runs there as a local service. It connects only to CERTInext Cloud, so no remote session, remote account or inbound port is needed on the server.
Figure 3 Agent-based installation
Windows servers running IIS. The Bot imports the certificate and private key into the Local Machine certificate store, grants IIS access to the private key, updates the HTTPS binding of the site and recycles the application pool of that site. Sites in other application pools are not restarted. The local system account is used because the certificate store and the bindings need local administrator rights.
Linux servers running Tomcat, NGINX or Apache. The Bot writes the new keystore or key files, updates the configuration and restarts the service. It runs as its own service account. At installation, the package detects the web servers on the host and gives that account sudo rights to start, stop, restart and reload them and to validate the NGINX configuration, together with write access to their configuration, certificate and key folders through the certbotd group. The certbotd account is a system account with no login shell, and each sudo rule names a specific service command. The exact rules are in /etc/sudoers.d/certbotd. If you add a web server later, run sudo certbotd-configure.
Permissions. No sign-in account is needed, because the Bot acts locally under its own service identity. That identity holds rights on that server only and has no directory rights.
Network. Outbound HTTPS on TCP 443 from the server to CERTInext Cloud.
b. Agentless (WinRM, SMB and SSH)
The Bot runs on a separate server, the Bot host, and connects to each target server with a service account you create for CERTInext. Nothing is installed on the target. The account needs administrator rights on Windows targets, or sudo on Linux targets, because the Bot writes to the protected certificate store, key folders and configuration files and restarts the web service.
Figure 4 Agentless installation on Windows and Linux servers
Windows servers running IIS. The Bot connects to the WinRM HTTPS listener on TCP 5986, set as the WinRM port of each server in the console, and signs in with NTLM. The Bot transfers the keystore, imports the certificate and private key into the Local Machine certificate store, updates the HTTPS binding of the site, removes the temporary keystore file and recycles the application pool of the site.
Windows servers running Tomcat or NGINX. The Bot copies the keystore or key files and its task scripts through the administrative share over SMB on TCP 445. It stops Tomcat, keeps backup copies of the keystore, key and configuration files, updates the configuration, then starts Tomcat or restarts NGINX over WinRM and removes the scripts.
Windows service account. A dedicated domain account, such as CORP\svc-certinext, that is a member of the local Administrators group on the servers in scope and is allowed to connect over WinRM. Group Policy is the usual way to grant this membership. In the console, enter the account in the svc-certinext@corp.example.com form. Deny the account interactive and Remote Desktop sign-in, and use a separate account for each server tier or security zone.
Linux servers running Tomcat, NGINX or Apache. The Bot signs in over SSH on TCP 22, or the port set for the server, and uploads the files to a temporary folder over SFTP. Using sudo, it stops Tomcat, keeps backup copies, moves the files into place, sets their owner and permissions, updates the configuration and restarts the service.
Linux service account. A local account, for example svc-certinext, that signs in over SSH with a password and has sudo rights for file copy, move, ownership and permission changes, configuration edits and the service restart. Treat this account as a privileged administration account. Allow it to sign in over SSH only from the Bot host address, for example with a Match Address block in sshd_config, and use a separate account for each server tier or security zone.
Permissions. Service accounts created for CERTInext on the servers in scope and used only by the Bot. No domain-wide administrative rights.
Network. Outbound from the Bot host to the servers in scope on TCP 5986 for WinRM, TCP 445 for SMB on Windows Tomcat and NGINX servers, and TCP 22 for SSH, with the matching inbound rule on each server. All of it stays inside your network.
c. API-driven (F5 BIG-IP, Kubernetes and OpenShift)
The Bot calls the platform management API from the Bot host with a service account you create on the platform. Nothing is installed on the platform. The Bot sends the certificate and private key over HTTPS to that platform API only.
Figure 5 API-driven installation
F5 BIG-IP. The Bot connects to the F5 management address over HTTPS, on TCP 443 by default, and signs in with the F5 user name and password. It uploads the certificate and private key, creates certificate, key and client SSL profile objects, and puts the new client SSL profile on the virtual server in place of the previous one. No service restart is needed.
F5 service account. A local F5 user with the Resource Administrator role covers deployment. Grant the Administrator role only on F5 systems where certificate discovery, or certificate requests built from a key already held on the F5, are enabled.
Kubernetes, AKS and OpenShift. The Bot connects to the Kubernetes Master URL over HTTPS, on the port in that URL, usually TCP 443 for AKS and TCP 6443 for OpenShift. It authenticates with a client certificate and the cluster CA certificate, or with a service account token. It creates or replaces the TLS Secret that holds the certificate and private key in the namespace and, when selected, points the Ingress or the OpenShift Route at the Secret.
Kubernetes service account. A service account bound through a Role and RoleBinding in the target namespace, with get, create and update on Secrets, and get and update on Ingresses, or get and patch on Routes for OpenShift. Discovery of the Secrets you select in the console needs get on those Secrets, through a Role in each namespace. A full cluster scan needs list on namespaces and Secrets through a ClusterRole.
Network. Outbound from the Bot host to the F5 management interface and to the cluster API server, inside your network.
4. Security and operational controls
Console access
Assign the permissions to manage Bots, agentless servers and deployment configurations only to the administrators responsible for them.
Enforce two-factor authentication or single sign-on for the account, and restrict console sign-in to your address ranges with IP Restrictions.
Review the audit log in the console. It records Bot activation and deactivation, deployment configuration changes, agentless server changes and manual deployments.
Data protection
Encryption in transit. All connections between CERTInext, the Bot, devices and browsers use TLS 1.2 or 1.3.
Key material. Private keys generated by CERTInext are packaged in encrypted keystores for storage and delivery. Key material exchanged between CERTInext and the Bot travels over TLS. Keystore passwords are encrypted at the application layer before they are stored.
CA keys. Private CAs hosted on emCA keep their signing keys in hardware security modules.
Customer-held keys. Where keys must stay under your control, key pairs can be generated in your own HSM, on F5 BIG-IP, Akamai, Cloudflare or iboss, or on the device itself through SCEP, EST, ACME or the REST API.
Vault integration. With HashiCorp Vault or CyberArk, target sign-in details stay in your vault. The Bot retrieves them inside your network when a task runs.
Bot host
Treat the Bot host as a privileged management server. The hardening steps, including the standard Bot configuration, are in Section 2.2 of Network and Firewall Requirements.
Before you install or upgrade the Bot on Windows, confirm that the installer is signed by EMUDHRA LIMITED.
Target accounts
Create a dedicated account for CERTInext on each target type, with the rights in Section 3 and no others. Use a separate account for each server tier or security zone, and allow these accounts to sign in only from the Bot host where the platform supports it.
Use a vault for target sign-in details where your policy requires it (Section 2).
Rotate target passwords and tokens on your normal schedule, and update them in the console or the vault.
Decommissioning a Bot
Deactivate the Bot on the Bots page in the console.
Uninstall the Bot. On Windows, use Apps and Features. On Debian and Ubuntu, run
sudo apt purge certinext-bot. On RHEL and compatible systems, runsudo dnf remove certinext-bot, then remove/etc/sudoers.d/certbotd,/etc/logrotate.d/certbotd, the/etc/certbotd,/var/lib/certbotdand/var/log/certbotdfolders, and thecertbotdaccount and group.Change the passwords, keys and tokens of every target the Bot managed.
Related pages
Last updated