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. | Option | Where the key pair is generated | | -------------------------------------------------- | ---------------------------------------------------------------------------- | | 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](https://docs.certinext.io/documentation/automation-and-devops/supported-protocols-acme-scep-est-etc). ### 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. | Task | What the Bot does | | ---------------------- | ------------------------------------------------------------------------------------------------------- | | 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. | Area | Integrations | | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements). #### What the Bot sends to CERTInext Cloud | Data | Content | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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](https://docs.certinext.io/documentation/deployment-and-operations/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](https://docs.certinext.io/documentation/deployment-and-operations/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 1. Deactivate the Bot on the Bots page in the console. 2. Uninstall the Bot. On Windows, use Apps and Features. On Debian and Ubuntu, run `sudo apt purge certinext-bot`. On RHEL and compatible systems, run `sudo dnf remove certinext-bot`, then remove `/etc/sudoers.d/certbotd`, `/etc/logrotate.d/certbotd`, the `/etc/certbotd`, `/var/lib/certbotd` and `/var/log/certbotd` folders, and the `certbotd` account and group. 3. Change the passwords, keys and tokens of every target the Bot managed. ### Related pages * [Bot Deployment and Management](https://docs.certinext.io/documentation/automation-and-devops/agent-deployment-and-management) * [Network and Firewall Requirements](https://docs.certinext.io/documentation/deployment-and-operations/network-and-firewall-requirements) * [Bot Connectivity Issues](https://docs.certinext.io/documentation/troubleshooting-and-faqs/agent-connectivity-issues)