Agents for private certificates
Monitor certificates CertWatchr cannot reach from the internet (intranet hosts, private CAs, self-signed devices) with a small agent in your own network.
Some certificates are only reachable from inside your network: the intranet, internal mail and LDAP servers, a Kubernetes API, the management interface of a server or a printer. CertWatchr's own checks run on the internet and deliberately never connect to private addresses. An agent closes that gap: it runs on a Linux server in your network, checks those hosts there, and reports what it saw. Expiry warnings, the health score, the notification centre and every alert work exactly as for a public certificate.
Agents are part of Pro (one agent) and Team (up to 25).
How it works
- The agent only makes outbound HTTPS calls to CertWatchr. Nothing has to be opened towards it, and it never touches anything but the hosts you allow.
- About once a minute it asks which checks are due, runs the TLS handshakes with your network's own DNS, and sends back what each server presented: the certificate chain, the TLS version and whether old protocol versions are still accepted.
- CertWatchr decides what that means. Whether the certificate is trusted, valid for the host name and close to expiry is judged on our side, with the same rules as every other check.
- Each domain an agent watches is looked at every 30 minutes; Check now asks the agent on its next poll.
Install an agent
- Open Settings → Agents, give the agent a name (say, Vienna data centre) and choose Add agent.
- Copy the command that appears. It contains a one-time install token that works for 24 hours and is shown only once.
-
Run it on a Linux server in the network the certificates are in:
docker run -d --name certwatchr-agent --restart unless-stopped \ -e CERTWATCHR_ENROLL=<token> \ -e CERTWATCHR_ALLOW_NETWORKS=10.0.0.0/8,172.16.0.0/12,192.168.0.0/16 \ -v certwatchr-agent:/var/lib/certwatchr-agent \ <image from the page> -
Within a minute the agent shows as Online.
Without Docker, on Debian or Ubuntu (Python 3.11 or newer), install the certwatchr-agent
package, put the token in /etc/certwatchr-agent/env as CERTWATCHR_ENROLL=<token>, set the
allowlist in /etc/certwatchr-agent/config.toml and run systemctl enable --now certwatchr-agent.
The first start enrolls the agent.
Lost the token, or moving the agent to another machine? New install token issues another; enrolling with it switches the old installation off.
The allowlist
The agent connects only to the address ranges and ports you allow (CERTWATCHR_ALLOW_NETWORKS,
CERTWATCHR_ALLOW_PORTS, optionally CERTWATCHR_ALLOW_HOSTNAMES), whatever it is asked to check.
A check outside the allowlist is reported as refused, and the domain shows why. Without Docker,
the same settings live in /etc/certwatchr-agent/config.toml.
Add a domain that an agent checks
When you add or edit a domain, Checked from offers CertWatchr cloud and each of your agents.
Choose the agent for a host only your network can reach; private addresses such as 10.0.0.5
are accepted then. Hosts given as an IP address are matched against the certificate's IP
addresses.
Your own CA
Certificates issued by your own CA (Active Directory Certificate Services, step-ca, Vault) are not known to public trust stores. Add the CA certificate under Settings → Agents → Your CA certificates, and every chain that leads to it counts as trusted. Only the certificate is needed, never its private key; CertWatchr refuses a file that contains one. A CA the agent's own machine already trusts counts too.
Self-signed devices
Management interfaces, NAS boxes and printers often have a self-signed certificate. Choose Trust: This exact certificate for them. The first certificate the agent sees is pinned; if it changes, the domain turns to error and you are alerted. Was the change expected? Trust the current certificate on the domain page pins the new one.
Revocation of private certificates
The agent also asks your CA whether a certificate was revoked: it downloads the revocation list (CRL) named in the certificate, as long as the CRL's address is inside the allowlist, and checks its signature against the issuing CA. A CRL the agent may not or cannot fetch counts as unknown and costs no points.
One certificate from several places (Team)
On Team, Checked from is a list of check boxes: tick the CertWatchr cloud and any of your agents. Each place checks on its own, and the domain page shows them side by side under Where it is checked from.
- The domain shows the worst place. A certificate that expires in three days in one data centre is critical, however healthy the other one looks.
- When the places see different certificates, you are alerted: usually one server or load balancer was missed during a renewal, or split-horizon DNS points somewhere else inside.
- The certificate details and the health score come from the first place: the cloud when it takes part, otherwise the oldest agent.
When an agent goes offline
If an agent has not asked for work for ten minutes, you get one e-mail and one entry in the notification centre, and its domains are not checked until it is back. When it returns, the entry closes by itself.
Plans
| Pro | Team | |
|---|---|---|
| Agents | 1 | up to 25 |
| Locations per certificate | 1 | as many as you like |
After a downgrade, agents beyond the plan pause rather than being deleted: they keep their token and their domains, and carry on with their next poll after an upgrade. From Team to Pro, each domain is checked from its first place only; the others are kept and come back on upgrade.